@leeovery/claude-technical-workflows 2.0.52 → 2.0.54

package/README.md

@@ -185,7 +185,7 @@ When using the full workflow, it progresses through six distinct phases:
 │ • Plan check  │   │ • Tests first │   │ • Phases      │
 │ • Specs check │   │ • Then code   │   │ • Tasks       │
 │ • Test quality│   │ • Commit often│   │ • Criteria    │
-│ • Code quality│   │ • Phase gates │   │ • Outputs     │
+│ • Code quality│   │ • Task gates  │   │ • Outputs     │
 └───────────────┘   └───────────────┘   └───────────────┘
 ```
 
@@ -197,7 +197,7 @@ When using the full workflow, it progresses through six distinct phases:
 
 **Phase 4 - Planning:** Converts specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear, Backlog.md).
 
-**Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, and stops for user approval between phases.
+**Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, with per-task approval gates (auto mode available).
 
 **Phase 6 - Review:** Validates completed work against specification requirements and plan acceptance criteria. The specification is the validated source of truth; earlier phases may contain rejected ideas that were intentionally filtered out. Provides structured feedback without fixing code directly.
 

package/agents/implementation-task-executor.md

@@ -0,0 +1,79 @@
+---
+name: implementation-task-executor
+description: Implements a single plan task via strict TDD. Invoked by technical-implementation skill for each task.
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: inherit
+---
+
+# Implementation Task Executor
+
+Act as an **expert senior developer** executing ONE task via strict TDD. Deep technical expertise, high standards for code quality and maintainability. Follow project-specific skills for language/framework conventions.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **tdd-workflow.md path** — TDD cycle rules
+2. **code-quality.md path** — Quality standards
+3. **Specification path** — For context when rationale is unclear
+4. **Project skill paths** — Relevant `.claude/skills/` paths for framework conventions
+5. **Task content** — Task ID, phase, and all instructional content: goal, implementation steps, acceptance criteria, tests, edge cases, context, notes. This is your scope.
+
+On **re-invocation after review feedback**, you also receive:
+- **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+- **Specific issues to address**
+
+## Your Process
+
+1. **Read tdd-workflow.md** — absorb the full TDD cycle before writing any code
+2. **Read code-quality.md** — absorb quality standards
+3. **Read project skills** — absorb framework conventions, testing patterns, architecture patterns
+4. **Read specification** (if provided) — understand broader context for this task
+5. **Explore codebase** — understand what exists before writing anything:
+   - Read files and tests related to the task's domain
+   - Identify patterns, conventions, and structures you'll need to follow or extend
+   - Check for existing code that the task builds on or integrates with
+6. **Execute TDD cycle** — follow the process in tdd-workflow.md for each acceptance criterion and test case.
+7. **Verify all acceptance criteria met** — every criterion from the task must be satisfied
+8. **Return structured result**
+
+## Code Only
+
+You write code and tests, and run tests. That is all.
+
+You do **NOT**:
+- Commit or stage changes in git (reading git history is fine)
+- Update tracking files or plan progress
+- Mark tasks complete
+- Make decisions about what to implement next
+
+Those are the orchestrator's responsibility.
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
+1. **No code before tests** — Write the failing test first. Always.
+2. **No test changes to pass** — Fix the code, not the test.
+3. **No scope expansion** — Only what's in the task. If you think "I should also handle X" — STOP. It's not in the task, don't build it.
+4. **No assumptions** — Uncertain about intent or approach? STOP and report back.
+5. **No git writes** — Do not commit or stage. Reading git history is fine. The orchestrator handles all git writes after review approval.
+6. **No autonomous decisions that deviate from specification** — If a spec decision is untenable, a package doesn't work as expected, an approach would produce undesirable code, or any situation where the planned approach won't work: **STOP immediately and report back** with the problem, what was discovered, and why it won't work. Do NOT choose an alternative. Do NOT work around it. Report and stop.
+7. **Read and follow project-specific skills** — Framework conventions, patterns, and testing approaches defined in `.claude/skills/` are authoritative for style and structure.
+
+## Your Output
+
+Return a structured completion report:
+
+```
+STATUS: complete | blocked | failed
+TASK: {task name}
+SUMMARY: {what was done}
+FILES_CHANGED: {list of files created/modified}
+TESTS_WRITTEN: {list of test files/methods}
+TEST_RESULTS: {all passing | failures — details}
+ISSUES: {any concerns, blockers, or deviations discovered}
+```
+
+- If STATUS is `blocked` or `failed`, ISSUES **must** explain why and what decision is needed.
+- If STATUS is `complete`, all acceptance criteria must be met and all tests passing.

package/agents/implementation-task-reviewer.md

@@ -0,0 +1,97 @@
+---
+name: implementation-task-reviewer
+description: Reviews a single implemented task for spec conformance, acceptance criteria, and architectural quality. Invoked by technical-implementation skill after each task.
+tools: Read, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Task Reviewer
+
+Act as a **senior architect** performing independent verification of ONE completed task. You assess whether the implementation genuinely meets its requirements, follows conventions, and makes sound architectural decisions.
+
+The executor must not mark its own homework — that's why you exist.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Specification path** — The validated specification for design decision context
+2. **Task content** — Same task content the executor received: task ID, phase, and all instructional content
+3. **Project skill paths** — Relevant `.claude/skills/` paths for checking framework convention adherence
+
+## Your Process
+
+1. **Read the specification** for relevant context — understand the broader design intent
+2. **Check unstaged changes** — use `git diff` and `git status` to identify files changed by the executor
+3. **Read all changed files** — implementation code and test code
+4. **Read project skills** — understand framework conventions, testing patterns, architecture patterns
+5. **Evaluate all five review dimensions** (see below)
+
+## Review Dimensions
+
+### 1. Spec Conformance
+Does the implementation match the specification's decisions?
+- Are the spec's chosen approaches followed (not alternatives)?
+- Do data structures, interfaces, and behaviors align with spec definitions?
+- Any drift from what was specified?
+
+### 2. Acceptance Criteria
+Are all criteria genuinely met — not just self-reported?
+- Walk through each criterion from the task
+- Verify the code actually satisfies it (don't trust the executor's claim)
+- Check for criteria that are technically met but miss the intent
+
+### 3. Test Adequacy
+Do tests actually verify the criteria? Are edge cases covered?
+- Is there a test for each acceptance criterion?
+- Would the tests fail if the feature broke?
+- Are edge cases from the task's test cases covered?
+- Flag both under-testing AND over-testing
+
+### 4. Convention Adherence
+Are project skill conventions followed?
+- Check against framework patterns from `.claude/skills/`
+- Architecture conventions respected?
+- Testing conventions followed (test structure, naming, patterns)?
+- Code style consistent with project?
+
+### 5. Architectural Quality
+Is this a sound design decision? Will it compose well with future tasks?
+- Does the structure make sense for this task's scope?
+- Are there coupling or abstraction concerns?
+- Will this cause problems for subsequent tasks in the phase?
+- Are there structural concerns that should be raised now rather than compounding?
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the review.**
+
+1. **Read-only** — Report findings, do not fix anything. Do not edit, write, or create files.
+2. **No git writes** — Do not commit or stage. Reading git history and diffs is fine. The orchestrator handles all git writes.
+3. **One task only** — You review exactly one plan task per invocation.
+4. **Independent judgement** — Evaluate the code yourself. Do not trust the executor's self-assessment.
+5. **All five dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, and architectural quality.
+6. **Be specific** — Include file paths and line numbers for every issue. Vague findings are not actionable.
+7. **Proportional** — Prioritize by impact. Don't nitpick style when the architecture is wrong.
+8. **Task scope only** — Only review what's in the task. Don't flag issues outside the task's scope.
+
+## Your Output
+
+Return a structured finding:
+
+```
+TASK: {task name}
+VERDICT: approved | needs-changes
+SPEC_CONFORMANCE: {conformant | drift detected — details}
+ACCEPTANCE_CRITERIA: {all met | gaps — list}
+TEST_COVERAGE: {adequate | gaps — list}
+CONVENTIONS: {followed | violations — list}
+ARCHITECTURE: {sound | concerns — details}
+ISSUES:
+- {specific issue with file:line reference}
+NOTES:
+- {non-blocking observations}
+```
+
+- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references
+- NOTES are for non-blocking observations — things worth noting but not requiring changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.52",
+  "version": "2.0.54",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-implementation/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: technical-implementation
-description: "Execute implementation plans using strict TDD workflow with quality gates. Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Writes tests first, implements to pass, commits frequently, stops for user approval between phases."
+description: "Orchestrate implementation of plans using agent-based TDD workflow with per-task review and approval gate (auto mode available). Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Dispatches executor and reviewer agents per task, commits after review approval."
 ---
 
 # Technical Implementation
 
-Act as **expert senior developer** who builds quality software through disciplined TDD. Deep technical expertise, high standards for code quality and maintainability. Follow project-specific skills for language/framework conventions.
+Orchestrate implementation by dispatching **executor** and **reviewer** agents per task. Each agent invocation starts fresh — flat context, no accumulated state.
 
-Execute plans through strict TDD. Write tests first, then code to pass them.
+- **Executor** (`.claude/agents/implementation-task-executor.md`) — implements one task via strict TDD
+- **Reviewer** (`.claude/agents/implementation-task-reviewer.md`) — independently verifies the task (opus)
+
+The orchestrator owns: plan reading, task extraction, agent invocation, git operations, tracking, task gates.
 
 ## Purpose in the Workflow
 
@@ -15,7 +18,7 @@ This skill can be used:
 - **Sequentially**: To execute a plan created by technical-planning
 - **Standalone** (Contract entry): To execute any plan that follows plan-format conventions
 
-Either way: Execute via strict TDD - tests first, implementation second.
+Either way: dispatch agents per task — executor implements via TDD, reviewer verifies independently.
 
 ### What This Skill Needs
 
@@ -44,235 +47,177 @@ If no specification is available, the plan becomes the sole authority for design
 Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:
 
 1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
-2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
-3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
-4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+2. **Check task progress in the plan** — use the plan adapter's instructions to read the plan's current state. Also read the implementation tracking file and any other working documents for additional context.
+3. **Check `task_gate_mode`** in the tracking file — if `auto`, the user previously opted out of per-task gates for this session.
+4. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+5. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
 
 Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
 
 ---
 
-## Hard Rules
-
-**MANDATORY. No exceptions. Violating these rules invalidates the work.**
-
-1. **No code before tests** - Write the failing test first. Always.
-2. **No test changes to pass** - Fix the code, not the test.
-3. **No scope expansion** - If it's not in the plan, don't build it.
-4. **No assumptions** - Uncertain? Check specification. Still uncertain? Stop and ask.
-5. **Commit after green** - Every passing test = commit point.
-
-**Pragmatic TDD**: The discipline is test-first sequencing, not artificial minimalism. Write complete, functional implementations - don't fake it with hardcoded returns. "Minimal" means no gold-plating beyond what the test requires.
+## Orchestrator Hard Rules
 
-See **[tdd-workflow.md](references/tdd-workflow.md)** for the full TDD cycle, violation recovery, and guidance on when tests can change.
+1. **No autonomous decisions on spec deviations** — when the executor reports a blocker or spec deviation, present to user and STOP. Never resolve on the user's behalf.
+2. **All git operations are the orchestrator's responsibility** — agents never commit, stage, or interact with git.
 
-## Workflow
+---
 
-### IMPORTANT: Setup Instructions
+## Step 1: Environment Setup
 
 Run setup commands EXACTLY as written, one step at a time.
 Do NOT modify commands based on other project documentation (CLAUDE.md, etc.).
-Do NOT parallelize steps - execute each command sequentially.
-Complete ALL setup steps before proceeding to implementation work.
-
-1. **Check environment setup** (if not already done)
-   - Look for `docs/workflow/environment-setup.md`
-   - If exists and states "No special setup required", skip to step 2
-   - If exists with instructions, follow the setup before proceeding
-   - If missing, ask: "Are there any environment setup instructions I should follow?"
-
-   See **[environment-setup.md](references/environment-setup.md)** for details.
-
-2. **Read the plan** from the provided location (typically `docs/workflow/planning/{topic}.md`)
-   - Check the `format` field in frontmatter
-   - Load the output adapter: `skills/technical-planning/references/output-formats/output-{format}.md`
-   - If no format field, ask user which format the plan uses
-   - Follow the **Implementation** section for how to read tasks and update progress
+Do NOT parallelize steps — execute each command sequentially.
+Complete ALL setup steps before proceeding.
 
-3. **Read the TDD workflow** - Load **[tdd-workflow.md](references/tdd-workflow.md)** before writing any code. This is mandatory.
+Load **[environment-setup.md](references/environment-setup.md)** and follow its instructions.
 
-4. **Initialize or resume implementation tracking**
-   - Check if `docs/workflow/implementation/{topic}.md` exists
-   - **If not**: Create it with the initial tracking frontmatter (see [Implementation Tracking](#implementation-tracking) below), set `status: in-progress`, `started: {today}`. Commit: `impl({topic}): start implementation`
-   - **If exists**: Read it to determine current position (see [Resuming After Context Refresh](#resuming-after-context-refresh) below)
+#### If `docs/workflow/environment-setup.md` states "No special setup required"
 
-5. **For each phase** (working through phases and tasks in plan order):
-   - Announce phase start and review acceptance criteria
-   - For each task: follow the TDD cycle loaded in step 3
-   - After each task completes: update progress in **both** the output format (as loaded in step 2) **and** the implementation tracking file (see below)
-   - Verify all phase acceptance criteria met
-   - **Ask user before proceeding to next phase**
+→ Proceed to **Step 2**.
 
-6. **Reference specification** when rationale unclear
+#### If setup instructions exist
 
-## Implementation Tracking
-
-Each topic has a tracking file at `docs/workflow/implementation/{topic}.md` that records progress programmatically (frontmatter) and as a human-readable summary (body).
-
-### Initial Tracking File
-
-When starting implementation for a topic, create:
-
-```yaml
----
-topic: {topic}
-plan: ../planning/{topic}.md
-format: {format from plan}
-status: in-progress
-current_phase: 1
-current_task: ~
-completed_phases: []
-completed_tasks: []
-started: YYYY-MM-DD
-updated: YYYY-MM-DD
-completed: ~
----
+Follow them. Complete ALL steps before proceeding.
 
