@leeovery/claude-technical-workflows 2.1.10 → 2.1.12

package/skills/technical-discussion/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: false
 
 # Technical Discussion
 
-Act as **expert software architect** participating in discussions AND **documentation assistant** capturing them. Do both simultaneously. Engage deeply while documenting for planning teams.
+Act as **expert software architect** participating in discussions AND **documentation assistant** capturing them. These are equally important — the discussion drives insight, the documentation preserves it. Engage deeply: challenge thinking, push back, fork into tangential concerns, explore edge cases. Then capture what emerged.
 
 ## Purpose in the Workflow
 
@@ -77,16 +77,23 @@ Use **[template.md](references/template.md)** for structure:
 
 See **[guidelines.md](references/guidelines.md)** for best practices and anti-hallucination techniques.
 
-## Commit Frequently
+## Write to Disk and Commit Frequently
 
-**Commit discussion docs often**:
+The discussion file is your memory. Context compaction is lossy — what's not on disk is lost. Don't hold content in conversation waiting for a "complete" answer. Partial, provisional documentation is expected and valuable.
 
-- At natural breaks in discussion
-- When solutions to problems are identified
-- When discussion branches/forks to new topics
-- Before context refresh (prevents hallucination/memory loss)
+**Write to the file at natural moments:**
 
-**Why**: You lose memory on context refresh. Commits help you track, backtrack, and fill gaps. Critical for avoiding hallucination.
+- A micro-decision is reached (even if provisional)
+- A piece of the puzzle is solved
+- The discussion is about to branch or fork
+- A question is answered or a new one uncovered
+- Before context refresh
+
+These are natural pauses, not every exchange. Document the reasoning and context — not a verbatim transcript.
+
+**After writing, git commit.** Commits let you track, backtrack, and recover after compaction. Don't batch — commit each time you write.
+
+**Create the file early.** After understanding the topic and initial questions, create the discussion file with frontmatter, context, and the questions list. Don't wait until you have answers.
 
 ## Quick Reference
 

package/skills/technical-discussion/references/guidelines.md

@@ -55,14 +55,19 @@ Best practices for documenting discussions. For DOCUMENTATION only - no plans or
 **False Paths**: What didn't work, why
 **Impact**: Who benefits, what enabled
 
-## Update as Discussing
+## Write to Disk as Discussing
+
+At natural pauses — not every exchange, but when something meaningful has been concluded, explored, or uncovered — update the file on disk:
 
 - Check off answered questions
 - Add options as explored
-- Document false paths immediately
-- Record decisions with rationale
+- Document false paths when identified
+- Record decisions (even provisional ones) with rationale
+- Capture new questions as they emerge
 - Keep "Current Thinking" updated
 
+Then commit. The file is the source of truth, not the conversation.
+
 ## Common Pitfalls
 
 **Jumping to implementation**: Discussion ends at decisions, not at "here's how to build it"

package/skills/technical-discussion/references/meeting-assistant.md

@@ -74,16 +74,15 @@ Who affected, problem solved, what enabled.
 
 Example: "200 enterprise users + sales get performant experience. Enables Q1 renewals."
 
-## Commit Often
+## Write and Commit Often
 
-**Git commit discussion docs frequently:**
+The file on disk is the work product. Context compaction will destroy conversation detail — the file is your defense against that.
 
-- Natural breaks in discussion
-- When problems solved
-- When discussion forks to new topics
-- Before context refresh
+**Write to the file at natural pauses** — when a micro-decision lands, a question is resolved (even provisionally), or the discussion is about to fork. Don't wait for finality. Partial documentation is expected.
 
-**Why**: Memory loss on context refresh causes hallucination. Commits help track, backtrack, fill gaps.
+**Then git commit.** Each write should be followed by a commit. This creates recovery points against context loss.
+
+**Don't transcribe** — capture the reasoning, options, and outcome. Keep it contextual, not verbatim.
 
 ## Principles
 

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.