@leeovery/claude-technical-workflows 2.1.27 → 2.1.28

package/skills/migrate/scripts/migrations/006-directory-restructure.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+#
+# 006-directory-restructure.sh
+#
+# Restructures specification and planning files from flat files to topic directories:
+#   - specification/{topic}.md → specification/{topic}/specification.md
+#   - planning/{topic}.md → planning/{topic}/plan.md
+#
+# Also moves tracking files into topic directories and strips topic prefix:
+#   - {topic}-review-*.md → {topic}/review-*.md
+#
+# Updates plan frontmatter `specification` field to use new directory paths.
+#
+# 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="006"
+SPEC_DIR="docs/workflow/specification"
+PLAN_DIR="docs/workflow/planning"
+
+#
+# Phase 1: Specification migration
+#
+if [ -d "$SPEC_DIR" ]; then
+    for file in "$SPEC_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+
+        # Skip if already a directory (already migrated)
+        if [ -d "$SPEC_DIR/$name" ] && [ -f "$SPEC_DIR/$name/specification.md" ]; then
+            new_path="$SPEC_DIR/$name/specification.md"
+            if ! is_migrated "$new_path" "$MIGRATION_ID"; then
+                record_migration "$new_path" "$MIGRATION_ID"
+            fi
+            report_skip "$new_path"
+            continue
+        fi
+
+        new_path="$SPEC_DIR/$name/specification.md"
+        if is_migrated "$new_path" "$MIGRATION_ID"; then
+            report_skip "$new_path"
+            continue
+        fi
+
+        # Create topic directory
+        mkdir -p "$SPEC_DIR/$name"
+
+        # Move the spec file
+        mv "$file" "$SPEC_DIR/$name/specification.md"
+
+        # Move any tracking files, stripping topic prefix
+        for tracking_file in "$SPEC_DIR/${name}-review-"*.md; do
+            [ -f "$tracking_file" ] || continue
+            tracking_basename=$(basename "$tracking_file")
+            # Strip the topic prefix: {name}-review-foo.md → review-foo.md
+            new_tracking_name="${tracking_basename#"${name}-"}"
+            mv "$tracking_file" "$SPEC_DIR/$name/$new_tracking_name"
+            report_update "$SPEC_DIR/$name/$new_tracking_name" "moved tracking file into topic directory"
+        done
+
+        record_migration "$new_path" "$MIGRATION_ID"
+        report_update "$new_path" "restructured to topic directory"
+    done
+fi
+
+#
+# Phase 2: Planning migration
+#
+if [ -d "$PLAN_DIR" ]; then
+    for file in "$PLAN_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+
+        # Skip if already a directory with plan.md
+        if [ -d "$PLAN_DIR/$name" ] && [ -f "$PLAN_DIR/$name/plan.md" ]; then
+            new_path="$PLAN_DIR/$name/plan.md"
+            if ! is_migrated "$new_path" "$MIGRATION_ID"; then
+                record_migration "$new_path" "$MIGRATION_ID"
+            fi
+            report_skip "$new_path"
+            continue
+        fi
+
+        new_path="$PLAN_DIR/$name/plan.md"
+        if is_migrated "$new_path" "$MIGRATION_ID"; then
+            report_skip "$new_path"
+            continue
+        fi
+
+        # Create topic directory (may already exist for local-markdown tasks)
+        mkdir -p "$PLAN_DIR/$name"
+
+        # Move the plan file
+        mv "$file" "$PLAN_DIR/$name/plan.md"
+
+        # Move any tracking files, stripping topic prefix
+        for tracking_file in "$PLAN_DIR/${name}-review-"*.md; do
+            [ -f "$tracking_file" ] || continue
+            tracking_basename=$(basename "$tracking_file")
+            new_tracking_name="${tracking_basename#"${name}-"}"
+            mv "$tracking_file" "$PLAN_DIR/$name/$new_tracking_name"
+            report_update "$PLAN_DIR/$name/$new_tracking_name" "moved tracking file into topic directory"
+        done
+
+        record_migration "$new_path" "$MIGRATION_ID"
+        report_update "$new_path" "restructured to topic directory"
+    done
+fi
+
+#
+# Phase 3: Update plan frontmatter specification field
+#
+# For each plan file (now at planning/{name}/plan.md), update
+# specification: {topic}.md → specification: {topic}/specification.md
+#
+if [ -d "$PLAN_DIR" ]; then
+    for file in "$PLAN_DIR"/*/plan.md; do
+        [ -f "$file" ] || continue
+
+        # Extract current specification field using awk (safe frontmatter extraction)
+        spec_value=$(awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null | \
+            grep "^specification:" | sed 's/^specification:[[:space:]]*//' | xargs)
+
+        # Skip if empty or already updated (contains /specification.md)
+        [ -z "$spec_value" ] && continue
+        case "$spec_value" in
+            */specification.md) continue ;;
+        esac
+
+        # Only update if it matches the old {topic}.md pattern
+        # Extract the topic name by stripping .md
+        case "$spec_value" in
+            *.md)
+                topic_name="${spec_value%.md}"
+                # Handle both relative paths: {topic}.md and ../specification/{topic}.md
+                case "$spec_value" in
+                    ../specification/*.md)
+                        new_spec_value="../specification/${topic_name#../specification/}/specification.md"
+                        ;;
+                    *)
+                        new_spec_value="${topic_name}/specification.md"
+                        ;;
+                esac
+
+                # Use awk to replace the specification field in frontmatter only
+                awk -v old="specification: $spec_value" -v new="specification: $new_spec_value" '
+                    BEGIN { c=0; done=0 }
+                    /^---$/ { c++; print; next }
+                    c==1 && !done && index($0, "specification:") == 1 {
+                        print new
+                        done=1
+                        next
+                    }
+                    { print }
+                ' "$file" > "${file}.tmp" && mv "${file}.tmp" "$file"
+
+                report_update "$file" "updated specification field: $spec_value → $new_spec_value"
+                ;;
+        esac
+    done
+fi

package/skills/migrate/scripts/migrations/007-tasks-subdirectory.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+#
+# 007-tasks-subdirectory.sh
+#
+# Moves local-markdown task files into a tasks/ subdirectory within each plan topic.
+#
+# Previous layout:
+#   planning/{topic}/
+#   ├── plan.md
+#   ├── {topic}-1-1.md
+#   ├── {topic}-1-2.md
+#   └── review-traceability-tracking-c1.md
+#
+# New layout:
+#   planning/{topic}/
+#   ├── plan.md
+#   ├── tasks/
+#   │   ├── {topic}-1-1.md
+#   │   └── {topic}-1-2.md
+#   └── review-traceability-tracking-c1.md
+#
+# Only targets files matching {topic}-*.md — won't touch plan.md or review-*-tracking-*.md.
+# Skips topics with no matching task files (may not be local-markdown format).
+# Idempotent: skips if tasks/ already exists and contains .md files.
+#
+# 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="007"
+PLAN_DIR="docs/workflow/planning"
+
+# Skip if no planning directory
+if [ ! -d "$PLAN_DIR" ]; then
+    return 0
+fi
+
+for topic_dir in "$PLAN_DIR"/*/; do
+    [ -d "$topic_dir" ] || continue
+
+    topic=$(basename "$topic_dir")
+    marker="${topic_dir}plan.md"
+
+    # Use plan.md as the migration tracking key
+    if is_migrated "$marker" "$MIGRATION_ID"; then
+        report_skip "$marker"
+        continue
+    fi
+
+    # Skip if no plan.md exists (not a valid topic directory)
+    if [ ! -f "$marker" ]; then
+        continue
+    fi
+
+    # Check if task files exist in the topic directory
+    task_files=("$topic_dir${topic}-"*.md)
+    if [ ! -f "${task_files[0]}" ]; then
+        # No task files — format may not be local-markdown, or tasks already moved
+        # Check if tasks/ already has files (idempotent check)
+        if [ -d "${topic_dir}tasks" ] && ls -1 "${topic_dir}tasks/"*.md >/dev/null 2>&1; then
+            record_migration "$marker" "$MIGRATION_ID"
+            report_skip "$marker"
+        else
+            record_migration "$marker" "$MIGRATION_ID"
+            report_skip "$marker"
+        fi
+        continue
+    fi
+
+    # Create tasks/ subdirectory
+    mkdir -p "${topic_dir}tasks"
+
+    # Move task files
+    moved=0
+    for task_file in "${task_files[@]}"; do
+        [ -f "$task_file" ] || continue
+        mv "$task_file" "${topic_dir}tasks/"
+        moved=$((moved + 1))
+    done
+
+    record_migration "$marker" "$MIGRATION_ID"
+    report_update "$marker" "moved $moved task file(s) to tasks/ subdirectory"
+done

