@leeovery/claude-technical-workflows 2.1.23 → 2.1.25

package/skills/start-planning/SKILL.md

@@ -97,13 +97,18 @@ Use `state.scenario` from the discovery output to determine the path:
 
 No specifications exist yet.
 
+> *Output the next fenced block as a code block:*
+
 ```
+Planning Overview
+
 No specifications found in docs/workflow/specification/
 
-The planning phase requires a concluded specification. Please run /start-specification first.
+The planning phase requires a concluded specification.
+Run /start-specification first.
 ```
 
-**STOP.** Wait for user to acknowledge before ending.
+**STOP.** Do not proceed — terminal condition.
 
 #### If scenario is "nothing_actionable"
 
@@ -125,65 +130,107 @@ Present everything discovered to help the user make an informed choice.
 
 **Present the full state:**
 
+> *Output the next fenced block as a code block:*
+
 ```
-Planning Phase
+Planning Overview
+
+{N} specifications found. {M} plans exist.
+
+1. {topic:(titlecase)}
+   └─ Plan: @if(has_plan) {plan_status:[in-progress|concluded]} @else (no plan) @endif
+   └─ Spec: concluded
+
+2. ...
+```
+
+**Tree rules:**
+
+Each numbered item shows a feature specification that is actionable:
+- Concluded spec with no plan → `Plan: (no plan)`
+- Has a plan with `plan_status: planning` → `Plan: in-progress`
+- Has a plan with `plan_status: concluded` → `Plan: concluded`
 
-Available:
-  1. + {topic-2} - create new plan
-  2. ▶ {topic-3} - continue in-progress plan
-  3. > {topic-4} - review concluded plan
+**If non-plannable specifications exist**, show them in a separate code block:
+
+> *Output the next fenced block as a code block:*
 
-Not plannable specifications:
-  · {topic-1} [feature, in-progress]
-  · {caching-strategy} [cross-cutting, concluded]
-  · {rate-limiting} [cross-cutting, in-progress]
 ```
+Specifications not ready for planning:
+These specifications are either still in progress or cross-cutting
+and cannot be planned directly.
 
-**Output in a fenced code block exactly as shown above.**
+  • {topic} ({type:[feature|cross-cutting]}, {status:[in-progress|concluded]})
+```
 
-**Formatting rules:**
+**Key/Legend** — show only statuses that appear in the current display. No `---` separator before this section.
 
-Available (numbered, selectable):
-- **`+`** — concluded spec with no plan yet
-- **`▶`** — has a plan with `plan_status: planning`
-- **`>`** — has a plan with `plan_status: concluded`
+> *Output the next fenced block as a code block:*
 
-Not plannable specifications (no number, not selectable — `[type, status]` format):
-- **`·`** — feature specs still in-progress, or cross-cutting specifications
-- Feature specs: `[feature, in-progress]`
-- Cross-cutting specs: `[cross-cutting, {status}]`
+```
+Key:
 
-Omit either section entirely if it has no entries.
+  Plan status:
+    in-progress — planning work is ongoing
+    concluded   — plan is complete
+
+  Spec type:
+    cross-cutting — architectural policy, not directly plannable
+    feature       — plannable feature specification
+```
+
+Omit any section entirely if it has no entries.
 
 **Then prompt based on what's actionable:**
 
 **If multiple actionable items:**
+
+The verb in the menu depends on the plan state:
+- No plan exists → **Create**
+- Plan is `in-progress` → **Continue**
+- Plan is `concluded` → **Review**
+
+> *Output the next fenced block as markdown (not a code block):*
+
 ```
 · · · · · · · · · · · ·
-Select a specification (enter number):
+1. Create "Auth Flow" — concluded spec, no plan
+2. Continue "Data Model" — plan in-progress
+3. Review "Billing" — plan concluded
+
+Select an option (enter number):
+· · · · · · · · · · · ·
 ```
 
+Recreate with actual topics and states from discovery.
+
 **STOP.** Wait for user response.
 
 **If single actionable item (auto-select):**
+
+> *Output the next fenced block as a code block:*
+
 ```
-Auto-selecting: {topic} (only actionable specification)
+Automatically proceeding with "{topic:(titlecase)}".
 ```
 
 → Proceed directly to **Step 4**.
 
 **If nothing actionable:**
