@leeovery/claude-technical-workflows 2.0.43 → 2.0.44

package/commands/link-dependencies.md

@@ -53,9 +53,9 @@ Compare the `format:` field across all discovered plans.
 ```
 Mixed output formats detected:
 
-- authentication: beads
-- billing-system: linear
-- notifications: beads
+- authentication: {format-a}
+- billing-system: {format-b}
+- notifications: {format-a}
 
 Cross-topic dependencies can only be wired within the same output format.
 Please consolidate your plans to use a single output format before linking dependencies.
@@ -78,15 +78,15 @@ For each plan, find the External Dependencies section:
 ```
 Dependency Summary
 
-Plan: authentication (format: beads)
+Plan: authentication (format: {format})
   - billing-system: Invoice generation (unresolved)
-  - user-management: User profiles → beads-7x2k (resolved)
+  - user-management: User profiles → {task-id} (resolved)
 
-Plan: billing-system (format: beads)
+Plan: billing-system (format: {format})
   - authentication: User context (unresolved)
   - ~~payment-gateway: Payment processing~~ → satisfied externally
 
-Plan: notifications (format: beads)
+Plan: notifications (format: {format})
   - authentication: User lookup (unresolved)
   - billing-system: Invoice events (unresolved)
 ```
@@ -133,11 +133,11 @@ Present a summary:
 Dependency Linking Complete
 
 RESOLVED (newly linked):
-  - authentication → billing-system: beads-b7c2.1.1 (Invoice generation)
-  - notifications → authentication: beads-a3f8.1.2 (Session management)
+  - authentication → billing-system: {task-id} (Invoice generation)
+  - notifications → authentication: {task-id} (Session management)
 
 ALREADY RESOLVED (no action needed):
-  - authentication → user-management: beads-9m3p
+  - authentication → user-management: {task-id}
 
 SATISFIED EXTERNALLY (no action needed):
   - billing-system → payment-gateway

package/commands/workflow/start-implementation.md

@@ -56,7 +56,7 @@ 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
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
 - `count` - total number of plans
 
 **From `environment` section:**
@@ -105,9 +105,9 @@ Present all discovered plans to help the user make an informed choice.
 ```
 Available Plans:
 
-  1. {topic-1} (in-progress) - format: local-markdown
-  2. {topic-2} (concluded) - format: local-markdown
-  3. {topic-3} (in-progress) - format: beads
+  1. {topic-1} (in-progress) - format: {format}
+  2. {topic-2} (concluded) - format: {format}
+  3. {topic-3} (in-progress) - format: {format}
 
 Which plan would you like to implement? (Enter a number or name)
 ```
@@ -259,6 +259,7 @@ Invoke the [technical-implementation](../../skills/technical-implementation/SKIL
 Implementation session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
+Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
 Scope: {all phases | Phase N | Task N.M | next-available}
 

package/commands/workflow/start-planning.md

@@ -64,7 +64,7 @@ This outputs structured YAML. Parse it to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist
-- `files` - each plan's name, format, and status
+- `files` - each plan's name, format, status, and plan_id (if present)
 
 **From `state` section:**
 - `scenario` - one of: `"no_specs"`, `"no_ready_specs"`, `"single_ready_spec"`, `"multiple_ready_specs"`
@@ -122,7 +122,7 @@ Cross-cutting specifications (reference context):
   - {rate-limiting} (concluded)
 
 Existing plans:
-  - {topic-3}.md (in-progress, local-markdown)
+  - {topic-3}.md (in-progress, {format})
 ```
 
 **Legend:**

package/commands/workflow/start-review.md

@@ -56,7 +56,7 @@ 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
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
 - `count` - total number of plans
 
 **From `state` section:**
@@ -154,6 +154,7 @@ Invoke the [technical-review](../../skills/technical-review/SKILL.md) skill for
 Review session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
+Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
 Scope: {all changes | specific paths | from git status}
 

package/package.json

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

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

@@ -55,9 +55,10 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         date=$(extract_field "$file" "date")
         date=${date:-"unknown"}
         format=$(extract_field "$file" "format")
-        format=${format:-"local-markdown"}
+        format=${format:-"MISSING"}
         specification=$(extract_field "$file" "specification")
         specification=${specification:-"${name}.md"}
+        plan_id=$(extract_field "$file" "plan_id")
 
         # Check if linked specification exists
         spec_exists="false"
@@ -73,6 +74,9 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         echo "      format: \"$format\""
         echo "      specification: \"$specification\""
         echo "      specification_exists: $spec_exists"
+        if [ -n "$plan_id" ]; then
+            echo "      plan_id: \"$plan_id\""
+        fi
 
         plan_count=$((plan_count + 1))
     done

package/scripts/discovery-for-planning.sh

@@ -136,13 +136,17 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
 
         name=$(basename "$file" .md)
         format=$(extract_field "$file" "format")
-        format=${format:-"local-markdown"}
+        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"

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

@@ -17,6 +17,9 @@
 #   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}
@@ -128,17 +131,51 @@ for file in "$SPEC_DIR"/*.md; do
         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
-    frontmatter="---
+    # 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")

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

@@ -6,7 +6,7 @@
 #
 # Legacy format (partial frontmatter + inline metadata):
 #   ---
-#   format: local-markdown
+#   format: {format}
 #   ---
 #
 #   # Implementation Plan: {Feature/Project Name}
@@ -20,8 +20,9 @@
 #   topic: {topic-name}
 #   status: in-progress | concluded
 #   date: YYYY-MM-DD
-#   format: local-markdown
+#   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}
@@ -85,7 +86,14 @@ for file in "$PLAN_DIR"/*.md; do
     # 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
+        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
@@ -107,8 +115,8 @@ for file in "$PLAN_DIR"/*.md; do
             ;;
     esac
 
-    # Extract date from **Date**: YYYY-MM-DD
-    date_value=$(grep -m1 '^\*\*Date\*\*:' "$file" 2>/dev/null | \
+    # 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
@@ -134,14 +142,25 @@ for file in "$PLAN_DIR"/*.md; do
     # Build new file content
     #
 
-    # Create frontmatter
-    frontmatter="---
+    # 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")

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