implement-task-code

name	implement-task-code
description	Implement a specific task from the implementation plan using strict TDD. Writes failing tests first, then minimal code to pass, with human approval before committing. Tracks status in plan/{prefix}-plan.md.
argument-hint	[prefix] <task number, e.g. "client 1.1" or "1.1">

Implement a specific task from the implementation plan using strict Test-Driven Development methodology.

Input

The user must provide: $ARGUMENTS which may include a design prefix and/or a task number (e.g., "client 1.1", "1.1", "2.3").

• If two parts are given (e.g., "client 1.1"), the first part is the design prefix and the second is the task number.
• If only one part is given and it looks like a task number (contains a dot, e.g., "1.1"), it is the task number and the prefix will be discovered from existing files.
• If no task number is provided, use AskUserQuestion to ask which task to implement. Show eligible tasks from the task tracker.

Expected Folder Structure

project/
├── plan/
│   └── {prefix}-plan.md            # Task plan with batches, tracks, dependencies, and status tracking
├── design/
│   ├── {prefix}-requirements.md    # Reference: requirement IDs for traceability
│   ├── {prefix}-high-level-design.md  # Reference: architectural context
│   └── {prefix}-low-level-design.md   # Reference: class diagrams, interfaces, testing strategy

Process

---

Phase 1: Validate Inputs and Check Status

1. Parse $ARGUMENTS and discover the design prefix

   • If $ARGUMENTS contains two parts (e.g., "client 1.1"), the first part is the prefix and the second is the task number.
   • If $ARGUMENTS contains one part that looks like a task number (contains a dot), it is just the task number — the prefix must be discovered.
   • If $ARGUMENTS is empty, the prefix must be discovered and the task number will be asked for.

2. Resolve the plan file

   • If a prefix was provided, look for plan/{prefix}-plan.md.
   • If no prefix was provided, scan the plan/ directory for files matching *-plan.md. Also check for an unprefixed plan.md.
     • One match: Use it and infer the prefix from the filename (e.g., client-plan.md means prefix is client; unprefixed plan.md means no prefix is used).
     • Multiple matches: Use AskUserQuestion listing the options and ask the user which plan to use.
     • No matches: Use AskUserQuestion to ask where the plan file is located.
   • Once the plan file is found and the prefix is established, use the same prefix for all design doc references throughout.

3. Check for task number argument

   • If the task number is still unknown or not a valid task number format (e.g., "1.1"), read the Task Status Tracker section of plan/{prefix}-plan.md to show eligible tasks
   • Use AskUserQuestion with eligible tasks as options

4. Read the task tracker

   • Read the Task Status Tracker section of plan/{prefix}-plan.md to check task status
   • Parse the status table to understand current state

5. Validate task is eligible

   • Check task is not already [x] completed
   • Check task is not already [~] in progress (warn if so)
   • Check all prerequisite tasks are [x] completed
   • Check for soft conflicts — if a conflicting task is [~] in progress, warn the user that concurrent work will cause merge conflicts on shared files
   • If prerequisites incomplete, warn user and ask if they want to proceed anyway

6. Read task details from plan

   • Look for plan at plan/{prefix}-plan.md
   • Find the task section matching the provided number
   • Extract: objective, instructions, verification criteria, prerequisites, conflicts, parallel group, requirements covered

Phase 1.5: Discover Project Tooling

Before doing any implementation work, figure out how this project runs its toolchain. This is critical since the skill is language-neutral.

1. Check for existing project instructions

   • Look for CLAUDE.md in the project root first
   • If not found, look for AGENTS.md in the project root
   • If either exists, read it and extract commands for: test runner, linter, auto-formatter, build command

2. If instructions are missing or incomplete, discover the toolchain:

   • Check for Makefile (look for test, lint, fmt, check, build targets)
   • Check for Cargo.toml (Rust: cargo test, cargo clippy, cargo fmt, cargo build)
   • Check for package.json (Node: look at scripts for test, lint, format, build)
   • Check for pyproject.toml or setup.cfg (Python: pytest, ruff/flake8, black/ruff format)
   • Check for go.mod (Go: go test ./..., golangci-lint run, gofmt)
   • Check for Justfile, Taskfile.yml, or similar task runner configs
   • If ambiguous, use AskUserQuestion to ask the user

