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.

Execute a single issue from start to finish.

Codex Lifecycle Guard

When this skill runs in Codex hookless mode (CODEX_THREAD_ID is set or CODEX_INTERNAL_ORIGINATOR_OVERRIDE is Codex Desktop), ensure startup context before claiming or implementing the issue:

ao codex ensure-start 2>/dev/null || true

ao codex ensure-start is the single startup guard for Codex skills. It records startup once per thread and skips duplicate startup automatically. Leave ao codex ensure-stop to dedicated closeout skills such as $validation, $post-mortem, or $handoff.

Execution Steps

Given $implement <issue-id-or-description>:

Step 0: Pre-Flight Checks (Resume + Gates)

For resume protocol details, read references/resume-protocol.md.

For ratchet gate checks and pre-mortem gate details, read references/gate-checks.md.

Step 0.5: Pull Relevant Knowledge

# Pull knowledge scoped to this issue (if ao available)
ao lookup --bead <issue-id> --limit 3 2>/dev/null || true

Apply retrieved knowledge (mandatory when results returned):

If learnings or patterns are returned, do NOT just load them as passive context. For each returned item:

1. Check: does this learning apply to the current issue? (answer yes/no)
2. If yes: treat it as an implementation constraint — does it warn about an approach? suggest a pattern? flag a known pitfall?
3. Reference applicable learnings in your implementation decisions (e.g., "per learning X, avoiding approach Y")
4. Cite applicable learnings by filename in commit messages or PR descriptions

After reviewing, record each citation with the correct type:

# Only use "applied" when the learning actually influenced your output.
# Use "retrieved" for items that were loaded but not referenced in your work.
ao metrics cite "<learning-path>" --type applied 2>/dev/null || true   # influenced a decision
ao metrics cite "<learning-path>" --type retrieved 2>/dev/null || true # loaded but not used

Section evidence: When lookup results include section_heading, matched_snippet, or match_confidence fields, prefer the matched section over the whole file — it pinpoints the relevant portion. Higher match_confidence (>0.7) means the section is a strong match; lower values (<0.4) are weaker signals. Use the matched_snippet as the primary context rather than reading the full file.

Skip silently if ao is unavailable or returns no results.

Step 1: Get Issue Details

If beads issue ID provided (e.g., gt-123):

bd show <issue-id> 2>/dev/null

If plain description provided: Use that as the task description.

If no argument: Check for ready work:

bd ready 2>/dev/null | head -3

Step 2: Claim the Issue

bd update <issue-id> --status in_progress 2>/dev/null

Step 2a: Build Context Briefing

if command -v ao &>/dev/null; then
    ao context assemble --task='<issue title and description>'
fi

This produces a 5-section briefing (GOALS, HISTORY, INTEL, TASK, PROTOCOL) at .agents/rpi/briefing-current.md with secrets redacted. Read it before gathering additional context.

Step 2b: Apply Behavioral Discipline

Before exploring or editing, load the behavioral discipline standard from $standards and write a short execution frame for yourself:

• Assumptions: what is known, what is ambiguous, and which unknowns would change the solution
• Smallest change: the minimum patch that could satisfy the request
• Blast radius: which files or surfaces are in scope, plus what is explicitly out of scope
• Verification: the tests, commands, or gates that will prove the work is done

Rules:

• If ambiguity would materially change the implementation, ask before editing instead of silently choosing.
• If a simpler approach exists than the heavier path implied by the prompt, say so and prefer it.
• If you notice unrelated cleanup, create a bead or note it separately; do not fold it into the patch.
• Every changed line should trace back to the request or to cleanup that your change made necessary.

Step 3: Gather Context

Spawn an exploration agent (via spawn_agent or codex exec) to gather context:

prompt: |
    Find code relevant to: <issue description>

    1. Search for related files (Glob)
    2. Search for relevant keywords (Grep)
    3. Read key files to understand current implementation
    4. Identify where changes need to be made

    Return:
    - Files to modify (paths)
    - Current implementation summary
    - Suggested approach
    - Any risks or concerns

Step 3.5: Grep for Existing Utilities

Before implementing any new function or utility, grep the codebase for existing implementations:

# Search for the function name pattern you're about to create
grep -rn "<function-name-pattern>" --include="*.go" --include="*.py" --include="*.ts" .

Why: In context-orchestration-leverage, a worker created a duplicate estimateTokens function that already existed in context.go. A 5-second grep would have prevented the duplication and the rework needed to consolidate it.

If you find an existing implementation, reuse it. If it needs modification, modify it in place rather than creating a parallel version.

Step 3.6: Write Failing Tests First (TDD-First Default)

Before implementing, write tests that define the expected behavior:

1. Write tests covering: happy path, one error path, one edge case
2. Run tests to confirm they FAIL (RED confirmation)
3. If tests pass → feature already exists or tests are wrong. Investigate before proceeding.
4. Proceed to Step 4 with failing tests as the implementation target

# Run tests - ALL new tests must FAIL
# Python: pytest tests/test_<feature>.py -v
# Go: go test ./path/to/... -run TestNew
# Node: npm test -- --grep "new feature"

Test level selection: Classify each test by pyramid level (see the test pyramid standard (test-pyramid.md in the standards skill)):

• L0 (Contract): Write if the issue touches spec boundaries, file existence, or registration
• L1 (Unit): Write always for feature/bug issues — happy path, one error path, one edge case
• L2 (Integration): Write if the change crosses module boundaries or involves multiple components
• L3 (Component): Write if the change affects a full subsystem workflow (with mocked external deps)

If the issue includes test_levels metadata from $plan, use those levels. Otherwise, default to L1 + any applicable higher levels from the decision tree above. When delegating to $test, carry those selected levels and any BF expectations into the request context. --quick is not permission to collapse to L1-only coverage.

Bug-Finding Level Selection (alongside L0–L3):

If the implementation touches external boundaries (APIs, databases, file I/O):

• Add BF4 chaos test: mock the boundary to fail, verify graceful error handling
• This catches the bugs that L1 unit tests mock away

If the implementation includes data transformations (parse, render, serialize):

• Add BF1 property test: randomize inputs with hypothesis/gopter/fast-check
• This catches edge cases no human would write

If the implementation generates output files (configs, reports, manifests):

• Add BF2 golden test: generate canonical output, save as golden file, assert match

Reference: the test pyramid standard in $standards for full tooling matrix.

Or use $test <feature> to auto-generate test candidates, then hand-refine.

Skip conditions (any of these bypasses Step 3.5):

• GREEN mode is active (invoked by $crank --test-first — tests already exist)
• Issue type is chore, docs, or ci
• --no-tdd flag is set
• No test framework detected in the project

Note: Tests written here are MU