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

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

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