@leeovery/claude-technical-workflows 2.0.41 → 2.0.43

package/commands/workflow/start-review.md

@@ -1,5 +1,6 @@
 ---
 description: Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill.
+allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
 ---
 
 Invoke the **technical-review** skill for this conversation.
@@ -15,7 +16,7 @@ This is **Phase 6** of the six-phase workflow:
 | 3. Specification | REFINE - validate into standalone spec | |
 | 4. Planning | HOW - phases, tasks, acceptance criteria | |
 | 5. Implementation | DOING - tests first, then code | |
-| **6. Review** | VALIDATING - check work against artifacts | HERE |
+| **6. Review** | VALIDATING - check work against artifacts | ◀ HERE |
 
 **Stay in your lane**: Verify that every plan task was implemented, tested adequately, and meets quality standards. Don't fix code - identify problems. You're reviewing, not building.
 
@@ -23,13 +24,17 @@ This is **Phase 6** of the six-phase workflow:
 
 ## Instructions
 
-Follow these steps EXACTLY as written. Do not skip steps or combine them.
+Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
 
-Before beginning, discover existing work and gather necessary information.
+**CRITICAL**: This guidance is mandatory.
 
-## Important
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+- Do not act on gathered information until the skill is loaded - it contains the instructions for how to proceed
 
-Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+---
 
 ## Step 0: Run Migrations
 
@@ -39,22 +44,37 @@ Invoke the `/migrate` command and assess its output before proceeding to Step 1.
 
 ---
 
-## Step 1: Discover Existing Plans
+## Step 1: Run Discovery Script
+
+Run the discovery script to gather current state:
+
+```bash
+.claude/scripts/discovery-for-implementation-and-review.sh
+```
+
+This outputs structured YAML. Parse it to understand:
+
+**From `plans` section:**
+- `exists` - whether any plans exist
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists
+- `count` - total number of plans
+
+**From `state` section:**
+- `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+
+**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.
 
-Scan the codebase for plans:
+→ Proceed to **Step 2**.
 
-1. **Find plans**: Look in `docs/workflow/planning/`
-   - Run `ls docs/workflow/planning/` to list plan files
-   - Each file is named `{topic}.md`
+---
+
+## Step 2: Route Based on Scenario
 
-2. **Check plan format**: For each plan file
-   - Run `head -10 docs/workflow/planning/{topic}.md` to read the frontmatter
-   - Note the `format:` field
-   - Do NOT use bash loops - run separate `head` commands for each topic
+Use `state.scenario` from the discovery output to determine the path:
 
-## Step 2: Check Prerequisites
+#### If scenario is "no_plans"
 
-**If no plans exist:**
+No plans exist yet.
 
 ```
 No plans found in docs/workflow/planning/
@@ -62,39 +82,68 @@ 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.
 ```
 
-Stop here and wait for the user to acknowledge.
+**STOP.** Wait for user to acknowledge before ending.
+
+#### If scenario is "single_plan" or "multiple_plans"
+
+Plans exist.
+
+→ Proceed to **Step 3** to present options.
+
+---
+
+## Step 3: Present Plans and Select
 
-## Step 3: Present Options to User
+Present all discovered plans to help the user make an informed choice.
 
-Show what you found:
+**Present the full state:**
 
 ```
-Plans found:
-  {topic-1} (format: {format})
-  {topic-2} (format: {format})
+Available Plans:
 
-Which plan would you like to review the implementation for?
+  1. {topic-1} ({status}) - format: {format}, spec: {exists|missing}
+  2. {topic-2} ({status}) - format: {format}, spec: {exists|missing}
+
+Which plan would you like to review the implementation for? (Enter a number or name)
+```
+
+**If single plan exists (auto-select):**
+```
+Auto-selecting: {topic} (only available plan)
 ```
+→ Proceed directly to **Step 4**.
 
-**Auto-select:** If exactly one plan exists, automatically select it and proceed to Step 4. Inform the user which plan was selected. Do not ask for confirmation.
+**If multiple plans exist:**
+
+**STOP.** Wait for user response.
+
+→ Based on user choice, proceed to **Step 4**.
+
+---
 
 ## Step 4: Identify Implementation Scope
 
-Determine what code to review:
+Ask the user what code to review:
 
-1. **Check git status** - See what files have changed
-2. **Ask user** if unclear:
-   - "What code should I review? (all changes, specific directories, or specific files)"
+```
+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?
+```
 
-## Step 5: Locate Specification (Optional)
+**STOP.** Wait for user response.
 
-Check if a specification exists:
+If they choose specific directories/files, ask them to specify.
 
-1. **Look for specification**: Check `docs/workflow/specification/{topic}.md`
-2. **If exists**: Note the path for context
-3. **If missing**: Proceed without - the plan is the primary review artifact
+→ Proceed to **Step 5**.
 
-## Step 6: Invoke the Skill
+---
+
+## Step 5: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -105,13 +154,8 @@ Invoke the [technical-review](../../skills/technical-review/SKILL.md) skill for
 Review session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
-Specification: docs/workflow/specification/{topic}.md (or: Not available)
-Scope: {implementation scope}
+Specification: {specification} (exists: {true|false})
+Scope: {all changes | specific paths | from git status}
 
 Invoke the technical-review skill.
 ```