-# Implementation: {Topic Name}
+→ Proceed to **Step 2**.
 
-Implementation started.
-```
+#### If no setup file exists
 
-### Updating Progress
+Ask:
 
-When a task or phase completes, update **two** things:
+> "No environment setup document found. Are there any setup instructions I should follow before implementing?"
 
-1. **Output format progress** — Follow the output adapter's Implementation section (loaded in workflow step 2) to mark tasks/phases complete in the plan index file and any format-specific files. This is the plan's own progress tracking.
+**STOP.** Wait for user response.
 
-2. **Implementation tracking file** — Update `docs/workflow/implementation/{topic}.md` as described below. This enables cross-topic dependency resolution and resume detection.
+Save their instructions to `docs/workflow/environment-setup.md` (or "No special setup required." if none needed). Commit.
 
-**After each task completes (tracking file):**
-- Append the task ID to `completed_tasks`
-- Update `current_task` to the next task (or `~` if phase done)
-- Update `updated` date
-- Update the body progress section
+→ Proceed to **Step 2**.
 
-**After each phase completes (tracking file):**
-- Append the phase number to `completed_phases`
-- Update `current_phase` to the next phase (or leave as last)
-- Update the body progress section
+---
 
-**On implementation completion (tracking file):**
-- Set `status: completed`
-- Set `completed: {today}`
-- Commit: `impl({topic}): complete implementation`
+## Step 2: Read Plan + Load Plan Adapter
 
-Task IDs in `completed_tasks` use whatever ID format the output format assigns -- the same IDs used in dependency references.
+1. Read the plan from the provided location (typically `docs/workflow/planning/{topic}.md`)
+2. Plans can be stored in various formats. The `format` field in the plan's frontmatter identifies which format this plan uses.
+3. Load the corresponding adapter file: `skills/technical-planning/references/output-formats/output-{format}.md` — this document provides instructions for reading tasks from and writing progress to the plan. Hereafter referred to as the **plan adapter**.
+4. If no `format` field exists, ask the user which format the plan uses.
+5. Read the plan adapter's **Implementation** section to understand the instructions — they apply during Step 5.
 
-### Body Progress Section
+→ Proceed to **Step 3**.
 
-The body provides a human-readable summary for context refresh:
+---
 
-```markdown
-# Implementation: {Topic Name}
+## Step 3: Project Skills Discovery
 
