SpecClaw — Spec-Driven Development

Overview

SpecClaw brings structured, spec-driven development to OpenClaw agents. It manages the full lifecycle: propose → plan → build → verify → archive.

Directory Structure

When initialized (.specclaw/ exists in project root):

CODEBLOCK0

Commands

The user triggers commands conversationally. Recognize these patterns:

specclaw init

Trigger: "specclaw init", "initialize specclaw", "set up spec-driven development"

1. 1. Create .specclaw/ directory structure
2. Generate config.yaml from template (see templates/config.yaml)
3. Ask user for project name/description
4. Create initial INLINECODE5
5. Add .specclaw/ tracking to git

specclaw propose "<idea>"

Trigger: "specclaw propose", "propose a change", "new feature proposal"

1. 1. Create INLINECODE8
2. Generate proposal.md from template
3. Include: problem statement, proposed solution, scope, impact, open questions
4. Present proposal to user for review
5. Update INLINECODE10
6. GitHub sync (if github.sync is true): Run bash skill/scripts/gh-sync.sh create .specclaw <change> to create a GitHub Issue for the proposal. (gh-sync.sh create requires proposal.md — validation is enforced by validate-change.sh.)

specclaw plan <change>

Trigger: "specclaw plan", "plan the feature", "generate spec for"

1. 1. Validate: Run bash skill/scripts/validate-change.sh .specclaw <change> plan. If it fails, report missing prerequisites and stop.
2. Read the proposal
3. Analyze existing codebase (file structure, patterns, dependencies)
4. Generate:

- spec.md — functional requirements, acceptance criteria, edge cases - design.md — technical approach, architecture, file changes map - tasks.md — ordered implementation tasks with dependencies

1. 5. Present plan summary to user
2. Update status
3. GitHub sync (if enabled): Run bash skill/scripts/gh-sync.sh update .specclaw <change> to add the task checklist to the GitHub Issue.

specclaw build <change>

Trigger: "specclaw build", "implement the feature", "start building"

This is where OpenClaw shines. Follow this execution flow exactly:

Step 0 — Validate

Run bash skill/scripts/validate-change.sh .specclaw <change> build. If it fails, report missing prerequisites and stop.

Step 1 — Setup

Run the setup script to parse config, create a git branch, and get build configuration:

CODEBLOCK1

This returns JSON config including parallel_tasks, models.coding, git.strategy, and notifications.channel. Capture this output — you'll need parallel_tasks and model values throughout the build.

Worktree strategy: When git.strategy is "worktree-per-change", setup creates an isolated worktree at .specclaw/worktrees/<change>/. The worktree_path from the config JSON should be used as the cwd parameter when spawning coding agents via sessions_spawn, ensuring each change's agents work in complete isolation.

Parallel changes: With worktree-per-change strategy, multiple changes can be built simultaneously since each has its own worktree. No branch switching required.

Send a build started notification:

CODEBLOCK2

Step 2 — Parse Tasks

Get all actionable tasks:

CODEBLOCK3

This outputs JSON: INLINECODE34

For retries (re-running build on a change with prior failures):

CODEBLOCK4

Reset failed tasks to pending before re-executing:

CODEBLOCK5

Then re-parse with --status pending and continue from the appropriate wave.

Step 3 — Wave Loop

Execute tasks wave-by-wave. For each wave number (1, 2, 3...):

a. Filter tasks for this wave:

CODEBLOCK6

If no tasks returned for this wave, the build is complete — skip to Step 4.

Skip waves with blocked tasks: If a task's dependency failed in a prior wave, skip it and mark it failed:

CODEBLOCK7

b. For each task in the wave (up to parallel_tasks from config):

1. 1. Mark in-progress:

CODEBLOCK8

1. 2. Build context payload:

   bash skill/scripts/build-context.sh .specclaw <change> <TASK_ID>
   

This outputs a complete context string containing: spec sections, design sections, task details, relevant source file contents, and constraints. Use this output directly as the agent's task.

1. 3. Spawn coding agent:

CODEBLOCK10

c. Yield and wait:

After spawning all tasks in the wave batch, call sessions_yield to wait for agent completions. Results auto-announce back to you.

d. Process completed agents:

For each agent that succeeded:

1. 1. Mark complete:

CODEBLOCK11

If this task previously failed (was [!] before): Run INLINECODE39

1. 2. Git commit the changes:

CODEBLOCK12

1. 3. Send a task complete notification:

CODEBLOCK13

e. Process failed agents:

For each agent that failed:

1. 1. Mark failed:

CODEBLOCK14

