@leeovery/claude-technical-workflows 2.1.14 → 2.1.16

package/agents/implementation-analysis-architecture.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -34,7 +35,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent and boundaries
 4. **Read all implementation files** — understand the full picture
 5. **Analyze architecture** — evaluate how the pieces compose as a whole
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -48,7 +49,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-architecture.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-architecture-c{cycle-number}.md`:
 
 ```
 AGENT: architecture

package/agents/implementation-analysis-duplication.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -33,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read specification** — understand design intent
 4. **Read all implementation files** — build a mental map of the full codebase
 5. **Analyze for duplication** — compare patterns across files, identify extraction candidates
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -47,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-duplication.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-duplication-c{cycle-number}.md`:
 
 ```
 AGENT: duplication

package/agents/implementation-analysis-standards.md

@@ -18,6 +18,7 @@ You receive via the orchestrator's prompt:
 3. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
 4. **code-quality.md path** — quality standards
 5. **Topic name** — the implementation topic
+6. **Cycle number** — which analysis cycle this is (used in output file naming)
 
 ## Your Focus
 
@@ -33,7 +34,7 @@ You receive via the orchestrator's prompt:
 3. **Read code-quality.md** — understand quality standards
 4. **Read all implementation files** — map each file back to its spec requirements
 5. **Compare implementation against spec** — check every decision point
-6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards.md`
+6. **Write findings** to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`
 
 ## Hard Rules
 
@@ -47,7 +48,7 @@ You receive via the orchestrator's prompt:
 
 ## Output File Format
 
-Write to `docs/workflow/implementation/{topic}/analysis-standards.md`:
+Write to `docs/workflow/implementation/{topic}/analysis-standards-c{cycle-number}.md`:
 
 ```
 AGENT: standards

package/agents/implementation-analysis-synthesizer.md

@@ -20,13 +20,13 @@ You receive via the orchestrator's prompt:
 
 ## Your Process
 
-1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication.md`, `analysis-standards.md`, and `analysis-architecture.md`
+1. **Read all findings files** from `docs/workflow/implementation/{topic}/` — look for `analysis-duplication-c{cycle-number}.md`, `analysis-standards-c{cycle-number}.md`, and `analysis-architecture-c{cycle-number}.md`
 2. **Deduplicate** — same issue found by multiple agents → one finding, note all sources
 3. **Group related findings** — multiple findings about the same pattern become one task (e.g., 3 duplication findings about the same helper pattern = 1 "extract helper" task)
 4. **Filter** — discard low-severity findings unless they cluster into a pattern. Never discard high-severity.
 5. **Normalize** — convert each group into a task using the canonical task template (Problem / Solution / Outcome / Do / Acceptance Criteria / Tests)
-6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report.md`
-7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks.md` with `status: pending` for each task
+6. **Write report** — output to `docs/workflow/implementation/{topic}/analysis-report-c{cycle-number}.md`
+7. **Write staging file** — if actionable tasks exist, write to `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md` with `status: pending` for each task
 
 ## Report Format
 

package/agents/implementation-analysis-task-writer.md

@@ -26,6 +26,31 @@ You receive via the orchestrator's prompt:
 3. **Calculate next phase number** — max existing phase + 1
 4. **Read the authoring adapter** — understand how to create tasks in this format
 5. **Create tasks in the plan** — follow the authoring adapter's instructions for each approved task, using the topic name to scope tasks to this plan (e.g., directory paths, task ID prefixes, project association)
