@leeovery/claude-technical-workflows 2.0.41 → 2.0.43

package/scripts/discovery-for-planning.sh

@@ -0,0 +1,182 @@
+#!/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:-"local-markdown"}
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+
+        echo "    - name: \"$name\""
+        echo "      format: \"$format\""
+        echo "      status: \"$status\""
+    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,170 @@
+#!/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
+#   ---
+#
+#   # 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
+
+    #
+    # Build new file content
+    #
+
+    # Create frontmatter
+    frontmatter="---
+topic: $topic_kebab
+status: $status_new
+type: $type_new
+date: $date_value
+---"
+
+    # 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,172 @@
+#!/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: local-markdown
+#   ---
+#
+#   # 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: local-markdown
+#   specification: {topic}.md
+#   ---
+#
+#   # 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="local-markdown"  # Default format
+    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
+    date_value=$(grep -m1 '^\*\*Date\*\*:' "$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
+    frontmatter="---
+topic: $topic_kebab
+status: $status_new
+date: $date_value
+format: $format_value
+specification: $spec_value
+---"
+
+    # 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-local-markdown.md

@@ -33,15 +33,15 @@ Create `{topic}.md` with this structure:
 
 ```markdown
 ---
+topic: {feature-name}
+status: in-progress
+date: YYYY-MM-DD
 format: local-markdown
+specification: {topic}.md
 ---
 
 # Implementation Plan: {Feature/Project Name}
 
-**Date**: YYYY-MM-DD *(use today's actual date)*
-**Status**: Draft | Ready | In Progress | Completed
-**Specification**: `docs/workflow/specification/{topic}.md`
-
 ## Overview
 
 **Goal**: What we're building and why (one sentence)
@@ -222,7 +222,19 @@ grep -A 5 "### Phase 1" docs/workflow/planning/billing-system.md | grep "\[x\]"
 
 ## Frontmatter
 
-The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file.
+Plan documents use YAML frontmatter for metadata:
+
+```yaml
+---
+topic: {feature-name}        # Matches filename (without .md)
+status: in-progress          # in-progress | concluded
+date: YYYY-MM-DD             # Creation date
+format: local-markdown       # Output format used
+specification: {topic}.md    # Source specification filename
+---
+```
+
+The `format` field tells implementation which output adapter to use for reading/updating the plan.
 
 ## Flagging Incomplete Tasks
 

package/skills/technical-research/SKILL.md

@@ -58,9 +58,18 @@ Ask one question at a time. Wait for the answer. Document. Then ask the next.
 
 **Output**: `docs/workflow/research/exploration.md`
 
+**Template**: Use `references/template.md` for document structure. All research documents use YAML frontmatter:
+
+```yaml
+---
+topic: exploration
+date: YYYY-MM-DD  # Use today's actual date
+---
+```
+
 Start with one file. Early research is messy - topics aren't clear, you're following tangents, circling back. Don't force structure too early.
 
-**Let themes emerge**: Over multiple sessions, topics may become distinct. When they do, split into semantic files (`market-landscape.md`, `technical-feasibility.md`).
+**Let themes emerge**: Over multiple sessions, topics may become distinct. When they do, split into semantic files (`market-landscape.md`, `technical-feasibility.md`). Update the `topic` field to match the filename.
 
 **Periodic review**: Every few sessions, assess: are themes emerging? Split them out. Still fuzzy? Keep exploring. Ready for deeper discussion or specification? Research is complete.
 

package/skills/technical-research/references/template.md

@@ -0,0 +1,39 @@
+# Research Document Template
+
+Use this template when creating research documents.
+
+## Template
+
+```markdown
+---
+topic: exploration
+date: YYYY-MM-DD  # Use today's actual date
+---
+
+# Research: {Title}
+
+Brief description of what this research covers and what prompted it.
+
+## Starting Point
+
+What we know so far:
+- {Initial thoughts or context from the user}
+- {Any constraints or existing knowledge}
+- {Where we're starting: technical, market, business, etc.}
+
+---
+
+{Content follows - freeform, managed by the skill}
+```
+
+## Field Notes
+
+- `topic`: Use `exploration` for the initial exploration file. Use semantic names (`market-landscape`, `technical-feasibility`) when splitting into focused files.
+- `date`: Today's date when creating the document.
+
+## Notes
+
+- The "Starting Point" section captures context from the initial conversation
+- Content after that is intentionally unstructured - let themes emerge naturally
+- When splitting into topic files, update the `topic` field to match the filename
+- The skill handles content organization during sessions