-## Phase 1: Foundation
-All tasks completed.
+#### If `.claude/skills/` does not exist or is empty
 
-## Phase 2: Core Logic (current)
-- Task 2.1: Service layer - done
-- Task 2.2: Validation - done
-- Task 2.3: Controllers (next)
+```
+No project skills found. Proceeding without project-specific conventions.
 ```
 
-## Progress Announcements
+→ Proceed to **Step 4**.
 
-Keep user informed of progress:
+#### If project skills exist
 
-```
-📍 Starting Phase 2: Core Cache Functionality
-📝 Task 1: Implement CacheManager.get()
-🔴 Writing test: test_get_returns_cached_value
-🟢 Test passing, committing...
-✅ Phase 2 complete. Ready for Phase 3?
-```
+Scan `.claude/skills/` for project-specific skill directories. Present findings:
 
-## When to Reference Specification
+> Found these project skills that may be relevant to implementation:
+> - `{skill-name}` — {brief description}
+> - `{skill-name}` — {brief description}
+> - ...
+>
+> Which of these should I pass to the implementation agents? (all / list / none)
 
-Check the specification when:
+**STOP.** Wait for user to confirm which skills are relevant.
 
-- Task rationale is unclear
-- Multiple valid approaches exist
-- Edge case handling not specified in plan
-- You need the "why" behind a decision
+Store the selected skill paths — they will be persisted to the tracking file in Step 4.
 
