@leeovery/claude-technical-workflows 2.0.35 → 2.0.37

package/README.md

@@ -251,7 +251,9 @@ agents/
 └── chain-verifier.md                # Parallel task verification for review
 
 scripts/                             # Helper scripts for commands
-└── specification-discovery.sh       # Discovery for specification command
+├── migrate.sh                       # Migration orchestrator
+├── specification-discovery.sh       # Discovery for specification command
+└── migrations/                      # Individual migration scripts (numbered)
 ```
 
 ## Skills
@@ -286,10 +288,11 @@ Sequential commands in `commands/workflow/`. They expect files from previous pha
 
 ### Utility Commands
 
-Helpers for navigating and understanding the workflow.
+Helpers for navigating and maintaining the workflow.
 
 | Command                                                                              | Description                                                                                                                                 |
 |--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/migrate**](commands/migrate.md)                                         | Keep workflow files in sync with the current system design. Runs automatically at the start of every workflow command.                      |
 | [**/status**](commands/workflow/status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
 | [**/view-plan**](commands/workflow/view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
 

package/commands/migrate.md

@@ -0,0 +1,43 @@
+---
+description: Run migrations to keep workflow files in sync with the current system design. This command is mandatory before running any workflow command.
+allowed-tools: Bash(.claude/scripts/migrate.sh)
+---
+
+# Migrate
+
+Keeps your workflow files up to date with how the system is designed to work. Runs all pending migrations automatically.
+
+## Instructions
+
+Run the migration script:
+
+```bash
+.claude/scripts/migrate.sh
+```
+
+### If files were updated
+
+The script will list which files were updated. Present this to the user:
+
+```
+{list from script output}
+
+Review changes with `git diff`, then proceed when ready.
+```
+
+Wait for user acknowledgment before returning control to the calling command.
+
+### If no updates needed
+
+```
+All documents up to date.
+```
+
+Return control silently - no user interaction needed.
+
+## Notes
+
+- This command is run automatically at the start of every workflow command
+- Migrations are tracked in `docs/workflow/.cache/migrations.log`
+- To force re-running all migrations, delete the tracking file
+- Each migration is idempotent - safe to run multiple times

package/commands/workflow/start-discussion.md

@@ -31,6 +31,14 @@ Before beginning, discover existing work and determine the best entry path.
 
 Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Discover Existing Work
 
 Scan the codebase for research and discussions:
@@ -44,8 +52,8 @@ Scan the codebase for research and discussions:
    - Each file is named `{topic}.md`
 
 3. **Check discussion status**: For each discussion file
-   - Run `head -10 docs/workflow/discussion/{topic}.md` to extract the `Status:` field
-   - Status values: `Exploring`, `Deciding`, or `Concluded`
+   - Run `head -10 docs/workflow/discussion/{topic}.md` to read the frontmatter
+   - Extract the `status:` field from YAML frontmatter: `in-progress` or `concluded`
    - Do NOT use bash loops - run separate commands for each file
 
 4. **Check for cached analysis** (if research files exist):
@@ -177,13 +185,13 @@ Then skip to Step 5 (Gather Context) with the fresh topic path.
   • {topic}.md — {Status}
     "{Brief description from context section}"
 
-  • {topic}.md — Concluded
+  • {topic}.md — concluded
     "{Brief description}"
 ```
 
 **Key:**
-- Exploring/Deciding = In progress
-- Concluded = Complete (can still be reopened)
+- in-progress = Active discussion
+- concluded = Complete (can still be reopened)
 
 **Then present the options based on what exists:**
 

package/commands/workflow/start-implementation.md

@@ -37,6 +37,14 @@ Before beginning, discover existing work and gather necessary information.
 
 Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Discover Existing Plans
 
 Scan the codebase for plans:

package/commands/workflow/start-planning.md

@@ -31,6 +31,14 @@ Before beginning, discover existing work and gather necessary information.
 
 Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Discover Existing Work
 
 Scan the codebase for specifications and plans:

package/commands/workflow/start-research.md

