Implement

plugin: conductor updated: 2026-01-20

<status_progression>
  Task status MUST follow this progression:
  - [ ] (pending) - Not started
  - [~] (in_progress) - Currently working
  - [x] (complete) - Finished
  - [!] (blocked) - Blocked by issue

  Only ONE task can be [~] at a time.
</status_progression>

<tdd_workflow>
  Follow Test-Driven Development for each task:

  **Red Phase:**
  1. Create test file for the feature
  2. Write tests defining expected behavior
  3. Run tests - confirm they FAIL
  4. Do NOT proceed until tests fail

  **Green Phase:**
  1. Write MINIMUM code to pass tests
  2. Run tests - confirm they PASS
  3. No refactoring yet

  **Refactor Phase:**
  1. Improve code clarity and performance
  2. Remove duplication
  3. Run tests - confirm they still PASS
</tdd_workflow>

<git_commit_protocol>
  After completing each task:
  1. Stage relevant changes
  2. Commit with proper format:
     ```
     <type>(<scope>): <description>

     - Detail 1
     - Detail 2

     Task: {phase}.{task}
     ```
  3. Attach git note with task summary:
     ```bash
     git notes add -m "Task: {phase}.{task} - {title}

     Summary: {what was accomplished}

     Files Changed:
     - {file1}: {description}

     Why: {business reason}" $(git log -1 --format="%H")
     ```
  4. Update metadata.json with commit SHA
</git_commit_protocol>

<commit_types>
  | Type | Use For |
  |------|---------|
  | feat | New feature |
  | fix | Bug fix |
  | docs | Documentation |
  | style | Formatting |
  | refactor | Code restructuring |
  | test | Adding tests |
  | chore | Maintenance |
  | perf | Performance |
</commit_types>

<workflow_adherence>
  ALWAYS follow procedures in conductor/workflow.md:
  - TDD Red/Green/Refactor cycle
  - Quality gates (>80% coverage, linting)
  - Document deviations in tech-stack.md
  - Phase Completion Protocol at phase end
</workflow_adherence>

<human_approval_gates>
  Pause and ask for user approval:
  - Before starting each new phase
  - When encountering blockers
  - Before marking phase complete
  - During Phase Completion Protocol Step 5
</human_approval_gates>

<principle name="Test First" priority="critical">
  Write failing tests BEFORE implementation.
  This is the Red phase of TDD.
  Never skip this step.
</principle>

<principle name="Continuous Status Updates" priority="critical">
  Update plan.md status immediately when:
  - Starting a task ([~])
  - Completing a task ([x])
  - Encountering a blocker ([!] with note)
</principle>

<principle name="Traceable Commits" priority="high">
  Every commit links to track/task.
  Commit messages follow type convention.
  Git notes provide audit trail.
</principle>

<phase number="2" name="Task Selection">
  <step>Find first pending task (or ask user)</step>
  <step>Mark task as [~] in_progress in plan.md</step>
  <step>TaskUpdate to match</step>
  <step>Read task requirements and context</step>
</phase>

<phase number="3" name="TDD Implementation">
  <step>**Red Phase:** Write failing tests for the task</step>
  <step>Run tests, confirm they FAIL</step>
  <step>**Green Phase:** Write minimum code to pass</step>
  <step>Run tests, confirm they PASS</step>
  <step>**Refactor Phase:** Improve code quality</step>
  <step>Run tests, confirm they still PASS</step>
  <step>Verify coverage meets >80% requirement</step>
</phase>

<phase number="4" name="Quality & Commit">
  <step>Run all quality checks (lint, typecheck, test)</step>
  <step>If checks fail, fix before proceeding</step>
  <step>Stage relevant file changes</step>
  <step>Create commit with proper type and message</step>
  <step>Add git note with task summary</step>
  <step>Mark task as [x] complete in plan.md</step>
  <step>Commit plan.md update separately</step>
  <step>Update metadata.json with commit info</step>
  <step>TaskUpdate to match</step>
</phase>

<phase number="5" name="Phase Transition Check">
  <step>Check if phase is complete (all tasks [x])</step>
  <step>If NOT complete, continue to next pending task</step>
  <step>If phase IS complete, execute Phase Completion Protocol</step>
</phase>

1. **Announce Protocol Start**
   Inform user: "Phase {N} complete. Starting verification protocol."

2. **Ensure Test Coverage**
   ```bash
   # Find files changed in this phase
   PREV_SHA=$(grep -o '\[checkpoint: [a-f0-9]*\]' plan.md | tail -1 | grep -o '[a-f0-9]*')
   git diff --name-only $PREV_SHA HEAD
   # Verify tests exist for each code file
   # Create missing tests if needed
   ```

3. **Execute Automated Tests**
   ```bash
   echo "Running: CI=true npm test"
   CI=true npm test
   # If fail: attempt fix (max 2 times), then ask user
   ```

4. **Propose Manual Verification Plan**
   Provide step-by-step manual testing instructions.
   Include specific commands and expected outcomes.

5. **Await User Confirmation**
   Ask: "Does this meet your expectations? Confirm with 'yes' or provide feedback."
   **PAUSE** - do not proceed without explicit yes.

6. **Create Checkpoint Commit**
   ```bash
   git add -A
   git commit -m "conductor(checkpoint): End of Phase {N} - {Phase Name}"
   ```

7. **Attach Verification Report**
   ```bash
   git notes add -m "Phase Verification Report
   Phase: {N} - {Phase Name}
   Automated Tests: PASSED
   Manual Verification: User confirmed
   Coverage: {X}%" $(git log -1 --format="%H")
   ```

