@leeovery/claude-technical-workflows 2.0.49 → 2.0.51

package/commands/workflow/start-planning.md

@@ -60,18 +60,20 @@ This outputs structured YAML. Parse it to understand:
 
 **From `specifications` section:**
 - `exists` - whether any specifications exist
-- `feature` - list of feature specs (name, status, has_plan)
+- `feature` - list of feature specs (name, status, has_plan, plan_status)
 - `crosscutting` - list of cross-cutting specs (name, status)
 - `counts.feature` - total feature specifications
 - `counts.feature_ready` - feature specs ready for planning (concluded + no plan)
+- `counts.feature_with_plan` - feature specs that already have plans
 - `counts.crosscutting` - total cross-cutting specifications
 
 **From `plans` section:**
 - `exists` - whether any plans exist
 - `files` - each plan's name, format, status, and plan_id (if present)
+- `common_format` - the output format if all existing plans share the same one; empty string otherwise
 
 **From `state` section:**
-- `scenario` - one of: `"no_specs"`, `"no_ready_specs"`, `"single_ready_spec"`, `"multiple_ready_specs"`
+- `scenario` - one of: `"no_specs"`, `"nothing_actionable"`, `"has_options"`
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -95,18 +97,20 @@ The planning phase requires a concluded specification. Please run /start-specifi
 
 **STOP.** Wait for user to acknowledge before ending.
 
-#### If scenario is "no_ready_specs"
+#### If scenario is "nothing_actionable"
 
-Specifications exist but none are ready for planning (either still in-progress, or already have plans).
+Specifications exist but none are actionable — all are still in-progress and no plans exist to continue.
 
 → Proceed to **Step 3** to show the state.
 
-#### If scenario is "single_ready_spec" or "multiple_ready_specs"
+#### If scenario is "has_options"
 
-Specifications are ready for planning.
+At least one specification is ready for planning, or an existing plan can be continued or reviewed.
 
 → Proceed to **Step 3** to present options.
 
+---
+
 ## Step 3: Present Workflow State and Options
 
 Present everything discovered to help the user make an informed choice.
@@ -114,47 +118,55 @@ Present everything discovered to help the user make an informed choice.
 **Present the full state:**
 
 ```
-Workflow Status: Planning Phase
-
-Feature specifications:
-  1. · {topic-1} (in-progress) - not ready
-  2. ✓ {topic-2} (concluded) - ready for planning
-  3. - {topic-3} (concluded) → plan exists
+Planning Phase
 
-Cross-cutting specifications (reference context):
-  - {caching-strategy} (concluded)
-  - {rate-limiting} (concluded)
+Available:
+  1. + {topic-2} - create new plan
+  2. ▶ {topic-3} - continue in-progress plan
+  3. > {topic-4} - review concluded plan
 
-Existing plans:
-  - {topic-3}.md (in-progress, {format})
+Not plannable specifications:
+  · {topic-1} [feature, in-progress]
+  · {caching-strategy} [cross-cutting, concluded]
+  · {rate-limiting} [cross-cutting, in-progress]
 ```
 
-**Legend:**
-- `·` = not ready for planning (still in-progress)
-- `✓` = ready for planning (concluded, no plan yet)
-- `-` = already has a plan
+**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}]`
 
-**Then present options based on what's ready:**
+Omit either section entirely if it has no entries.
 
-**If multiple specs ready for planning:**
+**Then prompt based on what's actionable:**
+
+**If multiple actionable items:**
 ```
-Which specification would you like to plan? (Enter a number or name)
+Select a specification (enter number):
 ```
 
 **STOP.** Wait for user response.
 
-**If single spec ready for planning (auto-select):**
+**If single actionable item (auto-select):**
 ```
-Auto-selecting: {topic} (only ready specification)
+Auto-selecting: {topic} (only actionable specification)
 ```
+
 → Proceed directly to **Step 4**.
 
-**If no specs ready for planning:**
+**If nothing actionable:**
 ```
-No specifications ready for planning.
+No plannable specifications.
 
 To proceed:
