Speckit Coding Agent

Integrates spec-kit workflow with OpenCode to sequentially generate project constitution, specification, plan, and tasks for spec-driven development.

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

bash

# 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

bash

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

Step 2: Initialize spec-kit in project

bash

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

bash

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

bash

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

bash

echo "/speckit.plan" | opencode run

✅ Creates: PLAN.md

Step 4: Generate Tasks

bash

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

bash

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

bash

# 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

text

┌─────────────────────────────────────────────────────────────────┐
│ 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!)

1. Install spec-kit:

   bash

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

2. Initialize spec-kit in your project:

   bash

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

3. Execute workflow SEQUENTIALLY:

   Create Constitution

   bash

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

   Create Specification

   bash

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

   Create Plan

   bash

   echo "/speckit.plan" | opencode run
   

   Generate Tasks

   bash

   echo "/speckit.tasks" | opencode run
   

4. Delegate to Subagents:

   • Read all artifacts (CONSTITUTION.md, SPECIFICATION.md, PLAN.md, TASKS.md)
   • Implement tasks from TASKS.md

5. Update Tasks with Execution Status:

   bash

   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

bash

# 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

bash

# 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:

bash

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

✅ Do this instead:

bash

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:

bash

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

❌ DO NOT skip /speckit.implement after implementation:

bash

# 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:

bash

# 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:

1. Automatic tracking: TASKS.md gets updated with execution status
2. Progress visibility: Clear view of what's done vs pending
3. Audit trail: History of implementation steps
4. 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:

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

Usage

bash

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

Example: Updated TASKS.md

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

Before:

markdown

## Tasks

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

After:

markdown

## 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:

bash

# 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

1. Living Documentation: TASKS.md becomes a real-time project status
2. Progress Visibility: Instantly see what's done, in-progress, pending
3. Accountability: Timestamps track when each task was completed
4. Context Preservation: Future team members see implementation history
5. 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

json

{
  "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.

bash

# 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

bash

# 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)

bash

# --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.

bash

# 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

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

---

Pi Coding Agent

bash

# 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:

bash

# 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:

bash

# 1. Clone repo to temp location
cd /tmp && git clone [e-mail]: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

1. Respect tool choice — if user asks for Codex, use Codex. Do not offer to build it yourself.
2. Be patient — don't kill sessions because they're "slow"
3. Monitor with process:log — check progress without interfering
4. --full-auto for building — auto-approves changes
5. Parallel is OK — run many Codex processes at once for batch work
6. Avoid starting Codex in ~/clawd/ — it may read sensitive docs. Use target project dir or /tmp for blank slate chats
7. 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