@leeovery/claude-technical-workflows 2.1.11 → 2.1.12

package/skills/technical-implementation/SKILL.md

@@ -49,7 +49,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`, `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.
+3. **Check `task_gate_mode`, `fix_gate_mode`, `fix_attempts`, and `analysis_cycle`** 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. If `analysis_cycle` > 0, you've completed analysis cycles — check for findings files on disk (`analysis-*.md` in `{topic}/`) to determine mid-analysis state.
 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.
 
@@ -105,78 +105,36 @@ Save their instructions to `docs/workflow/environment-setup.md` (or "No special
    - **reading.md** — how to read tasks from the plan
    - **updating.md** — how to write progress to the plan
 4. If no `format` field exists, ask the user which format the plan uses.
-5. These adapter files apply during Step 5 (task loop).
+5. These adapter files apply during Step 6 (task loop) and Step 7 (analysis).
+6. Also load the format's **authoring.md** adapter — needed in Step 7 if analysis tasks are created.
 
 → Proceed to **Step 3**.
 
 ---
 
-## Step 3: Project Skills Discovery
+## Step 3: Initialize Implementation Tracking
 
-#### If `.claude/skills/` does not exist or is empty
+#### If `docs/workflow/implementation/{topic}/tracking.md` already exists
 
-```
-No project skills found. Proceeding without project-specific conventions.
-```
+Reset `task_gate_mode` and `fix_gate_mode` to `gated`, `fix_attempts` to `0`, and `analysis_cycle` to `0` (fresh session = fresh gates/cycles).
 
 → Proceed to **Step 4**.
 
-#### If project skills exist
-
-Scan `.claude/skills/` for project-specific skill directories. Present findings:
-
-> 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)
-
-**STOP.** Wait for user to confirm which skills are relevant.
-
-Store the selected skill paths — they will be persisted to the tracking file in Step 4.
-
-→ Proceed to **Step 4**.
-
----
-
-## Step 4: Initialize Implementation Tracking
-
-#### If `docs/workflow/implementation/{topic}.md` already exists
-
-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:
-
-> "Previous session used these project skills:
-> - `{skill-name}` — {path}
-> - ...
->
-> · · ·
->
-> - **`y`/`yes`** — Keep these, proceed
-> - **`c`/`change`** — Add or remove skills"
-
-**STOP.** Wait for user choice.
-
-- **`y`/`yes`**: Proceed with the persisted paths.
-- **`change`**: Re-run discovery (Step 3), update `project_skills` in the tracking file.
-
-→ Proceed to **Step 5**.
-
 #### If no tracking file exists
 
-Create `docs/workflow/implementation/{topic}.md`:
+Create `docs/workflow/implementation/{topic}/tracking.md`:
 
 ```yaml
 ---
 topic: {topic}
-plan: ../planning/{topic}.md
+plan: ../../planning/{topic}.md
 format: {format from plan}
 status: in-progress
 task_gate_mode: gated
 fix_gate_mode: gated
 fix_attempts: 0
+linters: []
+analysis_cycle: 0
 project_skills: []
 current_phase: 1
 current_task: ~
@@ -192,99 +150,114 @@ completed: ~
 Implementation started.
 ```
 
-After creating the file, populate `project_skills` with the paths confirmed in Step 3 (empty array if none).
-
 Commit: `impl({topic}): start implementation`
 
-→ Proceed to **Step 5**.
+→ Proceed to **Step 4**.
 
 ---
 
-## Step 5: Task Loop
+## Step 4: Project Skills Discovery
 
-Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its instructions as written.
+#### If `project_skills` is populated in the tracking file
 
-→ After the loop completes, proceed to **Step 6**.
+Present the existing configuration for confirmation:
 
----
+> "Previous session used these project skills:
+> - `{skill-name}` — {path}
+> - ...
+>
+> · · ·
+>
+> - **`y`/`yes`** — Keep these, proceed
+> - **`c`/`change`** — Re-discover and choose skills"
 
-## Step 6: Polish
+**STOP.** Wait for user choice.
 