-- Complete any "in-progress" specifications with /start-specification
+- Complete any in-progress specifications with /start-specification
 - Or create a new specification first
 ```
 
@@ -164,7 +176,23 @@ To proceed:
 
 ---
 
-## Step 4: Gather Additional Context
+## Step 4: Route by Plan State
+
+Check whether the selected specification already has a plan (from `has_plan` in discovery output).
+
+#### If no existing plan (fresh start)
+
+→ Proceed to **Step 5** to gather context before invoking the skill.
+
+#### If existing plan (continue or review)
+
+The plan already has its context from when it was created. Skip context gathering.
+
+→ Go directly to **Step 7** to invoke the skill.
+
+---
+
+## Step 5: Gather Additional Context
 
 Ask:
 - Any additional context or priorities to consider?
@@ -172,46 +200,72 @@ Ask:
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 5**.
+→ Proceed to **Step 6**.
 
 ---
 
-## Step 5: Surface Cross-Cutting Context
+## Step 6: Surface Cross-Cutting Context
 
-If any **concluded cross-cutting specifications** exist (from `specifications.crosscutting` in discovery), surface them as reference context for planning:
+**If no cross-cutting specifications exist**: Skip this step. → Proceed to **Step 7**.
 
-1. **List applicable cross-cutting specs**:
-   - Read each cross-cutting specification
-   - Identify which ones are relevant to the feature being planned
-   - Relevance is determined by topic overlap (e.g., caching strategy applies if the feature involves data retrieval or API calls)
+Read each cross-cutting specification from `specifications.crosscutting` in the discovery output.
 
-2. **Summarize for handoff**:
-   ```
-   Cross-cutting specifications to reference:
-   - caching-strategy.md: [brief summary of key decisions]
-   - rate-limiting.md: [brief summary of key decisions]
-   ```
+### 6a: Warn about in-progress cross-cutting specs
 
-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.
+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 no cross-cutting specifications exist**: Skip this step.
+If any are relevant:
 
-→ Proceed to **Step 6**.
+```
+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)
+```
+
+**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:
+
+```
+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.
+
+→ Proceed to **Step 7**.
 
 ---
 
