/implement

Implement a feature using a persistent agentic loop that continues until verification passes:

Arguments: $ARGUMENTS

Core Principle (from Anthropic)

"Claude marked features complete without proper testing" - NEVER trust self-assessment. Always run actual verification commands.

Phase 0: Load Loop State

1. Check for existing loop state:

   • Read .claude-harness/loop-state.json
   • If status is "in_progress" and matches $ARGUMENTS:
     • Display: "Resuming loop for {feature} at attempt {attempt}/{maxAttempts}"
     • Load history of previous attempts
   • If no active loop or different feature:
     • Initialize new loop state

2. Read feature definition:

   • Parse $ARGUMENTS as feature ID
   • Read .claude-harness/feature-list.json
   • Extract feature details including verificationCommands
   • If verificationCommands is missing, detect or ask user

3. Initialize/update .claude-harness/loop-state.json:

   {
     "version": 1,
     "feature": "{feature-id}",
     "featureName": "{feature name}",
     "status": "in_progress",
     "attempt": 1,
     "maxAttempts": 10,
     "startedAt": "{timestamp}",
     "lastAttemptAt": null,
     "verification": {
       "build": "npm run build",
       "tests": "npm run test",
       "lint": "npm run lint",
       "typecheck": "npx tsc --noEmit",
       "custom": []
     },
     "history": [],
     "lastCheckpoint": null,
     "escalationRequested": false
   }
   

Phase 1: Health Check

4. Before attempting any work, verify the environment is healthy:

   • Run build command (if defined) to ensure app isn't broken
   • If health check fails:
     • Check git status for uncommitted changes
     • Attempt git stash or inform user
     • If still failing, this is attempt 0 - fixing baseline

5. Report health status:

   ┌─────────────────────────────────────────────────────────────────┐
   │  AGENTIC LOOP: {feature-name}                                   │
   ├─────────────────────────────────────────────────────────────────┤
   │  Health Check: ✅ PASSED (build succeeds, tests baseline)       │
   │  Attempt: {n}/{maxAttempts}                                     │
   │  Previous attempts: {count}                                     │
   └─────────────────────────────────────────────────────────────────┘
   

Phase 2: Attempt Implementation

6. Read attempt history to understand what was tried:

   • If history exists, summarize:
     • What approaches were tried
     • What errors occurred
     • What files were modified
   • Use this to avoid repeating failed approaches

7. Plan the current attempt:

   • Read feature description and verification criteria
   • If first attempt: Plan fresh approach
   • If retry: Analyze previous errors and plan different approach
   • Document the approach in loop state before executing

8. Execute the implementation:

   • Work on the feature following the planned approach
   • Make code changes as needed
   • Document key decisions made

9. Update loop state after attempt:

   {
     "history": [..., {
       "attempt": {n},
       "timestamp": "{ISO timestamp}",
       "approach": "{description of what was tried}",
       "filesModified": ["{paths}"],
       "filesCreated": ["{paths}"],
       "result": "pending_verification"
     }]
   }
   

Phase 3: Verification (MANDATORY - NEVER SKIP)

10. Run ALL verification commands:

    ┌─────────────────────────────────────────────────────────────────┐
    │  VERIFICATION PHASE                                             │
    ├─────────────────────────────────────────────────────────────────┤
    │  ⏳ Running: npm run build                                      │
    │  ⏳ Running: npm run test                                       │
    │  ⏳ Running: npm run lint                                       │
    │  ⏳ Running: npx tsc --noEmit                                   │
    └─────────────────────────────────────────────────────────────────┘
    

11. Collect verification results:

    • For each command, capture:
      • Exit code (0 = pass, non-zero = fail)
      • stdout/stderr output
      • Specific error messages

12. Determine overall result:

    • ALL commands must pass for success
    • Any failure = overall failure
    • Parse error output to identify specific issues

Phase 4: Handle Result

If ALL Verification Passes:

13. Celebration and checkpoint:

    ┌─────────────────────────────────────────────────────────────────┐
    │  ✅ VERIFICATION PASSED                                         │
    ├─────────────────────────────────────────────────────────────────┤
    │  Build:     ✅ PASSED                                           │
    │  Tests:     ✅ PASSED                                           │
    │  Lint:      ✅ PASSED                                           │
    │  Typecheck: ✅ PASSED                                           │
    ├─────────────────────────────────────────────────────────────────┤
    │  Feature complete in {n} attempts!                              │
    └─────────────────────────────────────────────────────────────────┘
    

14. Create git checkpoint:

    • Stage all changes: git add -A
    • Commit with descriptive message:

      feat({feature-id}): {feature-name}
      
      Implemented via agentic loop ({n} attempts)
      
      Verification passed:
      - Build: ✅
      - Tests: ✅
      - Lint: ✅
      - Typecheck: ✅
      

    • Record commit hash in loop state