package/skills/start-discussion/references/handle-selection.md

@@ -15,6 +15,9 @@ User chose to start from research (e.g., "research 1", "1", "from research", or
 - Control returns to the backbone
 
 **If user just said "from research" without specifying:**
+
+> *Output the next fenced block as a code block:*
+
 ```
 Which research topic would you like to discuss? (Enter a number or topic name)
 ```
@@ -30,6 +33,9 @@ User chose to continue a discussion (e.g., "continue auth-flow" or "continue dis
 - Control returns to the backbone
 
 **If user just said "continue discussion" without specifying:**
+
+> *Output the next fenced block as a code block:*
+
 ```
 Which discussion would you like to continue?
 ```
@@ -42,6 +48,8 @@ User wants to start a fresh discussion. Control returns to the backbone.
 
 #### If user chose "refresh"
 
+> *Output the next fenced block as a code block:*
+
 ```
 Refreshing analysis...
 ```

package/skills/start-feature/SKILL.md

@@ -37,7 +37,7 @@ Based on the feature description, suggest a topic name for the specification fil
 ```
 Based on what you've described, I'd suggest the topic name: {suggested-topic}
 
-This will create: docs/workflow/specification/{suggested-topic}.md
+This will create: docs/workflow/specification/{suggested-topic}/specification.md
 
 Is this name okay, or would you prefer something else?
 ```
@@ -77,6 +77,6 @@ Work from the inline context provided above.
 ## Notes
 
 - The specification skill contains instructions for synthesizing the inline context, presenting it for validation, and building the specification
-- Output is a standard specification file at `docs/workflow/specification/{topic}.md`
+- Output is a standard specification file at `docs/workflow/specification/{topic}/specification.md`
 - From there, the user can proceed to `/start-planning` as normal
 - This path skips formal discussion documentation - use the full workflow for complex features that need debate captured

package/skills/start-implementation/SKILL.md

@@ -369,8 +369,6 @@ Environment setup file found: docs/workflow/environment-setup.md
 
 **If `setup_file_exists: false` or `requires_setup: unknown`:**
 
-Ask:
-
 > *Output the next fenced block as a code block:*
 
 ```
@@ -396,7 +394,7 @@ Invoke the [technical-implementation](../technical-implementation/SKILL.md) skil
 **Example handoff:**
 ```
 Implementation session for: {topic}
-Plan: docs/workflow/planning/{topic}.md
+Plan: docs/workflow/planning/{topic}/plan.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})

