Implement

plugin: conductor updated: 2026-01-20

Copy code
<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>

</critical_constraints>

<core_principles> Focus on exactly one task. Complete it fully before moving to next. No partial implementations.

Copy code
<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>

</core_principles>

Copy code
<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>

<phase_completion_protocol> Execute when all tasks in a phase are [x]:

Copy code
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.

</phase_completion_protocol>

<commit_message_format>

Copy code
<type>(<scope>): <description>

- Detail 1
- Detail 2

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

Copy code
Example:

Copy code
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>

Copy code
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>

Copy code
  **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>

Copy code
  **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>

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

Copy code
  </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>