-**Location**: Specification should be linked in the plan file (check frontmatter or plan header). Ask user if not found.
+→ Proceed to **Step 4**.
 
-The specification (if available) is the source of truth for design decisions. If no specification exists, the plan is the authority.
+---
 
-**Important:** If prior source material exists (research notes, discussion documents, etc.), ignore it during implementation. It may contain outdated ideas, rejected approaches, or superseded decisions. The specification filtered and validated that content - refer only to the specification and plan.
+## Step 4: Initialize Implementation Tracking
 
-## Project-Specific Conventions
+#### If `docs/workflow/implementation/{topic}.md` already exists
 
-Follow project-specific coding skills in `.claude/skills/` for:
+Reset `task_gate_mode` to `gated` in the tracking file before proceeding (fresh session = fresh gate).
 
-- Framework patterns (Laravel, Vue, Python, etc.)
-- Code style and formatting
-- Architecture conventions
-- Testing conventions
+If `project_skills` is populated in the tracking file, present for confirmation:
 
-This skill contains the implementation **process**. Project skills contain the **style**.
+> "Previous session used these project skills:
+> - `{skill-name}` — {path}
+> - ...
+>
+> - **`y`/`yes`** — Keep these, proceed
+> - **`change`** — Add or remove skills"
 
-## Handling Problems
+**STOP.** Wait for user choice.
 
