clawspec 1.0.0

package/index.ts

@@ -0,0 +1,3 @@
+import plugin from "./src/index.ts";
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,129 @@
+{
+  "id": "clawspec",
+  "name": "ClawSpec",
+  "description": "OpenSpec-aware project orchestration for OpenClaw channels",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable or disable the ClawSpec plugin"
+      },
+      "allowedChannels": {
+        "type": "array",
+        "description": "Optional list of channel ids allowed to use /clawspec",
+        "items": {
+          "type": "string"
+        }
+      },
+      "maxAutoContinueTurns": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 50,
+        "description": "Deprecated no-op retained for backward compatibility with older configs"
+      },
+      "maxNoProgressTurns": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 10,
+        "description": "Deprecated no-op retained for backward compatibility with older configs"
+      },
+      "openSpecTimeoutMs": {
+        "type": "integer",
+        "minimum": 5000,
+        "maximum": 600000,
+        "description": "Timeout in milliseconds for each OpenSpec CLI invocation"
+      },
+      "workerWaitTimeoutMs": {
+        "type": "integer",
+        "minimum": 10000,
+        "maximum": 3600000,
+        "description": "Deprecated no-op retained for backward compatibility with older configs"
+      },
+      "workerAgentId": {
+        "type": "string",
+        "description": "ACP agent id used for background planning and implementation"
+      },
+      "workerBackendId": {
+        "type": "string",
+        "description": "Optional ACP backend id used for background worker sessions"
+      },
+      "watcherPollIntervalMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 60000,
+        "description": "Background watcher recovery poll interval in milliseconds"
+      },
+      "subagentLane": {
+        "type": "string",
+        "description": "Deprecated no-op retained for backward compatibility with older configs"
+      },
+      "archiveDirName": {
+        "type": "string",
+        "description": "Directory name used under .openclaw/clawspec/ for archived runs"
+      },
+      "defaultWorkspace": {
+        "type": "string",
+        "description": "Base directory used for default project browsing and relative /clawspec path inputs"
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable ClawSpec",
+      "help": "Enable or disable the ClawSpec plugin"
+    },
+    "allowedChannels": {
+      "label": "Allowed Channels",
+      "help": "Optional list of channel ids allowed to use /clawspec"
+    },
+    "maxAutoContinueTurns": {
+      "label": "Deprecated Auto Turns",
+      "help": "Deprecated no-op retained for backward compatibility"
+    },
+    "maxNoProgressTurns": {
+      "label": "Deprecated No Progress",
+      "help": "Deprecated no-op retained for backward compatibility"
+    },
+    "openSpecTimeoutMs": {
+      "label": "OpenSpec Timeout",
+      "help": "Timeout in milliseconds for each OpenSpec command",
+      "advanced": true
+    },
+    "workerWaitTimeoutMs": {
+      "label": "Deprecated Worker Timeout",
+      "help": "Deprecated no-op retained for backward compatibility",
+      "advanced": true
+    },
+    "workerAgentId": {
+      "label": "Worker Agent",
+      "help": "ACP agent id used for background planning and implementation turns",
+      "advanced": true
+    },
+    "workerBackendId": {
+      "label": "Worker ACP Backend",
+      "help": "Optional ACP backend id used for background worker sessions",
+      "advanced": true
+    },
+    "watcherPollIntervalMs": {
+      "label": "Watcher Poll Interval",
+      "help": "Background watcher recovery poll interval in milliseconds",
+      "advanced": true
+    },
+    "subagentLane": {
+      "label": "Deprecated Lane Hint",
+      "help": "Deprecated no-op retained for backward compatibility",
+      "advanced": true
+    },
+    "archiveDirName": {
+      "label": "Archive Folder",
+      "help": "Directory name used for archived run bundles",
+      "advanced": true
+    },
+    "defaultWorkspace": {
+      "label": "Default Workspace",
+      "help": "Base directory used for `/clawspec workspace` and `/clawspec use`"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "clawspec",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
+  "keywords": [
+    "openclaw",
+    "openspec",
+    "plugin",
+    "project-orchestration",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bytegh/clawspec.git"
+  },
+  "homepage": "https://github.com/bytegh/clawspec#readme",
+  "bugs": {
+    "url": "https://github.com/bytegh/clawspec/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src",
+    "skills",
+    "test",
+    "README.md",
+    "README.zh-CN.md",
+    "openclaw.plugin.json",
+    "tsconfig.json"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "openclaw": ">=0.0.0"
+  },
+  "devDependencies": {
+    "openclaw": "2026.3.24"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types -e \"import('./index.ts')\"",
+    "test": "node --experimental-strip-types --test --test-reporter spec test/*.test.ts",
+    "test:fast": "node --experimental-strip-types --test --test-reporter spec test/acp-client.test.ts test/acpx-dependency.test.ts test/assistant-journal.test.ts test/command-surface.test.ts test/config.test.ts test/detach-attach.test.ts test/file-lock.test.ts test/fs-utils.test.ts test/helpers.test.ts test/keywords.test.ts test/notifier.test.ts test/openspec-dependency.test.ts test/pause-cancel.test.ts test/planning-journal.test.ts test/plugin-registration.test.ts test/project-memory.test.ts test/proposal.test.ts test/queue-planning.test.ts test/queue-work.test.ts test/service-archive.test.ts test/shell-command.test.ts test/state-store.test.ts test/tasks-and-checkpoint.test.ts test/use-project.test.ts test/worker-command.test.ts test/worker-skills.test.ts",
+    "test:slow": "node --experimental-strip-types --test --test-reporter spec test/watcher-planning.test.ts test/watcher-work.test.ts test/recovery.test.ts"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/skills/openspec-apply-change.md

@@ -0,0 +1,146 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+Input: Optionally specify a change name. If omitted, infer it from context when possible. If ambiguous, ask the user to choose from available changes.
+
+Steps
+
+1. Select the change
+
+- If a name is provided, use it.
+- Otherwise infer it from the conversation.
+- If only one active change exists, auto-select it.
+- If still ambiguous, run `openspec list --json` and ask the user to choose.
+- Always announce: `Using change: <name>`.
+
+2. Check status
+
+```bash
+openspec status --change "<name>" --json
+```
+
+Use the JSON to understand:
+
+- `schemaName`
+- which artifact contains tasks
+
+3. Get apply instructions
+
+```bash
+openspec instructions apply --change "<name>" --json
+```
+
+Use the returned data for:
+
+- `contextFiles`
+- task progress
+- remaining tasks
+- dynamic instruction text
+
+Handle states:
+
+- If `state` is `blocked`, explain the blocker and suggest continuing after planning/artifact fixes.
+- If `state` is `all_done`, report completion and suggest archiving.
+- Otherwise proceed to implementation.
+
+4. Read context files
+
+- Read every file listed in `contextFiles`.
+- Do not assume fixed filenames; trust the CLI output.
+
+5. Show progress
+
+Display:
+
+- schema
+- `N/M tasks complete`
+- remaining task overview
+- the current apply instruction
+
+6. Implement tasks
+
+For each pending task:
+
+- announce the task
+- make the minimal focused code changes
+- update the task checkbox in the tasks file from `- [ ]` to `- [x]` immediately after completion
+- continue to the next task
+
+Pause if:
+
+- a task is ambiguous
+- the implementation exposes a design problem
+- an error or blocker is encountered
+- the user interrupts
+
+7. Finish or pause cleanly
+
+When stopping, display:
+
+- tasks completed in this session
+- overall progress
+- whether the change is complete or paused
+- the next action needed
+
+Output during implementation
+
+```text
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation...]
+Task complete
+```
+
+Output on completion
+
+```text
+## Implementation Complete
+
+Change: <change-name>
+Schema: <schema-name>
+Progress: 7/7 tasks complete
+
+Completed This Session
+- [x] Task 1
+- [x] Task 2
+
+All tasks complete. Ready to archive.
+```
+
+Output on pause
+
+```text
+## Implementation Paused
+
+Change: <change-name>
+Schema: <schema-name>
+Progress: 4/7 tasks complete
+
+Issue Encountered
+<description>
+
+Options:
+1. <option 1>
+2. <option 2>
+3. Other approach
+```
+
+Guardrails
+
+- Keep going until done or truly blocked.
+- Always read the context files first.
+- Keep changes minimal and scoped.
+- Do not guess through ambiguous requirements.
+- Update the task checkbox immediately after each completed task.
+- If implementation reveals planning problems, stop and suggest updating artifacts first.

package/skills/openspec-explore.md

@@ -0,0 +1,75 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Enter explore mode.
+
+Important: explore mode is for thinking, not implementing. You may read files, inspect the codebase, and reason about architecture, but you must not implement product code in this mode.
+
+Stance
+
+- Curious, not prescriptive
+- Open multiple lines of thought
+- Use diagrams when helpful
+- Ground the discussion in the real codebase
+- Do not rush to a conclusion
+
+What you might do
+
+- clarify the problem
+- investigate current architecture
+- compare options and tradeoffs
+- surface risks and unknowns
+- suggest what should be captured in OpenSpec artifacts
+
+OpenSpec awareness
+
+At the start, you may inspect:
+
+```bash
+openspec list --json
+```
+
+When a relevant change exists:
+
+- read proposal, design, tasks, or spec files for context
+- reference those artifacts naturally in discussion
+- offer to capture new decisions in the appropriate artifact
+
+Typical capture targets
+
+- scope changes -> `proposal.md`
+- design decisions -> `design.md`
+- new or changed requirements -> `specs/.../spec.md`
+- new work items -> `tasks.md`
+
+Behavior rules
+
+- Do not follow a rigid script.
+- Do not auto-capture decisions unless the user asks.
+- Do not implement code.
+- Do not fake certainty when something is unclear.
+- Use codebase evidence where possible.
+
+Helpful ending style
+
+If the discussion reaches a useful stopping point, you may summarize:
+
+```text
+## What We Figured Out
+
+The problem: ...
+The likely approach: ...
+Open questions: ...
+Next steps:
+- keep exploring
+- capture this in artifacts
+- start a change proposal
+```

package/skills/openspec-propose.md

@@ -0,0 +1,102 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Propose a new change and generate the planning artifacts needed for implementation.
+
+Artifacts created:
+
+- `proposal.md`
+- `design.md`
+- `tasks.md`
+
+When ready to implement, run the apply workflow.
+
+Input
+
+- A change name in kebab-case, or
+- a description of what should be built
+
+Steps
+
+1. Confirm the intended change
+
+- If the request is vague, ask what should be built or fixed.
+- Derive a kebab-case change name when needed.
+- Do not proceed until the intended change is understood.
+
+2. Create the change
+
+```bash
+openspec new change "<name>"
+```
+
+3. Inspect workflow status
+
+```bash
+openspec status --change "<name>" --json
+```
+
+Use it to identify:
+
+- `applyRequires`
+- artifact dependency order
+- artifact readiness
+
+4. Build artifacts in dependency order
+
+For each ready artifact:
+
+```bash
+openspec instructions <artifact-id> --change "<name>" --json
+```
+
+Use the returned data to:
+
+- read completed dependency artifacts
+- follow the provided template
+- follow artifact-specific instruction text
+- write the artifact to the provided output path
+
+After each artifact:
+
+- report brief progress
+- re-run `openspec status --change "<name>" --json`
+- continue until every required apply artifact is complete
+
+5. Handle ambiguity
+
+- If the context is critically unclear, ask the user.
+- Prefer keeping momentum when the answer is reasonably inferable.
+
+6. Show final status
+
+- change name and location
+- artifacts created
+- readiness for implementation
+
+Suggested completion summary
+
+```text
+Created change: <name>
+Artifacts:
+- proposal.md
+- design.md
+- tasks.md
+
+All artifacts created. Ready for implementation.
+```
+
+Guardrails
+
+- Create every artifact required for implementation readiness.
+- Always read dependency artifacts before creating the next one.
+- Do not copy raw instruction metadata blocks into the artifact output.
+- If the change already exists, clarify whether to continue it or create a new one.