15. Update loop state to completed:

    {
      "status": "completed",
      "completedAt": "{timestamp}",
      "totalAttempts": {n},
      "finalCommit": "{commit-hash}",
      "history": [..., {
        "attempt": {n},
        "result": "passed",
        "verificationResults": {
          "build": "passed",
          "tests": "passed",
          "lint": "passed",
          "typecheck": "passed"
        }
      }]
    }
    

16. Update feature-list.json:

    • Set passes: true

17. Report success and next steps:

    • Recommend: /claude-harness:checkpoint to push and create PR

If Verification Fails:

18. Analyze failures:

    ┌─────────────────────────────────────────────────────────────────┐
    │  ❌ VERIFICATION FAILED                                         │
    ├─────────────────────────────────────────────────────────────────┤
    │  Build:     ✅ PASSED                                           │
    │  Tests:     ❌ FAILED - 2 tests failing                         │
    │  Lint:      ✅ PASSED                                           │
    │  Typecheck: ❌ FAILED - 3 type errors                           │
    ├─────────────────────────────────────────────────────────────────┤
    │  Attempt {n}/{maxAttempts}                                      │
    └─────────────────────────────────────────────────────────────────┘
    

19. Parse and categorize errors:

    • Extract specific error messages
    • Identify affected files and line numbers
    • Categorize: type errors, test failures, lint issues, runtime errors

20. Update loop state with failure details:

    {
      "history": [..., {
        "attempt": {n},
        "result": "failed",
        "errors": [
          "TS2322: Type 'string' is not assignable to type 'number' at src/auth.ts:42",
          "Test: auth.test.ts - expected 200, got 401"
        ],
        "verificationResults": {
          "build": "passed",
          "tests": "failed",
          "lint": "passed",
          "typecheck": "failed"
        }
      }]
    }
    

21. Check attempt count:

    • If attempt < maxAttempts: Continue to Phase 5 (Retry)
    • If attempt >= maxAttempts: Go to Phase 6 (Escalation)

Phase 5: Retry

22. Increment attempt counter and save state:

    {
      "attempt": {n+1},
      "lastAttemptAt": "{timestamp}"
    }
    

23. Analyze what went wrong:

    • Review the specific errors
    • Compare with previous attempts to avoid repeating
    • Identify if approach needs fundamental change or just fixes

24. Plan new approach:

    • If same errors recurring: Try fundamentally different approach
    • If new errors: Fix specific issues
    • Document new plan in loop state

25. Return to Phase 2 (Attempt Implementation)

    • Continue the loop until success or max attempts

Phase 6: Escalation

26. If max attempts reached without success:

    ┌─────────────────────────────────────────────────────────────────┐
    │  ⚠️  ESCALATION REQUIRED                                        │
    ├─────────────────────────────────────────────────────────────────┤
    │  Max attempts ({maxAttempts}) reached without success           │
    │                                                                 │
    │  Attempts Summary:                                              │
    │  1. {approach} → {error summary}                                │
    │  2. {approach} → {error summary}                                │
    │  ...                                                            │
    │                                                                 │
    │  Recurring Issues:                                              │
    │  - {pattern of failures}                                        │
    │                                                                 │
    │  Recommendation:                                                │
    │  {suggested human intervention or alternative approach}         │
    └─────────────────────────────────────────────────────────────────┘
    

27. Update loop state:

    {
      "status": "escalated",
      "escalationRequested": true,
      "escalationReason": "{summary of why automation couldn't complete}",
      "escalatedAt": "{timestamp}"
    }
    

28. Offer options:

    • Increase maxAttempts and continue: /claude-harness:implement {feature-id} --max-attempts 20
    • Get human guidance and retry
    • Abort and preserve progress

Session Continuity

If context window runs out during a loop:

29. Loop state is preserved in .claude-harness/loop-state.json

30. SessionStart hook will display:

    ┌─────────────────────────────────────────────────────────────────┐
    │  🔄 ACTIVE LOOP: {feature-id} (attempt {n}/{max})               │
    │     Last: "{approach summary}" → {result}                       │
    │     Resume: /claude-harness:implement {feature-id}              │
    └─────────────────────────────────────────────────────────────────┘
    

31. Running /claude-harness:implement {feature-id} resumes from Phase 0

Loop Control Commands

• Resume loop: /claude-harness:implement {feature-id}
• Check status: Read .claude-harness/loop-state.json
• Abort loop: Set status: "aborted" in loop-state.json
• Increase attempts: /claude-harness:implement {feature-id} --max-attempts {n}