Implementation

Given task file path .plans/<project>/implementation/NNN-task.md:

Process

Load Critical Patterns (if exists)

Before starting implementation, check for .plans/<project>/critical-patterns.md:

• If exists, read and internalize all patterns
• Apply matching patterns during implementation
• Violations will be flagged as CRITICAL in review

Use TodoWrite to track implementation progress:

☐ Read task file (LLM Prompt, Working Result, Validation)
☐ [LLM Prompt step 1]
☐ [LLM Prompt step 2]
...
☐ Write tests for new functionality
☐ Run full test suite
☐ Mark validation checkboxes
☐ Update status to READY_FOR_TESTING

Convert each step from the task's LLM Prompt into a todo. Mark completed as you progress.

1. Read task file - LLM Prompt, Working Result, Validation, Files
2. Follow LLM Prompt step-by-step, write code + tests, run full suite
3. Update task status using Edit tool:

- For initial implementation: Status: READYFORTESTING - For revision after rejection: Status: READYFORREVIEW (skip testing, go back to review)

1. Append implementation notes using Edit tool (add to end of task file):

``markdown implementation: - Followed LLM Prompt steps 1-N - Implemented [key functionality] - Added [N] tests: all passing - Full test suite: [M]/[M] passing - Working Result verified: ✓ [description] - Files: [list with brief descriptions] ``

1. Mark validation checkboxes: [ ] → [x] using Edit tool
2. Report completion

Stuck Handling

When blocked during implementation:

1. Mark Task as Stuck

• Update status using Edit tool:

- Find: Status: [current status] - Replace: Status: STUCK

• Append notes using Edit tool (add to end of task file):

``markdown implementation: - Attempted [what tried] - BLOCKED: [specific issue] - Launching research agents to investigate... ``

2. Launch Research Agents

Launch 2-3 researcher agents in parallel, each in a mode matching the blocker:

• survey: new technology or approach, best practices, comparisons
• deep-dive: specific error, issue, or implementation examples
• official-docs: API integration, library or framework specifics

Example:

Task(description: "Survey [technology]", prompt: "Mode: survey. How to [solve blocker]?", subagent_type: "experimental:research:researcher")
Task(description: "Official docs for [feature]", prompt: "Mode: official-docs. [library] documentation for [feature]", subagent_type: "experimental:research:researcher")

3. Synthesize Findings

Use research-synthesis skill (from essentials) to:

• Consolidate findings from all agents
• Identify concrete path forward
• Extract actionable implementation guidance

Update task file with research findings using Edit tool (add to end of task file):

**research findings:**
- [Agent 1]: [key insights]
- [Agent 2]: [key insights]
- [Agent 3]: [key insights]

**resolution:**
[Concrete path forward based on research]

4. Continue or Escalate

If unblocked:

• Update status back to IN_PROGRESS
• Capture the learning (auto-invoked):

``` Task( description: "Capture learning from blocker resolution", prompt: "Extract the learning from this resolved blocker.

Problem context: - STUCK notes: [from task file] - Research findings: [from task file]

Resolution: - What worked: [resolution notes] - Task: [task file path]

Save under: .plans/<project>/learnings/", subagent_type: "experimental:capture:knowledge-capturer" ) ```

• Resume implementation following research guidance
• Complete normally as per main Process section

If still stuck after research:

• Keep status as STUCK
• Append escalation notes using Edit tool (add to end of task file):

``markdown escalation: - Research completed but blocker remains - Reason: [why research didn't unblock] - Need: [what's needed - human decision, missing requirement, etc.] ``

• Then STOP and report blocker with full context.

Rejection Handling

If task moved back from review (check for review: notes in task file):

1. Read review notes for blocking issues
2. Fix all CRITICAL and HIGH issues
3. Update status to READYFORREVIEW (go back to review, skip testing)
4. Append revision notes:

`` implementation (revision): - Fixed [issue 1] - Fixed [issue 2] - Re-ran tests: [M]/[M] passing ``

Test Fix Handling

If task moved back from testing (check for testing: notes with NEEDS_FIX):

1. Read testing notes for failures
2. Fix the failing tests or code
3. Update status to READYFORTESTING (go back to testing)
4. Append fix notes:

`` implementation (test fix): - Fixed [test issue] - Re-ran tests: [M]/[M] passing ``

Completion

When implementation is complete:

• Initial implementation: Status = READYFORTESTING
• After review rejection: Status = READYFORREVIEW
• After test failure: Status = READYFORTESTING

Collect Implementation Metadata

Before setting final status, collect metadata for review triage:

**implementation_metadata:**
- files_changed: [count from git diff --stat]
- lines_changed: [insertions + deletions from git diff --stat]
- was_stuck: [true/false - was task ever marked STUCK?]
- research_agents_used: [list agents invoked, or 'none']
- severity_indicators: [list any detected: auth, crypto, payment, database-migration, etc.]
- complexity_indicators: [list any detected: state-machine, external-api, async-patterns, etc.]

Detection rules for severity_indicators:

• Scan Files for: auth, login, password, session, token, jwt, crypto, encrypt, secret, payment, billing, migration, permission, api_key
• If any found, add to severity_indicators list

Detection rules for complexity_indicators:

• Check for: state machines, external API calls, async/await patterns, database queries, caching logic
• If any found, add to complexity_indicators list

This metadata enables the review skill to route to LIGHTWEIGHT or FULL review.

Report: ✅ Implementation complete. Status: [STATUS]