implement

name: implement description: 'Implement one tracked issue. Triggers: "implement", "implement one tracked issue.", "implement skill".' practices:

• tdd
• refactoring
• code-complete hexagonal_role: driving-adapter consumes:
• domain produces:
• git-changes context_rel:
• kind: customer-of with: domain skill_api_version: 1 metadata: tier: execution dependencies:
  • beads-br
  • standards context: window: isolated intent: mode: task sections: exclude:
    • HISTORY intel_scope: topic output_contract: code changes, test results, bead status update, behavioral spec (optional)

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

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

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

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