+
+> *Output the next fenced block as a code block:*
+
 ```
-No plannable specifications.
+Planning Overview
 
-Before you can start planning:
-- Complete any in-progress specifications with /start-specification, or
-- Create a new specification first
+No plannable specifications found.
 
-Then re-run /start-planning.
+The planning phase requires a concluded feature specification.
+Complete any in-progress specifications with /start-specification,
+or create a new specification first.
 ```
 
-**STOP.** This workflow cannot continue — do not proceed.
+**STOP.** Do not proceed — terminal condition.
 
 → Based on user choice, proceed to **Step 4**.
 
@@ -207,9 +254,16 @@ The plan already has its context from when it was created. Skip context gatherin
 
 ## Step 5: Gather Additional Context
 
-Ask:
-- Any additional context or priorities to consider?
-- Any constraints since the specification was concluded?
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Any additional context since the specification was concluded?
+
+- **`c`/`continue`** — Continue with the specification as-is
+- Or provide additional context (priorities, constraints, new considerations)
+· · · · · · · · · · · ·
+```
 
 **STOP.** Wait for user response.
 
@@ -229,12 +283,14 @@ If any **in-progress** cross-cutting specifications exist, check whether they co
 
 If any are relevant:
 
-```
-Note: The following cross-cutting specifications are still in-progress:
-  · {rate-limiting} - in-progress
+> *Output the next fenced block as markdown (not a code block):*
 
+```
+Cross-cutting specifications still in progress:
 These may contain architectural decisions relevant to this plan.
 
+  • {topic}
+
 · · · · · · · · · · · ·
 - **`c`/`continue`** — Plan without them
 - **`s`/`stop`** — Complete them first (/start-specification)
@@ -249,6 +305,8 @@ If the user chooses to stop, end here. If they choose to continue, proceed.
 
 If any **concluded** cross-cutting specifications exist, identify which are relevant to the feature being planned and summarize for handoff:
 
+> *Output the next fenced block as a code block:*
+
 ```
 Cross-cutting specifications to reference:
 - caching-strategy.md: [brief summary of key decisions]

package/skills/start-research/references/gather-context.md

@@ -10,7 +10,7 @@ Ask each question below **one at a time**. After each, **STOP** and wait for the
 
 ## Seed Idea
 
-Ask:
+> *Output the next fenced block as a code block:*
 
 ```
 What's on your mind?
@@ -25,7 +25,7 @@ What's on your mind?
 
 ## Current Knowledge
 
-Ask:
+> *Output the next fenced block as a code block:*
 
 ```
 What do you already know?
@@ -40,7 +40,7 @@ What do you already know?
 
 ## Starting Point
 
-Ask:
+> *Output the next fenced block as a code block:*
 
 ```
 Where should we start?
@@ -55,7 +55,7 @@ Where should we start?
 
 ## Final Context
 
-Ask:
+> *Output the next fenced block as a code block:*
 
 ```
 Any constraints or context I should know about upfront?

package/skills/start-review/SKILL.md

@@ -90,13 +90,19 @@ Use `state.scenario` from the discovery output to determine the path:
 
 No plans exist yet.
 
+> *Output the next fenced block as a code block:*
+
 ```
+Review Overview
+
 No plans found in docs/workflow/planning/
 
-The review phase requires a completed implementation based on a plan. Please run /start-planning first to create a plan, then /start-implementation to build it.
+The review phase requires a completed implementation based on a plan.
+Run /start-planning first to create a plan, then /start-implementation
+to build it.
 ```
 
-**STOP.** Wait for user to acknowledge before ending.
+**STOP.** Do not proceed — terminal condition.
 
 #### If scenario is "single_plan" or "multiple_plans"
 
@@ -106,107 +112,17 @@ Plans exist.
 
 ---
 
