SpecKit Coding Agent

Version: 1.1.0

Summary

A complete Spec-Driven Development (SDD) workflow that transforms how you build software. Start with an idea → Create specifications → Generate plans → Execute tasks. Powered by spec-kit and OpenCode CLI, this skill ensures every line of code has a traceable requirement behind it.

Key Features

6-Phase Workflow: Constitution → Specification → Plan → Tasks → Implementation → Track
AI-Powered Artifacts: Each phase generates Markdown documents via OpenCode
Living Documentation: TASKS.md updates automatically as you implement
Multi-Agent Ready: Delegation to subagents with full context preservation
Best Practices Built-In: Clean code, TDD, and incremental delivery baked into the workflow

Who It's For

Developers who want specifications before code
Teams needing traceable requirements
AI-assisted projects requiring structured context
Anyone building with OpenCode CLI

Quick Example

# Initialize spec-kit
cd my-project && specify init --here --ai opencode

# Generate all artifacts
echo "/speckit.constitution" | opencode run  # Principles
echo "/speckit.specify" | opencode run       # Requirements
echo "/speckit.plan" | opencode run          # Architecture
echo "/speckit.tasks" | opencode run         # Action items

# Delegate to subagents → then update tracking
echo "/speckit.implement" | opencode run     # Marks completed tasks

This skill integrates spec-kit workflow with OpenCode for spec-driven development. Use this workflow to create specifications, plans, and tasks before coding.

Prerequisites: Install and Initialize Spec-Kit

These steps must be completed before using any speckit commands.

Step 1: Install spec-kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Step 2: Initialize spec-kit in project

cd /root/.openclaw/workspace/my-project
specify init --here --ai opencode

After initializing, /speckit.* commands will be available in your project directory.

Spec-Driven Development Workflow

Execute One Command at a Time - Sequential Execution Required!

Step 1: Create Constitution

echo "/speckit.constitution
Create a project constitution focused on clean code principles, simplicity, and test-driven development.
" | opencode run

✅ Creates: CONSTITUTION.md

Step 2: Create Specification

echo "/speckit.specify
Create a baseline specification for a Python function that calculates factorial numbers recursively.
" | opencode run

✅ Creates: SPECIFICATION.md

Step 3: Create Plan

echo "/speckit.plan" | opencode run

✅ Creates: PLAN.md

Step 4: Generate Tasks

echo "/speckit.tasks" | opencode run

✅ Creates: TASKS.md

Step 5: Execute Implementation and Update Tasks

After subagents complete implementation, update tasks.md with execution status:

Option A: Run /speckit.implement directly

echo "/speckit.implement" | /root/.opencode/bin/opencode run

Result: Updates TASKS.md with executed tasks, marks as complete

Option B: Manual update if implementation done externally

# Manually update TASKS.md to mark completed tasks
# or let /speckit.implement scan and update

Key Benefit: /speckit.implement maintains a living task list with execution history

Complete Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│ 1. /speckit.constitution → CONSTITUTION.md (principles)         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. /speckit.specify → SPECIFICATION.md (requirements)            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. /speckit.plan → PLAN.md (implementation phases)              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. /speckit.tasks → TASKS.md (actionable tasks)                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 5. Subagents read all artifacts and implement                   │
│    - CONSTITUTION.md, SPECIFICATION.md, PLAN.md, TASKS.md       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 6. /speckit.implement → Updates TASKS.md with status            │
│    - Marks [x] completed tasks                                  │
│    - Adds timestamps and metadata                               │
│    - Maintains living task list                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 7. Code implementation complete with tracked progress           │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites (MUST COMPLETE FIRST!)

Install spec-kit:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Initialize spec-kit in your project:

cd ~/project
specify init --here --ai opencode

Execute workflow SEQUENTIALLY:

Create Constitution

echo "/speckit.constitution
Create a project constitution focused on clean code principles.
" | opencode run

Create Specification

