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. Consumes one vertical slice from the slice validation plan; 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: ao (issue tracking via ao beads exec <cmd> — it resolves the bead tracker, bd or br, and its ledger; plus ratchet gates). Optional — see skills/shared/SKILL.md for fallback table. If no tracker is available, 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 ao beads exec ready.
• Use /implement <description> to implement an ad-hoc task without a tracked issue.

Folded triggers (ag-s43tg wave 1): pr-implement routes here

• pr-implement → OSS contribution mode. Use when you need to implement a scoped OSS PR — fork-based implementation of an open source contribution with mandatory isolation checks. Same single-issue TDD discipline as internal work, plus the fork lane: ensure the fork exists and is current, create an isolated worktree, run an isolation pre-check (BLOCK on mixed concerns) and post-check (BLOCK on scope creep), check for competing PRs before starting, and hand off to /pr-prep for commit/PR shaping. Input is the plan artifact from /pr-prep + /plan (run those first if no plan exists).

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 ao beads exec 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 ao beads exec ready — finds ag-3b7 (first unblocked issue)
2. Claims issue via ao beads exec 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

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

Execution

Read 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. The pre-commit autonomous quality loop lives in references/quality-loop.md. The behavioral spec format lives in references/behavioral-spec.md.

Key Rules

• TDD by default - write failing tests before implementing (skip with --no-tdd). Test-first is the default because the failing test is the slice's contract and its regression guard — but empirically the test-first ordering is not what drives quality (Finster 2026; see the standards skill's agentic-workflow-evidence reference); code-first / test-after (--no-tdd) is a defensible cost-efficient variant on fully-specified small tasks provided the two refactor invariants below hold.
• Refactor after every green — it is the load-bearing move. Refactor under green as its own commit after each behavior, never deferred to one final pass (deferred-refactor workflows were the worst-performing cluster in the study above). Never let a refactor step change a test — a test change during refactor means behavior changed, which is a new slice, not a refactor.
• One behavior per cycle (small batch). Implement one behavior, keep the suite green, refactor, move to the next — small batches beat all-at-once.
• 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, then run crank's Close checkpoint: a closed bead is a sensor reading — if what it taught falsifies an assumption the remaining plan depends on, surface it for re-planning instead of silently proceeding (age-cysr)

Without Beads

If br 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

Reference Documents

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

See also

• test — Test generation, coverage analysis, and TDD workflow