-If the task loop exited early (user chose `stop`), skip to **Step 7**.
+- **`yes`**: → Proceed to **Step 5**.
+- **`change`**: Clear `project_skills` and fall through to discovery below.
 
-**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:
+#### If `.claude/skills/` does not exist or is empty
 
 ```
-impl({topic}): pre-polish checkpoint
+No project skills found. Proceeding without project-specific conventions.
 ```
 
-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.
+→ Proceed to **Step 5**.
 
-**Invoke the polish agent:**
+#### If project skills exist
 
-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
+Scan `.claude/skills/` for project-specific skill directories. Present findings:
 
-> **Implementation polish complete** ({N} cycles)
->
-> {SUMMARY}
->
-> Findings:
-> {DISCOVERY}
->
-> Fixes applied:
-> {FIXES_APPLIED}
->
-> Integration tests added:
-> {TESTS_ADDED}
+> Found these project skills that may be relevant to implementation:
+> - `{skill-name}` — {brief description}
+> - `{skill-name}` — {brief description}
+> - ...
 >
-> Skipped (not addressed):
-> {SKIPPED}
+> Which of these should I pass to the implementation agents? (all / list / none)
+
+**STOP.** Wait for user to confirm which skills are relevant.
+
+Store the selected skill paths in the tracking file.
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 5: Linter Discovery
+
+Load **[linter-setup.md](references/linter-setup.md)** and follow its discovery process to identify project linters.
+
+If `linters` is already populated in the tracking file, present the existing configuration for confirmation (same pattern as project skills in Step 4). If confirmed, skip discovery and proceed.
+
+Otherwise, present discovery findings to the user:
+
+> **Linter discovery:**
+> - {tool} — `{command}` (installed / not installed)
+> - ...
 >
-> Test results: {TEST_RESULTS}
+> Recommendations: {any suggested tools with install commands}
 >
 > · · ·
 >
