@leeovery/claude-technical-workflows 2.0.42 → 2.0.44

package/scripts/discovery-for-planning.sh

@@ -0,0 +1,186 @@
+#!/bin/bash
+#
+# Discovers the current state of specifications and plans
+# for the /start-planning command.
+#
+# Outputs structured YAML that the command can consume directly.
+#
+
+set -eo pipefail
+
+SPEC_DIR="docs/workflow/specification"
+PLAN_DIR="docs/workflow/planning"
+
+# 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 "# Planning Command State Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# SPECIFICATIONS
+#
+echo "specifications:"
+
+feature_count=0
+feature_ready_count=0
+crosscutting_count=0
+
+if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  feature:"
+
+    # First pass: feature specifications
+    for file in "$SPEC_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        status=$(extract_field "$file" "status")
+        status=${status:-"active"}
+        spec_type=$(extract_field "$file" "type")
+        spec_type=${spec_type:-"feature"}
+
+        # Skip cross-cutting specs in this pass
+        [ "$spec_type" = "cross-cutting" ] && continue
+
+        # Check if plan exists
+        has_plan="false"
+        if [ -f "$PLAN_DIR/${name}.md" ]; then
+            has_plan="true"
+        fi
+
+        echo "    - name: \"$name\""
+        echo "      status: \"$status\""
+        echo "      has_plan: $has_plan"
+
+        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
+    done
+
+    if [ "$feature_count" -eq 0 ]; then
+        echo "    []  # No feature specifications"
+    fi
+
+    echo "  crosscutting:"
+
+    # Second pass: cross-cutting specifications
+    for file in "$SPEC_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        spec_type=$(extract_field "$file" "type")
+        spec_type=${spec_type:-"feature"}
+
+        # Only cross-cutting specs in this pass
+        [ "$spec_type" != "cross-cutting" ] && continue
+
+        status=$(extract_field "$file" "status")
+        status=${status:-"active"}
+
+        echo "    - name: \"$name\""
+        echo "      status: \"$status\""
+
+        crosscutting_count=$((crosscutting_count + 1))
+    done
+
+    if [ "$crosscutting_count" -eq 0 ]; then
+        echo "    []  # No cross-cutting specifications"
+    fi
+
+    echo "  counts:"
+    echo "    feature: $feature_count"
+    echo "    feature_ready: $feature_ready_count"
+    echo "    crosscutting: $crosscutting_count"
+else
+    echo "  exists: false"
+    echo "  feature: []"
+    echo "  crosscutting: []"
+    echo "  counts:"
+    echo "    feature: 0"
+    echo "    feature_ready: 0"
+    echo "    crosscutting: 0"
+fi
+
+echo ""
+
+#
+# PLANS
+#
+echo "plans:"
+
+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)
+        format=$(extract_field "$file" "format")
+        format=${format:-"MISSING"}
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+        plan_id=$(extract_field "$file" "plan_id")
+
+        echo "    - name: \"$name\""
+        echo "      format: \"$format\""
+        echo "      status: \"$status\""
+        if [ -n "$plan_id" ]; then
+            echo "      plan_id: \"$plan_id\""
+        fi
+    done
+else
+    echo "  exists: false"
+    echo "  files: []"
+fi
+
+echo ""
+
+#
+# WORKFLOW STATE SUMMARY
+#
+echo "state:"
+
+specs_exist="false"
+plans_exist="false"
+
+if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
+    specs_exist="true"
+fi
+
+if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
+    plans_exist="true"
+fi
+
+echo "  has_specifications: $specs_exist"
+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\""
+else
+    echo "  scenario: \"multiple_ready_specs\""
+fi

package/scripts/{specification-discovery.sh → discovery-for-specification.sh}

@@ -1,7 +1,5 @@
 #!/bin/bash
 #
-# discover-spec-state.sh
-#
 # Discovers the current state of discussions, specifications, and cache
 # for the /start-specification command.
 #
@@ -68,13 +66,20 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
 
         # Check if this discussion has a corresponding individual spec
         has_individual_spec="false"
