Channels
Clawspec
By ClawSpec is an OpenClaw plugin that brings OpenSpec workflows into chat with visible planning, durable background execution, and channel-scoped project state.
Install
npm install --omit=devConfiguration Example
{
"acp": {
"enabled": true,
"backend": "acpx",
"defaultAgent": "codex"
},
"plugins": {
"entries": {
"acpx": {
"enabled": true,
"config": {
"permissionMode": "approve-all",
"expectedVersion": "any"
}
},
"clawspec": {
"enabled": true,
"config": {
"defaultWorkspace": "~/clawspec/workspace",
"workerAgentId": "codex",
"openSpecTimeoutMs": 120000,
"watcherPollIntervalMs": 4000
}
}
}
}
}README
# ClawSpec
[Chinese (Simplified)](./README.zh-CN.md)
ClawSpec is an OpenClaw plugin that embeds an OpenSpec workflow directly into chat. It splits project control and execution on purpose:
- `/clawspec ...` manages workspace, project, change, and recovery state.
- `cs-*` chat keywords trigger work inside the active conversation.
- `cs-plan` runs planning sync in the visible chat turn.
- `cs-work` runs implementation in the background through a watcher and ACP worker, then reports short progress updates back into chat.
The result is an OpenSpec workflow that stays chat-native without hiding long-running implementation work inside the main session.
## At A Glance
- Workspace is remembered per chat channel.
- One active project is tracked per chat channel.
- One unfinished change is enforced per repo across channels.
- Discussion messages are recorded into a planning journal while context is attached.
- `cs-plan` refreshes `proposal.md`, `design.md`, `specs`, and `tasks.md` without implementing code.
- `cs-work` turns `tasks.md` into background execution, with watcher-driven progress and restart handling.
- `/clawspec cancel` restores tracked files from snapshots instead of doing a blanket Git reset.
- `/clawspec archive` validates and archives the finished OpenSpec change, then clears the active change from chat context.
## Why The Surface Is Split
ClawSpec uses two different control surfaces because they solve different problems:
| Surface | Examples | What it does | Why it exists |
| --- | --- | --- | --- |
| Slash command | `/clawspec use`, `/clawspec proposal`, `/clawspec status` | Direct plugin control, file system setup, state inspection | Fast, deterministic, no agent turn required |
| Chat keyword | `cs-plan`, `cs-work`, `cs-pause` | Injects workflow context into the current conversation or queues background execution | Keeps planning visible in chat and lets normal chat remain the primary UX |
In practice:
- Use `/clawspec ...` to set up and manage the project.
- Use `cs-plan` when you want the current visible agent turn to refresh planning artifacts.
- Use `cs-work` when you want the watcher to start background implementation.
## Architecture
```mermaid
flowchart TD
U[User In Chat] --> CMD[/clawspec command/]
U --> KEY[cs-* keyword]
U --> MSG[ordinary discussion]
CMD --> SVC[ClawSpec service]
KEY --> HOOK[before_prompt_build hook]
MSG --> INBOUND[message_received hook]
INBOUND --> JOURNAL[planning-journal.jsonl]
HOOK --> SVC
SVC --> STATE[plugin state store]
SVC --> WS[workspace store]
SVC --> MEM[project memory store]
SVC --> OSCLI[OpenSpec CLI]
SVC -->|cs-plan| MAIN[visible chat agent]
MAIN -->|skills + planning prompt| ARTIFACTS[proposal/design/specs/tasks]
SVC -->|cs-work| CTRL[execution-control.json]
CTRL --> WATCHER[watcher manager]
WATCHER --> ACP[ACP worker via acpx]
ACP --> PROGRESS[worker-progress.jsonl]
ACP --> RESULT[execution-result.json]
WATCHER --> NOTIFY[chat progress notifier]
NOTIFY --> U
JOURNAL --> MAIN
ARTIFACTS --> ACP
RESULT --> STATE
```
## What Runs Where
| Action | Runtime | Visible to user | Writes |
| --- | --- | --- | --- |
| `/clawspec workspace` | Plugin command handler | Immediate command reply | Workspace state |
| `/clawspec use` | Plugin command handler + `openspec init` if needed | Immediate command reply | Workspace/project selection, OpenSpec init |
| `/clawspec proposal` | Plugin command handler + `openspec new change` | Immediate command reply | Change scaffold, snapshots, fresh planning state |
| Ordinary discussion | Main chat agent + prompt injection | Yes | Planning journal, no artifact rewrite |
| `cs-plan` | Main chat agent in the current visible turn | Yes | Planning artifacts, planning journal snapshot |
| `cs-work` | Watcher + ACP worker | Progress updates only | Code changes, `tasks.md`, watcher support files |
| `/clawspec continue` | Plugin decides whether to re-arm planning or implementation | Immediate reply, then either visible planning or background work | Execution state |
## Requirements
- A recent OpenClaw build with plugin hooks and ACP runtime support.
- Node.js `>= 24` on the gateway host.
- `npm` available on the gateway host if OpenSpec must be bootstrapped automatically.
- An OpenClaw agent profile that can run shell commands and edit files for visible planning turns.
- ACP backend `acpx` enabled for background implementation.
ClawSpec depends on these OpenClaw hook points:
- `message_received`
- `before_prompt_build`
- `agent_end`
If your host disables plugin hooks globally, keyword-based workflow will not work correctly.
## Installation
### 1. Install the plugin
Recommended public install after publishing to npm:
```powershell
openclaw plugins install [email protected]
```
Current OpenClaw builds do not accept raw GitHub URLs as ordinary plugin install specs. A GitHub repo by itself is not enough for `openclaw plugins install`; the standard public path is an npm package spec such as `[email protected]`.
If you want an unreleased commit before npm publish, clone the repository and install from the local checkout or a downloaded `.tgz` archive instead.
### 2. Enable ACP and ACPX in OpenClaw
Example `~/.openclaw/openclaw.json`:
```json
{
"acp": {
"enabled": true,
"backend": "acpx",
"defaultAgent": "codex"
},
"plugins": {
"entries": {
"acpx": {
"enabled": true,
"config": {
"permissionMode": "approve-all",
"expectedVersion": "any"
}
},
"clawspec": {
"enabled": true,
"config": {
"defaultWorkspace": "~/clawspec/workspace",
"workerAgentId": "codex",
"openSpecTimeoutMs": 120000,
"watcherPollIntervalMs": 4000
}
}
}
}
}
```
Important notes:
- Recent OpenClaw builds often bundle `acpx` under the host install. In that case you usually only need to enable it.
- If your OpenClaw build does not bundle `acpx`, install or load it separately before relying on `cs-work`.
- ClawSpec itself does not ship its own ACP runtime backend.
- When ACPX is unavailable, the watcher now reports a short recovery hint in chat telling the user to enable `plugins.entries.acpx` and backend `acpx`.
### 3. Restart the gateway
```powershell
openclaw gateway restart
openclaw gateway status
```
### 4. Understand OpenSpec bootstrap behavior
On startup ClawSpec checks for `openspec` in this order:
1. Plugin-local binary under `node_modules/.bin`
2. `openspec` on `PATH`
3. If missing, it may run:
```powershell
npm install --omit=dev --no-save @fission-ai/openspec
```
That means the gateway host may need network access and a working `npm` if `openspec` is not already available.
## Quick Start
```text
/clawspec workspace "<workspace-path>"
/clawspec use "demo-app"
/clawspec proposal add-login-flow "Build login and session handling"
Describe the requirement in chat
cs-plan
cs-work
/clawspec status
/clawspec archive
```
What happens:
1. `/clawspec workspace` selects the workspace for this chat channel.
2. `/clawspec use` selects or creates a repo folder under that workspace and runs `openspec init` if needed.
3. `/clawspec proposal` creates the OpenSpec change scaffold and snapshot baseline.
4. Ordinary chat discussion appends requirement notes to the planning journal.
5. `cs-plan` refreshes planning artifacts in the visible chat turn.
6. `cs-work` arms the watcher and starts background implementation.
7. Watcher progress updates appear back in the same chat.
8. `/clawspec archive` validates and archives the completed change.
## Slash Commands
| Command | Purpose |
| --- | --- |
| `/clawspec workspace [path]` | Show the current workspace or switch the workspace for this chat channel |
| `/clawspec use <project-name>` | Select or create a project inside the current workspace |
| `/clawspec proposal <change-name> [description]` | Create a new OpenSpec change scaffold and rollback baseline |
| `/clawspec worker [agent-id]` | Show or set the ACP worker agent for this channel/project |
| `/clawspec worker status` | Show live worker state, current task, session, and heartbeat |
| `/clawspec attach` | Reattach ordinary chat to the active ClawSpec context |
| `/clawspec detach` | Detach ordinary chat from ClawSpec context |
| `/clawspec deattach` | Legacy alias for `/clawspec detach` |
| `/clawspec continue` | Resume planning or implementation depending on the current phase |
| `/clawspec pause` | Request a cooperative pause at the next safe boundary |
| `/clawspec status` | Reconcile and render current project status |
| `/clawspec archive` | Validate and archive a completed change |
| `/clawspec cancel` | Restore tracked files, remove the change, and clear runtime state |
Auxiliary host CLI:
| Command | Purpose |
| --- | --- |
| `clawspec-projects` | List remembered ClawSpec workspaces |
## Chat Keywords
Send these as normal chat messages in the active conversation.
| Keyword | Purpose |
| --- | --- |
| `cs-plan` | Run visible planning sync in the current chat turn |
| `cs-work` | Start background implementation for pending tasks |
| `cs-attach` | Reattach ordinary chat to project mode |
| `cs-detach` | Detach ordinary chat from project mode |
| `cs-deattach` | Legacy alias for `cs-detach` |
| `cs-pause` | Pause background execution cooperatively |
| `cs-continue` | Resume planning or implementation |
| `cs-status` | Show current project status |
| `cs-cancel` | Cancel the active change |
## End-To-End Workflow
```mermaid
sequenceDiagram
actor User
participant Chat as OpenClaw Chat
participant Plugin as ClawSpec Plugin
participant Main as Visible Chat Agent
participant Watcher as Watcher Manager
participant Worker as ACP Worker
participant OpenSpec as OpenSpec CLI
User->>Plugin: /clawspec workspace + /clawspec use
Plugin->>OpenSpec: openspec init (if nee
... (truncated)
channels
Comments
Sign in to leave a comment