8. **Update Plan with Checkpoint**
   Add `[checkpoint: abc1234]` to phase heading in plan.md.

9. **Commit Plan Update**
   ```bash
   git commit -m "conductor(plan): Mark phase '{Phase Name}' complete"
   ```

10. **Announce Completion**
    Inform user phase is complete with checkpoint and verification report.

• Detail 1
• Detail 2

Task: {phase}.{task} ({task_title})

    Example:

feat(auth): Implement password hashing

• Added bcrypt dependency
• Created hashPassword utility function
• Added unit tests for hashing

Task: 2.1 (Implement password hashing)

  </commit_message_format>

  <git_notes_format>

Task: {phase}.{task} - {task_title}

Summary: {what was accomplished}

Files Changed:

• {file1}: {description}
• {file2}: {description}

Why: {business reason for this change}

  </git_notes_format>

  <blocker_handling>
    When encountering a blocker:
    1. Mark task as [!] blocked in plan.md
    2. Add note describing blocker:
       ```markdown
       - [!] 2.3 Implement OAuth login
         > BLOCKED: Waiting for API credentials from team lead
       ```
    3. Ask user for guidance
    4. Either resolve or skip to different task
    5. Track blocker in metadata.json
  </blocker_handling>

  <deviation_protocol>
    If implementation differs from tech-stack.md:
    1. STOP implementation
    2. Update tech-stack.md with new design
    3. Add dated note explaining the change:
       ```markdown
       ## Changes Log
       - 2026-01-05: Changed from SQLite to PostgreSQL for better concurrency
       ```
    4. Resume implementation
  </deviation_protocol>
</knowledge>

<examples>
  <example name="Complete Task with TDD">
    <user_request>Start implementing the auth feature</user_request>
    <correct_approach>
      1. Load feature_auth_20260105 track
      2. Read plan.md - find first pending task: 1.1 Create user table
      3. Mark 1.1 as [~] in plan.md
      4. Initialize Tasks with plan tasks

      **Red Phase:**
      5. Create test file: tests/user-table.test.ts
      6. Write tests for user table schema
      7. Run tests - confirm they FAIL

      **Green Phase:**
      8. Create migration file
      9. Define user table schema
      10. Run tests - confirm they PASS

      **Refactor Phase:**
      11. Clean up migration code
      12. Run tests - confirm still PASS

      **Commit:**
      13. Run quality checks (all pass)
      14. Commit: "feat(db): Create user table schema"
      15. Add git note with task summary
      16. Commit plan.md update
      17. Mark 1.1 as [x] in plan.md
      18. Update metadata.json
      19. Move to next task 1.2
    </correct_approach>
  </example>

  <example name="Phase Completion">
    <user_request>Continue implementing auth</user_request>
    <correct_approach>
      1. Complete final task of Phase 1
      2. All Phase 1 tasks now [x]
      3. Announce: "Phase 1 complete. Starting verification protocol."

      **Phase Completion Protocol:**
      4. Check test coverage for all Phase 1 files
      5. Run: CI=true npm test (PASSED)
      6. Present manual verification steps to user
      7. Ask: "Does this meet your expectations?"
      8. User confirms: "yes"
      9. Create checkpoint commit
      10. Add verification report via git notes
      11. Update plan.md with [checkpoint: abc1234]
      12. Commit plan update
      13. Announce: "Phase 1 checkpoint created. Proceeding to Phase 2."
      14. Ask approval before starting Phase 2
    </correct_approach>
  </example>

  <example name="Handle Blocker">
    <user_request>Continue implementing auth</user_request>
    <correct_approach>
      1. Load track, find current task 2.1
      2. Start Red Phase, encounter issue
      3. Issue: Missing database credentials
      4. Mark 2.1 as [!] blocked
      5. Add note: "> BLOCKED: Need database credentials configured"
      6. Ask user: "Task 2.1 is blocked. Options:
         (A) Provide credentials to continue
         (B) Skip to task 2.2
         (C) Pause implementation"
      7. User provides credentials
      8. Remove blocker, mark [~] in_progress
      9. Continue TDD cycle
    </correct_approach>
  </example>
</examples>

<formatting>
  <progress_display>

Implementation Progress

Track: feature_auth_20260105 Phase: 2/4 - Core Authentication Task: 2.1/2.5 - Implement password hashing

[==========-----] 40% complete

Recent:

• 1.1 Create user table schema (abc1234)
• 1.2 Add migration scripts (def5678)
• 1.3 Set up database connection (ghi9012)
• 2.1 Implement password hashing (just completed)

Next:

• 2.2 Create login endpoint

  </progress_display>

  <task_completion_template>
## Task Complete

**Track:** {track_id}
**Task:** {phase}.{task} - {task_title}
**Commit:** {short_sha}
**Type:** {feat/fix/refactor/etc.}

**TDD Cycle:**
- Red: Tests written and failing
- Green: Implementation complete, tests passing
- Refactor: Code cleaned up

**Quality Checks:**
- Lint: PASS
- Tests: PASS ({N} tests, {X}% coverage)
- TypeCheck: PASS

**Next Task:** {next_task_id} - {next_task_title}

Continue to next task? [Yes/No]
  </task_completion_template>

  <phase_completion_template>
## Phase Complete

**Track:** {track_id}
**Phase:** {N} - {phase_name}
**Checkpoint:** {checkpoint_sha}

**Verification Report:**
- Automated Tests: PASSED
- Coverage: {X}%
- Manual Verification: User confirmed

**Git Note:** Attached to checkpoint commit

**Next Phase:** {N+1} - {next_phase_name}

Proceed to next phase? [Yes/No]
  </phase_completion_template>
</formatting>