@leeovery/claude-technical-workflows 2.1.41 → 2.2.0

package/skills/start-investigation/references/route-scenario.md

@@ -0,0 +1,69 @@
+# Route Based on Scenario
+
+*Reference for **[start-investigation](../SKILL.md)***
+
+---
+
+Use `state.scenario` from the discovery output to determine the path.
+
+#### If scenario is "has_investigations"
+
+> *Output the next fenced block as a code block:*
+
+```
+Investigations Overview
+
+@if(investigations.counts.in_progress > 0)
+In Progress:
+@foreach(inv in investigations.files where status is in-progress)
+  • {inv.topic}
+@endforeach
+@endif
+
+@if(investigations.counts.concluded > 0)
+Concluded:
+@foreach(inv in investigations.files where status is concluded)
+  • {inv.topic}
+@endforeach
+@endif
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+What would you like to do?
+
+@if(in_progress investigations exist)
+{N}. Resume "{topic}" investigation
+@endforeach
+@endif
+{N}. Start new investigation
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If resuming
+
+Set source="continue".
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6** with that topic.
+
+#### If new
+
+Set source="fresh".
+
+→ Return to **[the skill](../SKILL.md)** for **Step 5**.
+
+#### If scenario is "fresh"
+
+Set source="fresh".
+
+> *Output the next fenced block as a code block:*
+
+```
+No existing investigations found.
+```
+
+→ Return to **[the skill](../SKILL.md)** for **Step 5**.

package/skills/start-investigation/references/validate-investigation.md

@@ -0,0 +1,46 @@
+# Validate Investigation
+
+*Reference for **[start-investigation](../SKILL.md)***
+
+---
+
+Check if investigation already exists for this topic.
+
+```bash
+ls .workflows/investigation/
+```
+
+#### If investigation exists for this topic
+
+Read `.workflows/investigation/{topic}/investigation.md` frontmatter to check status.
+
+#### If status is "in-progress"
+
+> *Output the next fenced block as a code block:*
+
+```
+Resuming investigation: {topic:(titlecase)}
+```
+
+Set source="continue".
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6**.
+
+#### If status is "concluded"
+
+> *Output the next fenced block as a code block:*
+
+```
+Investigation Concluded
+
+The investigation for "{topic:(titlecase)}" has already concluded.
+Run /start-specification bugfix {topic} to continue to spec.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If no collision
+
+Set source="bridge".
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-investigation/scripts/discovery.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+#
+# Discovery script for /start-investigation.
+#
+# Scans the investigation directory for existing investigations.
+#
+# Outputs structured YAML that the skill can consume directly.
+#
+
+set -eo pipefail
+
+INVESTIGATION_DIR=".workflows/investigation"
+
+# Helper: Extract a frontmatter field value from a file
+# Usage: extract_field <file> <field_name>
+extract_field() {
+    local file="$1"
+    local field="$2"
+    local value=""
+
+    if head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        value=$(sed -n '2,/^---$/p' "$file" 2>/dev/null | \
+            grep -i -m1 "^${field}:" | \
+            sed -E "s/^${field}:[[:space:]]*//i" || true)
+    fi
+
+    echo "$value"
+}
+
+# Start YAML output
+echo "# Start-Investigation Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# INVESTIGATIONS
+#
+echo "investigations:"
+
+inv_count=0
+inv_in_progress=0
+inv_concluded=0
+
+if [ -d "$INVESTIGATION_DIR" ] && [ -n "$(ls -A "$INVESTIGATION_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+    for dir in "$INVESTIGATION_DIR"/*/; do
+        [ -d "$dir" ] || continue
+        file="${dir}investigation.md"
+        [ -f "$file" ] || continue
+
+        topic=$(basename "$dir")
+        status=$(extract_field "$file" "status")
+        status=${status:-"in-progress"}
+        date=$(extract_field "$file" "date")
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"bugfix"}
+
+        echo "    - topic: \"$topic\""
+        echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
+        [ -n "$date" ] && echo "      date: \"$date\""
+
+        inv_count=$((inv_count + 1))
+        [ "$status" = "concluded" ] && inv_concluded=$((inv_concluded + 1))
+        [ "$status" = "in-progress" ] && inv_in_progress=$((inv_in_progress + 1))
+    done
+    echo "  counts:"
+    echo "    total: $inv_count"
+    echo "    in_progress: $inv_in_progress"
+    echo "    concluded: $inv_concluded"
+else
+    echo "  exists: false"
+    echo "  files: []"
+    echo "  counts:"
+    echo "    total: 0"
+    echo "    in_progress: 0"
+    echo "    concluded: 0"
+fi
+
+echo ""
+
+#
+# STATE SUMMARY
+#
+echo "state:"
+
+if [ "$inv_count" -eq 0 ]; then
+    echo "  scenario: \"fresh\""
+else
+    echo "  scenario: \"has_investigations\""
+fi

package/skills/start-planning/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: start-planning
-description: "Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/specification/)
 hooks:
   PreToolUse:
     - hooks:
@@ -52,9 +51,13 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 Invoke the `/migrate` skill and assess its output.
 
-**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+#### If files were updated
 
-**If no updates needed**: Proceed to Step 1.
+**STOP.** Wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding.
+
+#### If no updates needed
+
+→ Proceed to **Step 1**.
 
 ---
 
@@ -91,113 +94,70 @@ Parse the discovery output to understand:
 **From `state` section:**
 - `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.
+**IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state.
 
 → Proceed to **Step 2**.
 
 ---
 
-## Step 2: Route Based on Scenario
-
-Use `state.scenario` from the discovery output to determine the path:
-
-#### If scenario is "no_specs"
-
-No specifications exist yet.
+## Step 2: Determine Mode
 
-> *Output the next fenced block as a code block:*
+Check for arguments: work_type = `$0`, topic = `$1`
 
-```
-Planning Overview
-
-No specifications found in .workflows/specification/
-
-The planning phase requires a concluded specification.
-Run /start-specification first.
-```
+#### If work_type and topic are both provided
 
-**STOP.** Do not proceed — terminal condition.
+→ Proceed to **Step 3**.
 
-#### If scenario is "nothing_actionable"
+#### If work_type is provided without topic
 
-Specifications exist but none are actionable — all are still in-progress and no plans exist to continue.
+Store work_type for the handoff.
 
-→ Proceed to **Step 3** to show the state.
-
-#### If scenario is "has_options"
-
-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
+→ Proceed to **Step 4**.
 
-Load **[display-state.md](references/display-state.md)** and follow its instructions as written.
+#### If neither is provided
 
 → Proceed to **Step 4**.
 
 ---
 
-## Step 4: Route by Plan State
+## Step 3: Validate Specification
 
-Check whether the selected specification already has a plan (from `has_plan` in discovery output).
+Load **[validate-spec.md](references/validate-spec.md)** and follow its instructions as written.
 
-#### If no existing plan (fresh start)
+→ Proceed to **Step 7**.
 
-→ Proceed to **Step 5** to gather context before invoking the skill.
+---
 
-#### If existing plan (continue or review)
+## Step 4: Route Based on Scenario
 
-The plan already has its context from when it was created. Skip context gathering.
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions as written.
 
-→ Go directly to **Step 7** to invoke the skill.
+→ Proceed to **Step 5**.
 
 ---
 
-## Step 5: Gather Additional Context
-
-> *Output the next fenced block as markdown (not a code block):*
-
-```
-· · · · · · · · · · · ·
-Any additional context since the specification was concluded?
+## Step 5: Present State and Options
 
-- **`c`/`continue`** — Continue with the specification as-is
-- Or provide additional context (priorities, constraints, new considerations)
-· · · · · · · · · · · ·
-```
-
-**STOP.** Wait for user response.
+Load **[display-state.md](references/display-state.md)** and follow its instructions as written.
 
 → Proceed to **Step 6**.
 
 ---
 
-## Step 6: Surface Cross-Cutting Context
+## Step 6: Route by Plan State
 
-Load **[cross-cutting-context.md](references/cross-cutting-context.md)** and follow its instructions as written.
-
-→ Proceed to **Step 7**.
+Load **[route-plan-state.md](references/route-plan-state.md)** and follow its instructions as written.
 
 ---
 
-## Step 7: Invoke the Skill
+## Step 7: Cross-Cutting Context
 
-Before invoking the processing skill, save a session bookmark.
+Load **[cross-cutting-context.md](references/cross-cutting-context.md)** and follow its instructions as written.
 
-> *Output the next fenced block as a code block:*
+→ Proceed to **Step 8**.
 
-```
-Saving session state so Claude can pick up where it left off if the conversation is compacted.
-```
+---
 
-```bash
-.claude/hooks/workflows/write-session-state.sh \
-  "{topic}" \
-  "skills/technical-planning/SKILL.md" \
-  ".workflows/planning/{topic}/plan.md"
-```
+## Step 8: Invoke the Skill
 
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

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

@@ -4,15 +4,15 @@
 
 ---
 
-**If no cross-cutting specifications exist**:
+#### If no cross-cutting specifications exist
 
-Skip this step.
+→ Return to **[the skill](../SKILL.md)**.
 
-→ Proceed to **Step 7**.
+#### If cross-cutting specifications exist
 
 Read each cross-cutting specification from `specifications.crosscutting` in the discovery output.
 
-### 6a: Warn about in-progress cross-cutting specs
+### 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).
 
@@ -36,7 +36,7 @@ These may contain architectural decisions relevant to this plan.
 
 If the user chooses to stop, end here. If they choose to continue, proceed.
 
-### 6b: Summarize concluded cross-cutting specs
+### 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:
 

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

@@ -4,22 +4,45 @@
 
 ---
 
-After completing the steps above, this skill's purpose is fulfilled.
+Before invoking the processing skill, save a session bookmark.
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state so Claude can pick up where it left off if the conversation is compacted.
+```
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-planning/SKILL.md" \
+  ".workflows/planning/{topic}/plan.md"
+```
+
+This skill's purpose is now 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):**
+---
+
+## Handoff
+
+Construct the handoff based on the plan state.
+
+#### If creating fresh plan (no existing plan)
+
 ```
 Planning session for: {topic}
 Specification: .workflows/specification/{topic}/specification.md
-Additional context: {summary of user's answers from Step 5}
+Additional context: {summary of user's additional context, or "none"}
 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):**
+#### If continuing or reviewing existing plan
+
 ```
 Planning session for: {topic}
 Specification: .workflows/specification/{topic}/specification.md

package/skills/start-planning/references/route-plan-state.md

@@ -0,0 +1,30 @@
+# Route by Plan State
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+Check whether the selected specification already has a plan (from `has_plan` in discovery output).
+
+#### If existing plan (continue or review)
+
+The plan already has its context from when it was created. Skip context gathering.
+
+→ Return to **[the skill](../SKILL.md)** for **Step 8**.
+
+#### If no existing plan (fresh start)
+
+> *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.
+
+→ Return to **[the skill](../SKILL.md)** for **Step 7**.

package/skills/start-planning/references/route-scenario.md

@@ -0,0 +1,38 @@
+# Route Based on Scenario
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+Discovery mode — use the discovery output from Step 1.
+
+Use `state.scenario` from the discovery output to determine the path:
+
+#### If scenario is "no_specs"
+
+No specifications exist yet.
+
+> *Output the next fenced block as a code block:*
+
+```
+Planning Overview
+
+No specifications found in .workflows/specification/
+
+The planning phase requires a concluded specification.
+Run /start-specification first.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If scenario is "nothing_actionable"
+
+Specifications exist but none are actionable — all are still in-progress and no plans exist to continue.
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If scenario is "has_options"
+
+At least one specification is ready for planning, or an existing plan can be continued or reviewed.
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-planning/references/validate-spec.md

@@ -0,0 +1,47 @@
+# Validate Specification
+
+*Reference for **[start-planning](../SKILL.md)***
+
+---
+
+Check if specification exists and is ready.
+
+```bash
+ls .workflows/specification/
+```
+
+Read `.workflows/specification/{topic}/specification.md` frontmatter.
+
+#### If specification doesn't exist
+
+> *Output the next fenced block as a code block:*
+
+```
+Specification Missing
+
+No specification found for "{topic:(titlecase)}".
+
+A concluded specification is required for planning.
+Run /start-specification {work_type} {topic} to create one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If specification exists but status is "in-progress"
+
+> *Output the next fenced block as a code block:*
+
+```
+Specification In Progress
+
+The specification for "{topic:(titlecase)}" is not yet concluded.
+Run /start-specification {work_type} {topic} to continue.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If specification exists and status is "concluded"
+
+Parse cross-cutting specs from `specifications.crosscutting` in the discovery output.
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-planning/scripts/discovery.sh

@@ -81,8 +81,12 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
             impl_status=${impl_status:-"unknown"}
         fi
 
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
+
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
         echo "      has_plan: $has_plan"
         if [ "$has_plan" = "true" ]; then
             echo "      plan_status: \"$plan_status\""
@@ -192,10 +196,13 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
         plan_id=$(extract_field "$file" "plan_id")
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         echo "    - name: \"$name\""
         echo "      format: \"$format\""
         echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
         if [ -n "$plan_id" ]; then
             echo "      plan_id: \"$plan_id\""
         fi

package/skills/start-research/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: start-research
-description: "Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion."
 disable-model-invocation: true
 allowed-tools: Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
@@ -50,21 +49,33 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 Invoke the `/migrate` skill and assess its output.
 
-**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+#### If files were updated
 
-**If no updates needed**: Proceed to Step 1.
+**STOP.** Wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding.
+
+#### If no updates needed
+
+→ Proceed to **Step 1**.
 
 ---
 
-## Step 1: Gather Context
+## Step 1: Check Arguments
 
-Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
+Check for arguments: work_type = `$0`. If provided, store for the handoff.
 
 → Proceed to **Step 2**.
 
 ---
 
-## Step 2: Invoke the Skill
+## Step 2: Gather Context
+
+Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Invoke the Skill
 
 Before invoking the processing skill, save a session bookmark.
 

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

@@ -8,9 +8,12 @@ This skill's purpose is now fulfilled.
 
 Invoke the [technical-research](../../technical-research/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.
 
+**If work_type is available** (from Step 1), add the Work type line in the handoff.
+
 **Example handoff:**
 ```
 Research session for: {topic}
+Work type: {work_type}
 Output: .workflows/research/exploration.md
 
 Context: