@leeovery/claude-technical-workflows 2.1.13 → 2.1.15

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.13",
+  "version": "2.1.15",
   "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-discussion/SKILL.md

@@ -95,6 +95,36 @@ These are natural pauses, not every exchange. Document the reasoning and context
 
 **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.
 
+## Concluding a Discussion
+
+When the user is ready to conclude the discussion:
+
+1. Update frontmatter `status: concluded`
+2. Final commit
+3. Check for remaining in-progress discussions in `docs/workflow/discussion/`
+
+**If other in-progress discussions exist:**
+
+```
+Discussion concluded: {topic}
+
+Remaining in-progress discussions:
+- {topic-1}
+- {topic-2}
+
+To continue, clear your context and run `/start-discussion` to pick up the next topic.
+```
+
+**If no in-progress discussions remain:**
+
+```
+Discussion concluded: {topic}
+
+All discussions are now concluded.
+```
+
+**Do not offer to continue with another discussion in this session.** Each discussion benefits from a fresh context — continuing risks compaction-related information loss and reduced attention. Always advise the user to clear context first.
+
 ## Quick Reference
 
 - **Approach**: **[meeting-assistant.md](references/meeting-assistant.md)** - Dual role, workflow

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

@@ -89,5 +89,3 @@ Before marking discussion complete:
 - ✅ Impact explained
 - ✅ Confidence stated
 - ✅ No hallucination
-
-**When complete**: Update frontmatter `status: concluded`.

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

@@ -128,5 +128,3 @@ What we chose, why, the deciding factor, trade-offs accepted, confidence level.
 - Major questions concluded with rationale
 - Trade-offs understood
 - Path forward clear
-
-**When complete**: Update frontmatter `status: concluded` to signal ready for specification.

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.