@@ -23,6 +23,14 @@ This is **Phase 1** of the six-phase workflow:
 
 ## Instructions
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding.
+
+---
+
 Ask these questions to gather context:
 
 1. **What's on your mind?**

package/commands/workflow/start-review.md

@@ -31,6 +31,14 @@ Before beginning, discover existing work and gather necessary information.
 
 Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Discover Existing Plans
 
 Scan the codebase for plans:

package/commands/workflow/start-specification.md

@@ -30,6 +30,14 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 ---
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Run Discovery Script
 
 Run the discovery script to gather current state:
@@ -78,9 +86,9 @@ The specification phase requires a completed discussion. Please run /start-discu
 ```
 No concluded discussions found.
 
-The following discussions are still exploring:
-  - {topic-1} (exploring)
-  - {topic-2} (exploring)
+The following discussions are still in progress:
+  - {topic-1} (in-progress)
+  - {topic-2} (in-progress)
 
 Please complete the discussion phase before creating specifications. Run /start-discussion to continue a discussion.
 ```
@@ -106,7 +114,7 @@ Discussions:
   ✓ {topic-1} - concluded - ready
   ✓ {topic-2} - concluded - ready
   ○ {topic-3} - concluded - has individual spec
-  · {topic-4} - exploring - not ready
+  · {topic-4} - in-progress - not ready
 
 Specifications:
   • {spec-1} (active) - sources: {topic-1}
@@ -118,7 +126,7 @@ Specifications:
 **Legend:**
 - `✓` = concluded, no spec yet (ready to specify)
 - `○` = concluded, has individual spec (can be combined or continued)
-- `·` = not concluded (not ready)
+- `·` = in-progress (not ready)
 
 #### Routing Based on State
 

package/commands/workflow/status.md

@@ -4,6 +4,14 @@ description: Show workflow status - what exists, where you are, and what to do n
 
 Show the current state of the workflow for this project.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Scan Directories
 
 Check for files in each workflow directory:

package/commands/workflow/view-plan.md

@@ -4,6 +4,14 @@ description: View a plan's tasks and progress, regardless of output format.
 
 Display a readable summary of a plan's phases, tasks, and status.
 
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
 ## Step 1: Identify the Plan
 
 If no topic is specified, list available plans:

package/package.json

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