+6. **Update the Plan Index File** — append the new phase and task table to the Plan Index File body (see below)
+
+## Update the Plan Index File
+
+The Plan Index File (`docs/workflow/planning/{topic}.md`) is the single source of truth for planning progress. After creating task files, you **must** append the new phase and task table to its body.
+
+Append at the end of the Plan Index File body:
+
+```markdown
+### Phase {N}: Analysis ({cycle description})
+status: approved
+
+**Goal**: Address findings from implementation analysis cycle {N}.
+
+#### Tasks
+| ID | Name | Edge Cases | Status |
+|----|------|------------|--------|
+| {topic}-{phase}-1 | {Task Title} | — | authored |
+| {topic}-{phase}-2 | {Task Title} | — | authored |
+```
+
+- Use `status: approved` for the phase (it's pre-approved by the user in the approval gate)
+- Use `authored` for each task status (the task files are fully written)
+- Use `—` for edge cases (analysis tasks don't have separate edge case annotations)
+- Task IDs must match the IDs used in the created task files
 
 ## Hard Rules
 
@@ -33,7 +58,7 @@ You receive via the orchestrator's prompt:
 
 1. **Approved only** — only create tasks with `status: approved`. Never create tasks that are `pending` or `skipped`.
 2. **No content modifications** — create tasks exactly as they appear in the staging file. Do not rewrite, reorder, or embellish.
-3. **No git writes** — do not commit or stage. Writing plan task files/entries are your only writes.
+3. **No git writes** — do not commit or stage. Writing plan task files/entries and updating the Plan Index File are your only writes.
 4. **Authoring adapter is authoritative** — follow its instructions for task file structure, naming, and format.
 
 ## Your Output

package/package.json

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

package/skills/start-discussion/SKILL.md

@@ -232,10 +232,10 @@ Discussions:
 
 How would you like to proceed?
 
+- **`r`/`refresh`** — Force fresh research analysis
 - From research — pick a topic number above (e.g., "1" or "research 1")
 - Continue discussion — name one above (e.g., "continue {topic}")
 - Fresh topic — describe what you want to discuss
-- **`r`/`refresh`** — Force fresh research analysis
 ```
 
 **If ONLY research exists:**
@@ -244,9 +244,9 @@ How would you like to proceed?
 
 How would you like to proceed?
 
+- **`r`/`refresh`** — Force fresh research analysis
 - From research — pick a topic number above (e.g., "1" or "research 1")
 - Fresh topic — describe what you want to discuss
-- **`r`/`refresh`** — Force fresh research analysis
 ```
 
 **If ONLY discussions exist:**

package/skills/start-implementation/SKILL.md

@@ -262,10 +262,9 @@ INCOMPLETE (planned but not implemented):
 
 · · ·
 
-OPTIONS:
-1. Implement the blocking dependencies first
-2. Mark a dependency as "satisfied externally" if it was implemented outside this workflow
-3. Run /link-dependencies to wire up any recently completed plans
+- **`i`/`implement`** — Implement the blocking dependencies first
+- **`l`/`link`** — Run /link-dependencies to wire up recently completed plans
+- Mark as "satisfied externally" — tell me which dependency was implemented outside this workflow
 ```
 
 **STOP.** Wait for user response.

package/skills/start-planning/SKILL.md

@@ -230,9 +230,12 @@ If any are relevant:
 Note: The following cross-cutting specifications are still in-progress:
   · {rate-limiting} - in-progress
 
-These may contain architectural decisions relevant to this plan. You can:
-- Continue planning without them
-- Stop and complete them first (/start-specification)
+These may contain architectural decisions relevant to this plan.
+
+· · ·
+
+- **`c`/`continue`** — Plan without them
+- **`s`/`stop`** — Complete them first (/start-specification)
 ```
 
 **STOP.** Wait for user response.

package/skills/start-review/SKILL.md

@@ -142,11 +142,9 @@ Ask the user what code to review:
 
 What code should I review?
 
-1. All changes since the plan was created
-2. Specific directories or files
-3. Let me identify from git status
-
-Which approach?
+- **`a`/`all`** — All changes since the plan was created
+- **`g`/`git`** — Identify from git status
+- Specific directories or files — tell me which
 ```
 
 **STOP.** Wait for user response.

package/skills/start-specification/SKILL.md

@@ -214,9 +214,9 @@ Check `cache.status` from discovery to determine which options to present.
 
 What would you like to do?
 
-- Continue an existing specification — resume work on a spec in progress
-- Select from groupings — choose from previously analyzed groupings ({cache.generated})
-- Re-analyze groupings — fresh analysis of discussion relationships
+- **`c`/`continue`** — Resume work on a spec in progress
+- **`s`/`select`** — Choose from previously analyzed groupings ({cache.generated})
+- **`r`/`refresh`** — Fresh analysis of discussion relationships
 ```
 
 **STOP.** Wait for user response.
@@ -230,8 +230,8 @@ What would you like to do?
 
 Note: A previous grouping analysis exists but is now outdated - discussion documents have changed since it was created. Re-analysis is required, but existing specification names will be preserved where groupings overlap.
 
-- Continue an existing specification — resume work on a spec in progress
-- Assess for groupings — re-analyze discussions for combinations
+- **`c`/`continue`** — Resume work on a spec in progress
+- **`a`/`assess`** — Re-analyze discussions for combinations
 ```
 
 **STOP.** Wait for user response.
@@ -243,13 +243,13 @@ Note: A previous grouping analysis exists but is now outdated - discussion docum
 
 What would you like to do?
 
-- Continue an existing specification — resume work on a spec in progress
-- Assess for groupings — analyze discussions for combinations
+- **`c`/`continue`** — Resume work on a spec in progress
+- **`a`/`assess`** — Analyze discussions for combinations
 ```
 
 **STOP.** Wait for user response.
 
-#### If "Continue an existing specification"
+#### If "continue"
 
 ```
 Which specification would you like to continue?
@@ -260,13 +260,13 @@ Which specification would you like to continue?
 
 **STOP.** Wait for user to pick, then skip to **Step 9**.
 
-#### If "Select from groupings" (valid cache path)
+#### If "select" (valid cache path)
 
 Load groupings from cache and → Skip directly to **Step 7: Present Grouping Options**.
 
 (Context was already gathered when the analysis was created - no need to ask again.)
 
-#### If "Re-analyze groupings"
+#### If "refresh"
 
 Delete the existing cache to force regeneration:
 ```bash
@@ -275,7 +275,7 @@ rm docs/workflow/.cache/discussion-consolidation-analysis.md
 
 → Proceed to **Step 4: Gather Analysis Context**.
 
-#### If "Assess for groupings" (no valid cache path)
+#### If "assess" (no valid cache path)
 
 → Proceed to **Step 4: Gather Analysis Context**.
 
@@ -478,11 +478,11 @@ Coupling: {explanation}
 
 How would you like to proceed?
 
-- Proceed as recommended — I'll ask which to start with
-- Combine differently — tell me your preferred groupings
-- Single specification — consolidate ALL into one unified spec
-- Individual specifications — create 1:1 specs (I'll ask which to start)
+- **`p`/`proceed`** — As recommended (I'll ask which to start with)
+- **`s`/`single`** — Consolidate ALL into one unified spec
+- **`i`/`individual`** — Create 1:1 specs (I'll ask which to start)
 - **`r`/`refresh`** — Re-analyze discussions
+- Combine differently — tell me your preferred groupings
 ```
 
 **Status Legend:**
@@ -502,7 +502,7 @@ How would you like to proceed?
 
 Based on user's choice from Step 7:
 
-#### If "Proceed as recommended"
+#### If "proceed"
 
 ```
 Which would you like to start with?
@@ -521,7 +521,7 @@ List ALL items from the analysis: grouped specifications first, then independent
 
 **STOP.** Wait for user to pick a number, then proceed to **Step 9**.
 
-#### If "Combine differently"
+#### If "combine differently"
 
 ```
 Please describe your preferred groupings. Which discussions should be combined together?
@@ -566,9 +566,8 @@ Moving discussions between established specifications requires deleting the affe
 
 · · ·
 
-Options:
-- Delete affected specs and proceed — remove {spec-1}, {spec-2} and create fresh specs for your new groupings
-- Reconsider — adjust your groupings to affect fewer specs
+- **`d`/`delete`** — Remove affected specs and create fresh ones for your new groupings
+- **`r`/`reconsider`** — Adjust your groupings to affect fewer specs
 ```
 
 **STOP.** Wait for user choice.
@@ -599,7 +598,7 @@ Which grouping would you like to start with?
 
 **STOP.** Wait for user to pick, then proceed to **Step 9**.
 
-#### If "Single specification"
+#### If "single"
 
 Use "unified" as the specification name.
 Check if `docs/workflow/specification/unified.md` already exists.
@@ -618,7 +617,7 @@ Proceed with unified specification?
 
 **STOP.** Wait for user to confirm, then proceed to **Step 9** with all discussions as sources.
 
-#### If "Individual specifications"
+#### If "individual"
 
 ```
 Which discussion would you like to specify?

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`, `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.
+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-*-c{cycle-number}.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.
 

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

@@ -79,6 +79,12 @@ Load **[invoke-analysis.md](invoke-analysis.md)** and follow its instructions.
 
 **STOP.** Do not proceed until all agents have returned.
 
+Commit the analysis findings:
+
+```
+impl({topic}): analysis cycle {N} — findings
+```
+
 → Proceed to **D. Dispatch Synthesis Agent**.
 
 ---
@@ -89,6 +95,12 @@ Load **[invoke-synthesizer.md](invoke-synthesizer.md)** and follow its instructi
 
 **STOP.** Do not proceed until the synthesizer has returned.
 
+Commit the synthesis output:
+
+```
+impl({topic}): analysis cycle {N} — synthesis
+```
+
 → If `STATUS: clean`, return to the skill for **Step 8**.
 
 → If `STATUS: tasks_proposed`, proceed to **E. Approval Gate**.
@@ -97,7 +109,7 @@ Load **[invoke-synthesizer.md](invoke-synthesizer.md)** and follow its instructi
 
 ## E. Approval Gate
 
-Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks.md`.
+Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`.
 
 Present an overview:
 
@@ -155,7 +167,15 @@ 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**.
+→ If all tasks were skipped:
+
+Commit the staging file updates:
+
+```
+impl({topic}): analysis cycle {N} — tasks skipped
+```
+
+Return to the skill for **Step 8**.
 
 ---
 
@@ -165,7 +185,7 @@ Load **[invoke-task-writer.md](invoke-task-writer.md)** and follow its instructi
 
 **STOP.** Do not proceed until the task writer has returned.
 
-Commit:
+Commit all analysis and plan changes (staging file, plan tasks, Plan Index File):
 
 ```
 impl({topic}): add analysis phase {N} ({K} tasks)

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

@@ -29,6 +29,7 @@ Dispatch **all three in parallel** via the Task tool. Each agent receives the sa
 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
+6. **Cycle number** — the current analysis cycle number (from `analysis_cycle` in the tracking file)
 
 Each agent knows its own output path convention and writes findings independently.
 

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

@@ -15,7 +15,7 @@ This step invokes the task writer agent to create plan tasks from approved analy
 Pass via the orchestrator's prompt:
 
 1. **Topic name** — the implementation topic
-2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks.md`
+2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.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`

package/skills/technical-research/SKILL.md

@@ -91,7 +91,7 @@ When you notice convergence, **flag it and give the user options**:
 >
 > - **`p`/`park`** — Mark as discussion-ready and move to another topic
 > - **`k`/`keep`** — Keep digging, there's more to understand
-> - **Comment** — Your call
+> - Comment — your call
 
 **Never decide for the user.** Even if the answer seems obvious, flag it and ask.