@leeovery/claude-technical-workflows 2.1.3 → 2.1.5

package/README.md

@@ -18,7 +18,7 @@
   <a href="https://leeovery.github.io/claude-technical-workflows/"><strong>Open the Interactive Workflow Explorer</strong></a>
 </p>
 
-> **Workflow Explorer** — A visual, interactive guide to every phase, skill, and command in this toolkit. See how commands route to skills, trace decision logic through flowcharts, and understand the full pipeline at a glance. No install required — runs in your browser.
+> **Workflow Explorer** — A visual, interactive guide to every phase and skill in this toolkit. Trace decision logic through flowcharts and understand the full pipeline at a glance. No install required — runs in your browser.
 
 ---
 
@@ -34,7 +34,7 @@ Research → Discussion → Specification → Planning → Implementation → Re
 
 **Why this matters:** Complex features benefit from thorough discussion before implementation. This toolkit documents the *what* and *why* before diving into the *how*, preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
 
-**Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Skills are input-agnostic - commands gather context and feed it to them.
+**Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Entry-point skills gather context and feed it to processing skills.
 
 > [!NOTE]
 > **Work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
@@ -69,47 +69,47 @@ Research → Discussion → Specification → Planning → Implementation → Re
 
 Start with `/start-research` or `/start-discussion` and follow the flow. Each phase outputs files that the next phase consumes.
 
-**2. Standalone Commands** - Jump directly to a skill with flexible inputs:
+**2. Standalone Skills** - Jump directly to a processing skill with flexible inputs:
 
-| Command | What it does |
-|---------|-------------|
+| Skill | What it does |
+|-------|-------------|
 | `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
 
-*More standalone commands coming soon.*
+*More standalone skills coming soon.*
 
-### The Command/Skill Architecture
+### The Two-Tier Skill Architecture
 
-**Skills are input-agnostic.** They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
+**Processing skills** (`technical-*`) are input-agnostic. They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
 
-**Commands are the input layer.** They gather context (from files, prompts, or inline) and pass it to skills. This separation means:
+**Entry-point skills** (`/start-*`, `/status`, etc.) are the input layer. They gather context (from files, prompts, or inline) and pass it to processing skills. This separation means:
 
-- The same skill can be invoked from different entry points
-- You can create custom commands that feed skills in new ways
-- Skills remain reusable without coupling to specific workflows
+- The same processing skill can be invoked from different entry points
+- You can create custom entry-point skills that feed processing skills in new ways
+- Processing skills remain reusable without coupling to specific workflows
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        COMMANDS                             │
-│  (gather inputs from files, prompts, inline context)        │
+│                    ENTRY-POINT SKILLS                        │
+│  (gather inputs from files, prompts, inline context)         │
 ├─────────────────────────────────────────────────────────────┤
-│  /start-specification   /start-feature   (your custom)  │
-│         │                       │                 │         │
-│         └───────────┬───────────┘                 │         │
-│                     ▼                             ▼         │
+│  /start-specification   /start-feature   (your custom)      │
+│         │                       │                 │          │
+│         └───────────┬───────────┘                 │          │
+│                     ▼                             ▼          │
 ├─────────────────────────────────────────────────────────────┤
-│                         SKILLS                              │
-│  (process inputs without knowing their source)              │
+│                    PROCESSING SKILLS                         │
+│  (process inputs without knowing their source)               │
 ├─────────────────────────────────────────────────────────────┤
-│           technical-specification skill                     │
-│           technical-planning skill                          │
-│           technical-implementation skill                    │
-│           etc.                                              │
+│           technical-specification skill                      │
+│           technical-planning skill                           │
+│           technical-implementation skill                     │
+│           etc.                                               │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-### Workflow Commands
+### Workflow Skills
 
-| Phase          | Command                 |
+| Phase          | Skill                   |
 |----------------|-------------------------|
 | Research       | `/start-research`       |
 | Discussion     | `/start-discussion`     |
@@ -118,7 +118,7 @@ Start with `/start-research` or `/start-discussion` and follow the flow. Each ph
 | Implementation | `/start-implementation` |
 | Review         | `/start-review`         |
 
-Run the command directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the skill.
+Run the skill directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the processing skill.
 
 ## Installation
 
@@ -234,27 +234,27 @@ Research starts with `exploration.md` and splits into topic files as themes emer
 ### Package Structure
 
 ```
-skills/                              # Input-agnostic processors
+skills/
+├── # Processing skills (model-invocable)
 ├── technical-research/              # Explore and validate ideas
 ├── technical-discussion/            # Document discussions
 ├── technical-specification/         # Build validated specifications
 ├── technical-planning/              # Create implementation plans
 ├── technical-implementation/        # Execute via TDD
-└── technical-review/                # Validate against artefacts
-
-commands/                            # Input layer (gather context → invoke skills)
-├── migrate.md                       # Keep workflow files in sync with system design
-├── start-feature.md                 # Standalone: spec from inline context
-├── link-dependencies.md             # Standalone: wire cross-topic deps
-└── workflow/                        # Sequential workflow commands
-    ├── start-research.md            # Begin research
-    ├── start-discussion.md          # Begin discussions
-    ├── start-specification.md       # Begin specification
-    ├── start-planning.md            # Begin planning
-    ├── start-implementation.md      # Begin implementation
-    ├── start-review.md              # Begin review
-    ├── status.md                    # Show workflow status
-    └── view-plan.md                 # View plan tasks
+├── technical-review/                # Validate against artefacts
+│
+├── # Entry-point skills (user-invocable)
+├── migrate/                         # Keep workflow files in sync with system design
+├── start-feature/                   # Standalone: spec from inline context
+├── link-dependencies/               # Standalone: wire cross-topic deps
+├── start-research/                  # Begin research
+├── start-discussion/                # Begin discussions
+├── start-specification/             # Begin specification
+├── start-planning/                  # Begin planning
+├── start-implementation/            # Begin implementation
+├── start-review/                    # Begin review
+├── status/                          # Show workflow status
+└── view-plan/                       # View plan tasks
 
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
@@ -265,11 +265,11 @@ agents/
 ├── planning-task-author.md          # Write full task detail
 └── planning-dependency-grapher.md   # Analyze task dependencies and priorities
 
