implement

$27

Examples

Implement Specific Issue

User says: /implement ag-5k2

What happens:

• Agent reads issue from beads: "Add JWT token validation middleware"

• Explore agent finds relevant auth code and middleware patterns

• Agent edits middleware/auth.go to add token validation

• Runs go test ./middleware/... — all tests pass

• Commits with message "Add JWT token validation middleware\n\nImplements: ag-5k2"

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

• Agent runs bd ready — finds ag-3b7 (first unblocked issue)

• Claims issue via bd update ag-3b7 --status in_progress

• Implements and verifies

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

• Agent receives failing tests (immutable) and contract

• Reads tests to understand expected behavior

• Implements ONLY enough to make tests pass

• Does NOT modify test files

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

• Skip the claim/close status updates

• Use the description as the task

• Still commit with descriptive message

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