implement

Execute an implementation plan, making changes and committing properly

SKILL.md

GitHub

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