Getting Started with ClawSpec + OpenSpec: Automating Continuous Project Progress and Eliminating Manual Intervention

Difficulty: Beginner | Duration: 20 minutes | Key Takeaway: Manage the entire project lifecycle via OpenSpec within a chat window, ensuring AI productivity without stalling.

---

Target Audience

You are already running OpenClaw and using it for daily tasks. During use, you may have encountered this issue:

The requirements were discussed clearly, and the agent agreed to start working, but after a while, you find it has stopped, waiting for your prompt instead of pushing forward.

This is particularly noticeable in long-term tasks, requirement changes, and "chat-as-you-go" scenarios. What you need is not just a chatty AI, but an execution system capable of organizing requirements, maintaining momentum, and automatically recovering without human supervision.

Target audience for this article:

• Existing OpenClaw users who want to complete the full project cycle (Requirement → Planning → Code → Archive) within a chat.
• Users who have experienced agent stagnation and want a controllable, continuous execution solution.
• Those interested in the OpenSpec workflow and looking to embed it directly into OpenClaw.

---

Core Dependencies and Environment

GitHub Repository: https://github.com/bytegh/clawspec

---

Full Project Structure

ClawSpec plugin directory structure (post-installation):

clawspec/
├── index.ts                    # Plugin entry point
├── src/                       # Core source code
│   ├── service/               # Service layer
│   ├── watcher/               # Background watcher management
│   ├── stores/                # State storage
│   └── hooks/                 # OpenClaw hooks
├── skills/                    # Built-in OpenSpec skill texts
├── test/                      # Test cases
├── openclaw.plugin.json       # Plugin configuration
├── package.json
└── tsconfig.json

At runtime, OpenClaw management files are generated under each repo:

<repo>/
├── .openclaw/clawspec/        # ClawSpec runtime state
│   ├── state.json             # Current project state
│   ├── execution-control.json # cs-work execution control
│   ├── execution-result.json  # Execution results
│   ├── worker-progress.jsonl  # Background progress logs
│   ├── planning-journal.jsonl  # Requirement discussion records
│   ├── planning-journal.snapshot.json  # Journal snapshot
│   ├── rollback-manifest.json # Rollback manifest
│   ├── snapshots/             # Change snapshot baselines
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # Archived changes
├── openspec/                  # OpenSpec specification directory
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

Step-by-Step Guide

Step 1: Install ClawSpec Plugin

ClawSpec offers three installation methods; the first is recommended:

Method A: Via OpenClaw Plugin Installer (Recommended)

openclaw plugins install clawspec@latest

Method B: Via ClawHub CLI

npx clawhub@latest install clawspec

Method C: Manual NPM Package Install (Fallback)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest always resolves to the latest published version on npm. If installing a development commit not yet on npm, use a local checkout or the downloaded .tgz package.

---

Step 2: Configure OpenClaw

After installation, enable ACP and configure ClawSpec in ~/.openclaw/openclaw.json:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

Key Configuration Descriptions:

If your OpenClaw lacks a built-in ACPX, ClawSpec will auto-install a local copy. Command paths for ACPX are managed by ClawSpec internally.

Once configured, restart the gateway:

openclaw gateway restart
openclaw gateway status

---

Step 3: Bind Workspace and Project

ClawSpec remembers workspaces per chat channel. Each channel can bind to a different project root.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

Expected outcomes:

• ClawSpec saves the workspace path to the current chat channel.
• If the demo-app directory doesn't exist, it is created automatically.
• Upon selecting this repo for the first time, openspec init is executed.

---

Step 4: Create an OpenSpec Change to Enter Project Context

/clawspec proposal add-login-flow "Build login and session handling"

This command performs three actions:

1. Creates standard scaffolding under openspec/changes/add-login-flow/ (proposal.md, design.md, tasks.md, specs/).
2. ClawSpec takes a snapshot baseline of currently tracked files (for future rollbacks).
3. The current chat enters the context of the add-login-flow active change.

Henceforth, all chat content while "attached" is automatically recorded into the planning journal.

---

Step 5: Describe Requirements in Chat

Describe your requirements naturally in the chat, for example:

Support login via email and password.
Refresh tokens are required.
Access tokens should expire in 15 minutes.

ClawSpec appends these to planning-journal.jsonl. Artifacts are not refreshed and code is not written yet—this stage is for recording only.

If you want the background process to continue while you chat about other things, use:

cs-detach

This separates standard chat from the planning journal, though watcher progress updates will still push. To reconnect later, use:

cs-attach

---

Step 6: cs-plan, Synchronizing Visible Planning

Once requirements are sufficiently discussed, execute:

cs-plan

ClawSpec will refresh these artifacts directly within the current visible chat turn:

• proposal.md — Project Proposal
• design.md — Architecture Design
• specs/ — Detailed Specifications
• tasks.md — Task List

cs-plan does not use the background ACP worker or hidden sub-agents—you can see the AI refreshing artifacts in the main chat window.

---

Step 7: cs-work, Start Background Continuous Implementation

Once the planning is clean, start the background implementation:

cs-work

cs-work does not write code in the main chat. It follows this path:

1. Validates that planning state is clean (dirty journals are intercepted).
2. Writes to execution-control.json, activating the watcher.
3. The watcher starts an ACP worker session via acpx.
4. The worker executes task-by-task according to tasks.md, updating progress in worker-progress.jsonl.
5. The watcher translates worker progress events into short chat messages pushed to you.

Your chat window will receive updates like:

[Watcher] ACP worker connected...
[Worker] Preparing login-flow: loading context
[Worker] Loaded proposal.md
[Worker] Context ready for Task 1
[Worker] Task 1/5 complete: User Authentication Module
[Worker] Task 2/5 complete: Token Refresh Logic
...
[Worker] All tasks complete.