-### Plan is Incomplete
+- **`y`/`yes`**: Proceed with the persisted paths.
+- **`change`**: Re-run discovery (Step 3), update `project_skills` in the tracking file.
 
-Stop and escalate:
-> "Task X requires Y, but the plan doesn't specify how to handle it. Options: (A) ... (B) ... Which approach?"
+→ Proceed to **Step 5**.
 
-### Plan Seems Wrong
+#### If no tracking file exists
 
-Stop and escalate:
-> "The plan says X, but during implementation I discovered Y. This affects Z. Should I continue as planned or revise?"
+Create `docs/workflow/implementation/{topic}.md`:
 
-### Test Reveals Design Flaw
+```yaml
+---
+topic: {topic}
+plan: ../planning/{topic}.md
+format: {format from plan}
+status: in-progress
+task_gate_mode: gated
+project_skills: []
+current_phase: 1
+current_task: ~
+completed_phases: []
+completed_tasks: []
+started: YYYY-MM-DD  # Use today's actual date
+updated: YYYY-MM-DD  # Use today's actual date
+completed: ~
+---
 
-Stop and escalate:
-> "Writing tests for X revealed that the approach won't work because Y. Need to revisit the design."
+# Implementation: {Topic Name}
+
+Implementation started.
+```
 
-Never silently deviate from the plan.
+After creating the file, populate `project_skills` with the paths confirmed in Step 3 (empty array if none).
 
-## Quality Standards
+Commit: `impl({topic}): start implementation`
 
-See [code-quality.md](references/code-quality.md) for:
+→ Proceed to **Step 5**.
 
-- DRY (without premature abstraction)
-- SOLID principles
-- Cyclomatic complexity
-- YAGNI enforcement
+---
 
-## Phase Completion Checklist
+## Step 5: Task Loop
 
-Before marking a phase complete:
+Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its instructions as written.
 
-- [ ] All phase tasks implemented
-- [ ] All tests passing
-- [ ] Tests cover task acceptance criteria
-- [ ] No skipped edge cases from plan
-- [ ] Code committed
-- [ ] Manual verification steps completed (if specified in plan)
+→ After the loop completes, proceed to **Step 6**.
 
-## Commit Practices
+---
 
