@leeovery/claude-technical-workflows 2.1.24 → 2.1.26

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"
 
@@ -121,71 +126,9 @@ At least one specification is ready for planning, or an existing plan can be con
 
 ## Step 3: Present Workflow State and Options
 
-Present everything discovered to help the user make an informed choice.
-
-**Present the full state:**
-
-```
-Planning Phase
-
-Available:
-  1. + {topic-2} - create new plan
-  2. ▶ {topic-3} - continue in-progress plan
-  3. > {topic-4} - review concluded plan
-
-Not plannable specifications:
-  · {topic-1} [feature, in-progress]
-  · {caching-strategy} [cross-cutting, concluded]
-  · {rate-limiting} [cross-cutting, in-progress]
-```
-
-**Output in a fenced code block exactly as shown above.**
-
-**Formatting rules:**
-
-Available (numbered, selectable):
-- **`+`** — concluded spec with no plan yet
-- **`▶`** — has a plan with `plan_status: planning`
-- **`>`** — has a plan with `plan_status: concluded`
-
-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}]`
-
-Omit either section entirely if it has no entries.
-
-**Then prompt based on what's actionable:**
-
-**If multiple actionable items:**
-```
-· · · · · · · · · · · ·
-Select a specification (enter number):
-```
-
-**STOP.** Wait for user response.
-
-**If single actionable item (auto-select):**
-```
-Auto-selecting: {topic} (only actionable specification)
-```
-
-→ Proceed directly to **Step 4**.
+Load **[display-state.md](references/display-state.md)** and follow its instructions as written.
 
-**If nothing actionable:**
-```
-No plannable specifications.
-
-Before you can start planning:
-- Complete any in-progress specifications with /start-specification, or
-- Create a new specification first
-
-Then re-run /start-planning.
-```
-
-**STOP.** This workflow cannot continue — do not proceed.
-
-→ Based on user choice, proceed to **Step 4**.
+→ Proceed to **Step 4**.
 
 ---
 
@@ -207,54 +150,26 @@ 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?
-
-**STOP.** Wait for user response.
-
-→ Proceed to **Step 6**.
-
----
-
-## Step 6: Surface Cross-Cutting Context
-
-**If no cross-cutting specifications exist**: Skip this step. → Proceed to **Step 7**.
-
-Read each cross-cutting specification from `specifications.crosscutting` in the discovery output.
-
-### 6a: Warn about in-progress cross-cutting specs
-
-If any **in-progress** cross-cutting specifications exist, check whether they could be relevant to the feature being planned (by topic overlap — e.g., a caching strategy is relevant if the feature involves data retrieval or API calls).
-
-If any are relevant:
+> *Output the next fenced block as markdown (not a code block):*
 
 ```
-Note: The following cross-cutting specifications are still in-progress:
-  · {rate-limiting} - in-progress
-
-These may contain architectural decisions relevant to this plan.
-
 · · · · · · · · · · · ·
-- **`c`/`continue`** — Plan without them
-- **`s`/`stop`** — Complete them first (/start-specification)
+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.
 
-If the user chooses to stop, end here. If they choose to continue, proceed.
-
-### 6b: Summarize concluded cross-cutting specs
+→ Proceed to **Step 6**.
 
-If any **concluded** cross-cutting specifications exist, identify which are relevant to the feature being planned and summarize for handoff:
+---
 
-```
-Cross-cutting specifications to reference:
-- caching-strategy.md: [brief summary of key decisions]
-```
+## Step 6: Surface Cross-Cutting Context
 
-These specifications contain validated architectural decisions that should inform the plan. The planning skill will incorporate these as a "Cross-Cutting References" section in the plan.
+Load **[cross-cutting-context.md](references/cross-cutting-context.md)** and follow its instructions as written.
 
 → Proceed to **Step 7**.
 
@@ -262,33 +177,4 @@ These specifications contain validated architectural decisions that should infor
 
 ## Step 7: Invoke the Skill
 
-After completing the steps above, this skill's purpose is fulfilled.
-
-Invoke the [technical-planning](../technical-planning/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 (fresh plan):**
-```
-Planning session for: {topic}
-Specification: docs/workflow/specification/{topic}.md
-Additional context: {summary of user's answers from Step 5}
-Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
-Recommended output format: {common_format from discovery if non-empty, otherwise "none"}
-
-Invoke the technical-planning skill.
-```
-
-**Example handoff (continue/review existing plan):**
-```
-Planning session for: {topic}
-Specification: docs/workflow/specification/{topic}.md
-Existing plan: docs/workflow/planning/{topic}.md
-
-Invoke the technical-planning skill.
-```
-
-## Notes
-
-- Ask questions clearly and wait for responses before proceeding
-- The feature specification is the primary source of truth for planning
-- Cross-cutting specifications provide supplementary context for architectural decisions
-- Do not reference discussions - only specifications
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-planning/references/cross-cutting-context.md

@@ -0,0 +1,50 @@
+# Cross-Cutting Context
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+**If no cross-cutting specifications exist**:
+
+Skip this step.
+
+→ Proceed to **Step 7**.
+
+Read each cross-cutting specification from `specifications.crosscutting` in the discovery output.
+
+### 6a: Warn about in-progress cross-cutting specs
+
+If any **in-progress** cross-cutting specifications exist, check whether they could be relevant to the feature being planned (by topic overlap — e.g., a caching strategy is relevant if the feature involves data retrieval or API calls).
+
+If any are relevant:
+
+> *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)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+If the user chooses to stop, end here. If they choose to continue, proceed.
+
+### 6b: Summarize concluded cross-cutting specs
+
+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]
+```
+
+These specifications contain validated architectural decisions that should inform the plan. The planning skill will incorporate these as a "Cross-Cutting References" section in the plan.

package/skills/start-planning/references/display-state.md

@@ -0,0 +1,109 @@
+# Display State and Options
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+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 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`
+
+**If non-plannable specifications exist**, show them in a separate code block:
+
+> *Output the next fenced block as a code block:*
+
+```
+Specifications not ready for planning:
+These specifications are either still in progress or cross-cutting
+and cannot be planned directly.
+
+  • {topic} ({type:[feature|cross-cutting]}, {status:[in-progress|concluded]})
+```
+
+**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:
+
+  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):*
+
+```
+· · · · · · · · · · · ·
+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:*
+
+```
+Automatically proceeding with "{topic:(titlecase)}".
+```
+
+**If nothing actionable:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Planning Overview
+
+No plannable specifications found.
+
+The planning phase requires a concluded feature specification.
+Complete any in-progress specifications with /start-specification,
+or create a new specification first.
+```
+
+**STOP.** Do not proceed — terminal condition.

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

@@ -0,0 +1,29 @@
+# Invoke the Skill
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+After completing the steps above, this skill's purpose is fulfilled.
+
+Invoke the [technical-planning](../../technical-planning/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 (fresh plan):**
+```
+Planning session for: {topic}
+Specification: docs/workflow/specification/{topic}.md
+Additional context: {summary of user's answers from Step 5}
+Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
+Recommended output format: {common_format from discovery if non-empty, otherwise "none"}
+
+Invoke the technical-planning skill.
+```
+
+**Example handoff (continue/review existing plan):**
+```
+Planning session for: {topic}
+Specification: docs/workflow/specification/{topic}.md
+Existing plan: docs/workflow/planning/{topic}.md
+
+Invoke the technical-planning skill.
+```

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**.