-> - **`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)
+> - **`y`/`yes`** — Approve these linter commands
+> - **`c`/`change`** — Modify the linter list
+> - **`s`/`skip`** — Skip linter setup (no linting during TDD)
 
-**STOP.** Wait for user input.
+**STOP.** Wait for user choice.
 
-#### If `yes`
+- **`yes`**: Store the approved linter commands in the tracking file.
+- **`change`**: Adjust based on user input, re-present for confirmation.
+- **`skip`**: Store empty linters array.
 
-Commit all polish changes:
+→ Proceed to **Step 6**.
 
-```
-impl({topic}): polish — {brief description}
-```
+---
 
-→ Proceed to **Step 7**.
+## Step 6: Task Loop
 
-#### If `skip`
+Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its instructions as written.
 
-Discard all polish changes. Reset the working tree to the pre-polish checkpoint:
+After the loop completes:
 
-```
-git checkout . && git clean -fd
-```
+→ If the task loop exited early (user chose `stop`), proceed to **Step 8**.
+
+→ Otherwise, proceed to **Step 7**.
+
+---
 
-This is safe because the checkpoint commit captured all prior work. Only polish-created changes are discarded. Gitignored files are untouched.
+## Step 7: Analysis Loop
 
-→ Proceed to **Step 7**.
+Load **[steps/analysis-loop.md](references/steps/analysis-loop.md)** and follow its instructions as written.
 
-#### If comment
+→ If new tasks were created in the plan, return to **Step 6**.
 
-→ 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).
+→ If no tasks were created, proceed to **Step 8**.
 
 ---
 
-## Step 7: Mark Implementation Complete
+## Step 8: Mark Implementation Complete
 
-Update the tracking file (`docs/workflow/implementation/{topic}.md`):
+Update the tracking file (`docs/workflow/implementation/{topic}/tracking.md`):
 - Set `status: completed`
 - Set `completed: YYYY-MM-DD` (use today's actual date)
 - Update `updated` date
@@ -296,10 +269,14 @@ Commit: `impl({topic}): complete implementation`
 ## References
 
 - **[environment-setup.md](references/environment-setup.md)** — Environment setup before implementation
+- **[linter-setup.md](references/linter-setup.md)** — Linter discovery and configuration
 - **[steps/task-loop.md](references/steps/task-loop.md)** — Task execution loop, task gates, tracking, commits
+- **[steps/analysis-loop.md](references/steps/analysis-loop.md)** — Analysis and refinement cycle
 - **[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
+- **[steps/invoke-analysis.md](references/steps/invoke-analysis.md)** — How to invoke analysis agents
+- **[steps/invoke-synthesizer.md](references/steps/invoke-synthesizer.md)** — How to invoke the synthesis agent
+- **[steps/invoke-task-writer.md](references/steps/invoke-task-writer.md)** — How to invoke the task writer 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/linter-setup.md

@@ -0,0 +1,39 @@
+# Linter Setup
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+Discover and configure project linters for use during the TDD cycle's LINT step. Linters run after every REFACTOR to catch mechanical issues (formatting, unused imports, type errors) that are cheaper to fix immediately than in review.
+
+---
+
+## Discovery Process
+
+1. **Identify project languages** — check file extensions, package files (`composer.json`, `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`, etc.), and project skills in `.claude/skills/`
+2. **Check for existing linter configs** — look for config files in the project root:
+   - PHP: `phpstan.neon`, `phpstan.neon.dist`, `pint.json`, `.php-cs-fixer.php`
+   - JavaScript/TypeScript: `.eslintrc*`, `eslint.config.*`, `biome.json`
+   - Go: `.golangci.yml`, `.golangci.yaml`
+   - Python: `pyproject.toml` (ruff/mypy sections), `setup.cfg`, `.flake8`
+   - Rust: `rustfmt.toml`, `clippy.toml`
+3. **Verify tools are installed** — run each discovered tool with `--version` or equivalent to confirm it's available
+4. **Recommend if none found** — if a language is detected but no linter is configured, suggest best-practice tools (e.g., PHPStan + Pint for PHP, ESLint for JS/TS, golangci-lint for Go). Include install commands.
+
+## Storage
+
+Linter commands are stored in the implementation tracking file frontmatter as a `linters` array:
+
+```yaml
+linters:
+  - name: phpstan
+    command: vendor/bin/phpstan analyse --memory-limit=512M
+  - name: pint
+    command: vendor/bin/pint --test
+```
+
+Each entry has:
+- **name** — identifier for display
+- **command** — the exact shell command to run (including flags)
+
+If the user skips linter setup, store an empty array: `linters: []`

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

@@ -0,0 +1,174 @@
+# Analysis Loop
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+Each cycle follows stages A through F sequentially. Always start at **A. Cycle Gate**.
+
+```
+A. Cycle gate (check analysis_cycle, warn if over limit)
+B. Git checkpoint
+C. Dispatch analysis agents → invoke-analysis.md
+D. Dispatch synthesis agent → invoke-synthesizer.md
+E. Approval gate (present tasks, approve/skip/comment)
+F. Create tasks in plan → invoke-task-writer.md
+→ Route on result
+```
+
+---
+
+## A. Cycle Gate
+
+Increment `analysis_cycle` in the implementation tracking file.
+
+If `analysis_cycle > 3`:
+
+> **Analysis cycle {N} — this is beyond the standard 3 cycles.**
+>
+> · · ·
+>
+> - **`s`/`skip`** — Skip analysis, proceed to completion
+> - **`p`/`proceed`** — Run analysis anyway
+
+**STOP.** Wait for user choice.
+
+- **`skip`**: → Return to the skill for **Step 8**.
+- **`proceed`**: → Continue to **B. Git Checkpoint**.
+
+→ If `analysis_cycle <= 3`, proceed to **B. Git Checkpoint**.
+
+---
+
+## B. Git Checkpoint
+
+Ensure a clean working tree before analysis. Run `git status`.
+
+→ If the working tree is clean, proceed to **C. Dispatch Analysis Agents**.
+
+If there are unstaged changes or untracked files, categorize them:
+
+- **Implementation files** (files touched by `impl({topic}):` commits) — stage these automatically.
+- **Unexpected files** (files not touched during implementation) — present to the user:
+
+> **Pre-analysis checkpoint — unexpected files detected:**
+> - `{file}` ({status: modified/untracked})
+> - ...
+>
+> · · ·
+>
+> - **`y`/`yes`** — Include all in the checkpoint commit
+> - **`s`/`skip`** — Exclude unexpected files, commit only implementation files
+> - **Comment** — Specify which to include
+
+**STOP.** Wait for user choice.
+
+Commit included files:
+
+```
+impl({topic}): pre-analysis checkpoint
+```
+
+→ Proceed to **C. Dispatch Analysis Agents**.
+
+---
+
+## C. Dispatch Analysis Agents
+
+Load **[invoke-analysis.md](invoke-analysis.md)** and follow its instructions.
+
+**STOP.** Do not proceed until all agents have returned.
+
+→ Proceed to **D. Dispatch Synthesis Agent**.
+
+---
+
+## D. Dispatch Synthesis Agent
+
+Load **[invoke-synthesizer.md](invoke-synthesizer.md)** and follow its instructions.
+
+**STOP.** Do not proceed until the synthesizer has returned.
+
+→ If `STATUS: clean`, return to the skill for **Step 8**.
+
+→ If `STATUS: tasks_proposed`, proceed to **E. Approval Gate**.
+
+---
+
+## E. Approval Gate
+
+Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks.md`.
+
+Present an overview:
+
+> **Analysis cycle {N}: {K} proposed tasks**
+>
+> 1. {title} ({severity})
+> 2. {title} ({severity})
+> ...
+
+Then present each task with `status: pending` individually:
+
+> **Task {current}/{total}: {title}** ({severity})
+> Sources: {sources}
+>
+> **Problem**: {problem}
+> **Solution**: {solution}
+> **Outcome**: {outcome}
+>
+> **Do**:
+> {steps}
+>
+> **Acceptance Criteria**:
+> {criteria}
+>
+> **Tests**:
+> {tests}
+>
+> · · ·
+>
+> - **`a`/`approve`** — Approve this task
+> - **`s`/`skip`** — Skip this task
+> - **Comment** — Revise based on feedback
+
+**STOP.** Wait for user input.
+
+#### If `approve`
+
+Update `status: approved` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If `skip`
+
+Update `status: skipped` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If comment
+
+Revise the task content in the staging file based on the user's feedback. Re-present this task.
+
+---
+
+After all tasks processed:
+
+→ If any tasks have `status: approved`, proceed to **F. Create Tasks in Plan**.
+
+→ If all tasks were skipped, return to the skill for **Step 8**.
+
+---
+
+## F. Create Tasks in Plan
+
+Load **[invoke-task-writer.md](invoke-task-writer.md)** and follow its instructions.
+
+**STOP.** Do not proceed until the task writer has returned.
+
+Commit:
+
+```
+impl({topic}): add analysis phase {N} ({K} tasks)
+```
+
+→ Return to the skill. New tasks are now in the plan.

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