-scripts/                             # Helper scripts for commands
+scripts/                             # Helper scripts for skills
 ├── migrate.sh                       # Migration orchestrator
-├── discovery-for-discussion.sh      # Discovery for discussion command
-├── discovery-for-specification.sh   # Discovery for specification command
-├── discovery-for-planning.sh        # Discovery for planning command
+├── discovery-for-discussion.sh      # Discovery for discussion skill
+├── discovery-for-specification.sh   # Discovery for specification skill
+├── discovery-for-planning.sh        # Discovery for planning skill
 ├── discovery-for-implementation-and-review.sh  # Discovery for impl/review
 └── migrations/                      # Individual migration scripts (numbered)
 
@@ -279,7 +279,9 @@ tests/
 
 ## Skills
 
-Skills are **input-agnostic processors**: they receive inputs and process them without knowing where the inputs came from. This makes them reusable across different commands and workflows.
+### Processing Skills
+
+Processing skills are **input-agnostic**: they receive inputs and process them without knowing where the inputs came from. This makes them reusable across different entry points and workflows.
 
 | Skill                                                            | Description                                                                                                                                                                                                  |
 |------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -290,48 +292,48 @@ Skills are **input-agnostic processors**: they receive inputs and process them w
 | [**technical-implementation**](skills/technical-implementation/) | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval.                                                       |
 | [**technical-review**](skills/technical-review/)                 | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
 
-## Commands
+### Entry-Point Skills
 
-Commands are the input layer: they gather context and pass it to skills. Two types:
+Entry-point skills are the input layer: they gather context and pass it to processing skills.
 
-### Workflow Commands
+#### Workflow Skills
 
-Sequential commands in `commands/workflow/`. They expect files from previous phases and pass content to skills.
+Sequential skills that expect files from previous phases and pass content to processing skills.
 
-| Command                                                                              | Description                                                                                                                                                                                                |
-|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-research**](commands/workflow/start-research.md)                  | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
-| [**/start-discussion**](commands/workflow/start-discussion.md)              | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
-| [**/start-specification**](commands/workflow/start-specification.md)        | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
-| [**/start-planning**](commands/workflow/start-planning.md)                  | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear). |
-| [**/start-implementation**](commands/workflow/start-implementation.md)      | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
-| [**/start-review**](commands/workflow/start-review.md)                      | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
+| Skill                                                                        | Description                                                                                                                                                                                                |
+|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/start-research**](skills/start-research/)                                | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
+| [**/start-discussion**](skills/start-discussion/)                            | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
+| [**/start-specification**](skills/start-specification/)                      | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
+| [**/start-planning**](skills/start-planning/)                                | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear). |
+| [**/start-implementation**](skills/start-implementation/)                    | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
+| [**/start-review**](skills/start-review/)                                    | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
 
-### Utility Commands
+#### Utility Skills
 
 Helpers for navigating and maintaining the workflow.
 
-| Command                                                                              | Description                                                                                                                                 |
-|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/migrate**](commands/migrate.md)                                         | Keep workflow files in sync with the current system design. Runs automatically at the start of every workflow command.                      |
-| [**/status**](commands/workflow/status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
-| [**/view-plan**](commands/workflow/view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
+| Skill                                                                        | Description                                                                                                                                 |
+|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/migrate**](skills/migrate/)                                              | Keep workflow files in sync with the current system design. Runs automatically at the start of every workflow skill.                        |
+| [**/status**](skills/status/)                                                | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
+| [**/view-plan**](skills/view-plan/)                                          | View a plan's tasks and progress, regardless of output format.                                                                              |
 
-### Standalone Commands
+#### Standalone Skills
 
-Independent commands that gather inputs flexibly (inline context, files, or prompts) and invoke skills directly. Use these when you want skill capabilities without the full workflow structure.
+Independent skills that gather inputs flexibly (inline context, files, or prompts) and invoke processing skills directly. Use these when you want capabilities without the full workflow structure.
 
-| Command                                                 | Description                                                                                                                                 |
+| Skill                                                   | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-feature**](commands/start-feature.md)         | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
-| [**/link-dependencies**](commands/link-dependencies.md) | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
+| [**/start-feature**](skills/start-feature/)              | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
+| [**/link-dependencies**](skills/link-dependencies/)      | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 
-### Creating Custom Commands
+### Creating Custom Skills
 
-Since skills are input-agnostic, you can create your own commands that feed them in new ways. A command just needs to:
+Since processing skills are input-agnostic, you can create your own entry-point skills that feed them in new ways. An entry-point skill just needs to:
 
-1. Gather the inputs the skill expects
-2. Invoke the skill with those inputs
+1. Gather the inputs the processing skill expects
+2. Invoke the processing skill with those inputs
 
 See `/start-feature` as an example: it provides inline context to the specification skill instead of a discussion document.
 

package/agents/implementation-polish.md

@@ -0,0 +1,188 @@
+---
+name: implementation-polish
+description: Performs holistic quality analysis over a completed implementation, discovering cross-task issues through multi-pass analysis and orchestrating fixes via the executor and reviewer agents. Invoked by technical-implementation skill after all tasks complete.
+tools: Read, Glob, Grep, Bash, Task
+model: opus
+---
+
+# Implementation Polish
+
+Act as a **senior developer** performing a holistic quality pass over a plan's implementation. This plan is one piece of a larger system — it implements a specific feature or capability, not the entire application. Other plans handle other features. Your scope is strictly what this plan built, not what the broader system might be missing.
+
+You've inherited a codebase built by a team — each member did solid work on their piece, but nobody has reviewed the whole picture. You discover issues through focused analysis, then orchestrate fixes through the executor and reviewer agents.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **code-quality.md path** — Quality standards (also passed to executor)
+2. **tdd-workflow.md path** — TDD cycle rules (passed to executor)
+3. **Specification path** — What was intended — design decisions and rationale
+4. **Plan file path** — What was built — the full task landscape
+5. **Plan format reading.md path** — How to read tasks from the plan (format-specific adapter)
+6. **Integration context file path** — Accumulated decisions and patterns from every task
+7. **Project skill paths** — Framework conventions
+
+On **re-invocation after user feedback**, additionally include:
+
+8. **User feedback** — the user's comments on what to change or focus on
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
+1. **No direct code changes** — dispatch the executor for all modifications. You are discovery and orchestration.
+2. **No new features** — only improve what exists. Nothing that isn't in the plan.
+3. **Plan scope only** — work within the plan's boundary. Do not flag missing features that belong to other plans (e.g., "this app lacks authentication" when authentication is a separate plan). Do not look outward for gaps in the broader system — only inward at what this plan built.
+4. **No git writes** — do not commit, stage, or interact with git. Reading git history and diffs is fine. The orchestrator handles all git operations.
+5. **Proportional** — prioritize high-impact changes. Don't spend effort on trivial style differences.
+6. **Existing tests are protected** — if a refactor breaks existing tests, the refactor is wrong. Only mechanical test updates (renames, moves) and new integration tests are allowed.
+7. **Minimum 2 cycles** — always complete at least 2 full discovery-fix cycles. A single pass is never sufficient.
+
+---
+
+## Step 1: Absorb Context
+
+Read and absorb the following. Do not write any code or dispatch any agents during this step.
+
+1. **Read code-quality.md** — absorb quality standards
+2. **Read specification** (if provided) — understand design intent
+3. **Read project skills** — absorb framework conventions
+4. **Read the plan format's reading.md** — understand how to retrieve tasks from the plan
+5. **Read the plan** — follow the reading adapter's instructions to retrieve all completed tasks. Understand the full scope: phases, tasks, acceptance criteria, what was built
+6. **Read the integration context file** — understand patterns, helpers, and conventions from all tasks
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Identify Implementation Scope
+
+Find all files changed during implementation. Use git history, the plan's task list, and the integration context to build a complete picture of what was touched. Read and understand the full implemented codebase.
+
+Build a definitive list of implementation files. This list is passed to analysis sub-agents in subsequent steps.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Discovery-Fix Loop
+
+Execute discovery-fix cycles. Minimum **2** cycles, maximum **5** cycles. Each cycle follows stages A through G sequentially. Always start at **A. Cycle Gate**.
+
+### A. Cycle Gate
+
+Increment the cycle count.
+
+If cycle count > 5 → exit loop, proceed to **Step 4**.
+
+If cycle count > 2 and the previous cycle's discovery found zero actionable issues → exit loop, proceed to **Step 4**.
+
+Otherwise → proceed to **B. Dispatch Fixed Analysis Passes**.
+
+### B. Dispatch Fixed Analysis Passes
+
+Dispatch all three analysis sub-agents **in parallel** via Task tool. Each sub-agent receives:
+- The list of implementation files (from Step 2)
+- The specific analysis focus (below)
+- Instruction to return findings as a structured list with file:line references
+
+**Sub-agent 1 — Code Cleanup:**
+Analyze all implementation files for: unused imports/variables/dead code, naming quality (abbreviation overuse, unclear names, inconsistent naming across files), formatting inconsistencies across the implementation. Compare naming conventions between files written by different tasks — flag drift.
+
+**Sub-agent 2 — Structural Cohesion:**
+Analyze all implementation files for: duplicated logic across task boundaries that should be extracted, class/module responsibilities (too much in one class, or unnecessarily fragmented across many), design patterns that are now obvious with the full picture but weren't visible to individual task executors, over-engineering (abstractions nobody uses) or under-engineering (raw code that should be extracted).
+
+**Sub-agent 3 — Cross-Task Integration:**
+Analyze all implementation files for: shared code paths where multiple tasks contributed behavior — verify the merged result is correct, workflow seams where one task's output feeds another's input — verify the handoff works, interface mismatches between producer and consumer (type mismatches, missing fields, wrong assumptions), gaps in integration test coverage for cross-task workflows.
+
+**STOP.** Do not proceed until all three sub-agents have returned their findings.
+
+→ Proceed to **C. Dispatch Dynamic Analysis Passes**.
+
+### C. Dispatch Dynamic Analysis Passes
+
+Review the findings from the fixed passes and the codebase. Based on what you find — language, framework, project conventions, areas flagged by fixed passes — determine whether additional targeted analysis is needed.
+
+If no dynamic passes are needed → proceed to **D. Synthesize Findings**.
+
+If dynamic passes are needed, dispatch sub-agents for deeper analysis. Examples: language-specific idiom checks, convention consistency across early and late tasks, deeper investigation into specific areas. Each dynamic sub-agent receives the relevant file subset and a focused analysis prompt, same as fixed passes.
+
+**STOP.** Do not proceed until all dynamic sub-agents have returned their findings.
+
+→ Proceed to **D. Synthesize Findings**.
+
+### D. Synthesize Findings
+
+Collect findings from all analysis passes (fixed and dynamic). Deduplicate, discard low-value nitpicks, and prioritize by impact.
+
+If no actionable findings remain → proceed to **G. Cycle Complete** (no fix needed this cycle).
+
+If actionable findings exist → proceed to **E. Invoke Executor**.
+
+### E. Invoke Executor
+
+Craft a task description covering the prioritized fixes. Include the following **test rules** in the task description — these constrain what test changes the executor may make during polish:
+- Write NEW integration tests for cross-task workflows — yes
+- Modify existing tests for mechanical changes (renames, moves) — yes
+- Modify existing tests semantically (different behavior) — no. If a refactor breaks existing tests, the refactor is wrong. Revert it.
+
+Invoke the `implementation-task-executor` agent (`.claude/agents/implementation-task-executor.md`) with:
+- The crafted task description (including test rules) as task content
+- tdd-workflow.md path
+- code-quality.md path
+- Specification path (if available)
+- Project skill paths
+- Plan file path
+- Integration context file path
+
+**STOP.** Do not proceed until the executor has returned its result.
+
+On receipt of result, route on STATUS:
+- `blocked` or `failed` → record in SKIPPED with the executor's ISSUES. Proceed to **G. Cycle Complete**.
+- `complete` → proceed to **F. Invoke Reviewer**.
+
+### F. Invoke Reviewer
+
+Invoke the `implementation-task-reviewer` agent (`.claude/agents/implementation-task-reviewer.md`) to independently verify the executor's work. Include the test rules in the reviewer's prompt so it can flag violations. Pass:
+- Specification path
+- The same task description used for the executor (including test rules)
+- Project skill paths
+- Integration context file path
+
+**STOP.** Do not proceed until the reviewer has returned its result.
+
+On receipt of result, route on VERDICT:
+- `approved` → proceed to **G. Cycle Complete**
+- `needs-changes` → return to **E. Invoke Executor** with the reviewer's feedback. Maximum 3 fix attempts per cycle — if not converged after 3, record remaining issues in SKIPPED and proceed to **G. Cycle Complete**.
+
+### G. Cycle Complete
+
+Record what was discovered and fixed this cycle.
+
+→ Return to **A. Cycle Gate**.
+
+---
+
+## Step 4: Return Report
+
+Return a structured report:
+
+```
+STATUS: complete | blocked
+SUMMARY: {overview — what was analyzed, key findings, what was fixed}
+CYCLES: {number of discovery-fix cycles completed}
+DISCOVERY:
+- {findings from analysis passes, organized by category}
+FIXES_APPLIED:
+- {what was changed and why, with file:line references}
+TESTS_ADDED:
+- {integration tests written, what workflows they exercise}
+SKIPPED:
+- {issues found but not addressed — too risky, needs design decision, or low impact}
+TEST_RESULTS: {all passing | failures — details}
+```
+
+- If STATUS is `blocked`, SUMMARY **must** explain what decision is needed.
+- If STATUS is `complete`, all applied fixes must have passing tests.
+- SKIPPED captures issues that were found but intentionally not addressed — too risky, needs a design decision, or low impact relative to effort.