package/scripts/migrate.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# migrate.sh
+#
+# Keeps workflow files in sync with the current system design.
+# Runs all migration scripts in order, tracking progress to avoid redundant processing.
+#
+# Usage:
+#   ./scripts/migrate.sh
+#
+# Tracking:
+#   Migrations are tracked in docs/workflow/.cache/migrations.log
+#   Format: "filepath: migration_id" (one per line, append-only)
+#   Delete the log file to force re-running all migrations.
+#
+# Adding new migrations:
+#   1. Create scripts/migrations/NNN-description.sh (e.g., 002-spec-frontmatter.sh)
+#   2. The script will be run automatically in numeric order
+#   3. Each migration script receives helper functions via source
+#
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MIGRATIONS_DIR="$SCRIPT_DIR/migrations"
+TRACKING_FILE="docs/workflow/.cache/migrations.log"
+
+# Track counts for final report
+FILES_UPDATED=0
+FILES_SKIPPED=0
+MIGRATIONS_RUN=0
+
+# Ensure cache directory exists
+mkdir -p "$(dirname "$TRACKING_FILE")"
+
+# Touch tracking file if it doesn't exist
+touch "$TRACKING_FILE"
+
+#
+# Helper function: Check if a migration has been applied to a file
+# Usage: is_migrated "filepath" "migration_id"
+# Returns: 0 if migrated, 1 if not
+#
+is_migrated() {
+    local filepath="$1"
+    local migration_id="$2"
+    grep -q "^${filepath}: ${migration_id}$" "$TRACKING_FILE" 2>/dev/null
+}
+
+#
+# Helper function: Record that a migration was applied to a file
+# Usage: record_migration "filepath" "migration_id"
+#
+record_migration() {
+    local filepath="$1"
+    local migration_id="$2"
+    echo "${filepath}: ${migration_id}" >> "$TRACKING_FILE"
+}
+
+#
+# Helper function: Report a file update (for migration scripts to call)
+# Usage: report_update "filepath" "description"
+#
+report_update() {
+    local filepath="$1"
+    local description="$2"
+    echo "  ✓ $filepath ($description)"
+    FILES_UPDATED=$((FILES_UPDATED + 1))
+}
+
+#
+# Helper function: Report a file skip (for migration scripts to call)
+# Usage: report_skip "filepath"
+#
+report_skip() {
+    local filepath="$1"
+    FILES_SKIPPED=$((FILES_SKIPPED + 1))
+}
+
+# Export functions and variables for migration scripts
+export -f is_migrated record_migration report_update report_skip
+export TRACKING_FILE FILES_UPDATED FILES_SKIPPED
+
+#
+# Main: Run all migrations in order
+#
+
+# Check if migrations directory exists and has scripts
+if [ ! -d "$MIGRATIONS_DIR" ]; then
+    echo "No migrations directory found at $MIGRATIONS_DIR"
+    exit 0
+fi
+
+# Find all migration scripts, sorted by name (numeric order)
+mapfile -t MIGRATION_SCRIPTS < <(find "$MIGRATIONS_DIR" -name "*.sh" -type f | sort)
+
+if [ ${#MIGRATION_SCRIPTS[@]} -eq 0 ]; then
+    echo "No migration scripts found."
+    exit 0
+fi
+
+for script in "${MIGRATION_SCRIPTS[@]}"; do
+    # Extract migration ID from filename (e.g., "001" from "001-discussion-frontmatter.sh")
+    migration_id=$(basename "$script" .sh | grep -oE '^[0-9]+')
+
+    if [ -z "$migration_id" ]; then
+        echo "Warning: Skipping $script (no numeric prefix)"
+        continue
+    fi
+
+    # Source and run the migration script
+    # The script has access to: is_migrated, record_migration, report_update, report_skip
+    # shellcheck source=/dev/null
+    source "$script"
+
+    MIGRATIONS_RUN=$((MIGRATIONS_RUN + 1))
+done
+
+# Only output if files were actually updated
+if [ "$FILES_UPDATED" -gt 0 ]; then
+    echo ""
+    echo "$FILES_UPDATED file(s) migrated. Review with \`git diff\`, then proceed."
+fi

package/scripts/migrations/001-discussion-frontmatter.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+#
+# 001-discussion-frontmatter.sh
+#
+# Migrates discussion documents from legacy markdown header format to YAML frontmatter.
+#
+# Legacy format:
+#   # Discussion: {Topic}
+#
+#   **Date**: YYYY-MM-DD
+#   **Status**: Exploring | Deciding | Concluded | Complete | ✅ Complete
+#   **Status:** Concluded  (alternate: colon outside bold)
+#
+# New format:
+#   ---
+#   topic: {topic-name}
+#   status: in-progress | concluded
+#   date: YYYY-MM-DD
+#   ---
+#
+#   # Discussion: {Topic}
+#
+# Status mapping:
+#   Exploring, Deciding → in-progress
+#   Concluded, Complete, ✅ Complete → concluded
+#
+# This script is sourced by migrate-documents.sh and has access to:
+#   - is_migrated "filepath" "migration_id"
+#   - record_migration "filepath" "migration_id"
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="001"
+DISCUSSION_DIR="docs/workflow/discussion"
+
+# Skip if no discussion directory
+if [ ! -d "$DISCUSSION_DIR" ]; then
+    return 0
+fi
+
+# Process each discussion file
+for file in "$DISCUSSION_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 **Date**: or **Started:**)
+    if ! grep -q '^\*\*Status\*\*:\|^\*\*Status:\*\*\|^\*\*Date\*\*:\|^\*\*Started:\*\*' "$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 date from **Date**: YYYY-MM-DD or **Started:** YYYY-MM-DD
+    date_value=$(grep -m1 '^\*\*Date\*\*:\|^\*\*Started:\*\*' "$file" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' || echo "")
+
+    # Extract status from **Status**: Value or **Status:** Value (colon inside or outside bold)
+    # First extract the line, then remove all variations of the prefix
+    status_raw=$(grep -m1 '^\*\*Status' "$file" | sed 's/^\*\*Status\*\*:[[:space:]]*//' | sed 's/^\*\*Status:\*\*[[:space:]]*//' | tr '[:upper:]' '[:lower:]')
+    # Remove any emoji characters (like ✅) and trim whitespace
+    status_raw=$(echo "$status_raw" | sed 's/✅//g' | xargs)
+
+    # Map legacy status to new values
+    case "$status_raw" in
+        exploring|deciding)
+            status_new="in-progress"
+            ;;
+        concluded|complete)
+            status_new="concluded"
+            ;;
+        *)
+            status_new="in-progress"  # Default for unknown
+            ;;
+    esac
+
+    # 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
+date: $date_value
+---"
+
+    # Extract H1 heading (preserve original)
+    h1_heading=$(grep -m1 "^# " "$file")
+
+    # Find line number of first ## heading (start of real content)
+    first_section_line=$(grep -n "^## " "$file" | head -1 | cut -d: -f1)
+
+    # Get content from first ## onwards (preserves all content including **Status:** in decisions)
+    if [ -n "$first_section_line" ]; then
+        content=$(tail -n +$first_section_line "$file")
+    else
+        # No ## found - take everything after metadata block
+        # Find first blank line after H1, 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"
+done