-- Commit after each passing test
-- Use descriptive commit messages referencing the task
-- Commits can be squashed before PR if desired
-- Never commit failing tests (except intentional red phase in TDD)
+## Step 6: Mark Implementation Complete
 
-Example commit message:
-```
-feat(cache): implement CacheManager.get() with TTL support
+Update the tracking file (`docs/workflow/implementation/{topic}.md`):
+- Set `status: completed`
+- Set `completed: YYYY-MM-DD` (use today's actual date)
+- Update `updated` date
 
-- Returns cached value if exists and not expired
-- Falls back to DB on cache miss
-- Handles connection failures gracefully
+Commit: `impl({topic}): complete implementation`
 
-Task: Phase 2, Task 1
-```
+---
 
 ## References
 
-- **[environment-setup.md](references/environment-setup.md)** - Environment setup before implementation
-- **[plan-execution.md](references/plan-execution.md)** - Following plans, phase verification, hierarchy
-- **[tdd-workflow.md](references/tdd-workflow.md)** - TDD cycle, test derivation, when tests can change
-- **[code-quality.md](references/code-quality.md)** - DRY, SOLID, complexity, YAGNI
+- **[environment-setup.md](references/environment-setup.md)** — Environment setup before implementation
+- **[steps/task-loop.md](references/steps/task-loop.md)** — Task execution loop, task gates, tracking, commits
+- **[steps/invoke-executor.md](references/steps/invoke-executor.md)** — How to invoke the executor agent
+- **[steps/invoke-reviewer.md](references/steps/invoke-reviewer.md)** — How to invoke the reviewer agent
+- **[task-normalisation.md](references/task-normalisation.md)** — Normalised task shape for agent invocation
+- **[tdd-workflow.md](references/tdd-workflow.md)** — TDD cycle (passed to executor agent)
+- **[code-quality.md](references/code-quality.md)** — Quality standards (passed to executor agent)

package/skills/technical-implementation/references/steps/invoke-executor.md

@@ -0,0 +1,42 @@
+# Invoke Executor
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the `implementation-task-executor` agent (`.claude/agents/implementation-task-executor.md`) to implement one task.
+
+---
+
+## Invoke the Agent
+
+Invoke `implementation-task-executor` with these file paths:
+
+1. **tdd-workflow.md**: `.claude/skills/technical-implementation/references/tdd-workflow.md`
+2. **code-quality.md**: `.claude/skills/technical-implementation/references/code-quality.md`
+3. **Specification path**: from the plan's frontmatter (if available)
+4. **Project skill paths**: from `project_skills` in the implementation tracking file
+5. **Task content**: normalised task content (see [task-normalisation.md](../task-normalisation.md))
+
+On **re-invocation after review feedback**, also include:
+- **User-approved review notes**: verbatim or as modified by the user
+- **Specific issues to address**: the ISSUES from the review
+
+---
+
+## Expected Result
+
+The agent returns a structured report:
+
+```
+STATUS: complete | blocked | failed
+TASK: {task name}
+SUMMARY: {2-5 lines — commentary, decisions made, anything off-script}
+TEST_RESULTS: {all passing | failures — details only if failures}
+ISSUES: {blockers or deviations — omit if none}
+```
+
+- `complete`: all acceptance criteria met, tests passing
+- `blocked` or `failed`: ISSUES explains why and what decision is needed
+
+Keep the report minimal. "All passing" is sufficient for TEST_RESULTS when nothing failed. ISSUES can be omitted entirely on a clean run.

package/skills/technical-implementation/references/steps/invoke-reviewer.md

@@ -0,0 +1,40 @@
+# Invoke Reviewer
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the `implementation-task-reviewer` agent (`.claude/agents/implementation-task-reviewer.md`) to independently verify a completed task.
+
+---
+
+## Invoke the Agent
+
+Invoke `implementation-task-reviewer` with:
+
+1. **Specification path**: same path given to the executor
+2. **Task content**: same normalised task content the executor received
+3. **Project skill paths**: from `project_skills` in the implementation tracking file
+
+---
+
+## Expected Result
+
+The agent returns a structured finding:
+
+```
+TASK: {task name}
+VERDICT: approved | needs-changes
+SPEC_CONFORMANCE: {conformant | drift detected — details}
+ACCEPTANCE_CRITERIA: {all met | gaps — list}
+TEST_COVERAGE: {adequate | gaps — list}
+CONVENTIONS: {followed | violations — list}
+ARCHITECTURE: {sound | concerns — details}
+ISSUES:
+- {specific issue with file:line reference}
+NOTES:
+- {non-blocking observations}
+```
+
+- `approved`: task passes all five review dimensions
+- `needs-changes`: ISSUES contains specific, actionable items