echo "/speckit.specify
Create a REST API for user management.
" | opencode run

Create Plan

echo "/speckit.plan" | opencode run

Generate Tasks

echo "/speckit.tasks" | opencode run

Delegate to Subagents:
- Read all artifacts (CONSTITUTION.md, SPECIFICATION.md, PLAN.md, TASKS.md)
- Implement tasks from TASKS.md
Update Tasks with Execution Status:
```
echo "/speckit.implement" | /root/.opencode/bin/opencode run
```
This updates TASKS.md to track what has been implemented.

Complete Workflow Examples

Example: Complete Spec-Driven Development Session

# Prerequisites (MUST DO FIRST!)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

cd ~/my-new-project
specify init --here --ai opencode

# Step 1: Create Constitution
echo "/speckit.constitution
Create a project constitution focused on clean code principles.
" | opencode run

# Step 2: Create Specification
echo "/speckit.specify
Create a REST API for user management.
" | opencode run

# Step 3: Generate Plan
echo "/speckit.plan" | opencode run

# Step 4: Generate Tasks
echo "/speckit.tasks" | opencode run

# Step 5: Delegate to subagent (read all artifacts first)

# Step 6: Update tasks.md with execution status
echo "/speckit.implement" | /root/.opencode/bin/opencode run
# This updates TASKS.md marking completed tasks

Example: Adding a New Feature

# Step 1: Create specification for new feature
echo "/speckit.specify
Add authentication endpoints with JWT support.
" | opencode run

# Step 2: Generate plan
echo "/speckit.plan" | opencode run

# Step 3: Generate tasks
echo "/speckit.tasks" | opencode run

# Step 4: Delegate to subagent (read all artifacts first)

# Step 5: Update tasks.md with execution status
echo "/speckit.implement" | /root/.opencode/bin/opencode run
# This updates TASKS.md marking completed tasks

Anti-Patterns to Avoid

❌ DO NOT try to use speckit commands before initialization:

cd /root/.openclaw/workspace/new-project
echo "/speckit.constitution" | opencode run  # Won't work!

✅ Do this instead:

cd /root/.openclaw/workspace/new-project
specify init --here --ai opencode  # DO THIS FIRST
echo "/speckit.constitution" | opencode run  # NOW it works

❌ DO NOT pipe multiple commands:

{ echo "/speckit.constitution"; echo "/speckit.specify"; } | opencode run

❌ DO NOT skip /speckit.implement after implementation:

# Wrong: TASKS.md stays with checkboxes empty
# Right: 
echo "/speckit.implement" | opencode run  # Updates TASKS.md

Why: Without updating TASKS.md, you lose track of what was actually implemented vs what was planned.

❌ DO NOT execute without reading spec context:

# Wrong: Subagent doesn't have spec context
sessions_spawn task="Implement authentication"
# Right: Subagent reads all artifacts
sessions_spawn task="Read CONSTITUTION.md, SPECIFICATION.md, PLAN.md, TASKS.md first."

Why Use /speckit.implement?

Benefits:

Automatic tracking: TASKS.md gets updated with execution status
Progress visibility: Clear view of what's done vs pending
Audit trail: History of implementation steps
Future reference: See completed work for maintenance

Best Practice:

Run /speckit.implement AFTER subagents complete work
Or run it periodically to update progress
The file becomes a living document of project state

/speckit.implement - Execution Tracking

Purpose: Updates TASKS.md with execution status, marking completed tasks and tracking implementation progress.

How It Works

When you run /speckit.implement, the system:

Scans the project directory for executed work
Reads the current TASKS.md
Marks tasks as [x] complete based on actual implementation
Updates the file with execution metadata

Usage

echo "/speckit.implement" | /root/.opencode/bin/opencode run

Example: Updated TASKS.md

After running /speckit.implement, TASKS.md transforms from:

Before:

## Tasks

- [ ] Create HTML structure
- [ ] Implement CSS styling
- [ ] Add JavaScript functionality