---

Step 8: Progress Tracking and Recovery

This is a core ClawSpec capability—automatic worker resumption after gateway restarts.

When the gateway restarts, the watcher manager will:

• Scan all active projects.
• Prioritize taking over surviving ACP worker sessions.
• If the old worker is dead, automatically re-arm and start a replacement.
• Maintain task progress and worker progress offsets.

You don't need to manually prompt cs-work after a restart; ClawSpec reconnects the broken workflow automatically.

To view worker status at runtime:

/clawspec worker status

This displays:

• Current configured worker agent.
• Transport layer status (connected / disconnected).
• Startup phase (loading context / ready / running).
• Real-time PID, heartbeat, and next-step suggestions.

When an ACP worker fails, ClawSpec distinguishes between "recoverable errors" and "true blockers," performing limited retries with backoff for the former. If retries exceed the limit (default 10), the project is marked blocked, requiring manual intervention.

Collaborative pause and resume:

cs-pause        # Pause worker at a safe boundary
cs-continue     # Resume planning or implementation

---

Step 9: Archiving and Completion

Once all tasks are finished, clean up the active change:

/clawspec archive

This will:

1. Validate the integrity of the OpenSpec change.
2. Move completed changes to the archives/ directory.
3. Clear the active change state from the current chat.

To discard the current change (without keeping code changes):

/clawspec cancel

ClawSpec restores tracked files from the snapshot baseline rather than performing a repository-wide git reset --hard.

The complete workflow cycle:

Discuss Requirements → cs-plan → cs-work → Wait for progress → cs-detach (optional) → cs-attach (optional)
→ /clawspec archive (upon completion)

---

Troubleshooting

1. cs-work prompts "Planning sync required"

Causes:

• Planning journal is dirty (new requirements discussed after the snapshot).
• Planning artifacts are missing or outdated.
• OpenSpec apply state is still blocked.

Resolution:

cs-plan
# Wait for planning to complete
cs-work

---

2. Watcher reports ACPX unavailable

Possible reasons:

• acp.enabled is false.
• acp.backend is not set to acpx.
• acp.defaultAgent is unconfigured.
• OpenClaw lacks built-in ACPX and ClawSpec found no local copy.

Quick Fix:

openclaw config set acp.backend acpx
openclaw config set acp.defaultAgent claude
openclaw gateway restart
cs-work

If ACPX is still unavailable, ClawSpec will attempt to install a local plugin copy. This may take time and network access on first run.

---

3. General chat polluted the planning journal

Normal chat was recorded into the journal, and cs-work is now blocked by a "dirty" status.

Detach immediately:

cs-detach

When ready to discuss requirements again:

cs-attach

---

4. Worker connected but hasn't started tasks

This usually means the ACP worker is active but still processing the implementation prompt or reading planning artifacts.

Check for these message types:

• Watcher side status: "starting worker", "ACP worker connected...".
• Worker-logged loading states: "Preparing <task>: loading context", "Loaded proposal.md", "Context ready...".

If you see "Context ready for ...", the worker has finished reading artifacts and will proceed to the first task shortly.

Run /clawspec worker status and focus on startup phase and startup wait to determine where the worker is stuck.

---

5. Worker errors "stdin is not a terminal" or session creation fails

Causes:

• Custom agent configurations exist in ~/.acpx/config.json (e.g., agents.codex pointing to a local CLI path).
• ACPX cannot start the agent via raw CLI in non-interactive environments.

Run diagnostics:

/clawspec doctor

If custom agent issues are reported, run auto-fix:

/clawspec doctor fix

Manual fix: Edit ~/.acpx/config.json and set "agents" to an empty object:

{
  "agents": {}
}

---

6. /clawspec use reports existing unfinished change

This is expected behavior. ClawSpec does not allow silently abandoning an active change on the same repo.

Choose one of three:

/clawspec continue      # Continue current change
/clawspec archive       # Archive completed change
/clawspec cancel        # Discard current change

---

Extended Reading / Advanced Directions

1. Advanced OpenSpec CLI Usage

ClawSpec's built-in OpenSpec CLI is a full project spec management system. You can run these directly in the project directory:

openspec status        # View current change status
openspec diff          # Compare current files with snapshot baseline
openspec validate      # Validate OpenSpec specification integrity

Deeply understanding the Propose → Design → Spec → Task → Apply chain helps you better plan the granularity and scope of changes.

2. Multi-channel/Multi-project Parallel Management

Since ClawSpec remembers workspaces per channel, you can:

• Manage a backend API project in a Telegram channel.
• Manage a frontend project in a Discord channel.
• The same repo can have different active changes in different channels (though only one unfinished change is allowed globally per repo).

Use cs-detach to keep background work running without having to monitor every channel continuously.

3. Custom Agent Configuration for ACP Workers

Beyond the global acp.defaultAgent, you can switch worker agents for specific channels/projects:

/clawspec worker codex    # Use codex for current channel/project
/clawspec worker claude  # Switch back to claude

This allows you to select the appropriate worker for tasks of varying complexity if you have multiple agent configurations.

4. Synergy with Other OpenSpec Toolchains

ClawSpec-generated tasks.md and proposal.md files can be read by other tools (e.g., Superpowers, custom CI scripts), creating a complete project management loop. OpenSpec spec files are pure Markdown and format-agnostic.

5. Customizing ClawSpec Configuration

plugins.entries.clawspec.config includes several advanced options:

{
  "clawspec": {
    "enabled": true,
    "config": {
      "archiveDirName": "archives",
      "allowedChannels": ["ch_xxx", "ch_yyy"]
    }
  }
}

allowedChannels can restrict ClawSpec to specific channels, ideal for team environments where only certain channels require this workflow.