implement

Implement Skill

Quick Ref: Execute single issue end-to-end. Output: code changes + commit + closed issue.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Loop position

Move 4 (TDD per slice) of the [operating loop](../../docs/architecture/operating-loop.md). Consumes one vertical slice from the [slice validation plan](../../docs/templates/slice-validation.md); produces failing test → passing implementation → refactor-under-green. Discipline: (1) first failing test must fail for the right reason (missing behavior, not syntax); (2) smallest change to flip green; (3) refactor as its own commit. Slices that mix refactor + feature are two slices, not one. Code without a failing test has no contract; the slice is not done.

Execute a single issue from start to finish.

CLI dependencies: bd (issue tracking), ao (ratchet gates). Both optional — see skills/shared/SKILL.md for fallback table. If bd is unavailable, use the issue description directly and track progress via TaskList instead of beads.

When to use

• Use /implement <issue-id> to implement a specific tracked issue.
• Use /implement (no argument) to pick up next ready work via bd ready.
• Use /implement <description> to implement an ad-hoc task without a tracked issue.

Examples

Implement Specific Issue

User says: /implement ag-5k2

What happens:

1. Agent reads issue from beads: "Add JWT token validation middleware"
2. Explore agent finds relevant auth code and middleware patterns
3. Agent edits middleware/auth.go to add token validation
4. Runs go test ./middleware/... — all tests pass
5. Commits with message "Add JWT token validation middleware\n\nImplements: ag-5k2"
6. Closes issue via bd close ag-5k2 --reason "commit:<sha> files:[middleware/auth.go]"

Result: Issue implemented, verified, committed, and closed. Ratchet recorded.

Pick Up Next Available Work

User says: /implement

What happens:

1. Agent runs bd ready — finds ag-3b7 (first unblocked issue)
2. Claims issue via bd update ag-3b7 --status in_progress
3. Implements and verifies
4. Closes issue

Result: Autonomous work pickup and completion from ready queue.

GREEN Mode (Test-First)

User says: /implement ag-8h3 (invoked by /crank --test-first)

What happens:

1. Agent receives failing tests (immutable) and contract
2. Reads tests to understand expected behavior
3. Implements ONLY enough to make tests pass
4. Does NOT modify test files
5. Verification: all tests pass with fresh output

Result: Minimal implementation driven by tests, no over-engineering.

Lifecycle Integration Flags

| Flag | Default | Description | |------|---------|-------------| | --no-lifecycle | off | Skip ALL lifecycle skill auto-invocations (test gen, review, refactor) | | --lifecycle=<tier> | matches complexity | Controls which lifecycle skills fire: minimal (test only), standard (+review), full (+refactor dry-run) |

Lifecycle tier defaults to matching the current complexity level. Explicit --lifecycle=<tier> overrides.

Execution

Read [references/workflow.md](references/workflow.md) when you need the full step-by-step procedure (Steps 0 through 8, including pre-flight gates, TDD discipline, build/security verification, the binary-deployment gate, the verification iron law, commit, close, and ratchet record).

GREEN mode rules live in [references/green-mode.md](references/green-mode.md). The pre-commit autonomous quality loop lives in [references/quality-loop.md](references/quality-loop.md). The behavioral spec format lives in [references/behavioral-spec.md](references/behavioral-spec.md).

Key Rules

• TDD by default - write failing tests before implementing (skip with --no-tdd)
• Lifecycle skills fire automatically - /test, /review, /refactor run at appropriate steps (disable with --no-lifecycle)
• Explore first - understand before changing
• Edit, don't rewrite - prefer Edit tool over Write tool
• Follow patterns - match existing code style
• Verify changes - run tests or sanity checks
• Commit with context - reference the issue ID
• Close the issue - update status when done

Without Beads

If bd CLI not available:

1. Skip the claim/close status updates
2. Use the description as the task
3. Still commit with descriptive message
4. Report completion to user

Output Specification

Per the output_contract in frontmatter: code changes, test results, bead status update, and behavioral spec (optional).

Completion Markers

<promise>DONE</promise>

If blocked or incomplete:

<promise>BLOCKED</promise>
Reason: <why blocked>

<promise>PARTIAL</promise>
Remaining: <what's left>

Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | Issue not found | Issue ID doesn't exist or local state looks stale | Run bd show <id> to verify; use bd vc status only if you need Dolt state | | GREEN mode violation | Edited a file not related to the issue scope | Revert unrelated changes. GREEN mode restricts edits to files relevant to the issue | | Verification gate fails | Tests fail or build breaks after implementation | Read the verification output, fix the specific failures, re-run verification | | "BLOCKED" status | Contract contradicts tests or is incomplete in GREEN mode | Write BLOCKED with specific reason, do NOT modify tests | | Fresh verification missing | Agent claims success without running verification command | MUST run verification command fresh with full output before claiming completion | | Ratchet record failed | ao CLI unavailable or chain.jsonl corrupted | Implementation still closes via bd, but ratchet chain needs manual repair |

Reference Documents

• [references/behavioral-spec.md](references/behavioral-spec.md) — Behavioral spec format for Stage 4 validation
• [references/binary-deployment-gate.md](references/binary-deployment-gate.md) — CLI/hook binary-deployment gate spec
• [references/gate-checks.md](references/gate-checks.md) — Ratchet and pre-mortem gate checks
• [references/green-mode.md](references/green-mode.md) — GREEN mode test-first implementation rules
• [references/implement.feature](references/implement.feature) — Executable spec: the /implement done-state (first-failing-test → green → refactor → verified close) (soc-qk4b.2)
• [references/quality-loop.md](references/quality-loop.md) — Pre-commit autonomous quality loop
• [references/resume-protocol.md](references/resume-protocol.md) — Resume protocol for interrupted sessions
• [references/workflow.md](references/workflow.md) — Full execution workflow (Steps 0 through 8)

See also

• [test](../test/SKILL.md) — Test generation, coverage analysis, and TDD workflow