3. Record what you discover

   • If CLAUDE.md already exists: update it with any missing tooling commands, under a ## Development Commands section (or similar existing heading)
   • If CLAUDE.md does not exist: create AGENTS.md with the discovered commands using this format:

     # Project Tooling
     
     ## Development Commands
     
     - **Run tests:** `{command}`
     - **Run linter:** `{command}`
     - **Auto-format:** `{command}`
     - **Build:** `{command}`
     

   • Only write what you've confirmed works — don't guess

4. Use these commands throughout the rest of this skill — the TDD cycle, verification, and pre-commit checks should all use the discovered commands rather than hardcoded assumptions.

Phase 2: Mark Task In Progress

1. Update the Task Status Tracker in plan/{prefix}-plan.md

   • Change the task status from [ ] to [~]

2. Update the "Eligible tasks" list (below the status table in plan/{prefix}-plan.md)

   • Remove this task from the eligible list
   • Eligible = status [ ] AND all prerequisites [x] AND no conflicting tasks [~]

Phase 3: Git Branch Management

All tasks should be implemented on a single shared feature branch until the user merges it. Do NOT create a new branch per task.

1. Check current branch

   • Run git branch to see current branch
   • If already on a feature/* branch, continue using it
   • Only create a new branch if on main or master

2. Create feature branch (only if on main/master)

   • Branch naming convention: feature/implementation
   • This single branch is used for all tasks until merged

3. Confirm branch is ready

   • Ensure working tree is clean or changes are related to the task
   • If there are uncommitted changes from a previous task, commit them first

Phase 4: Gather Context

1. Read relevant design sections

   • Read the low-level design (design/{prefix}-low-level-design.md) for class diagrams, interfaces, type signatures, and testing strategy relevant to this task
   • Reference the requirements doc (design/{prefix}-requirements.md) to understand what requirements this task covers — describe them in plain language, never cite requirement IDs like FR-x.x.x
   • Reference the high-level design (design/{prefix}-high-level-design.md) only if architectural context is needed

2. Read existing code this task depends on

   • Based on the task's prerequisites, read the files produced by those tasks
   • Understand the interfaces and types you'll be working with
   • Keep context lean — only read what's needed for this specific task

3. Create todo list

   • Use TodoWrite to break the task into TDD steps
   • Each todo should follow the TDD cycle:
     • Write failing test
     • Write minimal code to pass
     • Refactor if needed
     • Verify

Phase 5: TDD Implementation Cycle

For each component of the task, follow strict TDD:

Step 1: Write Failing Test

1. Create test file first (test file before implementation file)
2. Write test for expected behavior
   • Test should express the requirement clearly
   • Use the test descriptions from the low-level design's testing strategy where they exist
   • Describe what is being tested in plain language — do NOT reference requirement IDs (e.g., FR-x.x.x) in test names, comments, or code
3. Run the test to confirm it fails
   • Use the test command discovered in Phase 1.5
   • Verify it fails for the right reason (not found, not implemented)

Step 2: Minimal Implementation

1. Write the minimum code to make the test pass
   • Follow the type signatures and interfaces from the low-level design
   • Do not over-engineer
   • Do not add features not covered by tests
   • Do not add error handling not required by current tests
2. Run the test to confirm it passes
3. Run the full test suite to ensure no regressions

Step 3: Refactor (if needed)

1. Improve code quality while keeping tests green
   • Extract functions if too long
   • Improve naming
   • Add necessary comments for complex logic
2. Run tests again after refactoring

Step 4: Repeat

Continue the cycle until all requirements in the task are implemented.

Phase 6: Verify Task Completion

Use the commands discovered in Phase 1.5 for all verification steps:

1. Run verification criteria specified in the task
   • This might be build commands, specific tests, or other checks
2. Run auto-formatter if one was discovered
   • Format before linting to avoid spurious lint failures
3. Run linter if one was discovered
4. Ensure all tests pass
   • Run the full test suite, not just the new tests
5. Run build to confirm the project compiles cleanly

Phase 7: Request Human Approval

STOP before committing. Present a summary to the user:

1. Summary of changes

   • List files created/modified
   • Show git status output
   • Note which requirements are now covered by tests, described in plain language (not by ID)

2. Test results

   • Show test pass/fail status

3. Ask for approval

   • "Would you like me to commit these changes?"
   • Wait for explicit user confirmation

Phase 8: Commit and Update Status (only after approval)

1. Update the Task Status Tracker in plan/{prefix}-plan.md to mark complete (before staging)

   • Change the task status from [~] to [x]
   • Update the "Eligible tasks" list to add newly eligible tasks
   • Update the "Progress" count

2. Stage specific files (not git add .)

   • List files explicitly to avoid committing unintended files
   • Never commit secrets, credentials, or sensitive files
   • Include plan/{prefix}-plan.md in the staged files

3. Create commit with descriptive message

   • Format:

     Implement Task X.Y: {Task Title}
     
     {Brief description of what was implemented}
     - Bullet points of key changes
     
     Requirements covered:
     - {plain language description of each requirement}
     
     Co-Authored-By: Claude Opus 4.6 <[e-mail]>
     

   • IMPORTANT: Never cite requirement IDs (e.g., FR-1.2.3), section numbers, or other numeric references from design documents in commit messages, code comments, test names, or any other output. Always describe what the requirement is in plain language instead.

4. Verify commit succeeded

   • Show git log --oneline -1 to confirm
   • Show final git status

---

Task Status Tracker Format

The Task Status Tracker section in plan/{prefix}-plan.md uses this format:

| Task | Description | Prerequisites | Conflicts | Status |
|------|-------------|---------------|-----------|--------|
| 1.1 | Initialize project structure | None | — | [x] |
| 1.2 | Implement core types | 1.1 | 1.3 (shared mod.rs) | [ ] |
| 1.3 | Implement error types | 1.1 | 1.2 (shared mod.rs) | [ ] |

Status values:

• [ ] — Not started
• [~] — In progress
• [x] — Completed

Eligible task rules:

• Status is [ ]
• All prerequisites are [x]
• No conflicting task is [~]

To update status: Use Edit tool to change the status cell in the table row.

---

TDD Guidelines

The Three Laws of TDD:

1. You may not write production code until you have written a failing test
2. You may not write more of a test than is sufficient to fail
3. You may not write more production code than is sufficient to pass the test

What counts as a "failing test":

• Compilation failure (file/function doesn't exist) counts as failing
• Test assertion failure counts as failing
• For infrastructure tasks (directory structure, config files), the "test" may be the build command failing

When TDD is impractical:

• Pure configuration files (.gitignore, Makefile, K8s manifests, Cargo.toml)
• For these, the verification step serves as the "test"

---

Error Handling

If prerequisites seem missing:

• Warn the user but allow them to proceed
• They may have implemented prerequisites in a different way

If a conflicting task is in progress:

• Warn the user explicitly: "Task X.Z is in progress and conflicts with this task (shared file: mod.rs). Concurrent work will require manual merge resolution."
• Ask if they want to proceed anyway

If task is already in progress:

• Warn user and ask if they want to continue from where it left off
• Or reset the status and start fresh

If tests fail unexpectedly:

• Show the failure output
• Attempt to diagnose and fix
• If stuck, ask user for guidance

If pre-commit hooks block commit:

• Attempt to fix issues (linting, formatting)
• If coverage requirements block an infrastructure task, suggest --no-verify with user approval
• Never use --no-verify without explicit user consent

If user abandons task:

• If user explicitly abandons, reset status from [~] back to [ ] in the Task Status Tracker
• Update eligible tasks list

---

Output

After successful completion:

• Task implemented following TDD methodology
• All tests passing
• Code committed to feature branch
• Task Status Tracker in plan/{prefix}-plan.md updated with [x] status
• Eligible tasks list updated
• Summary of what was implemented and which requirements are now covered (described in plain language, never by ID)

The user can then continue to the next task or create a PR when a batch is complete.