package/skills/start-implementation/scripts/discovery.sh

@@ -162,10 +162,10 @@ 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
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         topic=$(extract_field "$file" "topic")
         topic=${topic:-"$name"}
         status=$(extract_field "$file" "status")
@@ -175,7 +175,7 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         format=$(extract_field "$file" "format")
         format=${format:-"MISSING"}
         specification=$(extract_field "$file" "specification")
-        specification=${specification:-"${name}.md"}
+        specification=${specification:-"${name}/specification.md"}
         plan_id=$(extract_field "$file" "plan_id")
 
         # Track plan data
@@ -326,10 +326,10 @@ echo "dependency_resolution:"
 if [ "$plan_count" -gt 0 ] && [ -d "$PLAN_DIR" ]; then
     has_resolution_data=false
 
-    for file in "$PLAN_DIR"/*.md; do
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         deps_output=$(extract_external_deps "$file")
         [ -z "$deps_output" ] && continue
 
@@ -424,9 +424,9 @@ echo "  plans_with_unresolved_deps: $plans_with_unresolved_deps"
 # Plans ready = concluded + all deps satisfied (no unresolved, all resolved tasks completed)
 plans_ready_count=0
 if [ "$plan_count" -gt 0 ] && [ -d "$PLAN_DIR" ]; then
-    for file in "$PLAN_DIR"/*.md; do
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
 
         if [ "$status" = "concluded" ]; then

package/skills/start-planning/references/invoke-skill.md

@@ -11,7 +11,7 @@ Invoke the [technical-planning](../../technical-planning/SKILL.md) skill for you
 **Example handoff (fresh plan):**
 ```
 Planning session for: {topic}
-Specification: docs/workflow/specification/{topic}.md
+Specification: docs/workflow/specification/{topic}/specification.md
 Additional context: {summary of user's answers from Step 5}
 Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
 Recommended output format: {common_format from discovery if non-empty, otherwise "none"}
@@ -22,8 +22,8 @@ Invoke the technical-planning skill.
 **Example handoff (continue/review existing plan):**
 ```
 Planning session for: {topic}
-Specification: docs/workflow/specification/{topic}.md
-Existing plan: docs/workflow/planning/{topic}.md
+Specification: docs/workflow/specification/{topic}/specification.md
+Existing plan: docs/workflow/planning/{topic}/plan.md
 
 Invoke the technical-planning skill.
 ```

package/skills/start-planning/scripts/discovery.sh

@@ -48,10 +48,10 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
     echo "  feature:"
 
     # First pass: feature specifications
-    for file in "$SPEC_DIR"/*.md; do
+    for file in "$SPEC_DIR"/*/specification.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
         status=${status:-"active"}
         spec_type=$(extract_field "$file" "type")