-## Step 3: Present Plans and Select Scope
-
-Present all discovered plans with implementation status to help the user understand what's reviewable.
-
-**Present the full state:**
-
-```
-Review Phase
-
-Reviewable:
-  1. ✓ {topic-1} (completed) - format: {format}, spec: {exists|missing}
-  2. ▶ {topic-2} (in-progress) - format: {format}, spec: {exists|missing}
-
-Not reviewable:
-  · {topic-3} [no implementation]
-```
-
-**Output in a fenced code block exactly as shown above.**
-
-**Formatting rules:**
-
-Reviewable (numbered, selectable):
-- **`✓`** — implementation_status: completed
-- **`▶`** — implementation_status: in-progress
-
-Not reviewable (not numbered, not selectable):
-- **`·`** — implementation_status: none
-
-Omit either section entirely if it has no entries.
-
-**Then route based on what's reviewable:**
-
-#### If no reviewable plans
-
-```
-No implemented plans found.
-
-The review phase requires at least one plan with an implementation.
-Please run /start-implementation first.
-```
-
-**STOP.** Wait for user to acknowledge before ending.
-
-#### If single reviewable plan
-
-```
-Auto-selecting: {topic} (only reviewable plan)
-Scope: single
-```
-
-→ Proceed directly to **Step 5**.
-
-#### If multiple reviewable plans
+## Step 3: Display Plans
 
-```
-· · · · · · · · · · · ·
-What scope would you like to review?
-
-- **`s`/`single`** — Review one plan's implementation
-- **`m`/`multi`** — Review selected plans together (cross-cutting)
-- **`a`/`all`** — Review all implemented plans (full product)
-· · · · · · · · · · · ·
-```
-
-**STOP.** Wait for user response.
+Load **[display-plans.md](references/display-plans.md)** and follow its instructions as written.
 
-→ Based on user choice, proceed to **Step 4**.
+→ Proceed to **Step 4**.
 
 ---
 
-## Step 4: Plan Selection
-
-This step only applies for `single` or `multi` scope chosen in Step 3.
-
-#### If scope is "all"
-
-All reviewable plans are included. No selection needed.
+## Step 4: Select Plans
 
-→ Proceed directly to **Step 5**.
-
-#### If scope is "single"
-
-```
-· · · · · · · · · · · ·
-Which plan would you like to review? (Enter a number from Step 3)
-· · · · · · · · · · · ·
-```
-
-**STOP.** Wait for user response.
-
-→ Proceed to **Step 5**.
-
-#### If scope is "multi"
-
-```
-· · · · · · · · · · · ·
-Which plans to include? (Enter numbers separated by commas, e.g. 1,3)
-· · · · · · · · · · · ·
-```
-
-**STOP.** Wait for user response.
+Load **[select-plans.md](references/select-plans.md)** and follow its instructions as written.
 
 → Proceed to **Step 5**.
 
@@ -214,29 +130,4 @@ Which plans to include? (Enter numbers separated by commas, e.g. 1,3)
 
 ## Step 5: Invoke the Skill
 