+        spec_status=""
         if [ -f "$SPEC_DIR/${name}.md" ]; then
             has_individual_spec="true"
+            # Extract spec status in real-time (not from cache)
+            spec_status=$(extract_field "$SPEC_DIR/${name}.md" "status")
+            spec_status=${spec_status:-"in-progress"}
         fi
 
         echo "  - name: \"$name\""
         echo "    status: \"$status\""
         echo "    has_individual_spec: $has_individual_spec"
+        if [ "$has_individual_spec" = "true" ]; then
+            echo "    spec_status: \"$spec_status\""
+        fi
     done
 else
     echo "  []  # No discussions found"

package/scripts/migrations/002-specification-frontmatter.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+#
+# 002-specification-frontmatter.sh
+#
+# Migrates specification documents from legacy markdown header format to YAML frontmatter.
+#
+# Legacy format:
+#   # Specification: {Topic}
+#
+#   **Status**: Building specification | Complete
+#   **Type**: feature | cross-cutting
+#   **Last Updated**: YYYY-MM-DD
+#
+# New format:
+#   ---
+#   topic: {topic-name}
+#   status: in-progress | concluded
+#   type: feature | cross-cutting | (empty if unknown)
+#   date: YYYY-MM-DD
+#   sources:              # Optional - only if Sources field exists
+#     - discussion-one
+#     - discussion-two
+#   ---
+#
+#   # Specification: {Topic}
+#
+# Status mapping (normalized across all document types):
+#   Building specification, Building, Draft → in-progress
+#   Complete, Completed, Done → concluded
+#
+# Type handling:
+#   feature → feature
+#   cross-cutting → cross-cutting
+#   (not found or unrecognized) → empty (requires manual review)
+#
+# This script is sourced by migrate.sh and has access to:
+#   - is_migrated "filepath" "migration_id"
+#   - record_migration "filepath" "migration_id"
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="002"
+SPEC_DIR="docs/workflow/specification"
+
+# Skip if no specification directory
+if [ ! -d "$SPEC_DIR" ]; then
+    return 0
+fi
+
+# Process each specification file
+for file in "$SPEC_DIR"/*.md; do
+    [ -f "$file" ] || continue
+
+    # Check if already migrated via tracking
+    if is_migrated "$file" "$MIGRATION_ID"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file already has YAML frontmatter
+    if head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        # Already has frontmatter - just record and skip
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file has legacy format (look for **Status**: or **Status:** or **Type**: or **Last Updated**:)
+    if ! grep -q '^\*\*Status\*\*:\|^\*\*Status:\*\*\|^\*\*Type\*\*:\|^\*\*Last Updated\*\*:' "$file" 2>/dev/null; then
+        # No legacy format found - might be malformed, skip
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    #
+    # Extract values from legacy format
+    #
+
+    # Use filename as topic (canonical identifier throughout the workflow)
+    topic_kebab=$(basename "$file" .md)
+
+    # Extract status from **Status**: Value or **Status:** Value
+    # Handle variations: "Building specification", "Building", "Complete", "Completed", etc.
+    status_raw=$(grep -m1 '^\*\*Status\*\*:\|^\*\*Status:\*\*' "$file" | \
+        sed 's/^\*\*Status\*\*:[[:space:]]*//' | \
+        sed 's/^\*\*Status:\*\*[[:space:]]*//' | \
+        tr '[:upper:]' '[:lower:]' | \
+        xargs)
+
+    # Map legacy status to normalized values (consistent across all document types)
+    case "$status_raw" in
+        "building specification"|"building"|"draft"|"in progress"|"in-progress"|"exploring"|"deciding")
+            status_new="in-progress"
+            ;;
+        "complete"|"completed"|"done"|"finished"|"concluded")
+            status_new="concluded"
+            ;;
+        *)
+            status_new="in-progress"  # Default for unknown
+            ;;
+    esac
+
+    # Extract type from **Type**: Value (may not exist in legacy files)
+    type_raw=$(grep -m1 '^\*\*Type\*\*:\|^\*\*Type:\*\*' "$file" 2>/dev/null | \
+        sed 's/^\*\*Type\*\*:[[:space:]]*//' | \
+        sed 's/^\*\*Type:\*\*[[:space:]]*//' | \
+        tr '[:upper:]' '[:lower:]' | \
+        xargs || echo "")
+
+    # Normalize type (leave empty if not found or unrecognized - requires manual review)
+    case "$type_raw" in
+        "feature")
+            type_new="feature"
+            ;;
+        "cross-cutting"|"crosscutting"|"cross cutting")
+            type_new="cross-cutting"
+            ;;
+        *)
+            type_new=""  # Empty - requires manual classification
+            ;;
+    esac
+
+    # Extract date from **Last Updated**: YYYY-MM-DD or **Date**: YYYY-MM-DD
+    date_value=$(grep -m1 '^\*\*Last Updated\*\*:\|^\*\*Date\*\*:' "$file" | \
+        grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "")
+
+    # Use today's date if none found
+    if [ -z "$date_value" ]; then
+        date_value=$(date +%Y-%m-%d)
+    fi
+
+    # Extract sources from **Sources**: source1, source2, ... (comma-separated list of discussion names)
+    # These link the specification back to the discussions that informed it
+    sources_raw=$(grep -m1 '^\*\*Sources\*\*:' "$file" 2>/dev/null | \
+        sed 's/^\*\*Sources\*\*:[[:space:]]*//' | \
+        xargs || echo "")
+
+    # Convert comma-separated list to array
+    sources_array=()
+    if [ -n "$sources_raw" ]; then
+        IFS=',' read -ra sources_parts <<< "$sources_raw"
+        for src in "${sources_parts[@]}"; do
+            # Trim whitespace
+            src=$(echo "$src" | xargs)
+            if [ -n "$src" ]; then
+                sources_array+=("$src")
+            fi
+        done
+    fi
+
+    #
+    # Build new file content
+    #
+
+    # Create frontmatter (conditionally include sources if present)
+    if [ ${#sources_array[@]} -gt 0 ]; then
+        sources_yaml=""
+        for src in "${sources_array[@]}"; do
+            sources_yaml="${sources_yaml}
+  - $src"
+        done
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+type: $type_new
+date: $date_value
+sources:$sources_yaml
+---"
+    else
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+type: $type_new
+date: $date_value
+---"
+    fi
+
+    # Extract H1 heading (preserve original)
+    h1_heading=$(grep -m1 "^# " "$file")
+
+    # Find line number of first ## heading (start of real content after metadata)
+    first_section_line=$(grep -n "^## " "$file" | head -1 | cut -d: -f1)
+
+    # Get content from first ## onwards (preserves all content)
+    if [ -n "$first_section_line" ]; then
+        content=$(tail -n +$first_section_line "$file")
+    else
+        # No ## found - take everything after the metadata block
+        # Find first blank line after the metadata, then take from there
+        content=""
+    fi
+
+    # Write new content: frontmatter + H1 + blank line + content
+    {
+        echo "$frontmatter"
+        echo ""
+        echo "$h1_heading"
+        echo ""
+        echo "$content"
+    } > "$file"
+
+    # Record and report
+    record_migration "$file" "$MIGRATION_ID"
+    report_update "$file" "added frontmatter (status: $status_new, type: $type_new)"
+done

package/scripts/migrations/003-planning-frontmatter.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+#
+# 003-planning-frontmatter.sh
+#
+# Migrates plan documents from legacy format to full YAML frontmatter.
+#
+# Legacy format (partial frontmatter + inline metadata):
+#   ---
+#   format: {format}
+#   ---
+#
+#   # Implementation Plan: {Feature/Project Name}
+#
+#   **Date**: YYYY-MM-DD
+#   **Status**: Draft | Ready | In Progress | Completed
+#   **Specification**: `docs/workflow/specification/{topic}.md`
+#
+# New format (all metadata in frontmatter):
+#   ---
+#   topic: {topic-name}
+#   status: in-progress | concluded
+#   date: YYYY-MM-DD
+#   format: {format}         # Required - no default, MISSING if not present
+#   specification: {topic}.md
+#   plan_id: {id}            # Optional - migrated from 'epic' or 'project' fields
+#   ---
+#
+#   # Implementation Plan: {Feature/Project Name}
+#
+# Status mapping (normalized across all document types):
+#   Draft, Ready, In Progress → in-progress
+#   Completed, Done → concluded
+#
+# This script is sourced by migrate.sh and has access to:
+#   - is_migrated "filepath" "migration_id"
+#   - record_migration "filepath" "migration_id"
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="003"
+PLAN_DIR="docs/workflow/planning"
+
+# Skip if no planning directory
+if [ ! -d "$PLAN_DIR" ]; then
+    return 0
+fi
+
+# Process each plan file
+for file in "$PLAN_DIR"/*.md; do
+    [ -f "$file" ] || continue
+
+    # Check if already migrated via tracking
+    if is_migrated "$file" "$MIGRATION_ID"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file already has full frontmatter (topic field present)
+    if head -10 "$file" 2>/dev/null | grep -q "^topic:"; then
+        # Already has full frontmatter - just record and skip
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if file has legacy format indicators
+    # Legacy format has partial frontmatter (format:) OR inline **Date**/**Status**/**Specification**
+    has_partial_frontmatter=$(head -5 "$file" 2>/dev/null | grep -c "^format:" || true)
+    has_inline_metadata=$(grep -c '^\*\*Date\*\*:\|^\*\*Status\*\*:\|^\*\*Specification\*\*:' "$file" 2>/dev/null || true)
+
+    if [ "${has_partial_frontmatter:-0}" = "0" ] && [ "${has_inline_metadata:-0}" = "0" ]; then
+        # No legacy format found - might be malformed, skip
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    #
+    # Extract values from legacy format
+    #
+
+    # Use filename as topic (canonical identifier throughout the workflow)
+    topic_kebab=$(basename "$file" .md)
+
+    # Extract format from existing frontmatter (if present)
+    format_value=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | grep "^format:" | sed 's/^format:[[:space:]]*//' | xargs || echo "")
+    if [ -z "$format_value" ]; then
+        format_value="MISSING"  # No default - missing format is an error
+    fi
+
+    # Extract plan_id from existing frontmatter - could be 'epic' (beads) or 'project' (linear/backlog)
+    # These are migrated to a unified 'plan_id' field
+    plan_id_value=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | grep "^epic:" | sed 's/^epic:[[:space:]]*//' | xargs || echo "")
+    if [ -z "$plan_id_value" ]; then
+        plan_id_value=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | grep "^project:" | sed 's/^project:[[:space:]]*//' | xargs || echo "")
+    fi
+
+    # Extract status from **Status**: Value
+    status_raw=$(grep -m1 '^\*\*Status\*\*:' "$file" 2>/dev/null | \
+        sed 's/^\*\*Status\*\*:[[:space:]]*//' | \
+        tr '[:upper:]' '[:lower:]' | \
+        xargs || echo "")
+
+    # Map legacy status to normalized values
+    case "$status_raw" in
+        "draft"|"ready"|"in progress"|"in-progress")
+            status_new="in-progress"
+            ;;
+        "completed"|"complete"|"done"|"concluded")
+            status_new="concluded"
+            ;;
+        *)
+            status_new="in-progress"  # Default for unknown
+            ;;
+    esac
+
+    # Extract date from **Date**: YYYY-MM-DD or **Created**: YYYY-MM-DD
+    date_value=$(grep -m1 '^\*\*Date\*\*:\|^\*\*Created\*\*:' "$file" 2>/dev/null | \
+        grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "")
+
+    # Use today's date if none found
+    if [ -z "$date_value" ]; then
+        date_value=$(date +%Y-%m-%d)
+    fi
+
+    # Extract specification from **Specification**: `docs/workflow/specification/{topic}.md`
+    # We just want the filename, not the full path
+    spec_raw=$(grep -m1 '^\*\*Specification\*\*:' "$file" 2>/dev/null | \
+        sed 's/^\*\*Specification\*\*:[[:space:]]*//' | \
+        sed 's/`//g' | \
+        xargs || echo "")
+
+    # Extract just the filename from the path
+    if [ -n "$spec_raw" ]; then
+        spec_value=$(basename "$spec_raw")
+    else
+        spec_value="${topic_kebab}.md"  # Default to topic name
+    fi
+
+    #
+    # Build new file content
+    #
+
+    # Create frontmatter (conditionally include plan_id if present)
+    if [ -n "$plan_id_value" ]; then
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+date: $date_value
+format: $format_value
+specification: $spec_value
+plan_id: $plan_id_value
+---"
+    else
+        frontmatter="---
+topic: $topic_kebab
+status: $status_new
+date: $date_value
+format: $format_value
+specification: $spec_value
+---"
+    fi
+
+    # Extract H1 heading (preserve original)
+    h1_heading=$(grep -m1 "^# " "$file")
+
+    # Find line number of first ## heading (start of real content after metadata)
+    first_section_line=$(grep -n "^## " "$file" | head -1 | cut -d: -f1)
+
+    # Get content from first ## onwards (preserves all content)
+    if [ -n "$first_section_line" ]; then
+        content=$(tail -n +$first_section_line "$file")
+    else
+        # No ## found - might be empty or malformed
+        content=""
+    fi
+
+    # Write new content: frontmatter + H1 + blank line + content
+    {
+        echo "$frontmatter"
+        echo ""
+        echo "$h1_heading"
+        echo ""
+        echo "$content"
+    } > "$file"
+
+    # Record and report
+    record_migration "$file" "$MIGRATION_ID"
+    report_update "$file" "added full frontmatter (status: $status_new, format: $format_value)"
+done

