@leeovery/claude-technical-workflows 2.1.4 → 2.1.5

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/package.json

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

package/skills/technical-implementation/SKILL.md

@@ -209,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`
@@ -226,6 +300,7 @@ 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)

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