package/scripts/specification-discovery.sh

@@ -15,28 +15,17 @@ SPEC_DIR="docs/workflow/specification"
 CACHE_FILE="docs/workflow/.cache/discussion-consolidation-analysis.md"
 
 # Helper: Extract a frontmatter field value from a file
-# Supports both YAML frontmatter and markdown format (**Field**: Value)
 # Usage: extract_field <file> <field_name>
 extract_field() {
     local file="$1"
     local field="$2"
     local value=""
 
-    # Try YAML frontmatter first (only if file starts with ---)
+    # 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 -m1 "^${field}:" | \
-            sed "s/^${field}:[[:space:]]*//" || true)
-    fi
-
-    # If empty, try markdown format: **Field**: Value
-    # Only search the header (before first ## heading) to avoid body matches
-    if [ -z "$value" ]; then
-        value=$(awk '/^## /{exit} {print}' "$file" 2>/dev/null | \
-            grep -i -m1 "^\*\*${field}\*\*:" | \
-            sed -E "s/^\*\*[^*]+\*\*:[[:space:]]*//" || true)
-        # Normalize to lowercase for consistency
-        value=$(echo "$value" | tr '[:upper:]' '[:lower:]')
+            grep -i -m1 "^${field}:" | \
+            sed -E "s/^${field}:[[:space:]]*//i" || true)
     fi
 
     echo "$value"

package/skills/technical-discussion/references/guidelines.md

@@ -84,3 +84,5 @@ Before marking discussion complete:
 - ✅ Impact explained
 - ✅ Confidence stated
 - ✅ No hallucination
+
+**When complete**: Update frontmatter `status: concluded`.

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

@@ -13,10 +13,13 @@ This is a single file per topic.
 ## Template
 
 ```markdown
-# Discussion: {Topic}
+---
+topic: {topic-name}
+status: in-progress
+date: YYYY-MM-DD  # Use today's actual date
+---
 
-**Date**: YYYY-MM-DD *(use today's actual date)*
-**Status**: Exploring | Deciding | Concluded
+# Discussion: {Topic}
 
 ## Context
 
@@ -97,7 +100,7 @@ What we chose, why, the deciding factor, trade-offs accepted, confidence level.
 **When creating**:
 1. Ensure discussion directory exists: `docs/workflow/discussion/`
 2. Create file: `{topic}.md`
-3. Fill header: date, status
+3. Fill frontmatter: topic, status, date
 4. Start with context: why discussing?
 5. List questions: what needs deciding?
 
@@ -125,3 +128,5 @@ What we chose, why, the deciding factor, trade-offs accepted, confidence level.
 - Major questions concluded with rationale
 - Trade-offs understood
 - Path forward clear
+
+**When complete**: Update frontmatter `status: concluded` to signal ready for specification.