@@ -0,0 +1,53 @@
+# Invoke Analysis Agents
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step dispatches the three analysis agents in parallel to evaluate the completed implementation from different perspectives: duplication, standards conformance, and architecture.
+
+---
+
+## Identify Scope
+
+Build the list of implementation files using git history:
+
+```bash
+git log --oneline --name-only --pretty=format: --grep="impl({topic}):" | sort -u | grep -v '^$'
+```
+
+This captures all files touched by implementation commits for the topic.
+
+---
+
+## Dispatch All Three Agents
+
+Dispatch **all three in parallel** via the Task tool. Each agent receives the same inputs:
+
+1. **Implementation files** — the file list from scope identification
+2. **Specification path** — from the plan's frontmatter (if available)
+3. **Project skill paths** — from `project_skills` in the implementation tracking file
+4. **code-quality.md path** — `../code-quality.md`
+5. **Topic name** — the implementation topic
+
+Each agent knows its own output path convention and writes findings independently.
+
+### Agent 1: Duplication
+
+- **Agent path**: `../../../../agents/implementation-analysis-duplication.md`
+
+### Agent 2: Standards
+
+- **Agent path**: `../../../../agents/implementation-analysis-standards.md`
+
+### Agent 3: Architecture
+
+- **Agent path**: `../../../../agents/implementation-analysis-architecture.md`
+
+---
+
+## Wait for Completion
+
+**STOP.** Do not proceed until all three agents have returned.
+
+Each agent writes its findings to its own output file and returns a brief status. If any agent fails (error, timeout), record the failure and continue — the synthesizer works with whatever findings files are available.

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

