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 ( is set or is ), ensure startup context before claiming or implementing the issue: is the single startup guard for Codex skills. It records startup once per thread and skips duplicate startup automatically. Leave to dedicated closeout skills such as , , or . Execution Steps Given : Step 0: Pre-Flight Checks (Resume + Gates…

\"\ncheck \"SKILL.md has name: implement\" \"grep -q '^name: implement' '$SKILL_DIR/SKILL.md'\"\ncheck \"references/ directory exists\" \"[ -d '$SKILL_DIR/references' ]\"\ncheck \"references/ has at least 2 files\" \"[ \\$(ls '$SKILL_DIR/references/' | wc -l) -ge 2 ]\"\ncheck \"SKILL.md mentions bd for issue tracking\" \"grep -q 'bd ' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions beads\" \"grep -qi 'beads' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions \\$validation for closeout\" \"grep -q '[$]validation' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions Explore agent\" \"grep -qi 'explore' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions verification gate\" \"grep -qi 'verification\\|verify' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions ratchet record\" \"grep -q 'ratchet record' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions GREEN mode\" \"grep -q 'GREEN' '$SKILL_DIR/SKILL.md'\"\ncheck \"SKILL.md mentions DONE/BLOCKED/PARTIAL markers\" \"grep -q 'DONE\\|BLOCKED\\|PARTIAL' '$SKILL_DIR/SKILL.md'\"\n\necho \"\"; echo \"Results: $PASS passed, $FAIL failed\"\n[ $FAIL -eq 0 ] && exit 0 || exit 1\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":1422,"content_sha256":"c6a9e46326770cb78b021982b1b96d1f61f36477e87ecfba554cc2c7c0cac784"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Implement Skill","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Quick Ref:","type":"text","marks":[{"type":"strong"}]},{"text":" Execute single issue end-to-end. Output: code changes + commit + closed issue.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Execute a single issue from start to finish.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Codex Lifecycle Guard","type":"text"}]},{"type":"paragraph","content":[{"text":"When this skill runs in Codex hookless mode (","type":"text"},{"text":"CODEX_THREAD_ID","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set or ","type":"text"},{"text":"CODEX_INTERNAL_ORIGINATOR_OVERRIDE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"Codex Desktop","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ensure startup context before claiming or implementing the issue:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"ao codex ensure-start 2>/dev/null || true","type":"text"}]},{"type":"paragraph","content":[{"text":"ao codex ensure-start","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the single startup guard for Codex skills. It records startup once per thread and skips duplicate startup automatically. Leave ","type":"text"},{"text":"ao codex ensure-stop","type":"text","marks":[{"type":"code_inline"}]},{"text":" to dedicated closeout skills such as ","type":"text"},{"text":"$validation","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"$post-mortem","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"$handoff","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Execution Steps","type":"text"}]},{"type":"paragraph","content":[{"text":"Given ","type":"text"},{"text":"$implement \u003cissue-id-or-description>","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0: Pre-Flight Checks (Resume + Gates)","type":"text"}]},{"type":"paragraph","content":[{"text":"For resume protocol details, read ","type":"text","marks":[{"type":"strong"}]},{"text":"references/resume-protocol.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"For ratchet gate checks and pre-mortem gate details, read ","type":"text","marks":[{"type":"strong"}]},{"text":"references/gate-checks.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 0.5: Pull Relevant Knowledge","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Pull knowledge scoped to this issue (if ao available)\nao lookup --bead \u003cissue-id> --limit 3 2>/dev/null || true","type":"text"}]},{"type":"paragraph","content":[{"text":"Apply retrieved knowledge (mandatory when results returned):","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"If learnings or patterns are returned, do NOT just load them as passive context. For each returned item:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check: does this learning apply to the current issue? (answer yes/no)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If yes: treat it as an implementation constraint — does it warn about an approach? suggest a pattern? flag a known pitfall?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reference applicable learnings in your implementation decisions (e.g., \"per learning X, avoiding approach Y\")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cite applicable learnings by filename in commit messages or PR descriptions","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"After reviewing, record each citation with the correct type:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Only use \"applied\" when the learning actually influenced your output.\n# Use \"retrieved\" for items that were loaded but not referenced in your work.\nao metrics cite \"\u003clearning-path>\" --type applied 2>/dev/null || true # influenced a decision\nao metrics cite \"\u003clearning-path>\" --type retrieved 2>/dev/null || true # loaded but not used","type":"text"}]},{"type":"paragraph","content":[{"text":"Section evidence:","type":"text","marks":[{"type":"strong"}]},{"text":" When lookup results include ","type":"text"},{"text":"section_heading","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"matched_snippet","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"match_confidence","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields, prefer the matched section over the whole file — it pinpoints the relevant portion. Higher ","type":"text"},{"text":"match_confidence","type":"text","marks":[{"type":"code_inline"}]},{"text":" (>0.7) means the section is a strong match; lower values (\u003c0.4) are weaker signals. Use the ","type":"text"},{"text":"matched_snippet","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the primary context rather than reading the full file.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip silently if ao is unavailable or returns no results.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Get Issue Details","type":"text"}]},{"type":"paragraph","content":[{"text":"If beads issue ID provided","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g., ","type":"text"},{"text":"gt-123","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bd show \u003cissue-id> 2>/dev/null","type":"text"}]},{"type":"paragraph","content":[{"text":"If plain description provided:","type":"text","marks":[{"type":"strong"}]},{"text":" Use that as the task description.","type":"text"}]},{"type":"paragraph","content":[{"text":"If no argument:","type":"text","marks":[{"type":"strong"}]},{"text":" Check for ready work:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bd ready 2>/dev/null | head -3","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Claim the Issue","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bd update \u003cissue-id> --status in_progress 2>/dev/null","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2a: Build Context Briefing","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"if command -v ao &>/dev/null; then\n ao context assemble --task='\u003cissue title and description>'\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"This produces a 5-section briefing (GOALS, HISTORY, INTEL, TASK, PROTOCOL) at ","type":"text"},{"text":".agents/rpi/briefing-current.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" with secrets redacted. Read it before gathering additional context.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2b: Apply Behavioral Discipline","type":"text"}]},{"type":"paragraph","content":[{"text":"Before exploring or editing, load the behavioral discipline standard from ","type":"text"},{"text":"$standards","type":"text","marks":[{"type":"code_inline"}]},{"text":" and write a short execution frame for yourself:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assumptions:","type":"text","marks":[{"type":"code_inline"}]},{"text":" what is known, what is ambiguous, and which unknowns would change the solution","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Smallest change:","type":"text","marks":[{"type":"code_inline"}]},{"text":" the minimum patch that could satisfy the request","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Blast radius:","type":"text","marks":[{"type":"code_inline"}]},{"text":" which files or surfaces are in scope, plus what is explicitly out of scope","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification:","type":"text","marks":[{"type":"code_inline"}]},{"text":" the tests, commands, or gates that will prove the work is done","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Rules:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ambiguity would materially change the implementation, ask before editing instead of silently choosing.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a simpler approach exists than the heavier path implied by the prompt, say so and prefer it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If you notice unrelated cleanup, create a bead or note it separately; do not fold it into the patch.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every changed line should trace back to the request or to cleanup that your change made necessary.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Gather Context","type":"text"}]},{"type":"paragraph","content":[{"text":"Spawn an exploration agent (via ","type":"text"},{"text":"spawn_agent","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"codex exec","type":"text","marks":[{"type":"code_inline"}]},{"text":") to gather context:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"prompt: |\n Find code relevant to: \u003cissue description>\n\n 1. Search for related files (Glob)\n 2. Search for relevant keywords (Grep)\n 3. Read key files to understand current implementation\n 4. Identify where changes need to be made\n\n Return:\n - Files to modify (paths)\n - Current implementation summary\n - Suggested approach\n - Any risks or concerns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3.5: Grep for Existing Utilities","type":"text"}]},{"type":"paragraph","content":[{"text":"Before implementing any new function or utility, grep the codebase for existing implementations:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Search for the function name pattern you're about to create\ngrep -rn \"\u003cfunction-name-pattern>\" --include=\"*.go\" --include=\"*.py\" --include=\"*.ts\" .","type":"text"}]},{"type":"paragraph","content":[{"text":"Why:","type":"text","marks":[{"type":"strong"}]},{"text":" In context-orchestration-leverage, a worker created a duplicate ","type":"text"},{"text":"estimateTokens","type":"text","marks":[{"type":"code_inline"}]},{"text":" function that already existed in ","type":"text"},{"text":"context.go","type":"text","marks":[{"type":"code_inline"}]},{"text":". A 5-second grep would have prevented the duplication and the rework needed to consolidate it.","type":"text"}]},{"type":"paragraph","content":[{"text":"If you find an existing implementation, reuse it. If it needs modification, modify it in place rather than creating a parallel version.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3.6: Write Failing Tests First (TDD-First Default)","type":"text"}]},{"type":"paragraph","content":[{"text":"Before implementing, write tests that define the expected behavior:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write tests covering:","type":"text","marks":[{"type":"strong"}]},{"text":" happy path, one error path, one edge case","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run tests to confirm they FAIL","type":"text","marks":[{"type":"strong"}]},{"text":" (RED confirmation)","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If tests pass → feature already exists or tests are wrong. Investigate before proceeding.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Proceed to Step 4","type":"text","marks":[{"type":"strong"}]},{"text":" with failing tests as the implementation target","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Run tests - ALL new tests must FAIL\n# Python: pytest tests/test_\u003cfeature>.py -v\n# Go: go test ./path/to/... -run TestNew\n# Node: npm test -- --grep \"new feature\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Test level selection:","type":"text","marks":[{"type":"strong"}]},{"text":" Classify each test by pyramid level (see the test pyramid standard (","type":"text"},{"text":"test-pyramid.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the standards skill)):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"L0 (Contract):","type":"text","marks":[{"type":"strong"}]},{"text":" Write if the issue touches spec boundaries, file existence, or registration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"L1 (Unit):","type":"text","marks":[{"type":"strong"}]},{"text":" Write always for feature/bug issues — happy path, one error path, one edge case","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"L2 (Integration):","type":"text","marks":[{"type":"strong"}]},{"text":" Write if the change crosses module boundaries or involves multiple components","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"L3 (Component):","type":"text","marks":[{"type":"strong"}]},{"text":" Write if the change affects a full subsystem workflow (with mocked external deps)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the issue includes ","type":"text"},{"text":"test_levels","type":"text","marks":[{"type":"code_inline"}]},{"text":" metadata from ","type":"text"},{"text":"$plan","type":"text","marks":[{"type":"code_inline"}]},{"text":", use those levels. Otherwise, default to L1 + any applicable higher levels from the decision tree above. When delegating to ","type":"text"},{"text":"$test","type":"text","marks":[{"type":"code_inline"}]},{"text":", carry those selected levels and any BF expectations into the request context. ","type":"text"},{"text":"--quick","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not permission to collapse to L1-only coverage.","type":"text"}]},{"type":"paragraph","content":[{"text":"Bug-Finding Level Selection (alongside L0–L3):","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"If the implementation touches external boundaries (APIs, databases, file I/O):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add BF4 chaos test: mock the boundary to fail, verify graceful error handling","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"This catches the bugs that L1 unit tests mock away","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the implementation includes data transformations (parse, render, serialize):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add BF1 property test: randomize inputs with hypothesis/gopter/fast-check","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"This catches edge cases no human would write","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the implementation generates output files (configs, reports, manifests):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add BF2 golden test: generate canonical output, save as golden file, assert match","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Reference: the test pyramid standard in ","type":"text"},{"text":"$standards","type":"text","marks":[{"type":"code_inline"}]},{"text":" for full tooling matrix.","type":"text"}]},{"type":"paragraph","content":[{"text":"Or use ","type":"text"},{"text":"$test \u003cfeature>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to auto-generate test candidates, then hand-refine.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip conditions (any of these bypasses Step 3.5):","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GREEN mode is active (invoked by ","type":"text"},{"text":"$crank --test-first","type":"text","marks":[{"type":"code_inline"}]},{"text":" — tests already exist)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Issue type is ","type":"text"},{"text":"chore","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"ci","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--no-tdd","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag is set","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No test framework detected in the project","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Note:","type":"text","marks":[{"type":"strong"}]},{"text":" Tests written here are MUTABLE — unlike GREEN mode's immutable tests, you may adjust these tests during implementation if you discover the initial test design was wrong. The goal is to think about behavior before code, not to be rigid.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3.6a: Auto-Generate Tests via $test (lifecycle integration)","type":"text"}]},{"type":"paragraph","content":[{"text":"If skip conditions above are NOT met AND ","type":"text"},{"text":"--no-lifecycle","type":"text","marks":[{"type":"code_inline"}]},{"text":" is NOT set:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"$test generate \u003cfeature-scope> --quick","type":"text"}]},{"type":"paragraph","content":[{"text":"The generated test request must preserve the selected ","type":"text"},{"text":"test_levels","type":"text","marks":[{"type":"code_inline"}]},{"text":" and BF expectations from Step 3.6. Review the generated tests. Adjust as needed (tests are MUTABLE in this context). If ","type":"text"},{"text":"$test","type":"text","marks":[{"type":"code_inline"}]},{"text":" fails to produce useful output or is unavailable, fall back to manual test writing in Step 3.6 above.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip if:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"--no-lifecycle","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag, GREEN mode active, issue type is chore/docs/ci, or ","type":"text"},{"text":"$test","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unavailable.","type":"text"}]},{"type":"paragraph","content":[{"text":"CI-safe tests:","type":"text","marks":[{"type":"strong"}]},{"text":" If the function under test shells out to an external CLI (","type":"text"},{"text":"bd","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"ao","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"gh","type":"text","marks":[{"type":"code_inline"}]},{"text":"), do NOT test the wrapper. Instead, test the underlying function that performs the testable work (event emission, state mutation, file I/O). See the Go standards (Testing section) for examples.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Implement the Change","type":"text"}]},{"type":"paragraph","content":[{"text":"GREEN Mode check:","type":"text","marks":[{"type":"strong"}]},{"text":" If test files were provided (invoked by $crank --test-first):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read all provided test files FIRST","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read the contract for invariants","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implement to make tests pass (do NOT modify test files)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skip to Step 5 verification","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Based on the context gathered:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Edit existing files","type":"text","marks":[{"type":"strong"}]},{"text":" using apply_patch (preferred)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Write new files","type":"text","marks":[{"type":"strong"}]},{"text":" only if necessary","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow existing patterns","type":"text","marks":[{"type":"strong"}]},{"text":" in the codebase","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep changes minimal","type":"text","marks":[{"type":"strong"}]},{"text":" - don't over-engineer","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4a: Build Verification (CLI repos only)","type":"text"}]},{"type":"paragraph","content":[{"text":"If the project has a Go ","type":"text"},{"text":"cmd/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory or a Makefile with a ","type":"text"},{"text":"build","type":"text","marks":[{"type":"code_inline"}]},{"text":" target, run build verification before proceeding to tests:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Detect CLI repo\nif [ -f go.mod ] && ls cmd/*/main.go &>/dev/null; then\n echo \"CLI repo detected — running build verification...\"\n\n # Build\n go build ./cmd/... 2>&1\n if [ $? -ne 0 ]; then\n echo \"BUILD FAILED — fix compilation errors before proceeding\"\n # Do NOT proceed to Step 5\n fi\n\n # Vet\n go vet ./cmd/... 2>&1\n\n # Smoke test: run the binary with --help\n BINARY=$(ls -t cmd/*/main.go | head -1 | xargs dirname | xargs basename)\n if [ -f \"bin/$BINARY\" ]; then\n ./bin/$BINARY --help > /dev/null 2>&1\n echo \"Smoke test: $BINARY --help passed\"\n fi\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"If build fails:","type":"text","marks":[{"type":"strong"}]},{"text":" Fix compilation errors and re-run before proceeding. Do NOT skip to verification with a broken build.","type":"text"}]},{"type":"paragraph","content":[{"text":"If not a CLI repo:","type":"text","marks":[{"type":"strong"}]},{"text":" This step is a no-op — proceed directly to Step 5.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4.5: Security Verification","type":"text"}]},{"type":"paragraph","content":[{"text":"Before proceeding to functional verification, check for common security issues in modified code:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Check","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"What to Look For","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Input validation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"User/external input used without validation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add validation at entry points","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Output escaping","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Raw data in HTML/templates (innerHTML, document.write, dangerouslySetInnerHTML)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use framework auto-escaping or explicit sanitization","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path safety","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Path traversal via ","type":"text"},{"text":"..","type":"text","marks":[{"type":"code_inline"}]},{"text":" sequences; file paths from user input without sanitization","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reject ","type":"text"},{"text":"..","type":"text","marks":[{"type":"code_inline"}]},{"text":", absolute paths; use ","type":"text"},{"text":"filepath.Clean()","type":"text","marks":[{"type":"code_inline"}]},{"text":" or equivalent; verify path stays within allowed directory","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auth gates","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Endpoints/handlers missing authentication or authorization checks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add middleware or guard clauses","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Content-Type","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HTTP responses without explicit Content-Type headers","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Set Content-Type to prevent MIME-sniffing attacks","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CORS","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Overly permissive CORS configuration (","type":"text"},{"text":"*","type":"text","marks":[{"type":"code_inline"}]},{"text":" origin, credentials: true)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Restrict to known origins; never combine wildcard with credentials","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CSRF tokens","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"State-changing endpoints (POST/PUT/DELETE) without anti-CSRF tokens","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add anti-CSRF token validation; do not rely solely on cookies for auth","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Rate limiting","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Authentication, API, and upload endpoints without rate limits","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Add rate-limit middleware; return 429 with Retry-After header","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Skip when:","type":"text","marks":[{"type":"strong"}]},{"text":" The change does not involve HTTP handlers, user-facing input, file system operations, or template rendering. Pure internal refactors, test-only changes, and documentation edits skip this step.","type":"text"}]},{"type":"paragraph","content":[{"text":"If issues found:","type":"text","marks":[{"type":"strong"}]},{"text":" Fix before proceeding to Step 5. Log fixes in the commit message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Verify the Change","type":"text"}]},{"type":"paragraph","content":[{"text":"Success Criteria (all must pass):","type":"text","marks":[{"type":"strong"}]}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"All existing tests pass (no new failures introduced)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"New code compiles/parses without errors","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"No new linter warnings (if linter available)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Change achieves the stated goal","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Check for test files and run them:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Find tests\nls *test* tests/ test/ __tests__/ 2>/dev/null | head -5\n\n# Run tests (adapt to project type)\n# Python: pytest\n# Go: go test ./...\n# Node: npm test\n# Rust: cargo test","type":"text"}]},{"type":"paragraph","content":[{"text":"If tests exist:","type":"text","marks":[{"type":"strong"}]},{"text":" All tests must pass. Any failure = verification failed.","type":"text"}]},{"type":"paragraph","content":[{"text":"If no tests exist:","type":"text","marks":[{"type":"strong"}]},{"text":" Manual verification required:","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Syntax check passes (file compiles/parses)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Imports resolve correctly","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Can reproduce expected behavior manually","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Edge cases identified during implementation are handled","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If verification fails:","type":"text","marks":[{"type":"strong"}]},{"text":" Do NOT proceed to Step 5a. Fix the issue first.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5.5: Binary-Deployment Gate (CLI/Hook Bug Fixes) — MANDATORY","type":"text"}]},{"type":"paragraph","content":[{"text":"For the full gate spec (rationale, mtime check, plugin-cache check, remediation), read ","type":"text","marks":[{"type":"strong"}]},{"text":"references/binary-deployment-gate.md","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This gate BLOCKS declaring \"done\" when the diff touches CLI/hook surfaces.","type":"text","marks":[{"type":"strong"}]},{"text":" It is not a warning. Council finding (","type":"text"},{"text":".agents/council/2026-05-01-evolution-cycle-council.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", finding 1, action item A; 6/6 judges): a fix shipped to source while the deployed runtime is pre-fix keeps reproducing the bug during its own post-mortem. Captured failure mode: ","type":"text"},{"text":".agents/learnings/2026-05-01-fix-shipped-binary-stale.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Trigger","type":"text","marks":[{"type":"strong"}]},{"text":" — gate fires if the diff touches ","type":"text"},{"text":"cli/cmd/**","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"hooks/**","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"cli/embedded/hooks/**","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"CHANGED=$(git diff --name-only HEAD~1 2>/dev/null; git diff --name-only --cached; git diff --name-only)\nTRIGGERS=$(printf '%s\\n' \"$CHANGED\" | grep -E '^(cli/cmd/|hooks/|cli/embedded/hooks/)' | sort -u)\n[ -z \"$TRIGGERS\" ] && echo \"Binary-deployment gate: no CLI/hook surfaces touched, skipping\" || echo \"Binary-deployment gate FIRES on: $TRIGGERS\"","type":"text"}]},{"type":"paragraph","content":[{"text":"When fired, both checks below MUST pass before Step 5a.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Check A — deployed binary mtime ≥ source-fix commit timestamp","type":"text","marks":[{"type":"strong"}]},{"text":" (per binary under ","type":"text"},{"text":"cli/cmd/\u003cbin>/","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"BIN=\u003cbinary-name> # e.g., ao\nDEPLOYED=$(command -v \"$BIN\") || { echo \"BLOCK: $BIN not on PATH\"; exit 1; }\nDEPLOYED_MTIME=$(stat -c %Y \"$DEPLOYED\" 2>/dev/null || stat -f %m \"$DEPLOYED\") # Linux | macOS\nSOURCE_MTIME=$(git log -1 --format=%ct -- \"cli/cmd/$BIN/\")\n[ \"$DEPLOYED_MTIME\" -lt \"$SOURCE_MTIME\" ] && { echo \"BLOCK: deployed $BIN is pre-fix — rebuild & redeploy\"; exit 1; }","type":"text"}]},{"type":"paragraph","content":[{"text":"Check B — plugin-cache hook copies reflect the fix","type":"text","marks":[{"type":"strong"}]},{"text":" (for any ","type":"text"},{"text":"hooks/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"cli/embedded/hooks/","type":"text","marks":[{"type":"code_inline"}]},{"text":" change, substitute the marker string introduced by the fix, e.g., ","type":"text"},{"text":"AGENTOPS_STARTUP_CLOSE_LOOP","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"STALE=$(find ~/.codex/plugins/cache \\\n -name '\u003chook-name>.sh' -path '*agentops*' \\\n -exec grep -L \"\u003cMARKER>\" {} \\; 2>/dev/null)\n[ -n \"$STALE\" ] && { echo \"BLOCK: stale plugin-cache hook copies: $STALE\"; exit 1; }","type":"text"}]},{"type":"paragraph","content":[{"text":"Pass criteria:","type":"text","marks":[{"type":"strong"}]},{"text":" both checks clean (or trigger is empty). Only then proceed to Step 5a. Failure modes, fallbacks, and remediation steps are in the references doc.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5a: Verification Gate (MANDATORY)","type":"text"}]},{"type":"paragraph","content":[{"text":"THE IRON LAW:","type":"text","marks":[{"type":"strong"}]},{"text":" NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE","type":"text"}]},{"type":"paragraph","content":[{"text":"Before reporting success, you MUST:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"IDENTIFY","type":"text","marks":[{"type":"strong"}]},{"text":" - What command proves this claim works?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"RUN","type":"text","marks":[{"type":"strong"}]},{"text":" - Execute the FULL command (fresh, not cached output)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"READ","type":"text","marks":[{"type":"strong"}]},{"text":" - Check full output AND exit code","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"VERIFY","type":"text","marks":[{"type":"strong"}]},{"text":" - Does output actually confirm the claim?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ONLY THEN","type":"text","marks":[{"type":"strong"}]},{"text":" - Make the completion claim","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Forbidden phrases without fresh verification evidence:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"should work\", \"probably fixed\", \"seems to be working\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Great!\", \"Perfect!\", \"Done!\" (without output proof)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"I just ran it\" (must run it AGAIN, fresh)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Rationalization Table","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Excuse","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Reality","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"Too simple to verify\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Simple code breaks. Verification takes 10 seconds.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"I just ran it\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run it AGAIN. Fresh output only.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"Tests passed earlier\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run them NOW. State changes.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"It's obvious it works\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Nothing is obvious. Evidence or silence.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"The edit looks correct\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Looking != working. Run the code.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Store checkpoint:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"bd update \u003cissue-id> --append-notes \"CHECKPOINT: Step 5a verification passed at $(date -Iseconds)\" 2>/dev/null","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"GREEN Mode (Test-First Implementation)","type":"text"}]},{"type":"paragraph","content":[{"text":"When invoked by $crank with ","type":"text"},{"text":"--test-first","type":"text","marks":[{"type":"code_inline"}]},{"text":", the worker receives:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Failing tests","type":"text","marks":[{"type":"strong"}]},{"text":" (immutable — DO NOT modify)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Contract","type":"text","marks":[{"type":"strong"}]},{"text":" (contract-{issue-id}.md)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Issue description","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"GREEN Mode Rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read failing tests FIRST","type":"text","marks":[{"type":"strong"}]},{"text":" — understand what must pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read contract","type":"text","marks":[{"type":"strong"}]},{"text":" — understand invariants and failure modes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implement ONLY enough","type":"text","marks":[{"type":"strong"}]},{"text":" to make all tests pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do NOT modify test files","type":"text","marks":[{"type":"strong"}]},{"text":" — tests are immutable in GREEN mode","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do NOT add features","type":"text","marks":[{"type":"strong"}]},{"text":" beyond what tests require","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BLOCKED if spec error","type":"text","marks":[{"type":"strong"}]},{"text":" — if contract contradicts tests or is incomplete, write BLOCKED with reason","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Verification (GREEN Mode):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run test suite → ALL tests must PASS","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Standard Iron Law (Step 5a) still applies — fresh verification evidence required","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No untested code — every line must be reachable by a test","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Test Immutability Enforcement:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workers may ADD new test files but MUST NOT modify existing test files provided by the TEST WAVE","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a test appears wrong, write BLOCKED with the specific test and reason — do NOT fix it","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5b: Autonomous Quality Loop (Pre-Commit)","type":"text"}]},{"type":"paragraph","content":[{"text":"Before committing, run a fix-verify loop on all files modified in this session (max 3 iterations):","type":"text"}]},{"type":"paragraph","content":[{"text":"Iteration N:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List modified files:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"git diff --name-only HEAD","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read each modified file completely","type":"text","marks":[{"type":"strong"}]},{"text":" — do not skim","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for defects:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Wrong variable references (copy-paste errors, stale names)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Silent error swallowing (","type":"text"},{"text":"_ = err","type":"text","marks":[{"type":"code_inline"}]},{"text":" or empty catch blocks)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hardcoded values that should be configurable or constants","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing edge cases identified during implementation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inconsistencies with existing patterns in the codebase","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unused imports or variables","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Complexity budget violations (function cyclomatic complexity >15)","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report findings","type":"text","marks":[{"type":"strong"}]},{"text":" as a numbered list with severity (HIGH/MEDIUM/LOW)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"HIGH findings:","type":"text","marks":[{"type":"strong"}]},{"text":" Fix immediately, re-run tests, re-sweep (next iteration)","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a fix causes test regression: ","type":"text"},{"text":"revert the fix","type":"text","marks":[{"type":"strong"}]},{"text":", report as unresolvable, proceed","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MEDIUM/LOW findings:","type":"text","marks":[{"type":"strong"}]},{"text":" Report in commit message, proceed","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Loop termination:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"0 HIGH findings → exit loop, proceed to Step 6","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3 iterations exhausted with HIGH findings remaining → ","type":"text"},{"text":"BLOCK commit","type":"text","marks":[{"type":"strong"}]},{"text":". Report remaining HIGHs and stop. Do NOT proceed to Step 6.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Override: ","type":"text"},{"text":"--force-commit","type":"text","marks":[{"type":"code_inline"}]},{"text":" allows proceeding with documented HIGHs (explicit opt-in only)","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Output:","type":"text","marks":[{"type":"strong"}]},{"text":" Record iteration count, findings per iteration, and remaining items.","type":"text"}]},{"type":"paragraph","content":[{"text":"If no modified files or sweep finds zero issues on first pass, proceed directly to Step 5c.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5c: Generate Behavioral Spec (Optional)","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip if:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"--no-spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag, or issue type is ","type":"text"},{"text":"docs","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"chore","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"ci","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"After verification passes, produce a behavioral spec documenting what the implementation does. This feeds Stage 4 behavioral validation (STEP 1.8 in ","type":"text"},{"text":"$validation","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"mkdir -p .agents/specs\ncat > .agents/specs/\u003cissue-id>.json \u003c\u003c'SPEC'\n{\n \"id\": \"auto-\u003cissue-id>\",\n \"version\": 1,\n \"date\": \"\u003cYYYY-MM-DD>\",\n \"goal\": \"\u003cone-line: what user outcome this implementation serves>\",\n \"narrative\": \"\u003c2-3 sentences: what the implementation does and how a user interacts with it>\",\n \"expected_outcome\": \"\u003cwhat a satisfied user observes when this works correctly>\",\n \"acceptance_vectors\": [\n {\n \"dimension\": \"\u003cname: correctness|performance|usability|security|...>\",\n \"threshold\": \u003c0.0-1.0>,\n \"check\": \"\u003coptional: mechanical check command>\"\n }\n ],\n \"satisfaction_threshold\": 0.7,\n \"scope\": {\n \"files\": [\"\u003clist of modified files>\"],\n \"functions\": [\"\u003ckey functions added/modified>\"],\n \"behaviors\": [\"\u003cbehavioral descriptions>\"]\n },\n \"source\": \"agent\",\n \"status\": \"active\"\n}\nSPEC","type":"text"}]},{"type":"paragraph","content":[{"text":"Guidelines:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"acceptance_vectors","type":"text","marks":[{"type":"code_inline"}]},{"text":" should capture the BEHAVIORAL contract, not test assertions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include at least 2 acceptance vectors (correctness + one other dimension).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scope.files","type":"text","marks":[{"type":"code_inline"}]},{"text":" must match the files you actually modified (not planned files).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If skipped:","type":"text","marks":[{"type":"strong"}]},{"text":" Log \"Behavioral spec skipped (reason: \u003cflag|issue-type>)\" and proceed.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 6: Commit the Change","type":"text"}]},{"type":"paragraph","content":[{"text":"If the change is complete and verified:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"git add \u003cmodified-files>\ngit commit -m \"\u003cdescriptive message>\n\nImplements: \u003cissue-id>\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7: Close the Issue with Evidence","type":"text"}]},{"type":"paragraph","content":[{"text":"Close with scoped evidence so the closure-integrity audit can resolve without parser_miss/timing_miss. The close reason must cite the commit and changed files from Step 6.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo \"unknown\")\nCHANGED_FILES=$(git diff --name-only HEAD~1 2>/dev/null | head -10 | tr '\\n' ' ' | sed 's/ $//')\nbd close \u003cissue-id> --reason \"commit:${COMMIT_SHA} files:[${CHANGED_FILES}]\" 2>/dev/null","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"bd close","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unavailable, fall back to ","type":"text"},{"text":"bd update \u003cissue-id> --status closed","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7a: Record Implementation in Ratchet Chain","type":"text"}]},{"type":"paragraph","content":[{"text":"After successful issue closure, record in ratchet:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check if ao CLI is available\nif command -v ao &>/dev/null; then\n # Reuse commit evidence from Step 7\n COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo \"\")\n CHANGED_FILES=$(git diff --name-only HEAD~1 2>/dev/null | tr '\\n' ',' | sed 's/,$//')\n\n if [ -n \"$COMMIT_HASH\" ]; then\n # Record successful implementation\n ao ratchet record implement \\\n --output \"$COMMIT_HASH\" \\\n --files \"$CHANGED_FILES\" \\\n --issue \"\u003cissue-id>\" \\\n 2>&1 | tee -a .agents/ratchet.log\n\n if [ $? -eq 0 ]; then\n echo \"Ratchet: Implementation recorded (commit: ${COMMIT_HASH:0:8})\"\n else\n echo \"Ratchet: Failed to record - chain.jsonl may need repair\"\n fi\n else\n echo \"Ratchet: No commit found - skipping record\"\n fi\nelse\n echo \"Ratchet: ao CLI not available - implementation NOT recorded\"\n echo \" Run manually: ao ratchet record implement --output \u003ccommit>\"\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"On failure/blocker:","type":"text","marks":[{"type":"strong"}]},{"text":" Record the blocker in ratchet:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"if command -v ao &>/dev/null; then\n ao ratchet record implement \\\n --status blocked \\\n --reason \"\u003cblocker description>\" \\\n 2>/dev/null\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Fallback:","type":"text","marks":[{"type":"strong"}]},{"text":" If ao is not available, the issue is still closed via bd but won't be tracked in the ratchet chain. The skill continues normally.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7b: Post-Implementation Ratchet Record","type":"text"}]},{"type":"paragraph","content":[{"text":"After implementation is complete:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"if command -v ao &>/dev/null; then\n ao ratchet record implement --output \"\u003cissue-id>\" 2>/dev/null || true\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Tell user: \"Implementation complete. Run $validation for closeout before pushing.\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 8: Report to User","type":"text"}]},{"type":"paragraph","content":[{"text":"Tell the user:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What was changed (files modified)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"How it was verified (with actual command output)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Issue status (closed)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Any follow-up needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ratchet status","type":"text","marks":[{"type":"strong"}]},{"text":" (implementation recorded or skipped)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Output completion marker:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\u003cpromise>DONE\u003c/promise>","type":"text"}]},{"type":"paragraph","content":[{"text":"If blocked or incomplete:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\u003cpromise>BLOCKED\u003c/promise>\nReason: \u003cwhy blocked>","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\u003cpromise>PARTIAL\u003c/promise>\nRemaining: \u003cwhat's left>","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Key Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"TDD by default","type":"text","marks":[{"type":"strong"}]},{"text":" - write failing tests before implementing (skip with ","type":"text"},{"text":"--no-tdd","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explore first","type":"text","marks":[{"type":"strong"}]},{"text":" - understand before changing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Edit, don't rewrite","type":"text","marks":[{"type":"strong"}]},{"text":" - prefer targeted edits over full file rewrites","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Follow patterns","type":"text","marks":[{"type":"strong"}]},{"text":" - match existing code style","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify changes","type":"text","marks":[{"type":"strong"}]},{"text":" - run tests or sanity checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commit with context","type":"text","marks":[{"type":"strong"}]},{"text":" - reference the issue ID","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Close the issue","type":"text","marks":[{"type":"strong"}]},{"text":" - update status when done","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Without Beads","type":"text"}]},{"type":"paragraph","content":[{"text":"If bd CLI not available:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skip the claim/close status updates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use the description as the task","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Still commit with descriptive message","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report completion to user","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Implement Specific Issue","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"$implement ag-5k2","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"What happens:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agent reads issue from beads: \"Add JWT token validation middleware\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explore agent finds relevant auth code and middleware patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agent edits ","type":"text"},{"text":"middleware/auth.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" to add token validation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runs ","type":"text"},{"text":"go test ./middleware/...","type":"text","marks":[{"type":"code_inline"}]},{"text":" — all tests pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Commits with message \"Add JWT token validation middleware","type":"text"},{"type":"br"},{"type":"br"},{"text":"Implements: ag-5k2\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Closes issue via ","type":"text"},{"text":"bd close ag-5k2 --reason \"commit:\u003csha> files:[middleware/auth.go]\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" Issue implemented, verified, committed, and closed. Ratchet recorded.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pick Up Next Available Work","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"$implement","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"What happens:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agent runs ","type":"text"},{"text":"bd ready","type":"text","marks":[{"type":"code_inline"}]},{"text":" — finds ","type":"text"},{"text":"ag-3b7","type":"text","marks":[{"type":"code_inline"}]},{"text":" (first unblocked issue)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Claims issue via ","type":"text"},{"text":"bd update ag-3b7 --status in_progress","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implements and verifies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Closes issue","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" Autonomous work pickup and completion from ready queue.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"GREEN Mode (Test-First)","type":"text"}]},{"type":"paragraph","content":[{"text":"User says:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"$implement ag-8h3","type":"text","marks":[{"type":"code_inline"}]},{"text":" (invoked by ","type":"text"},{"text":"$crank --test-first","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"paragraph","content":[{"text":"What happens:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Agent receives failing tests (immutable) and contract","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reads tests to understand expected behavior","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implements ONLY enough to make tests pass","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Does NOT modify test files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verification: all tests pass with fresh output","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Result:","type":"text","marks":[{"type":"strong"}]},{"text":" Minimal implementation driven by tests, no over-engineering.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Problem","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cause","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Solution","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Issue not found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Issue ID doesn't exist or local state looks stale","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Run ","type":"text"},{"text":"bd show \u003cid>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to verify; use ","type":"text"},{"text":"bd vc status","type":"text","marks":[{"type":"code_inline"}]},{"text":" only if you need Dolt state","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GREEN mode violation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Edited a file not related to the issue scope","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Revert unrelated changes. GREEN mode restricts edits to files relevant to the issue","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Verification gate fails","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tests fail or build breaks after implementation","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Read the verification output, fix the specific failures, re-run verification","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"BLOCKED\" status","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Contract contradicts tests or is incomplete in GREEN mode","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Write BLOCKED with specific reason, do NOT modify tests","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fresh verification missing","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Agent claims success without running verification command","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MUST run verification command fresh with full output before claiming completion","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ratchet record failed","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ao CLI unavailable or chain.jsonl corrupted","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Implementation still closes via bd, but ratchet chain needs manual repair","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"See Also","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"test","type":"text","marks":[{"type":"link","attrs":{"href":"../test/SKILL.md","title":null}}]},{"text":" — Test generation, coverage analysis, and TDD workflow","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Documents","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/binary-deployment-gate.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/binary-deployment-gate.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/gate-checks.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/gate-checks.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/resume-protocol.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/resume-protocol.md","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Local Resources","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"references/","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/binary-deployment-gate.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/binary-deployment-gate.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/gate-checks.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/gate-checks.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/resume-protocol.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/resume-protocol.md","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"scripts/","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scripts/validate.sh","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"\u003c!-- Lifecycle integration wired: 2026-03-28. See skills/implement/SKILL.md for canonical -->","type":"text"}]}]},"metadata":{"date":"2026-06-05","name":"implement","author":"@skillopedia","source":{"stars":375,"repo_name":"agentops","origin_url":"https://github.com/boshu2/agentops/blob/HEAD/skills-codex/implement/SKILL.md","repo_owner":"boshu2","body_sha256":"767c6ef89eca149eb96cf4b15b68a6d4a884d7d79251a24ab1ac2c4de6335bc1","cluster_key":"dcc8db4aec3884ca8d5ca032183c8286a4a88e8c13c9616e690854c2f51696e0","clean_bundle":{"format":"clean-skill-bundle-v1","source":"boshu2/agentops/skills-codex/implement/SKILL.md","attachments":[{"id":"b4055c0f-1763-5fc4-ad4e-0b464f9cc4c7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b4055c0f-1763-5fc4-ad4e-0b464f9cc4c7/attachment.json","path":".agentops-generated.json","size":273,"sha256":"40828714fc9a879cb6b137f443cbe3cf64a9ba065ccebd012e2e8e72ea813444","contentType":"application/json; charset=utf-8"},{"id":"85260fbc-44f8-5bb3-ae94-eb429087c70e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/85260fbc-44f8-5bb3-ae94-eb429087c70e/attachment.md","path":"prompt.md","size":802,"sha256":"0de95be5b7621b40c1d074841f51f988aaeecd09bb6a894e522b14ca1438f632","contentType":"text/markdown; charset=utf-8"},{"id":"1f21c692-cf20-5b1a-99e9-18b59010d396","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1f21c692-cf20-5b1a-99e9-18b59010d396/attachment.md","path":"references/binary-deployment-gate.md","size":6271,"sha256":"589f933a31516d79e225f32543fe2705b4700ba7720451dbda01d3e2e490c065","contentType":"text/markdown; charset=utf-8"},{"id":"2e8479d5-5e7f-5b12-85dc-c720cb39615d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2e8479d5-5e7f-5b12-85dc-c720cb39615d/attachment.md","path":"references/gate-checks.md","size":2400,"sha256":"403ae63777ca62246c027c317e1ce327c5666f6021036cf0b4af89392c93e6b3","contentType":"text/markdown; charset=utf-8"},{"id":"6835ce75-ddfd-57d9-ad0b-27e8b9338d1f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6835ce75-ddfd-57d9-ad0b-27e8b9338d1f/attachment.md","path":"references/resume-protocol.md","size":898,"sha256":"896fdc174cde3fe8a0193945221684fdafa84c40c8f8d03275ef4e3539f44315","contentType":"text/markdown; charset=utf-8"},{"id":"d22d6963-cd41-5c28-90f5-889630602be3","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d22d6963-cd41-5c28-90f5-889630602be3/attachment.sh","path":"scripts/validate.sh","size":1422,"sha256":"c6a9e46326770cb78b021982b1b96d1f61f36477e87ecfba554cc2c7c0cac784","contentType":"application/x-sh; charset=utf-8"}],"bundle_sha256":"b1b36a1866947611a7fa283a032f7bcb34f4e05d7b523c45660833ccd9d03bc3","attachment_count":6,"text_attachments":6,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills-codex/implement/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"general","category_label":"General"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"general","import_tag":"clean-skills-v1","description":"Implement one tracked issue."}},"renderedAt":1782979966420}

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 ( is set or is ), ensure startup context before claiming or implementing the issue: is the single startup guard for Codex skills. It records startup once per thread and skips duplicate startup automatically. Leave to dedicated closeout skills such as , , or . Execution Steps Given : Step 0: Pre-Flight Checks (Resume + Gates…