After:

## Tasks

- [x] Create HTML structure (completed 2026-02-11 19:42 UTC)
- [ ] Implement CSS styling (in progress)
- [ ] Add JavaScript functionality (pending)

When to Run

| Timing | Action | |--------|--------| | After subagent completes | Run /speckit.implement to track progress | | Before review | Check which tasks are done vs pending | | After each feature | Update task status | | End of session | Final update for audit trail |

Manual Update Alternative

If implementation was done externally:

# Edit TASKS.md manually to mark completed tasks:
- [x] Task completed
- [ ] Task pending

Or use the subagent to scan and update automatically.

Benefits of Consistent Usage

Living Documentation: TASKS.md becomes a real-time project status
Progress Visibility: Instantly see what's done, in-progress, pending
Accountability: Timestamps track when each task was completed
Context Preservation: Future team members see implementation history
Regression Prevention: Know exactly what was changed and when

Best Practices

Run /speckit.implement after EVERY subagent task
Include in your daily workflow alongside spec commands
Keep TASKS.md updated even for small changes
Use timestamps for audit trail
Reference updated TASKS.md when asking for help or reviews

Fallback Strategy

When using OpenCode for coding tasks, the system follows this fallback strategy:

| Priority | Model | Provider | Role | |----------|-------|----------|------| | Primary | opencode/kimi-k2.5-free | OpenCode | Main model for coding tasks | | Fallback 1 | opencode/minimax-m2.1-free | OpenCode | High-quality alternative | | Fallback 2 | opencode/glm-4.7-free | OpenCode | Efficient standard tasks | | Secundário | openrouter/xiaomi/mimo-v2-flash | OpenRouter | Cross-provider backup |

Model Order for Opencode Task Execution

{
  "primary": "opencode/kimi-k2.5-free",
  "fallbacks": [
    "opencode/minimax-m2.1-free",
    "opencode/glm-4.7-free"
  ]
}

Cross-Provider Backup: When OpenCode models are rate-limited or unavailable, the system falls back to openrouter/xiaomi/mimo-v2-flash (OpenRouter) for cross-provider resilience.

The primary model (kimi-k2.5-free) is used first, and if unavailable, the system automatically falls back through the other models in order.

Why This Order?

Primary (Kimi K.25): Best overall capability for coding and complex reasoning tasks
Fallback 1 (MiniMax M2.1): Similar capability level, excellent for complex reasoning
Fallback 2 (GLM 4.7): Efficient model for standard tasks when higher models hit limits
Secundário (Xiaomi Mimo v2 Flash): Different provider (OpenRouter) ensures continuity when OpenCode models are rate-limited

OpenCode

Default Model: opencode/kimi-k2.5-free

OpenCode is the preferred coding agent for this workspace. It uses kimi-k2.5-free as the primary model with automatic fallbacks to other free models.

# Basic usage (uses default kimi-k2.5-free model)
bash workdir:~/project background:true command:"opencode run \"Your task\""

# Explicit model specification (optional, defaults to kimi-k2.5-free)
bash workdir:~/project background:true command:"opencode run --model opencode/kimi-k2.5-free \"Your task\""

# If primary is unavailable, it automatically falls back:
# minimax-m2.1-free → glm-4.7-free → (openrouter/xiaomi/mimo-v2-flash as cross-provider backup)

The Pattern: workdir + background

# Create temp space for chats/scratch work
SCRATCH=$(mktemp -d)

# Start agent in target directory ("little box" - only sees relevant files)
bash workdir:$SCRATCH background:true command:"<agent command>"
# Or for project work:
bash workdir:~/project/folder background:true command:"<agent command>"
# Returns sessionId for tracking

# Monitor progress
process action:log sessionId:XXX

# Check if done  
process action:poll sessionId:XXX

# Send input (if agent asks a question)
process action:write sessionId:XXX data:"y"

# Kill if needed
process action:kill sessionId:XXX

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files.

Codex CLI