package/agents/implementation-task-executor.md

@@ -18,10 +18,14 @@ You receive file paths and context via the orchestrator's prompt:
 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.
+6. **Plan file path** — The implementation plan, for understanding the overall task landscape and where this task fits
+7. **Integration context file path** (if exists) — Accumulated notes from prior tasks about established patterns, conventions, and decisions
 
-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**
+On **re-invocation after review feedback**, you receive all of the above, plus:
+8. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+9. **Specific issues to address**
+
+You are stateless — each invocation starts fresh. The full task content is always provided so you can see what was asked, what was done, and what needs fixing.
 
 ## Your Process
 
@@ -29,10 +33,14 @@ On **re-invocation after review feedback**, you also receive:
 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:
+5. **Explore codebase** — you are weaving into an existing canvas, not creating isolated patches:
+   - If an integration context file was provided, read it first — identify helpers, patterns, and conventions you must reuse before writing anything new
+   - Skim the plan file to understand the task landscape — what's been built, what's coming, where your task fits. Use this for awareness, not to build ahead (YAGNI still applies)
    - 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
+   - Search for existing helpers, utilities, and abstractions that solve similar problems — reuse, don't duplicate
+   - When creating an interface or API boundary, read BOTH sides: the code that will consume it AND the code that will implement it
+   - Match conventions established in the codebase: error message style, naming patterns, file organisation, type placement
+   - Your code should read as if the same developer wrote the entire codebase
 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**