1. 2. Log error: Run bash skill/scripts/log-error.sh .specclaw <change> <task_id> <wave> <agent_label> "<failure summary>" — pipe agent error output if available

1. 3. Log the error in status.md with the failure reason

1. 4. Send a task failed notification:

CODEBLOCK15

1. 5. Mark all dependent tasks in later waves as skipped/failed — they cannot proceed
2. GitHub sync (if enabled): Run bash skill/scripts/gh-sync.sh comment .specclaw <change> "❌ Task <task_id> failed: <summary>" to log the error on the issue.

f. GitHub sync (if enabled): Run bash skill/scripts/gh-sync.sh update .specclaw <change> to update task checkboxes.

g. Repeat for the next wave number until no pending tasks remain.

Step 4 — Finalize

Run the finalize script to execute tests and merge the branch:

CODEBLOCK16

This runs the configured test_command (if any) and merges the branch per git.strategy.

Step 5 — Post-Build Review

If automation.post_build_review is true in config, run an automated review before updating the dashboard:

a. Scope deviation check:

Compare files actually changed against files declared in tasks:

CODEBLOCK17

Cross-reference with files listed in each task in tasks.md. Flag any files changed but not declared in any task's Files: field.

b. Review prompt:

Evaluate the build and auto-log findings (~150 words max):

CODEBLOCK18

c. Auto-log scope deviations:

For any files changed outside declared task scope, automatically log as design_gap:

CODEBLOCK19

d. Pattern scan: Run bash skill/scripts/detect-patterns.sh .specclaw scan <change> to check for recurring patterns across changes.

e. If any patterns have recurrence >= 3, alert the user: "⚠️ Pattern PAT-XXX has N occurrences — consider promoting its prevention rule to agent context."

Step 6 — Update Dashboard

Regenerate the project status dashboard:

CODEBLOCK20

Step 7 — Notify

Send the build summary via the message tool to the configured notification channel:

CODEBLOCK21

If any tasks failed, include a remediation section:

CODEBLOCK22

Retry Flow

When specclaw build is called on a change that has failed tasks:

1. 1. Parse failed tasks: INLINECODE54
2. Reset each to pending: INLINECODE55
3. Re-parse pending tasks and determine which waves need re-execution
4. Execute only the waves containing reset tasks (and their dependents)

- Retried tasks automatically get previous error context via build-context.sh

1. 5. Finalize and notify as normal

Key Principles

• - Fresh context always — each agent gets ONLY what it needs via build-context.sh. No stale context from prior tasks. This is critical for quality.
• Parallel within waves — tasks in the same wave with no cross-dependencies spawn simultaneously, up to parallel_tasks limit.
• Sequential across waves — wave N+1 starts only after wave N completes.
• Fail-fast on dependencies — if a task fails, all tasks depending on it are immediately marked failed.

specclaw learn <change> "<insight>"

Trigger: "specclaw learn", "log a learning", "what did we learn", "capture insight"

Capture build learnings — spec gaps, design misses, and patterns discovered during implementation.

Log a learning:
CODEBLOCK23

Categories: spec_gap | design_gap | pattern | best_practice | agent_issue
Priorities: low | medium | INLINECODE67

List learnings for a change:
CODEBLOCK24

Promote a learning (mark for elevation to agent prompts/SKILL.md):
CODEBLOCK25

When to log:

• - After a build reveals a spec gap (requirements were unclear or missing)
• When a design decision needed mid-build adjustment
• When agents discovered a useful pattern worth reusing
• When parallel tasks created conflicts (duplicate code, shared dependencies)
• When an agent struggled with the context or instructions

Learnings are stored in .specclaw/changes/<change>/learnings.md and feed into the pattern detection system for cross-change analysis.

specclaw patterns

Trigger: "specclaw patterns", "check patterns", "recurring issues", "what keeps happening"

Track recurring patterns across changes — errors and learnings that repeat become prevention rules.

Scan a change for patterns:

bash skill/scripts/detect-patterns.sh .specclaw scan <change>

Reads errors.md and learnings.md, matches against existing patterns, creates new or increments existing.

List all patterns:
CODEBLOCK27

Promote a pattern (mark for elevation to agent prompts):
CODEBLOCK28

Auto-promotion: Patterns with 3+ occurrences are flagged ⚠️ — their prevention rules should be added to agent context templates or SKILL.md build instructions.

Pattern registry lives at .specclaw/patterns.md (global, not per-change).

specclaw verify <change>

Trigger: "specclaw verify", "validate implementation", "check against spec"

Validate that the implementation satisfies the spec's acceptance criteria.

Step 0: Validate

Run bash skill/scripts/validate-change.sh .specclaw <change> verify. If it fails (tasks not all complete), report and stop.

Step 1: Collect Evidence

Run bash skill/scripts/verify.sh collect .specclaw <change> to gather:

• - Acceptance criteria from spec.md
• Current content of all changed files
• Test/lint/build command results (if configured)

Step 2: Build Verify Context

Run bash skill/scripts/verify-context.sh .specclaw <change> to construct the verification agent's context payload from the evidence + Verify Agent prompt template.

Step 3: Spawn Verify Agent

Spawn a verification agent:

sessions_spawn(
  task: <verify context payload>,
  model: <config.yaml models.review>,  # default: anthropic/claude-sonnet-4-5
  mode: "run",
  label: "specclaw-verify-<change>"
)

Wait for completion via sessions_yield.

Step 4: Save Report

Save the agent's output as .specclaw/changes/<change>/verify-report.md.

Step 5: Update Status

Run bash skill/scripts/verify.sh update-status .specclaw <change> <verdict> where verdict is PASS, FAIL, or PARTIAL (extracted from the report).

Update status.md and run bash skill/scripts/update-status.sh .specclaw to refresh the dashboard.

Step 6: GitHub Sync (if enabled)

If github.sync is true, post verification summary as a comment:
INLINECODE80

Step 7: Notify

Send verification results via configured notification channel.

Auto-Verify

When automation.auto_verify: true in config.yaml, the build flow automatically triggers verification after a successful build (all tasks complete).

Remediation

If verdict is FAIL or PARTIAL:

1. 1. List the failed acceptance criteria
2. Suggest creating remediation tasks (new tasks targeting the gaps)
3. The user can re-plan just the failed criteria or manually fix and re-verify

specclaw status

Trigger: "specclaw status", "project status", "what's the progress"

For a specific change: INLINECODE83

1. 1. Read all changes in INLINECODE84
2. Compile dashboard showing:

- Active changes with progress % - Pending proposals - Recently archived - Overall project health

1. 3. Update INLINECODE85

specclaw archive <change>

Trigger: "specclaw archive", "mark as done", "archive the change"

1. 1. Validate: Run bash skill/scripts/validate-change.sh .specclaw <change> archive. If it fails, report and stop.
2. Verify change is complete (all tasks done, verification passed)
3. Move to INLINECODE88
4. Update INLINECODE89
5. GitHub sync (if enabled): Run bash skill/scripts/gh-sync.sh close .specclaw <change> to close the issue.
6. Optionally create git tag

specclaw auto

Trigger: "specclaw auto", "autonomous mode", "auto-build"

1. 1. Check STATUS.md for next actionable item
2. If proposal exists without plan → generate plan
3. If plan exists without implementation → build
4. If built without verification → verify
5. Respect config.yaml limits (maxtasksper_run)
6. Notify user of results

Task Format in tasks.md

CODEBLOCK30

Status markers:

• - [ ] — pending
• INLINECODE95 — in progress
• INLINECODE96 — complete
• INLINECODE97 — failed (needs remediation)

Agent Context Preparation

Context construction is handled by the build-context.sh script:

CODEBLOCK31

The script automatically assembles a complete context payload containing:

1. 1. Task header — task ID, title, and estimate
2. Spec context — relevant sections from spec.md (requirements, acceptance criteria)
3. Design context — relevant sections from design.md (architecture, approach)
4. Task details — full task description, file list, and dependencies from INLINECODE101
5. Source files — current contents of files listed in the task's Files: field
6. Constraints — standard rules (follow patterns, write tests, stay in scope)

The output is a single string ready to pass directly as the task parameter to sessions_spawn. Do not manually construct context — always use the script to ensure consistency and freshness.

Configuration Reference

See templates/config.yaml for the full config schema.

Key settings:

• - models.planning — model for proposals, specs, design (default: opus)
• INLINECODE107 — model for implementation (default: codex)
• INLINECODE108 — model for verification (default: sonnet)
• INLINECODE109 — "branch-per-change", "direct", or "worktree-per-change"
• INLINECODE110 — where to send updates
• INLINECODE111 — limit for auto mode

Best Practices

1. 1. Keep proposals focused — one change per proposal, small scope
2. Review specs before building — garbage in, garbage out
3. Wave-based execution — group independent tasks, respect dependencies
4. Fresh context always — never let agents accumulate stale context
5. Verify early — run verification after each wave, not just at the end

GitHub Integration (Optional)

When github.sync: true in config.yaml, SpecClaw creates a GitHub Issue per change and tracks progress as a task checklist. Requires gh CLI (authenticated) or GITHUB_TOKEN environment variable.

Run bash skill/scripts/gh-sync.sh setup to verify auth and create labels.