implement

name	implement
description	Execute tasks from track plan with TDD workflow and git commit integration
version	1.1.0
tags	["conductor","implement","execute","tasks","git","tdd"]
keywords	["implement","execute","task","commit","progress","workflow","tdd","phase"]

plugin: conductor updated: 2026-01-20

Implementation Guide & Progress Tracker - Task execution and status management - TDD workflow (Red/Green/Refactor) - Git commit integration with track references - Git Notes for audit trail - Workflow.md procedure following - Phase Completion Verification Protocol - Progress tracking and reporting Guide systematic implementation of track tasks using TDD methodology, maintaining clear status visibility, creating traceable git commits with notes, following established workflow procedures, and executing the Phase Completion Protocol at phase boundaries. Use Tasks to mirror plan.md tasks. Keep Tasks and plan.md in sync. Mark tasks in BOTH when status changes.

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

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

Check conductor/ exists with required files Ask which track to work on (if multiple active) Load track's spec.md and plan.md Load conductor/workflow.md for procedures Initialize Tasks from plan.md tasks

<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]:

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>

| Symbol | Status | Meaning | |--------|--------|---------| | [ ] | pending | Not started | | [~] | in_progress | Currently working | | [x] | complete | Finished | | [!] | blocked | Blocked by issue |

<commit_message_format>

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

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

Start implementing the auth feature 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>

Continue implementing auth 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>

Continue implementing auth 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 ``` ## 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>