-## Step 6: Invoke the Skill
+## Step 7: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
 Invoke the [technical-planning](../../skills/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:**
+**Example handoff (fresh plan):**
 ```
 Planning session for: {topic}
 Specification: docs/workflow/specification/{topic}.md
-Additional context: {summary of user's answers from Step 4}
+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/commands/workflow/start-specification.md

@@ -120,25 +120,31 @@ At least one concluded discussion exists.
 Show the current state clearly. Use this EXACT format:
 
 ```
-Workflow Status: Specification Phase
+Specification Phase
 
-Discussions:
-  ✓ {topic-1} - concluded - ready
-  ✓ {topic-2} - concluded - ready
-  ○ {topic-3} - concluded - spec: {spec_status}
-  · {topic-4} - in-progress - not ready
+Available discussions:
+  + {topic-1} - create new spec
+  + {topic-2} - create new spec
+  ▶ {topic-3} - continue in-progress spec
+  > {topic-4} - review concluded spec
 
-Specifications:
-  • {spec-1} (active) - sources: {topic-1}
-  • {spec-2} (superseded → {other-spec}) - sources: {topic-x}
+Not specifiable discussions:
+  · {topic-5} [in-progress]
+
+Existing specifications:
+  • {spec-1} [active] - sources: {topic-1}
+  • {spec-2} [superseded → {other-spec}] - sources: {topic-x}
 
 {N} concluded discussions available.
 ```
 
 **Legend:**
-- `✓` = concluded, no spec yet (ready to specify)
-- `○` = concluded, has individual spec (shows spec status: in-progress or concluded)
-- `·` = in-progress (not ready)
+- `+` = concluded, no spec yet (create new)
+- `▶` = concluded, has in-progress spec (continue)
+- `>` = concluded, has concluded spec (review)
+- `·` = in-progress (not specifiable)
+
+Omit either discussions section if it has no entries.
 
 #### Routing Based on State
 

package/package.json

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

package/scripts/discovery-for-planning.sh

@@ -40,6 +40,7 @@ echo "specifications:"
 
 feature_count=0
 feature_ready_count=0
+feature_with_plan_count=0
 crosscutting_count=0
 
 if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
@@ -59,21 +60,30 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         # Skip cross-cutting specs in this pass
         [ "$spec_type" = "cross-cutting" ] && continue
 
-        # Check if plan exists
+        # Check if plan exists and its status
         has_plan="false"
+        plan_status=""
         if [ -f "$PLAN_DIR/${name}.md" ]; then
             has_plan="true"
+            plan_status=$(extract_field "$PLAN_DIR/${name}.md" "status")
+            plan_status=${plan_status:-"unknown"}
         fi
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
         echo "      has_plan: $has_plan"
+        if [ "$has_plan" = "true" ]; then
+            echo "      plan_status: \"$plan_status\""
+        fi
 
         feature_count=$((feature_count + 1))
         # "concluded" specs without plans are ready for planning
         if [ "$status" = "concluded" ] && [ "$has_plan" = "false" ]; then
             feature_ready_count=$((feature_ready_count + 1))
         fi
+        if [ "$has_plan" = "true" ]; then
+            feature_with_plan_count=$((feature_with_plan_count + 1))
+        fi
     done
 
     if [ "$feature_count" -eq 0 ]; then
@@ -109,6 +119,7 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
     echo "  counts:"
     echo "    feature: $feature_count"
     echo "    feature_ready: $feature_ready_count"
+    echo "    feature_with_plan: $feature_with_plan_count"
     echo "    crosscutting: $crosscutting_count"
 else
     echo "  exists: false"
@@ -117,6 +128,7 @@ else
     echo "  counts:"
     echo "    feature: 0"
     echo "    feature_ready: 0"
+    echo "    feature_with_plan: 0"
     echo "    crosscutting: 0"
 fi
 
@@ -127,6 +139,9 @@ echo ""
 #
 echo "plans:"
 
+plan_format_seen=""
+plan_format_unanimous="true"
+
 if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
     echo "  exists: true"
     echo "  files:"
@@ -137,6 +152,15 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         name=$(basename "$file" .md)
         format=$(extract_field "$file" "format")
         format=${format:-"MISSING"}
+
+        if [ "$format" != "MISSING" ]; then
+            if [ -z "$plan_format_seen" ]; then
+                plan_format_seen="$format"
+            elif [ "$plan_format_seen" != "$format" ]; then
+                plan_format_unanimous="false"
+            fi
+        fi
+
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
         plan_id=$(extract_field "$file" "plan_id")
@@ -148,9 +172,16 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
             echo "      plan_id: \"$plan_id\""
         fi
     done
+
+    if [ "$plan_format_unanimous" = "true" ] && [ -n "$plan_format_seen" ]; then
+        echo "  common_format: \"$plan_format_seen\""
+    else
+        echo "  common_format: \"\""
+    fi
 else
     echo "  exists: false"
     echo "  files: []"
+    echo "  common_format: \"\""
 fi
 
 echo ""
@@ -177,10 +208,8 @@ echo "  has_plans: $plans_exist"
 # Determine workflow state for routing
 if [ "$specs_exist" = "false" ]; then
     echo "  scenario: \"no_specs\""
-elif [ "$feature_ready_count" -eq 0 ]; then
-    echo "  scenario: \"no_ready_specs\""
-elif [ "$feature_ready_count" -eq 1 ]; then
-    echo "  scenario: \"single_ready_spec\""
+elif [ "$feature_ready_count" -eq 0 ] && [ "$feature_with_plan_count" -eq 0 ]; then
+    echo "  scenario: \"nothing_actionable\""
 else
-    echo "  scenario: \"multiple_ready_specs\""
+    echo "  scenario: \"has_options\""
 fi

package/skills/technical-planning/SKILL.md

@@ -22,6 +22,7 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Specification content** (required) - The validated decisions and requirements to plan from
 - **Topic name** (optional) - Will derive from specification if not provided
 - **Output format preference** (optional) - Will ask if not specified
+- **Recommended output format** (optional) - A format suggestion for consistency with existing plans
 - **Cross-cutting references** (optional) - Cross-cutting specifications that inform technical decisions in this plan
 
 **Before proceeding**, verify the required input is available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
@@ -97,7 +98,21 @@ Read **[output-formats.md](references/output-formats.md)**, find the entry match
 
 #### If no Plan Index File exists
 
-First, choose the Output Format. Present the formats from **[output-formats.md](references/output-formats.md)** to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.
+First, choose the Output Format.
+
+**If a recommended output format was provided** (non-empty, not "none"):
+
+Present the recommendation:
+
+> "Existing plans use **{format}**. Use the same format for consistency?
+> - **yes** — use {format}
+> - **no** — see all available formats"
+
+**STOP.** Wait for user choice. If declined, fall through to the full list below.
+
+**If no recommendation, or user declined:**
+
+Present the formats from **[output-formats.md](references/output-formats.md)** to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.
 
 **STOP.** Wait for the user to choose.
 

package/skills/technical-planning/references/steps/plan-construction.md

@@ -88,6 +88,17 @@ Present the task list to the user for review.
 
 Work through each task in the phase's task table, in order.
 
+### Parallel authoring (optional optimization)
+
+After the first `pending` task in a phase is approved, you may invoke multiple Step B agents concurrently for tasks you judge to be independent — where the authored detail of one would not inform the other. This is an invocation optimization only; the approval flow is unchanged:
+
+- Present tasks one at a time, in order
+- Each task still requires explicit user approval before logging
+- If user feedback on a presented task changes context that could affect any already-authored task waiting to be presented, discard those results and re-invoke Step B
+- When uncertain about independence, default to sequential — it is always safe
+
+Never parallelize the first `pending` task in a phase. Never parallelize across phases.
+
 #### If the task status is `authored`
 
 Already written. Present a brief summary: