implement

Execute an implementation plan or review fixes, making code changes and committing according to guidelines.

Arguments

/implement [target]

Target (optional)

Specifies what to implement. Can be:

• Nothing - auto-detect from branch name, check for review.md then plan.md
• Directory name - folder within .ai/ (e.g., issue-59-add-no-verify-option)
• Relative path - path to .ai/ folder (e.g., .ai/my-feature)
• File path - direct path to a specific file (e.g., .ai/my-feature/review.md)

Source Priority

When given a directory (or auto-detecting):

1. If review.md exists → implement fixes from the review
2. Otherwise if plan.md exists → implement the plan
3. If neither exists → suggest running /create-plan or /code-review first

Examples

# Auto-detect from branch, prefer review.md over plan.md
/implement

# Use specific folder in .ai/
/implement issue-59-add-no-verify-option

# Use relative path
/implement .ai/my-feature

# Use specific file directly
/implement .ai/my-feature/plan.md
/implement .ai/my-feature/review.md

Instructions

1. Parse Arguments and Find Source

   If a file path was provided (ends with .md):

   • Use that file directly
   • Determine if it's a plan or review from filename

   If a directory/folder was provided:

   • If it starts with .ai/, use it directly
   • Otherwise, treat it as a folder name within .ai/
   • Check for review.md first, then plan.md

   If no argument provided:

   • Extract issue number from branch name (e.g., feature/59-... → 59)
   • Look for existing .ai/issue-<number>-* folder
   • Check for review.md first, then plan.md

   If no source file found:

   • Suggest running /create-plan for new work
   • Suggest running /code-review if code exists but needs review

2. Verify Prerequisites

   • Confirm on correct feature branch
   • Check working directory is clean (git status)
   • Ensure tests pass before starting: go test ./...

3. Load Guidelines

   • Read CODING_GUIDELINES.md for implementation standards
   • Read COMMIT_GUIDELINES.md for commit format
   • Read GIT_TEST_SCENARIOS.md when implementing tests (required for Git scenario setup)

4. Execute Work

   For Plan Mode (implementing from plan.md)

   Tests come first. The plan's Test Plan section was gated by /validate-tests and is authoritative:

   1. Confirm the plan was gated: .ai/<folder>/codex-test-plan.md exists. If not, stop and run /validate-tests first
   2. Implement all Test Plan scenarios as tests before any production code
   3. Verify they fail for the right reason — missing behavior, not setup bugs — then commit the tests
   4. Only then work through the remaining implementation tasks

   For each task in the plan:

   Before Each Task:

   • Review task requirements and identify all files to modify
   • Read CODING_GUIDELINES.md rules relevant to the change

   Code Changes:

   • Make focused, atomic changes
   • Follow existing patterns in the codebase
   • Keep changes minimal — don't over-engineer

   After Each Task:

   • Verify build: go build ./...
   • Run tests: go test ./...
   • Review changes: git diff

   Test Immutability Rule (Plan Mode)

   Tests MUST NOT be changed to make the implementation pass. If the implementation and a test disagree, the test plan is challenged — not quietly edited:

   1. Stop implementing. Re-read the spec/analysis and the Test Plan and determine which is wrong: the implementation approach (usual case — fix the implementation) or genuinely the test plan
   2. If the test plan must change: revise the Test Plan section, re-run the /validate-tests Codex gate on the revised plan, and append an entry to the plan's Test Plan Revisions section: what changed, why, revision count
   3. Then update the affected tests to match the revised plan and continue

   Abort rule: if this happens more than 3 times in one implementation, error out — stop all work, leave the branch as-is, and report to the user that the plan and implementation are fundamentally at odds and need human review. Do not attempt a fourth revision.

   For Review Mode (implementing from review.md)

   For each issue found in the review:

   Must fix:

   • Address all must-fix issues before continuing
   • These prevent the PR from being merged

   Should fix:

   • Address should-fix items that improve code quality
   • Document any intentionally skipped with rationale

   Nit:

   • Consider implementing if they improve the code
   • Skip if they add unnecessary complexity

   After Fixes:

   • Verify build: go build ./...
   • Run tests: go test ./...
   • Review changes: git diff

5. Commit Strategy

   When to Commit

   • After completing a logical unit of work
   • After each checkpoint in the plan (plan mode)
   • After fixing a category of issues (review mode)
   • Keep commits atomic and focused
   • Use /commit skill for proper formatting

6. Checkpoint Verification

   At each checkpoint:

   • [ ] Build succeeds: go build ./...
   • [ ] Tests pass: go test ./...
   • [ ] Expected behavior works
   • [ ] Changes committed

7. Track Progress

   For plan mode - update plan.md checkboxes:

   - [x] Completed task
   - [ ] Pending task
   

   For review mode - update review.md checkboxes:

   - [x] Fixed: <issue description>
   - [ ] Pending: <issue description>
   

8. Handle Issues

   If problems arise:

   • Document the issue
   • Check if it affects the plan/review
   • Adjust approach if needed
   • Ask for clarification if blocked

Completion

For Plan Mode:

1. Verify all tests pass
2. Check all checkboxes in plan.md are complete
3. Suggest running /code-review before PR

For Review Mode:

1. Verify all tests pass
2. Check all blocking issues are resolved
3. Update review.md with fixes applied
4. Ready for PR if all blocking issues fixed