@@ -73,7 +81,10 @@ 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}
+INTEGRATION_NOTES:
+- {3-5 concise bullet points: key patterns, helpers, conventions, interface decisions established by this task. Anchor to concrete file paths where applicable (e.g., "Created `ValidationHelper` in `src/helpers/validation.ts` — use for all input validation"), but high-level observations without a specific file reference are also valuable}
 ```
 
 - 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.
+- After completing the task, document what you created or established that future tasks should be aware of in INTEGRATION_NOTES. This is factual — what exists and why — not evaluative.

package/agents/implementation-task-reviewer.md

@@ -18,6 +18,7 @@ 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
+4. **Integration context file path** (if exists) — Accumulated notes from prior tasks, for evaluating cohesion with established patterns
 
 ## Your Process
 
@@ -25,7 +26,7 @@ You receive via the orchestrator's prompt:
 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)
+5. **Evaluate all six review dimensions** (see below)
 
 ## Review Dimensions
 
@@ -62,6 +63,31 @@ Is this a sound design decision? Will it compose well with future tasks?
 - Will this cause problems for subsequent tasks in the phase?
 - Are there structural concerns that should be raised now rather than compounding?
 
+### 6. Codebase Cohesion
+Does the new code integrate well with the existing codebase? If integration context exists from prior tasks, check against established patterns.
+- Is there duplicated logic that should be extracted into a shared helper?
+- Are existing helpers and patterns being reused where applicable?
+- Are naming conventions consistent with existing code?
+- Are error message conventions consistent (casing, wrapping style, prefixes)?
+- Do interfaces use concrete types rather than generic/any types where possible?
+- Are related types co-located with the interfaces or functions they serve?
+
+## Fix Recommendations (needs-changes only)
+
+When your verdict is `needs-changes`, you must also recommend how to fix each issue. You have full context — the spec, the task, the conventions, and the code — so use it.
+
+For each issue, provide:
+- **FIX**: The recommended approach to resolve the issue
+- **ALTERNATIVE** (optional): If multiple valid approaches exist, state them with tradeoffs and indicate which you recommend
+- **CONFIDENCE**: `high` | `medium` | `low`
+  - `high` — single obvious approach, no ambiguity
+  - `medium` — recommended approach is sound but alternatives exist
+  - `low` — genuinely uncertain, multiple approaches with significant tradeoffs
+
+Be specific and actionable. "Fix the validation" is not useful. "Add a test case in `tests/UserTest.php` that asserts `ValidationException` is thrown when email is empty, following the existing test pattern at line 45" is useful.
+
+When alternatives exist, explain the tradeoff briefly — don't just list options. State which you recommend and why.
+
 ## Hard Rules
 
 **MANDATORY. No exceptions. Violating these rules invalidates the review.**
@@ -70,7 +96,7 @@ Is this a sound design decision? Will it compose well with future tasks?
 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.
+5. **All six dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, architectural quality, and codebase cohesion.
 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.
@@ -87,11 +113,20 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
+CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
+  FIX: {recommended approach}
+  ALTERNATIVE: {other valid approach with tradeoff — optional, only when multiple valid approaches exist}
+  CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
+COHESION_NOTES:
+- {2-4 concise bullet points: patterns to maintain, conventions confirmed, architectural integration observations}
 ```
 
-- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references
+- If VERDICT is `approved`, omit ISSUES entirely (or leave empty)
+- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references AND fix recommendations
+- Each issue must include FIX and CONFIDENCE. ALTERNATIVE is optional — include only when genuinely multiple valid approaches exist
 - NOTES are for non-blocking observations — things worth noting but not requiring changes
+- COHESION_NOTES are always included — they capture patterns and conventions observed for future task context

package/package.json

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