package/skills/technical-planning/references/output-backlog-md.md

@@ -53,7 +53,7 @@ The plan file in `docs/workflow/planning/{topic}.md` serves as the reference poi
 ```markdown
 ---
 format: backlog-md
-project: {TOPIC_NAME}
+plan_id: {TOPIC_NAME}
 ---
 
 # Plan Reference: {Topic Name}

package/skills/technical-planning/references/output-beads.md

@@ -240,7 +240,7 @@ Create `docs/workflow/planning/{topic}.md`:
 ```markdown
 ---
 format: beads
-epic: bd-{EPIC_ID}
+plan_id: bd-{EPIC_ID}
 ---
 
 # Plan Reference: {Topic Name}
@@ -304,7 +304,7 @@ The `format: beads` frontmatter tells implementation to use beads CLI:
 ```yaml
 ---
 format: beads
-epic: bd-a3f8
+plan_id: bd-a3f8
 ---
 ```
 
@@ -327,7 +327,7 @@ In the task body:
 
 ### Reading Plans
 
-1. Extract `epic` ID from frontmatter
+1. Extract `plan_id` (beads epic ID) from frontmatter
 2. Check `.beads/config.yaml` for `no-db` setting
 3. Run `bd ready` to get unblocked tasks
 4. View task details with `bd show bd-{id}`

package/skills/technical-planning/references/output-linear.md

@@ -148,7 +148,7 @@ Create `docs/workflow/planning/{topic}.md`:
 ```markdown
 ---
 format: linear
-project: {PROJECT_NAME}
+plan_id: {PROJECT_NAME}
 project_id: {ID from MCP response}
 team: {TEAM_NAME}
 ---
@@ -207,7 +207,7 @@ The frontmatter contains all information needed to query Linear:
 ```yaml
 ---
 format: linear
-project: USER-AUTH-FEATURE
+plan_id: USER-AUTH-FEATURE
 project_id: abc123-def456
 team: Engineering
 ---
@@ -257,7 +257,7 @@ Linear:
 
 ### Reading Plans
 
-1. Extract `project_id` from frontmatter
+1. Extract `plan_id` (Linear project name) from frontmatter
 2. Query Linear MCP for project issues
 3. Filter issues by phase label (e.g., `phase-1`, `phase-2`)
 4. Process in phase order