-
-## Notes
-
-- Ask questions clearly and wait for responses before proceeding
-- Review produces feedback (approve, request changes, or comments) - it does NOT fix code

package/commands/workflow/start-specification.md

@@ -1,6 +1,6 @@
 ---
 description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
-allowed-tools: Bash(.claude/scripts/specification-discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
+allowed-tools: Bash(.claude/scripts/discovery-for-specification.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -26,7 +26,13 @@ This is **Phase 3** of the six-phase workflow:
 
 Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
 
-**CRITICAL**: After each user interaction, STOP and wait for their response before proceeding. Never assume or anticipate user choices.
+**CRITICAL**: This guidance is mandatory.
+
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+- Do not act on gathered information until the skill is loaded - it contains the instructions for how to proceed
 
 ---
 
@@ -43,13 +49,14 @@ Invoke the `/migrate` command and assess its output before proceeding to Step 1.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/specification-discovery.sh
+.claude/scripts/discovery-for-specification.sh
 ```
 
 This outputs structured YAML. Parse it to understand:
 
 **From `discussions` array:**
 - Each discussion's name, status, and whether it has an individual specification
+- If `has_individual_spec` is true, `spec_status` contains the spec's status (in-progress/concluded)
 
 **From `specifications` array:**
 - Each specification's name, status, sources, and superseded_by (if applicable)
@@ -114,7 +121,7 @@ Workflow Status: Specification Phase
 Discussions:
   ✓ {topic-1} - concluded - ready
   ✓ {topic-2} - concluded - ready
-  ○ {topic-3} - concluded - has individual spec
+  ○ {topic-3} - concluded - spec: {spec_status}
   · {topic-4} - in-progress - not ready
 
 Specifications:
@@ -126,7 +133,7 @@ Specifications:
 
 **Legend:**
 - `✓` = concluded, no spec yet (ready to specify)
-- `○` = concluded, has individual spec (can be combined or continued)
+- `○` = concluded, has individual spec (shows spec status: in-progress or concluded)
 - `·` = in-progress (not ready)
 
 #### Routing Based on State
@@ -137,7 +144,7 @@ This is the simple path - no choices needed.
 
 ```
 Single concluded discussion found: {topic}
-{If has spec: "An existing specification will be continued/refined."}
+{If has spec: "An existing specification ({spec_status}) will be continued/refined."}
 
 Proceeding with this discussion.
 ```
@@ -391,11 +398,11 @@ For each grouping, show:
 
 Recommended Groupings:
 
-### 1. {Grouping Name} {if spec exists: "(specification exists)"}
+### 1. {Grouping Name} {if spec exists: "(spec: {spec_status})"}
 | Discussion | Status |
 |------------|--------|
 | {topic-a} | discussion only |
-| {topic-b} | has individual spec |
+| {topic-b} | spec: {spec_status} |
 | {topic-c} | discussion only |
 
 Coupling: {explanation}
@@ -439,7 +446,7 @@ Which would you like to start with?
 
 Grouped:
 1. {Grouping Name A} - {N} discussions
-2. {Grouping Name B} - {N} discussions (specification exists)
+2. {Grouping Name B} - {N} discussions (spec: {spec_status})
 3. {Grouping Name C} - {N} discussions
 
 Independent:
@@ -523,7 +530,7 @@ Groupings confirmed. Cache updated.
 
 Which grouping would you like to start with?
 
-1. {Grouping A} - {N} discussions {if has spec: "(specification exists)"}
+1. {Grouping A} - {N} discussions {if has spec: "(spec: {spec_status})"}
 2. {Grouping B} - {N} discussions
 ```
 
@@ -550,7 +557,7 @@ Proceed with unified specification? (y/n)
 Which discussion would you like to specify?
 
 1. {topic-1}
-2. {topic-2} (has individual spec - will continue/refine)
+2. {topic-2} (spec: {spec_status})
 3. {topic-3}
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.41",
+  "version": "2.0.43",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",
@@ -11,7 +11,9 @@
   "type": "module",
   "scripts": {
     "postinstall": "claude-manager add",
-    "preuninstall": "npx --yes --package=@leeovery/claude-manager claude-manager remove"
+    "preuninstall": "npx --yes --package=@leeovery/claude-manager claude-manager remove",
+    "test:scripts:discovery": "bash tests/scripts/test-discovery-for-discussion.sh && bash tests/scripts/test-discovery-for-specification.sh && bash tests/scripts/test-discovery-for-planning.sh && bash tests/scripts/test-discovery-for-implementation-and-review.sh",
+    "test:scripts:migration": "bash tests/scripts/test-migration-001.sh && bash tests/scripts/test-migration-002.sh && bash tests/scripts/test-migration-003.sh"
   },
   "dependencies": {
     "@leeovery/claude-manager": "^2.0.0"

package/scripts/discovery-for-discussion.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+#
+# Discovers the current state of research, discussions, and cache
+# for the /start-discussion command.
+#
+# Outputs structured YAML that the command can consume directly.
+#
+
+set -eo pipefail
+
+RESEARCH_DIR="docs/workflow/research"
+DISCUSSION_DIR="docs/workflow/discussion"
+CACHE_FILE="docs/workflow/.cache/research-analysis.md"
+
+# 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=""
+
+    # Extract from YAML frontmatter (file must start with ---)
+    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 "# Discussion Command State Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# RESEARCH FILES
+#
+echo "research:"
+
+if [ -d "$RESEARCH_DIR" ] && [ -n "$(ls -A "$RESEARCH_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+    for file in "$RESEARCH_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        topic=$(extract_field "$file" "topic")
+        topic=${topic:-"$name"}
+
+        echo "    - name: \"$name\""
+        echo "      topic: \"$topic\""
+    done
+
+    # Compute checksum of all research files (deterministic via sorted glob)
+    research_checksum=$(cat "$RESEARCH_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
+    echo "  checksum: \"$research_checksum\""
+else
+    echo "  exists: false"
+    echo "  files: []"
+    echo "  checksum: null"
+fi
+
+echo ""
+
+#
+# DISCUSSIONS
+#
+echo "discussions:"
+
+if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+
+    in_progress_count=0
+    concluded_count=0
+
+    for file in "$DISCUSSION_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+        date=$(extract_field "$file" "date")
+
+        echo "    - name: \"$name\""
+        echo "      status: \"$status\""
+        if [ -n "$date" ]; then
+            echo "      date: \"$date\""
+        fi
+
+        if [ "$status" = "in-progress" ]; then
+            in_progress_count=$((in_progress_count + 1))
+        elif [ "$status" = "concluded" ]; then
+            concluded_count=$((concluded_count + 1))
+        fi
+    done
+
+    echo "  counts:"
+    echo "    in_progress: $in_progress_count"
+    echo "    concluded: $concluded_count"
+else
+    echo "  exists: false"
+    echo "  files: []"
+    echo "  counts:"
+    echo "    in_progress: 0"
+    echo "    concluded: 0"
+fi
+
+echo ""
+
+#
+# CACHE STATE
+#
+# status: "valid" | "stale" | "none"
+#   - valid: cache exists and checksums match
+#   - stale: cache exists but research has changed
+#   - none: no cache file exists
+#
+echo "cache:"
+
+if [ -f "$CACHE_FILE" ]; then
+    cached_checksum=$(extract_field "$CACHE_FILE" "checksum")
+    cached_date=$(extract_field "$CACHE_FILE" "generated")
+
+    # Determine status based on checksum comparison
+    if [ -d "$RESEARCH_DIR" ] && [ -n "$(ls -A "$RESEARCH_DIR" 2>/dev/null)" ]; then
+        current_checksum=$(cat "$RESEARCH_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
+
+        if [ "$cached_checksum" = "$current_checksum" ]; then
+            echo "  status: \"valid\""
+            echo "  reason: \"checksums match\""
+        else
+            echo "  status: \"stale\""
+            echo "  reason: \"research has changed since cache was generated\""
+        fi
+    else
+        echo "  status: \"stale\""
+        echo "  reason: \"no research files to compare\""
+    fi
+
+    echo "  checksum: \"${cached_checksum:-unknown}\""
+    echo "  generated: \"${cached_date:-unknown}\""
+
+    # Extract cached research files list
+    echo "  research_files:"
+    files_found=false
+    while IFS= read -r file; do
+        file=$(echo "$file" | sed 's/^[[:space:]]*-[[:space:]]*//' | tr -d ' ')
+        if [ -n "$file" ]; then
+            echo "    - \"$file\""
+            files_found=true
+        fi
+    done < <(sed -n '/^research_files:/,/^---$/p' "$CACHE_FILE" 2>/dev/null | grep "^[[:space:]]*-" || true)
+
+    if [ "$files_found" = false ]; then
+        echo "    []  # No research files in cache"
+    fi
+else
+    echo "  status: \"none\""
+    echo "  reason: \"no cache exists\""
+    echo "  checksum: null"
+    echo "  generated: null"
+    echo "  research_files: []"
+fi
+
+echo ""
+
+#
+# WORKFLOW STATE SUMMARY
+#
+echo "state:"
+
+research_exists="false"
+discussions_exist="false"
+
+if [ -d "$RESEARCH_DIR" ] && [ -n "$(ls -A "$RESEARCH_DIR" 2>/dev/null)" ]; then
+    research_exists="true"
+fi
+
+if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+    discussions_exist="true"
+fi
+
+echo "  has_research: $research_exists"
+echo "  has_discussions: $discussions_exist"
+
+# Determine workflow state for routing
+if [ "$research_exists" = "false" ] && [ "$discussions_exist" = "false" ]; then
+    echo "  scenario: \"fresh\""
+elif [ "$research_exists" = "true" ] && [ "$discussions_exist" = "false" ]; then
+    echo "  scenario: \"research_only\""
+elif [ "$research_exists" = "false" ] && [ "$discussions_exist" = "true" ]; then
+    echo "  scenario: \"discussions_only\""
+else
+    echo "  scenario: \"research_and_discussions\""
+fi

package/scripts/discovery-for-implementation-and-review.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+#
+# Discovers the current state of plans for /start-implementation and /start-review commands.
+#
+# Outputs structured YAML that the commands can consume directly.
+#
+
+set -eo pipefail
+
+PLAN_DIR="docs/workflow/planning"
+SPEC_DIR="docs/workflow/specification"
+ENVIRONMENT_FILE="docs/workflow/environment-setup.md"
+
+# 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=""
+
+    # Extract from YAML frontmatter (file must start with ---)
+    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 "# Implementation Command State Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# PLANS
+#
+echo "plans:"
+
+plan_count=0
+
+if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+
+    for file in "$PLAN_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        topic=$(extract_field "$file" "topic")
+        topic=${topic:-"$name"}
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+        date=$(extract_field "$file" "date")
+        date=${date:-"unknown"}
+        format=$(extract_field "$file" "format")
+        format=${format:-"local-markdown"}
+        specification=$(extract_field "$file" "specification")
+        specification=${specification:-"${name}.md"}
+
+        # Check if linked specification exists
+        spec_exists="false"
+        spec_file="$SPEC_DIR/$specification"
+        if [ -f "$spec_file" ]; then
+            spec_exists="true"
+        fi
+
+        echo "    - name: \"$name\""
+        echo "      topic: \"$topic\""
+        echo "      status: \"$status\""
+        echo "      date: \"$date\""
+        echo "      format: \"$format\""
+        echo "      specification: \"$specification\""
+        echo "      specification_exists: $spec_exists"
+
+        plan_count=$((plan_count + 1))
+    done
+
+    echo "  count: $plan_count"
+else
+    echo "  exists: false"
+    echo "  files: []"
+    echo "  count: 0"
+fi
+
+echo ""
+
+#
+# ENVIRONMENT
+#
+echo "environment:"
+
+if [ -f "$ENVIRONMENT_FILE" ]; then
+    echo "  setup_file_exists: true"
+    echo "  setup_file: \"$ENVIRONMENT_FILE\""
+
+    # Check if it says "no special setup required" (case insensitive)
+    if grep -qi "no special setup required" "$ENVIRONMENT_FILE" 2>/dev/null; then
+        echo "  requires_setup: false"
+    else
+        echo "  requires_setup: true"
+    fi
+else
+    echo "  setup_file_exists: false"
+    echo "  setup_file: \"$ENVIRONMENT_FILE\""
+    echo "  requires_setup: unknown"
+fi
+
+echo ""
+
+#
+# WORKFLOW STATE SUMMARY
+#
+echo "state:"
+
+echo "  has_plans: $([ "$plan_count" -gt 0 ] && echo "true" || echo "false")"
+echo "  plan_count: $plan_count"
+
+# Determine workflow state for routing
+if [ "$plan_count" -eq 0 ]; then
+    echo "  scenario: \"no_plans\""
+elif [ "$plan_count" -eq 1 ]; then
+    echo "  scenario: \"single_plan\""
+else
+    echo "  scenario: \"multiple_plans\""
+fi