package/{commands/link-dependencies.md → skills/link-dependencies/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format.
+name: link-dependencies
+description: "Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format."
+disable-model-invocation: true
 ---
 
 Link cross-topic dependencies across all existing plans.

package/{commands/migrate.md → skills/migrate/SKILL.md}

@@ -1,5 +1,6 @@
 ---
-description: Run migrations to keep workflow files in sync with the current system design. This command is mandatory before running any workflow command.
+name: migrate
+description: "Run migrations to keep workflow files in sync with the current system design. This skill is mandatory before running any workflow skill."
 allowed-tools: Bash(.claude/scripts/migrate.sh)
 ---
 
@@ -25,7 +26,7 @@ The script will list which files were updated. Present this to the user:
 Review changes with `git diff`, then proceed when ready.
 ```
 
-Wait for user acknowledgment before returning control to the calling command.
+Wait for user acknowledgment before returning control to the calling skill.
 
 ### If no updates needed
 
@@ -37,7 +38,7 @@ Return control silently - no user interaction needed.
 
 ## Notes
 
-- This command is run automatically at the start of every workflow command
+- This skill is run automatically at the start of every workflow skill
 - Migrations are tracked in `docs/workflow/.cache/migrations.log`
 - To force re-running all migrations, delete the tracking file
 - Each migration is idempotent - safe to run multiple times

package/{commands/workflow/start-discussion.md → skills/start-discussion/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
+name: start-discussion
+description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
+disable-model-invocation: true
 allowed-tools: Bash(.claude/scripts/discovery-for-discussion.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
 ---
 
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -354,9 +356,9 @@ What would you like to focus on in this session?
 
 ## Step 7: Invoke the Skill
 
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-discussion](../../skills/technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-discussion](../technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff (from research):**
 ```

package/{commands/start-feature.md → skills/start-feature/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building.
+name: start-feature
+description: "Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building."
+disable-model-invocation: true
 ---
 
 Invoke the **technical-specification** skill for this conversation with inline feature context.
@@ -8,7 +10,7 @@ Invoke the **technical-specification** skill for this conversation with inline f
 
 Follow these steps EXACTLY as written. Do not skip steps or combine them.
 
-This command is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
+This skill is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
 
 ## Step 1: Gather Feature Context
 
@@ -55,7 +57,7 @@ If a specification with the same name exists, inform the user and ask how to pro
 
 ## Step 4: Invoke Specification Skill
 
-Pass the gathered context to the technical-specification skill:
+Pass the gathered context to the [technical-specification](../technical-specification/SKILL.md) skill:
 
 ```
 Feature specification for: {topic}

package/{commands/workflow/start-implementation.md → skills/start-implementation/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill.
+name: start-implementation
+description: "Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill."
+disable-model-invocation: true
 allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
 ---
 
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -314,9 +316,9 @@ Are there any environment setup instructions I should follow before implementati
 
 ## Step 6: Invoke the Skill
 
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-implementation](../../skills/technical-implementation/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-implementation](../technical-implementation/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```

package/{commands/workflow/start-planning.md → skills/start-planning/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill.
+name: start-planning
+description: "Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill."
+disable-model-invocation: true
 allowed-tools: Bash(.claude/scripts/discovery-for-planning.sh)
 ---
 
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -250,9 +252,9 @@ These specifications contain validated architectural decisions that should infor
 
 ## Step 7: Invoke the Skill
 
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-planning](../../skills/technical-planning/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-planning](../technical-planning/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff (fresh plan):**
 ```

package/{commands/workflow/start-research.md → skills/start-research/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.
+name: start-research
+description: "Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion."
+disable-model-invocation: true
 ---
 
 Invoke the **technical-research** skill for this conversation.
@@ -39,7 +41,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -116,9 +118,9 @@ Any constraints or context I should know about upfront?
 
 ## Step 5: Invoke the Skill
 
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-research](../../skills/technical-research/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-research](../technical-research/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```

package/{commands/workflow/start-review.md → skills/start-review/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill.
+name: start-review
+description: "Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill."
+disable-model-invocation: true
 allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
 ---
 
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -153,9 +155,9 @@ If they choose specific directories/files, ask them to specify.
 
 ## Step 5: Invoke the Skill
 
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-review](../../skills/technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-review](../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```

package/{commands/workflow/start-specification.md → skills/start-specification/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
+name: start-specification
+description: "Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
+disable-model-invocation: true
 allowed-tools: Bash(.claude/scripts/discovery-for-specification.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
 ---
 
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 
@@ -757,9 +759,9 @@ Before invoking the specification skill:
 
 ## Step 11: Invoke the Skill
 
-After completing all steps above, this command's purpose is fulfilled.
+After completing all steps above, this skill's purpose is fulfilled.
 
-Invoke the [technical-specification](../../skills/technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-specification](../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 #### Handoff Format
 

package/{commands/workflow/status.md → skills/status/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: Show workflow status - what exists, where you are, and what to do next.
+name: status
+description: "Show workflow status - what exists, where you are, and what to do next."
+disable-model-invocation: true
 ---
 
 Show the current state of the workflow for this project.
@@ -8,7 +10,7 @@ Show the current state of the workflow for this project.
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
 

package/skills/technical-implementation/SKILL.md

@@ -48,7 +48,7 @@ Context refresh (compaction) summarizes the conversation, losing procedural deta
 
 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. **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.
+3. **Check `task_gate_mode`, `fix_gate_mode`, and `fix_attempts`** in the tracking file — if gates are `auto`, the user previously opted out. If `fix_attempts` > 0, you're mid-fix-loop for the current task.
 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.
 
@@ -143,7 +143,7 @@ Store the selected skill paths — they will be persisted to the tracking file i
 
 #### If `docs/workflow/implementation/{topic}.md` already exists
 
-Reset `task_gate_mode` to `gated` in the tracking file before proceeding (fresh session = fresh gate).
+Reset `task_gate_mode` and `fix_gate_mode` to `gated`, and `fix_attempts` to `0`, in the tracking file before proceeding (fresh session = fresh gates).
 
 If `project_skills` is populated in the tracking file, present for confirmation:
 
@@ -174,6 +174,8 @@ plan: ../planning/{topic}.md
 format: {format from plan}
 status: in-progress
 task_gate_mode: gated
+fix_gate_mode: gated
+fix_attempts: 0
 project_skills: []
 current_phase: 1
 current_task: ~
@@ -193,6 +195,8 @@ After creating the file, populate `project_skills` with the paths confirmed in S
 
 Commit: `impl({topic}): start implementation`
 
+Integration context will accumulate in `docs/workflow/implementation/{topic}-context.md` as tasks complete. This file is created automatically during the task loop — no initialisation needed here.
+
 → Proceed to **Step 5**.
 
 ---
@@ -205,7 +209,81 @@ Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its inst
 
 ---
 
-## Step 6: Mark Implementation Complete
+## Step 6: Polish
+
+If the task loop exited early (user chose `stop`), skip to **Step 7**.
+
+**Git checkpoint** — ensure a clean working tree before invoking the polish agent. Run `git status`. If there are unstaged changes or untracked files, commit them:
+
+```
+impl({topic}): pre-polish checkpoint
+```
+
+This ensures all prior work is safely committed. The polish agent makes no git operations — all its changes will exist as unstaged modifications. If the user discards polish, the working tree resets cleanly to this checkpoint.
+
+**Invoke the polish agent:**
+
+1. Load **[steps/invoke-polish.md](references/steps/invoke-polish.md)** and follow its instructions.
+2. **STOP.** Do not proceed until the polish agent has returned its result.
+3. Route on STATUS:
+   - `blocked` → present SUMMARY to the user, ask how to proceed
+   - `complete` → present the report below
+
+> **Implementation polish complete** ({N} cycles)
+>
+> {SUMMARY}
+>
+> Findings:
+> {DISCOVERY}
+>
+> Fixes applied:
+> {FIXES_APPLIED}
+>
+> Integration tests added:
+> {TESTS_ADDED}
+>
+> Skipped (not addressed):
+> {SKIPPED}
+>
+> Test results: {TEST_RESULTS}
+>
+> · · ·
+>
+> - **`y`/`yes`** — Approve and commit polish changes
+> - **`s`/`skip`** — Discard polish changes, mark complete as-is
+> - **Comment** — Feedback (re-invokes polish agent with your notes)
+
+**STOP.** Wait for user input.
+
+#### If `yes`
+
+Commit all polish changes:
+
+```
+impl({topic}): polish — {brief description}
+```
+
+→ Proceed to **Step 7**.
+
+#### If `skip`
+
+Discard all polish changes. Reset the working tree to the pre-polish checkpoint:
+
+```
+git checkout . && git clean -fd
+```
+
+This is safe because the checkpoint commit captured all prior work. Only polish-created changes are discarded. Gitignored files are untouched.
+
+→ Proceed to **Step 7**.
+
+#### If comment
+
+→ Re-invoke the polish agent with the user's feedback. Return to the top of **Step 6** (after the git checkpoint — do not re-checkpoint).
+
+---
+
+## Step 7: Mark Implementation Complete
 
 Update the tracking file (`docs/workflow/implementation/{topic}.md`):
 - Set `status: completed`
@@ -222,6 +300,8 @@ Commit: `impl({topic}): complete 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
+- **[steps/invoke-polish.md](references/steps/invoke-polish.md)** — How to invoke the polish 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)
+- **Integration context** — `docs/workflow/implementation/{topic}-context.md` — accumulated notes from completed tasks (created during task loop)

package/skills/technical-implementation/references/code-quality.md

@@ -37,5 +37,15 @@ Only implement what's in the plan. Ask: "Is this in the plan?"
 - Long parameter lists (4+)
 - Boolean parameters
 
+## Convention Consistency
+
+When adding to an existing codebase, match what's already there:
+- **Error messages**: Match the casing, wrapping style, and prefix patterns in existing code
+- **Naming**: Follow the project's conventions for files, functions, types, and variables
+- **File organisation**: Follow the project's pattern for splitting concerns across files
+- **Helpers**: Search for existing helpers before creating new ones. After creating one, check if existing code could use it too
+- **Types**: Prefer concrete types over generic/any types when the set of possibilities is known. Use structured return types over multiple bare return values for extensibility
+- **Co-location**: Keep related types near the interfaces or functions they serve
+
 ## Project Standards
 Check `.claude/skills/` for project-specific patterns.

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

@@ -10,17 +10,21 @@ This step invokes the `implementation-task-executor` agent (`.claude/agents/impl
 
 ## Invoke the Agent
 
-Invoke `implementation-task-executor` with these file paths:
+**Every invocation** — initial or re-attempt — includes 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))
+6. **Plan file path**: the implementation plan (same path used to read tasks)
+7. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.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
+**Re-attempts after review feedback** additionally include:
+8. **User-approved review notes**: verbatim or as modified by the user
+9. **Specific issues to address**: the ISSUES from the review
+
+The executor is stateless — each invocation starts fresh with no memory of previous attempts. Always pass the full task content so the executor can see what was asked, what was done, and what needs fixing.
 
 ---
 
@@ -34,6 +38,8 @@ 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}
+INTEGRATION_NOTES:
+- {3-5 bullets: patterns, helpers, conventions established — anchor to file paths where applicable}
 ```
 
 - `complete`: all acceptance criteria met, tests passing

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

@@ -0,0 +1,51 @@
+# Invoke Polish
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the `implementation-polish` agent (`.claude/agents/implementation-polish.md`) to perform holistic quality analysis and orchestrate fixes after all tasks are complete.
+
+---
+
+## Invoke the Agent
+
+**Every invocation** includes these file paths:
+
+1. **code-quality.md**: `.claude/skills/technical-implementation/references/code-quality.md`
+2. **tdd-workflow.md**: `.claude/skills/technical-implementation/references/tdd-workflow.md`
+3. **Specification path**: from the plan's frontmatter (if available)
+4. **Plan file path**: the implementation plan
+5. **Plan format reading.md**: `.claude/skills/technical-planning/references/output-formats/{format}/reading.md` (format from plan frontmatter)
+6. **Integration context file**: `docs/workflow/implementation/{topic}-context.md`
+7. **Project skill paths**: from `project_skills` in the implementation tracking file
+
+**Re-invocation after user feedback** additionally includes:
+
+8. **User feedback**: the user's comments on what to change or focus on
+
+The polish agent is stateless — each invocation starts fresh. Always pass all inputs.
+
+---
+
+## Expected Result
+
+The agent returns a structured report:
+
+```
+STATUS: complete | blocked
+SUMMARY: {overview — what was analyzed, key findings, what was fixed}
+CYCLES: {number of discovery-fix cycles completed}
+DISCOVERY:
+- {findings from analysis passes, organized by category}
+FIXES_APPLIED:
+- {what was changed and why, with file:line references}
+TESTS_ADDED:
+- {integration tests written, what workflows they exercise}
+SKIPPED:
+- {issues found but not addressed — too risky, needs design decision, or low impact}
+TEST_RESULTS: {all passing | failures — details}
+```
+
+- `complete`: all applied fixes have passing tests, discovery-fix loop finished
+- `blocked`: SUMMARY explains what decision is needed

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

@@ -15,6 +15,7 @@ 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
+4. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.md` — for checking cohesion with established patterns
 
 ---
 
@@ -30,11 +31,17 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
+CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
+  FIX: {recommended approach}
+  ALTERNATIVE: {other valid approach with tradeoff — optional}
+  CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
+COHESION_NOTES:
+- {2-4 bullets: patterns to maintain, conventions confirmed, integration quality}
 ```
 
-- `approved`: task passes all five review dimensions
-- `needs-changes`: ISSUES contains specific, actionable items
+- `approved`: task passes all six review dimensions
+- `needs-changes`: ISSUES contains specific, actionable items with fix recommendations and confidence levels

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

@@ -13,7 +13,7 @@ A. Retrieve next task
 B. Execute task → invoke-executor.md
    → Executor Blocked (conditional)
 C. Review task → invoke-reviewer.md
-   → Review Changes (conditional)
+   → Review Changes with fix analysis (conditional, fix_gate_mode)
 D. Task gate (gated → prompt user / auto → announce)
 E. Update progress + commit
 → loop back to A until done
@@ -26,6 +26,7 @@ E. Update progress + commit
 1. Follow the format's **reading.md** 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)**.
+4. Reset `fix_attempts` to `0` in the implementation tracking file.
 
 ---
 
@@ -55,7 +56,7 @@ Present the executor's ISSUES to the user:
 
 #### 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.
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's comments.
 
 #### If `skip`
 
@@ -77,26 +78,44 @@ Present the executor's ISSUES to the user:
 
 ### Review Changes
 
-Present the reviewer's findings to the user:
+Increment `fix_attempts` in the implementation tracking file.
 
-> **Review for Task {id}: {Task Name} — needs changes**
+#### If `fix_gate_mode: auto` and `fix_attempts < 3`
+
+Announce the fix round (one line, no stop):
+
+> **Review for Task {id}: {Task Name} — needs changes** (attempt {N}/{max 3}, fix analysis included). Re-invoking executor.
+
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
+
+#### If `fix_gate_mode: gated`, or `fix_attempts >= 3`
+
+If `fix_attempts >= 3`, the executor and reviewer have failed to converge. Prepend:
+
+> The executor and reviewer have not converged after {N} attempts. Escalating for human review.
+
+Present the reviewer's findings and fix analysis to the user:
+
+> **Review for Task {id}: {Task Name} — needs changes** (attempt {N})
 >
-> {ISSUES from reviewer}
+> {ISSUES from reviewer, including FIX, ALTERNATIVE, and CONFIDENCE for each}
 >
 > Notes (non-blocking):
 > {NOTES from reviewer}
 >
 > · · ·
 >
-> - **`y`/`yes`** — Accept these notes and pass them to the executor to fix
+> - **`y`/`yes`** — Accept the review and fix analysis, pass to executor
+> - **`a`/`auto`** — Accept and auto-approve future fix analyses
 > - **`s`/`skip`** — Override the reviewer and proceed as-is
-> - **Comment** — Modify or add to the notes before passing to the executor
+> - **Comment** — Any commentary, adjustments, alternative approaches, or questions before passing to 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.
+- **`y`/`yes`**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
+- **`auto`**: Note that `fix_gate_mode` should be updated to `auto` during the next commit step. → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
 - **`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.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content, the reviewer's notes, and the user's commentary.
 
 ---
 
@@ -124,7 +143,7 @@ Present a summary and 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.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's notes.
 
 ### If `task_gate_mode: auto`
 
@@ -145,9 +164,24 @@ Announce the result (one line, no stop):
 - 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`
+- If user chose `auto` at the task gate this turn: update `task_gate_mode: auto`
+- If user chose `auto` at the fix gate this turn: update `fix_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` and `fix_gate_mode`).
+
+**Append integration context** — extract INTEGRATION_NOTES from the executor's final output and COHESION_NOTES from the reviewer's output. Append both to `docs/workflow/implementation/{topic}-context.md`:
+
+```
+## T{task-id}: {task name}
+
+### Integration (executor)
+{INTEGRATION_NOTES content}
+
+### Cohesion (reviewer)
+{COHESION_NOTES content}
+```
 
-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`).
+Create the file if it doesn't exist. This is mechanical text extraction and file append — the same as extracting STATUS to route on. Use outputs from the final approved iteration only.
 
 **Commit all changes** in a single commit:
 
@@ -155,7 +189,7 @@ The tracking file is a derived view for discovery scripts and cross-topic depend
 impl({topic}): T{task-id} — {brief description}
 ```
 
-Code, tests, plan progress, and tracking file — one commit per approved task.
+Code, tests, plan progress, tracking file, and integration context — one commit per approved task.
 
 This is the end of this iteration.
 

package/{commands/workflow/view-plan.md → skills/view-plan/SKILL.md}

@@ -1,5 +1,7 @@
 ---
-description: View a plan's tasks and progress, regardless of output format.
+name: view-plan
+description: "View a plan's tasks and progress, regardless of output format."
+disable-model-invocation: true
 ---
 
 Display a readable summary of a plan's phases, tasks, and status.