Model: gpt-5.2-codex is the default (set in ~/.codex/config.toml)

Building/Creating (use --full-auto or --yolo)

# --full-auto: sandboxed but auto-approves in workspace
bash workdir:~/project background:true command:"codex exec --full-auto \"Build a snake game with dark theme\""

# --yolo: NO sandbox, NO approvals (fastest, most dangerous)
bash workdir:~/project background:true command:"codex --yolo \"Build a snake game with dark theme\""

Reviewing PRs (vanilla, no flags)

Avoid reviewing PRs in the live clawdbot project folder. Use the project where the PR is submitted (if it's NOT ~/Projects/clawdbot), or clone to a temp folder first.

# Option 1: Review in the actual project (if NOT clawdbot)
bash workdir:~/Projects/some-other-repo background:true command:"codex review --base main"

# Option 2: Clone to temp folder for safe review (REQUIRED for clawdbot PRs!)
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/clawdbot/clawdbot.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
bash workdir:$REVIEW_DIR background:true command:"codex review --base origin/main"

Why? Checking out branches in the running Clawdbot repo can break the live instance!

Claude Code

bash workdir:~/project background:true command:"claude \"Your task\""

Pi Coding Agent

# Install: npm install -g @mariozechner/pi-coding-agent
bash workdir:~/project background:true command:"pi \"Your task\""

Pi flags (common)

--print / -p: non-interactive; runs prompt and exits.
--provider <name>: pick provider (default: google).
--model <id>: pick model (default: gemini-2.5-flash).

Examples:

# Set provider + model, non-interactive
bash workdir:~/project background:true command:"pi --provider openai --model gpt-4o-mini -p \"Summarize src/\""

tmux (interactive sessions)

Use the tmux skill for interactive coding sessions (always, except very simple one-shot prompts). Prefer bash background mode for non-interactive runs.

Parallel Issue Fixing with git worktrees + tmux

For fixing multiple issues in parallel, use git worktrees (isolated branches) + tmux sessions:

# 1. Clone repo to temp location
cd /tmp && git clone git@github.com:user/repo.git repo-worktrees
cd repo-worktrees

# 2. Create worktrees for each issue (isolated branches!)
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 3. Set up tmux sessions
SOCKET="${TMPDIR:-/tmp}/codex-fixes.sock"
tmux -S "$SOCKET" new-session -d -s fix-78
tmux -S "$SOCKET" new-session -d -s fix-99

# 4. Launch Codex in each (after pnpm install!)
tmux -S "$SOCKET" send-keys -t fix-78 "cd /tmp/issue-78 && pnpm install && codex --yolo 'Fix issue #78.'" Enter
tmux -S "$SOCKET" send-keys -t fix-99 "cd /tmp/issue-99 && pnpm install && codex --yolo 'Fix issue #99.'" Enter

# 5. Monitor progress
tmux -S "$SOCKET" capture-pane -p -t fix-78 -S -30

# 6. Cleanup
tmux -S "$SOCKET" kill-server
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

Why worktrees? Each Codex works in isolated branch, no conflicts. Can run 5+ parallel fixes!

Guidelines

Respect tool choice — if user asks for Codex, use Codex. Do not offer to build it yourself.
Be patient — don't kill sessions because they're "slow"
Monitor with process:log — check progress without interfering
--full-auto for building — auto-approves changes
Parallel is OK — run many Codex processes at once for batch work
Avoid starting Codex in ~/clawd/ — it may read sensitive docs. Use target project dir or /tmp for blank slate chats
Avoid checking out branches in ~/Projects/clawdbot/ — that directory contains the LIVE instance. Clone to /tmp or use git worktree for PR reviews

References

Spec-Kit GitHub Repository: https://github.com/github/spec-kit
OpenCode CLI Documentation: https://opencode.ai/docs

Related Skills

opencode-controller: For controlling OpenCode via slash commands
freeride-opencode: For configuring free models from OpenCode Zen