@@ -63,9 +63,9 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         # Check if plan exists and its status
         has_plan="false"
         plan_status=""
-        if [ -f "$PLAN_DIR/${name}.md" ]; then
+        if [ -f "$PLAN_DIR/${name}/plan.md" ]; then
             has_plan="true"
-            plan_status=$(extract_field "$PLAN_DIR/${name}.md" "status")
+            plan_status=$(extract_field "$PLAN_DIR/${name}/plan.md" "status")
             plan_status=${plan_status:-"unknown"}
         fi
 
@@ -93,10 +93,10 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
     echo "  crosscutting:"
 
     # Second pass: cross-cutting specifications
-    for file in "$SPEC_DIR"/*.md; do
+    for file in "$SPEC_DIR"/*/specification.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         spec_type=$(extract_field "$file" "type")
         spec_type=${spec_type:-"feature"}
 
@@ -146,10 +146,10 @@ 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
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         format=$(extract_field "$file" "format")
         format=${format:-"MISSING"}
 

package/skills/start-review/references/invoke-skill.md

@@ -12,7 +12,7 @@ Invoke the [technical-review](../../technical-review/SKILL.md) skill for your ne
 ```
 Review session for: {topic}
 Review scope: single
-Plan: docs/workflow/planning/{topic}.md
+Plan: docs/workflow/planning/{topic}/plan.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
@@ -25,8 +25,8 @@ Invoke the technical-review skill.
 Review session for: {scope description}
 Review scope: {multi | all}
 Plans:
-  - docs/workflow/planning/{topic-1}.md (format: {format}, spec: {spec})
-  - docs/workflow/planning/{topic-2}.md (format: {format}, spec: {spec})
+  - docs/workflow/planning/{topic-1}/plan.md (format: {format}, spec: {spec})
+  - docs/workflow/planning/{topic-2}/plan.md (format: {format}, spec: {spec})
 
 Invoke the technical-review skill.
 ```

package/skills/start-review/scripts/discovery.sh

@@ -52,10 +52,10 @@ 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
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         topic=$(extract_field "$file" "topic")
         topic=${topic:-"$name"}
         status=$(extract_field "$file" "status")
@@ -65,7 +65,7 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         format=$(extract_field "$file" "format")
         format=${format:-"MISSING"}
         specification=$(extract_field "$file" "specification")
-        specification=${specification:-"${name}.md"}
+        specification=${specification:-"${name}/specification.md"}
         plan_id=$(extract_field "$file" "plan_id")
 
         # Check if linked specification exists

package/skills/start-specification/references/confirm-continue.md

@@ -11,7 +11,7 @@
 ```
 Continuing specification: {Title Case Name}
 
-Existing: docs/workflow/specification/{kebab-case-name}.md (in-progress)
+Existing: docs/workflow/specification/{kebab-case-name}/specification.md (in-progress)
 
 Sources to extract:
   • {discussion-name} (pending)
@@ -37,7 +37,7 @@ Proceed?
 ```
 Continuing specification: {Title Case Name}
 
-Existing: docs/workflow/specification/{kebab-case-name}.md (in-progress)
+Existing: docs/workflow/specification/{kebab-case-name}/specification.md (in-progress)
 
 All sources extracted:
   • {discussion-name}
@@ -61,7 +61,7 @@ Proceed?
 ```
 Continuing specification: {Title Case Name}
 
-Existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+Existing: docs/workflow/specification/{kebab-case-name}/specification.md (concluded)
 
 New sources to extract:
   • {discussion-name} (pending)

package/skills/start-specification/references/confirm-create.md

@@ -15,7 +15,7 @@ Sources:
   • {discussion-name}
   • {discussion-name}
 
-Output: docs/workflow/specification/{kebab-case-name}.md
+Output: docs/workflow/specification/{kebab-case-name}/specification.md
 ```
 
 > *Output the next fenced block as markdown (not a code block):*
@@ -41,10 +41,10 @@ Sources:
   • {discussion-name} (has individual spec — will be incorporated)
   • {discussion-name}
 
-Output: docs/workflow/specification/{kebab-case-name}.md
+Output: docs/workflow/specification/{kebab-case-name}/specification.md
 
 After completion:
-  specification/{discussion-name}.md → marked as superseded
+  specification/{discussion-name}/specification.md → marked as superseded
 ```
 
 > *Output the next fenced block as markdown (not a code block):*

package/skills/start-specification/references/confirm-refine.md

@@ -9,7 +9,7 @@
 ```
 Refining specification: {Title Case Name}
 
-Existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+Existing: docs/workflow/specification/{kebab-case-name}/specification.md (concluded)
 
 All sources extracted:
   • {discussion-name}

package/skills/start-specification/references/confirm-unify.md

@@ -17,10 +17,10 @@ Sources:
   ...
 
 Existing specifications to incorporate:
-  • {spec-name}.md → will be superseded
-  • {spec-name}.md → will be superseded
+  • {spec-name}/specification.md → will be superseded
+  • {spec-name}/specification.md → will be superseded
 
-Output: docs/workflow/specification/unified.md
+Output: docs/workflow/specification/unified/specification.md
 ```
 
 > *Output the next fenced block as markdown (not a code block):*
@@ -45,7 +45,7 @@ Sources:
   • {discussion-name}
   ...
 
-Output: docs/workflow/specification/unified.md
+Output: docs/workflow/specification/unified/specification.md
 ```
 
 > *Output the next fenced block as markdown (not a code block):*

package/skills/start-specification/references/handoffs/continue-concluded.md

@@ -4,12 +4,14 @@
 
 ---
 
+Before invoking the skill, reset `finding_gate_mode` to `gated` in the specification frontmatter if present. Commit if changed: `spec({topic}): reset gate mode`
+
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
 ```
 Specification session for: {Title Case Name}
 
-Continuing existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+Continuing existing: docs/workflow/specification/{kebab-case-name}/specification.md (concluded)
 
 New sources to extract:
 - docs/workflow/discussion/{new-discussion-name}.md

package/skills/start-specification/references/handoffs/continue.md

@@ -4,12 +4,14 @@
 
 ---
 
+Before invoking the skill, reset `finding_gate_mode` to `gated` in the specification frontmatter if present. Commit if changed: `spec({topic}): reset gate mode`
+
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
 ```
 Specification session for: {Title Case Name}
 
-Continuing existing: docs/workflow/specification/{kebab-case-name}.md
+Continuing existing: docs/workflow/specification/{kebab-case-name}/specification.md
 
 Sources for reference:
 - docs/workflow/discussion/{discussion-name}.md

package/skills/start-specification/references/handoffs/create-with-incorporation.md

@@ -14,9 +14,9 @@ Source discussions:
 - docs/workflow/discussion/{discussion-name}.md
 
 Existing specifications to incorporate:
-- docs/workflow/specification/{spec-name}.md (covers: {discussion-name} discussion)
+- docs/workflow/specification/{spec-name}/specification.md (covers: {discussion-name} discussion)
 
-Output: docs/workflow/specification/{kebab-case-name}.md
+Output: docs/workflow/specification/{kebab-case-name}/specification.md
 
 Context: This consolidates multiple sources. The existing {spec-name}.md specification should be incorporated - extract and adapt its content alongside the discussion material. The result should be a unified specification, not a simple merge.
 

package/skills/start-specification/references/handoffs/create.md

@@ -13,7 +13,7 @@ Sources:
 - docs/workflow/discussion/{discussion-name}.md
 - docs/workflow/discussion/{discussion-name}.md
 
-Output: docs/workflow/specification/{kebab-case-name}.md
+Output: docs/workflow/specification/{kebab-case-name}/specification.md
 
 ---
 Invoke the technical-specification skill.

package/skills/start-specification/references/handoffs/unify-with-incorporation.md

@@ -15,10 +15,10 @@ Source discussions:
 ...
 
 Existing specifications to incorporate:
-- docs/workflow/specification/{spec-name}.md
-- docs/workflow/specification/{spec-name}.md
+- docs/workflow/specification/{spec-name}/specification.md
+- docs/workflow/specification/{spec-name}/specification.md
 
-Output: docs/workflow/specification/unified.md
+Output: docs/workflow/specification/unified/specification.md
 
 Context: This consolidates all discussions into a single unified specification. The existing specifications should be incorporated - extract and adapt their content alongside the discussion material.
 

package/skills/start-specification/references/handoffs/unify.md

@@ -14,7 +14,7 @@ Sources:
 - docs/workflow/discussion/{discussion-name}.md
 ...
 
-Output: docs/workflow/specification/unified.md
+Output: docs/workflow/specification/unified/specification.md
 
 ---
 Invoke the technical-specification skill.