@@ -17,10 +17,11 @@ This step invokes the `implementation-task-executor` agent (`../../../../agents/
 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. **Linter commands**: from `linters` in the implementation tracking file (if configured)
 
 **Re-attempts after review feedback** additionally include:
-6. **User-approved review notes**: verbatim or as modified by the user
-7. **Specific issues to address**: the ISSUES from the review
+7. **User-approved review notes**: verbatim or as modified by the user
+8. **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.
 

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

@@ -0,0 +1,37 @@
+# Invoke Synthesizer
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the synthesis agent to read analysis findings, deduplicate, and write normalized tasks to a staging file for user approval.
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../../agents/implementation-analysis-synthesizer.md`
+
+Pass via the orchestrator's prompt:
+
+1. **Task normalization reference path** — `../task-normalisation.md`
+2. **Topic name** — the implementation topic
+3. **Cycle number** — the current analysis cycle number
+4. **Specification path** — from the plan's frontmatter (if available)
+
+The agent knows its own file path conventions — it locates findings files and writes output files based on the topic name.
+
+---
+
+## Expected Result
+
+Returns a brief status:
+
+```
+STATUS: tasks_proposed | clean
+TASKS_PROPOSED: {N}
+SUMMARY: {1-2 sentences}
+```
+
+- `tasks_proposed`: tasks written to staging file — orchestrator should present for approval
+- `clean`: no actionable findings — orchestrator should proceed to completion

package/skills/technical-implementation/references/steps/invoke-task-writer.md

@@ -0,0 +1,36 @@
+# Invoke Task Writer
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the task writer agent to create plan tasks from approved analysis findings.
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../../agents/implementation-analysis-task-writer.md`
+
+Pass via the orchestrator's prompt:
+
+1. **Topic name** — the implementation topic
+2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks.md`
+3. **Plan path** — the implementation plan path
+4. **Plan format reading adapter path** — `../../../technical-planning/references/output-formats/{format}/reading.md`
+5. **Plan format authoring adapter path** — `../../../technical-planning/references/output-formats/{format}/authoring.md`
+
+---
+
+## Expected Result
+
+The agent creates tasks in the plan for all approved entries in the staging file.
+
+Returns a brief status:
+
+```
+STATUS: complete
+TASKS_CREATED: {N}
+PHASE: {N}
+SUMMARY: {1 sentence}
+```

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

@@ -4,9 +4,7 @@
 
 ---
 
-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.
+Follow stages A through E sequentially for each task. Do not abbreviate, skip, or compress stages based on previous iterations.
 
 ```
 A. Retrieve next task
@@ -64,7 +62,7 @@ Present the executor's ISSUES to the user:
 
 #### If `stop`
 
-→ Return to the skill for **Step 6**.
+→ Return to the skill for **Step 7**.
 
 ---
 
@@ -159,7 +157,7 @@ Announce the result (one line, no stop):
 
 **Update task progress in the plan** — follow the format's **updating.md** instructions to mark the task complete.
 
-**Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}.md`):
+**Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}/tracking.md`):
 - Append the task ID to `completed_tasks`
 - Update `current_phase` if phase changed
 - Update `current_task` to the next task (or `~` if done)
@@ -187,4 +185,4 @@ This is the end of this iteration.
 
 > "All tasks complete. {M} tasks implemented."
 
-→ Return to the skill for **Step 6**.
+→ Return to the skill for **Step 7**.