Speckit Coding Agent

SKILL.md

# 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

```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

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

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