package/skills/technical-implementation/references/steps/task-loop.md

@@ -0,0 +1,164 @@
+# Task Loop
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+Follow these stages sequentially, one task at a time: retrieve a task from the plan (delegating to the plan adapter for ordering and extraction), run it through execution, review, gating, and commit, then repeat until all tasks are done.
+
+Every iteration must follow stages A through E fully — do not abbreviate, skip, or compress stages based on previous iterations.
+
+```
+A. Retrieve next task
+B. Execute task → invoke-executor.md
+   → Executor Blocked (conditional)
+C. Review task → invoke-reviewer.md
+   → Review Changes (conditional)
+D. Task gate (gated → prompt user / auto → announce)
+E. Update progress + commit
+→ loop back to A until done
+```
+
+---
+
+## A. Retrieve Next Task
+
+1. Follow the plan adapter's Reading instructions to determine the next available task.
+2. If no available tasks remain → skip to **When All Tasks Are Complete**.
+3. Normalise the task content following **[task-normalisation.md](../task-normalisation.md)**.
+
+---
+
+## B. Execute Task
+
+1. Load **[invoke-executor.md](invoke-executor.md)** and follow its instructions. Pass the normalised task content.
+2. **STOP.** Do not proceed until the executor has returned its result.
+3. On receipt of result, route on STATUS:
+   - `blocked` or `failed` → follow **Executor Blocked** below
+   - `complete` → proceed to **C. Review Task**
+
+### Executor Blocked
+
+Present the executor's ISSUES to the user:
+
+> **Task {id}: {Task Name} — {blocked/failed}**
+>
+> {executor's ISSUES content}
+>
+> - **`retry`** — Re-invoke the executor with your comments (provide below)
+> - **`skip`** — Skip this task and move to the next
+> - **`stop`** — Stop implementation entirely
+
+**STOP.** Wait for user choice.
+
+#### If `retry`
+
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the user's comments added to the task context.
+
+#### If `skip`
+
+→ Proceed to **E. Update Progress and Commit** (mark task as skipped).
+
+#### If `stop`
+
+→ Return to the skill for **Step 6**.
+
+---
+
+## C. Review Task
+
+1. Load **[invoke-reviewer.md](invoke-reviewer.md)** and follow its instructions. Pass the executor's result.
+2. **STOP.** Do not proceed until the reviewer has returned its result.
+3. On receipt of result, route on VERDICT:
+   - `needs-changes` → follow **Review Changes** below
+   - `approved` → proceed to **D. Task Gate**
+
+### Review Changes
+
+Present the reviewer's findings to the user:
+
+> **Review for Task {id}: {Task Name} — needs changes**
+>
+> {ISSUES from reviewer}
+>
+> Notes (non-blocking):
+> {NOTES from reviewer}
+>
+> - **`y`/`yes`** — Accept these notes and pass them to the executor to fix
+> - **`skip`** — Override the reviewer and proceed as-is
+> - **Comment** — Modify or add to the notes before passing to the executor
+
+**STOP.** Wait for user choice.
+
+- **`y`/`yes`**: → Return to the top of **B. Execute Task** and re-invoke the executor with the reviewer's notes added.
+- **`skip`**: → Proceed to **D. Task Gate**.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the user's notes.
+
+---
+
+## D. Task Gate
+
+After the reviewer approves a task, check the `task_gate_mode` field in the implementation tracking file.
+
+### If `task_gate_mode: gated`
+
+Present a summary and wait for user input:
+
+> **Task {id}: {Task Name} — approved**
+>
+> Phase: {phase number} — {phase name}
+> {executor's SUMMARY — brief commentary, decisions, implementation notes}
+>
+> **Options:**
+> - **`y`/`yes`** — Approve, commit, continue to next task
+> - **`auto`** — Approve this and all future reviewer-approved tasks automatically
+> - **Comment** — Feedback the reviewer missed (triggers a fix round)
+
+**STOP.** Wait for user input.
+
+- **`y`/`yes`**: → Proceed to **E. Update Progress and Commit**.
+- **`auto`**: Note that `task_gate_mode` should be updated to `auto` during the commit step. → Proceed to **E. Update Progress and Commit**.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the user's notes added.
+
+### If `task_gate_mode: auto`
+
+Announce the result (one line, no stop):
+
+> **Task {id}: {Task Name} — approved** (phase {N}: {phase name}, {brief summary}). Committing.
+
+→ Proceed to **E. Update Progress and Commit**.
+
+---
+
+## E. Update Progress and Commit
+
+**Update task progress in the plan** — follow the plan adapter's Implementation section for instructions on how to mark the task complete.
+
+**Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}.md`):
+- Append the task ID to `completed_tasks`
+- Update `current_phase` if phase changed
+- Update `current_task` to the next task (or `~` if done)
+- Update `updated` to today's date
+- If user chose `auto` this turn: update `task_gate_mode: auto`
+
+The tracking file is a derived view for discovery scripts and cross-topic dependency resolution — not a decision-making input during implementation (except `task_gate_mode`).
+
+**Commit all changes** in a single commit:
+
+```
+impl({topic}): T{task-id} — {brief description}
+```
+
+Code, tests, plan progress, and tracking file — one commit per approved task.
+
+This is the end of this iteration.
+
+→ Proceed to **A. Retrieve Next Task** and follow the instructions as written.
+
+---
+
+## When All Tasks Are Complete
+
+> "All tasks complete. {M} tasks implemented."
+
+→ Return to the skill for **Step 6**.

package/skills/technical-implementation/references/task-normalisation.md

@@ -0,0 +1,25 @@
+# Task Normalisation
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+Normalise task content into this shape before passing to executor and reviewer agents. The plan adapter tells you how to extract the task — this reference tells you what shape to present it in.
+
+---
+
+## Template
+
+```
+TASK: {id} — {name}
+PHASE: {N} — {phase name}
+
+INSTRUCTIONS:
+{all instructional content from the task}
+```
+
+## Rules
+
+- **Include** everything instructional: goal, implementation steps, acceptance criteria, tests, edge cases, context, notes
+- **Strip** meta fields: status, priority, dependencies, dates, progress markers
+- **Preserve** the internal structure of the instructional content as-is from the plan — do not summarise, reorder, or rewrite

package/skills/technical-implementation/references/tdd-workflow.md

@@ -6,7 +6,7 @@
 
 ## The Cycle
 
-RED → GREEN → REFACTOR → COMMIT
+RED → GREEN → REFACTOR
 
 Repeat for each task. **Never skip steps. Never reorder.**
 
@@ -64,9 +64,9 @@ If you think "I should also handle X" - STOP. Write a test for X first.
 
 Run tests after. If they fail, undo the refactor.
 
-## COMMIT: After Every Green
+## COMMIT: Orchestrator Responsibility
 
-Commit with descriptive message referencing the task. This is non-negotiable - it creates recovery points.
+The executor agent does NOT commit. Your responsibility ends at GREEN — all tests passing. The orchestrator commits after review approval, one commit per approved task covering code, tests, tracking, and plan progress.
 
 ## When Tests CAN Change
 

package/skills/technical-implementation/references/plan-execution.md

@@ -1,49 +0,0 @@
-# Plan Execution
-
-*Reference for **[technical-implementation](../SKILL.md)***
-
----
-
-## Plan Structure
-
-Plans live in `docs/workflow/planning/{topic}.md` with phases and tasks.
-
-**Phase** = grouping with acceptance criteria
-**Task** = single TDD cycle = one commit
-
-## Before Starting
-
-1. Read entire plan
-2. Read specification for context
-3. Check dependencies and blockers
-
-## Execution Flow
-
-For each phase:
-1. Announce phase start with acceptance criteria
-2. For each task: follow the TDD cycle in **[tdd-workflow.md](tdd-workflow.md)**
-3. Verify all acceptance criteria met
-4. **Wait for user confirmation before next phase**
-
-## Referencing Specification
-
-Check `docs/workflow/specification/{topic}.md` when:
-- Task rationale unclear
-- Multiple valid approaches
-- Edge case handling not specified
-
-The specification is the source of truth. Don't look further back than this.
-
-## Handling Problems
-
-- **Plan incomplete**: Stop and escalate with options
-- **Plan seems wrong**: Stop and escalate discrepancy
-- **Discovery during implementation**: Stop and escalate impact
-
-**Never silently deviate.**
-
-## Context Refresh Recovery
-
-1. Check `git log` for recent commits
-2. Find current phase/task in plan
-3. Resume from last committed task