-After completing the steps above, this skill's purpose is fulfilled.
-
-Invoke the [technical-review](../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
-
-**Example handoff (single):**
-```
-Review session for: {topic}
-Review scope: single
-Plan: docs/workflow/planning/{topic}.md
-Format: {format}
-Plan ID: {plan_id} (if applicable)
-Specification: {specification} (exists: {true|false})
-
-Invoke the technical-review skill.
-```
-
-**Example handoff (multi/all):**
-```
-Review session for: {scope description}
-Review scope: {multi | all}
-Plans:
-  - docs/workflow/planning/{topic-1}.md (format: {format}, spec: {spec})
-  - docs/workflow/planning/{topic-2}.md (format: {format}, spec: {spec})
-
-Invoke the technical-review skill.
-```
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-review/references/display-plans.md

@@ -0,0 +1,103 @@
+# Display Plans
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+Present all discovered plans with implementation status to help the user understand what's reviewable.
+
+**Present the full state:**
+
+Show reviewable plans as numbered tree items.
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Overview
+
+{N} plans found. {M} with implementations.
+
+1. {topic:(titlecase)}
+   └─ Plan: concluded ({format})
+   └─ Implementation: {impl_status:[completed|in-progress]}
+   └─ Spec: {spec:[exists|missing]}
+
+2. ...
+```
+
+**Tree rules:**
+
+Reviewable (numbered):
+- Implementation `status: completed` → `Implementation: completed`
+- Implementation `status: in-progress` → `Implementation: in-progress`
+
+Omit any section entirely if it has no entries.
+
+**If non-reviewable plans exist**, show them in a separate code block:
+
+> *Output the next fenced block as a code block:*
+
+```
+Plans not ready for review:
+These plans have no implementation to review.
+
+  • {topic} (no implementation)
+```
+
+**Key/Legend** — show only statuses that appear in the current display. No `---` separator before this section.
+
+> *Output the next fenced block as a code block:*
+
+```
+Key:
+
+  Implementation status:
+    completed   — all tasks implemented
+    in-progress — implementation still ongoing
+```
+
+**Then route based on what's reviewable:**
+
+#### If no reviewable plans
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Overview
+
+No implemented plans found.
+
+The review phase requires at least one plan with an implementation.
+Run /start-implementation first.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If single reviewable plan
+
+> *Output the next fenced block as a code block:*
+
+```
+Automatically proceeding with "{topic:(titlecase)}".
+Scope: single
+```
+
+→ Proceed directly to **Step 5**.
+
+#### If multiple reviewable plans
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+What scope would you like to review?
+
+- **`s`/`single`** — Review one plan's implementation
+- **`m`/`multi`** — Review selected plans together (cross-cutting)
+- **`a`/`all`** — Review all implemented plans (full product)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+→ Based on user choice, proceed to **Step 4**.

package/skills/start-review/references/invoke-skill.md

@@ -0,0 +1,32 @@
+# Invoke the Skill
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+After completing the steps above, this skill's purpose is fulfilled.
+
+Invoke the [technical-review](../../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+
+**Example handoff (single):**
+```
+Review session for: {topic}
+Review scope: single
+Plan: docs/workflow/planning/{topic}.md
+Format: {format}
+Plan ID: {plan_id} (if applicable)
+Specification: {specification} (exists: {true|false})
+
+Invoke the technical-review skill.
+```
+
+**Example handoff (multi/all):**
+```
+Review session for: {scope description}
+Review scope: {multi | all}
+Plans:
+  - docs/workflow/planning/{topic-1}.md (format: {format}, spec: {spec})
+  - docs/workflow/planning/{topic-2}.md (format: {format}, spec: {spec})
+
+Invoke the technical-review skill.
+```

package/skills/start-review/references/select-plans.md

@@ -0,0 +1,41 @@
+# Select Plans
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+This step only applies for `single` or `multi` scope chosen in Step 3.
+
+#### If scope is "all"
+
+All reviewable plans are included. No selection needed.
+
+→ Proceed directly to **Step 5**.
+
+#### If scope is "single"
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Which plan would you like to review? (Enter a number from Step 3)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 5**.
+
+#### If scope is "multi"
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Which plans to include? (Enter numbers separated by commas, e.g. 1,3)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 5**.

package/skills/start-specification/references/analysis-flow.md

@@ -6,6 +6,8 @@
 
 ## A. Gather Analysis Context
 
+> *Output the next fenced block as a code block:*
+
 ```
 Before analyzing, is there anything about how these discussions relate
 that would help me group them appropriately?

package/skills/start-specification/references/confirm-continue.md

@@ -6,6 +6,8 @@
 
 #### If spec is in-progress with pending sources
 
+> *Output the next fenced block as a code block:*
+
 ```
 Continuing specification: {Title Case Name}
 
@@ -18,14 +20,20 @@ Previously extracted (for reference):
   • {discussion-name}
 ```
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 Proceed?
 - **`y`/`yes`**
 - **`n`/`no`**
 · · · · · · · · · · · ·
+```
 
 #### If spec is in-progress with all sources extracted
 
+> *Output the next fenced block as a code block:*
+
 ```
 Continuing specification: {Title Case Name}
 
@@ -36,14 +44,20 @@ All sources extracted:
   • {discussion-name}
 ```
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 Proceed?
 - **`y`/`yes`**
 - **`n`/`no`**
 · · · · · · · · · · · ·
+```
 
 #### If spec is concluded with pending sources
 
+> *Output the next fenced block as a code block:*
+
 ```
 Continuing specification: {Title Case Name}
 
@@ -56,11 +70,15 @@ Previously extracted (for reference):
   • {discussion-name}
 ```
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 Proceed?
 - **`y`/`yes`**
 - **`n`/`no`**
 · · · · · · · · · · · ·
+```
 
 **STOP.** Wait for user response.
 
@@ -78,12 +96,14 @@ Proceed?
 
 #### If single discussion (no menu to return to)
 
+> *Output the next fenced block as a code block:*
+
 ```
 Understood. You can run /start-discussion to continue working on
 discussions, or re-run this command when ready.
 ```
 
-Command ends.
+**STOP.** Do not proceed — terminal condition.
 
 #### If groupings or specs menu