@leeovery/claude-technical-workflows 2.1.39 → 2.1.41

package/skills/migrate/scripts/migrations/011-rename-workflow-directory.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# 011-rename-workflow-directory.sh
+#
+# Moves docs/workflow/ → .workflows/ at project root.
+# Workflow artefacts aren't documentation — the dot-prefixed directory
+# better communicates their role as planning artefacts.
+#
+# Steps:
+#   1. Skip if docs/workflow/ doesn't exist (fresh install or already migrated)
+#   2. Create .workflows/ if needed
+#   3. Move all contents preserving structure (including .state/, .cache/)
+#   4. Update .gitignore: docs/workflow/.cache/ → .workflows/.cache/
+#   5. Remove docs/workflow/ and docs/ if empty
+#
+# Idempotent: safe to run multiple times.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+
+OLD_DIR="docs/workflow"
+NEW_DIR=".workflows"
+GITIGNORE=".gitignore"
+OLD_GITIGNORE_ENTRY="docs/workflow/.cache/"
+NEW_GITIGNORE_ENTRY=".workflows/.cache/"
+
+# --- Step 1: Skip if nothing to migrate ---
+
+if [ ! -d "$OLD_DIR" ]; then
+    report_skip "$OLD_DIR (not found)"
+else
+    # --- Step 2: Create destination ---
+    mkdir -p "$NEW_DIR"
+
+    # --- Step 3: Move contents ---
+    # Use find to get all top-level items (including hidden dirs like .state/, .cache/)
+    for item in "$OLD_DIR"/* "$OLD_DIR"/.*; do
+        basename_item=$(basename "$item")
+        # Skip . and ..
+        [ "$basename_item" = "." ] || [ "$basename_item" = ".." ] && continue
+        # Skip if glob didn't match anything
+        [ ! -e "$item" ] && continue
+
+        if [ -e "$NEW_DIR/$basename_item" ]; then
+            report_skip "$basename_item (already exists at destination)"
+        else
+            mv "$item" "$NEW_DIR/$basename_item"
+            report_update "$NEW_DIR/$basename_item" "moved from $OLD_DIR/"
+        fi
+    done
+
+    # --- Step 4: Remove old directory ---
+    rmdir "$OLD_DIR" 2>/dev/null && report_update "$OLD_DIR" "removed empty directory" || true
+
+    # Remove docs/ if empty
+    if [ -d "docs" ]; then
+        rmdir "docs" 2>/dev/null && report_update "docs" "removed empty directory" || true
+    fi
+fi
+
+# --- Step 5: Update .gitignore ---
+
+if [ -f "$GITIGNORE" ] && grep -qF "$OLD_GITIGNORE_ENTRY" "$GITIGNORE"; then
+    # Replace old entry with new
+    awk -v old="$OLD_GITIGNORE_ENTRY" -v new="$NEW_GITIGNORE_ENTRY" '{
+        if ($0 == old) print new; else print
+    }' "$GITIGNORE" > "${GITIGNORE}.tmp"
+    mv "${GITIGNORE}.tmp" "$GITIGNORE"
+    report_update "$GITIGNORE" "updated .cache/ path"
+elif [ -f "$GITIGNORE" ] && grep -qxF "$NEW_GITIGNORE_ENTRY" "$GITIGNORE"; then
+    report_skip "$GITIGNORE (already has new entry)"
+fi

package/skills/migrate/scripts/migrations/012-environment-setup-to-state.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+#
+# 012-environment-setup-to-state.sh
+#
+# Moves environment-setup.md into .state/ directory.
+# This file is project state, not a workflow artifact.
+#
+# Idempotent: safe to run multiple times.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+
+OLD_FILE=".workflows/environment-setup.md"
+NEW_FILE=".workflows/.state/environment-setup.md"
+
+if [ -f "$OLD_FILE" ]; then
+    mkdir -p "$(dirname "$NEW_FILE")"
+    mv "$OLD_FILE" "$NEW_FILE"
+    report_update "$NEW_FILE" "moved from workflows root"
+elif [ -f "$NEW_FILE" ]; then
+    report_skip "$NEW_FILE (already in .state/)"
+fi

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,7 @@
 name: start-discussion
 description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.state), Bash(rm docs/workflow/.state/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
   PreToolUse:
     - hooks:
@@ -180,7 +180,7 @@ Saving session state so Claude can pick up where it left off if the conversation
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-discussion/SKILL.md" \
-  "docs/workflow/discussion/{topic}.md"
+  ".workflows/discussion/{topic}.md"
 ```
 
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-discussion/references/gather-context-research.md

@@ -11,7 +11,7 @@ Summarise the selected research topic in 2-5 lines, drawing from the source, sum
 ```
 New discussion: {topic}
 
-Based on research: docs/workflow/research/{filename}.md (lines {start}-{end})
+Based on research: .workflows/research/{filename}.md (lines {start}-{end})
 
 {2-5 line summary of the topic and what needs discussing}
 

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

@@ -56,7 +56,7 @@ Refreshing analysis...
 
 Delete the cache file:
 ```bash
-rm docs/workflow/.state/research-analysis.md
+rm .workflows/.state/research-analysis.md
 ```
 
 → Return to **Step 3** to re-analyze.

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

@@ -11,10 +11,10 @@ Invoke the [technical-discussion](../../technical-discussion/SKILL.md) skill for
 **Example handoff (from research):**
 ```
 Discussion session for: {topic}
-Output: docs/workflow/discussion/{topic}.md
+Output: .workflows/discussion/{topic}.md
 
 Research reference:
-Source: docs/workflow/research/{filename}.md (lines {start}-{end})
+Source: .workflows/research/{filename}.md (lines {start}-{end})
 Summary: {the 1-2 sentence summary from the research analysis}
 
 Invoke the technical-discussion skill.
@@ -24,7 +24,7 @@ Invoke the technical-discussion skill.
 ```
 Discussion session for: {topic}
 Source: {existing discussion | fresh}
-Output: docs/workflow/discussion/{topic}.md
+Output: .workflows/discussion/{topic}.md
 
 Invoke the technical-discussion skill.
 ```

package/skills/start-discussion/references/research-analysis.md

@@ -14,7 +14,7 @@ Use `cache.status` from discovery to determine the approach:
 Using cached research analysis (unchanged since {cache.generated})
 ```
 
-Load the topics from `docs/workflow/.state/research-analysis.md` and proceed.
+Load the topics from `.workflows/.state/research-analysis.md` and proceed.
 
 #### If cache.status is "stale" or "none"
 
@@ -40,10 +40,10 @@ Read each research file and extract key themes and potential discussion topics.
 
 Ensure the cache directory exists:
 ```bash
-mkdir -p docs/workflow/.state
+mkdir -p .workflows/.state
 ```
 
-Create/update `docs/workflow/.state/research-analysis.md`:
+Create/update `.workflows/.state/research-analysis.md`:
 
 ```markdown
 ---

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

@@ -8,9 +8,9 @@
 
 set -eo pipefail
 
-RESEARCH_DIR="docs/workflow/research"
-DISCUSSION_DIR="docs/workflow/discussion"
-CACHE_FILE="docs/workflow/.state/research-analysis.md"
+RESEARCH_DIR=".workflows/research"
+DISCUSSION_DIR=".workflows/discussion"
+CACHE_FILE=".workflows/.state/research-analysis.md"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>

package/skills/start-feature/SKILL.md

@@ -2,7 +2,7 @@
 name: start-feature
 description: "Start a new feature through the full pipeline. Gathers context via structured interview, creates a discussion, then bridges to continue-feature for specification, planning, and implementation."
 disable-model-invocation: true
-allowed-tools: Bash(ls docs/workflow/discussion/), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(ls .workflows/discussion/), Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
   PreToolUse:
     - hooks:
@@ -45,7 +45,7 @@ Invoke the `/migrate` skill and assess its output.
 Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:
 
 1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
-2. **Identify the topic.** Check conversation history for the topic name. If unknown, check `docs/workflow/discussion/` for recently modified files via `git log --oneline -5`.
+2. **Identify the topic.** Check conversation history for the topic name. If unknown, check `.workflows/discussion/` for recently modified files via `git log --oneline -5`.
 3. **Determine current step from artifacts:**
    - No discussion file exists → resume at **Step 1**
    - Discussion exists with `status: in-progress` → resume at **Step 3** (re-invoke technical-discussion)
@@ -73,7 +73,7 @@ Based on the feature description, suggest a topic name:
 ```
 Suggested topic name: {suggested-topic:(kebabcase)}
 
-This will create: docs/workflow/discussion/{suggested-topic}.md
+This will create: .workflows/discussion/{suggested-topic}.md
 ```
 
 > *Output the next fenced block as markdown (not a code block):*
@@ -92,7 +92,7 @@ Is this name okay?
 Once the topic name is confirmed, check for naming conflicts:
 
 ```bash
-ls docs/workflow/discussion/
+ls .workflows/discussion/
 ```
 
 If a discussion with the same name exists, inform the user:
@@ -130,7 +130,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-discussion/SKILL.md" \
-  "docs/workflow/discussion/{topic}.md" \
+  ".workflows/discussion/{topic}.md" \
   --pipeline "This session is part of the feature pipeline. After the discussion concludes, load and follow the phase bridge at skills/start-feature/references/phase-bridge.md for topic '{topic}'."
 ```
 

package/skills/start-feature/references/phase-bridge.md

@@ -26,7 +26,7 @@ continue the feature pipeline from specification onwards.
 - Topic: {topic}
 - Completed phase: discussion
 - Expected next phase: specification
-- Discussion: docs/workflow/discussion/{topic}.md
+- Discussion: .workflows/discussion/{topic}.md
 
 ## How to proceed
 

package/skills/start-implementation/SKILL.md

@@ -119,7 +119,7 @@ No plans exist yet.
 ```
 Implementation Overview
 
-No plans found in docs/workflow/planning/
+No plans found in .workflows/planning/
 
 The implementation phase requires a plan.
 Run /start-planning first to create a plan from a specification.
@@ -369,7 +369,7 @@ Environment: No special setup required.
 > *Output the next fenced block as a code block:*
 
 ```
-Environment setup file found: docs/workflow/environment-setup.md
+Environment setup file found: .workflows/environment-setup.md
 ```
 → Proceed to **Step 6**.
 
@@ -384,8 +384,8 @@ Are there any environment setup instructions I should follow before implementati
 
 **STOP.** Wait for user response.
 
-- If the user provides instructions, save them to `docs/workflow/environment-setup.md`, commit and push
-- If the user says no/none, create `docs/workflow/environment-setup.md` with "No special setup required." and commit
+- If the user provides instructions, save them to `.workflows/environment-setup.md`, commit and push
+- If the user says no/none, create `.workflows/environment-setup.md` with "No special setup required." and commit
 
 → Proceed to **Step 6**.
 
@@ -405,7 +405,7 @@ Saving session state so Claude can pick up where it left off if the conversation
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-implementation/SKILL.md" \
-  "docs/workflow/implementation/{topic}/tracking.md"
+  ".workflows/implementation/{topic}/tracking.md"
 ```
 
 After completing the steps above, this skill's purpose is fulfilled.
@@ -415,7 +415,7 @@ Invoke the [technical-implementation](../technical-implementation/SKILL.md) skil
 **Example handoff:**
 ```
 Implementation session for: {topic}
-Plan: docs/workflow/planning/{topic}/plan.md
+Plan: .workflows/planning/{topic}/plan.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})

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

@@ -7,10 +7,10 @@
 
 set -eo pipefail
 
-PLAN_DIR="docs/workflow/planning"
-SPEC_DIR="docs/workflow/specification"
-IMPL_DIR="docs/workflow/implementation"
-ENVIRONMENT_FILE="docs/workflow/environment-setup.md"
+PLAN_DIR=".workflows/planning"
+SPEC_DIR=".workflows/specification"
+IMPL_DIR=".workflows/implementation"
+ENVIRONMENT_FILE=".workflows/environment-setup.md"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>

package/skills/start-planning/SKILL.md

@@ -74,11 +74,13 @@ Parse the discovery output to understand:
 
 **From `specifications` section:**
 - `exists` - whether any specifications exist
-- `feature` - list of feature specs (name, status, has_plan, plan_status)
+- `feature` - list of feature specs (name, status, has_plan, plan_status, has_impl, impl_status)
 - `crosscutting` - list of cross-cutting specs (name, status)
 - `counts.feature` - total feature specifications
 - `counts.feature_ready` - feature specs ready for planning (concluded + no plan)
 - `counts.feature_with_plan` - feature specs that already have plans
+- `counts.feature_actionable_with_plan` - specs with plans that are NOT fully implemented
+- `counts.feature_implemented` - specs with `impl_status: completed`
 - `counts.crosscutting` - total cross-cutting specifications
 
 **From `plans` section:**
@@ -108,7 +110,7 @@ No specifications exist yet.
 ```
 Planning Overview
 
-No specifications found in docs/workflow/specification/
+No specifications found in .workflows/specification/
 
 The planning phase requires a concluded specification.
 Run /start-specification first.
@@ -195,7 +197,7 @@ Saving session state so Claude can pick up where it left off if the conversation
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-planning/SKILL.md" \
-  "docs/workflow/planning/{topic}/plan.md"
+  ".workflows/planning/{topic}/plan.md"
 ```
 
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-planning/references/display-state.md

@@ -6,6 +6,15 @@
 
 Present everything discovered to help the user make an informed choice.
 
+**Actionable vs. non-actionable:**
+
+A specification is **actionable** for planning if:
+- It is a feature spec (not cross-cutting)
+- Its status is `concluded`
+- It does NOT have `impl_status: completed` (already fully implemented)
+
+Specs with `impl_status: completed` have finished the full workflow and should not be offered for planning work.
+
 **Present the full state:**
 
 > *Output the next fenced block as a code block:*
@@ -18,16 +27,31 @@ Planning Overview
 1. {topic:(titlecase)}
    └─ Plan: @if(has_plan) {plan_status:[in-progress|concluded]} @else (no plan) @endif
    └─ Spec: concluded
+   @if(has_impl && impl_status != completed) └─ Impl: {impl_status} @endif
 
 2. ...
 ```
 
 **Tree rules:**
 
-Each numbered item shows a feature specification that is actionable:
+Each numbered item shows a feature specification that is **actionable** (not fully implemented):
 - Concluded spec with no plan → `Plan: (no plan)`
 - Has a plan with `plan_status: planning` → `Plan: in-progress`
 - Has a plan with `plan_status: concluded` → `Plan: concluded`
+- Has implementation tracking (but not completed) → show `Impl: {impl_status}`
+
+Do NOT include specs with `impl_status: completed` in the numbered list — they go in the "Completed specifications" section.
+
+**If completed specifications exist** (impl_status: completed), show them in a separate code block:
+
+> *Output the next fenced block as a code block:*
+
+```
+Completed specifications:
+These specifications have been fully implemented.
+
+  • {topic} (implementation completed)
+```
 
 **If non-plannable specifications exist**, show them in a separate code block:
 
@@ -52,6 +76,10 @@ Key:
     in-progress — planning work is ongoing
     concluded   — plan is complete
 
+  Impl status:
+    in-progress — implementation work is ongoing
+    completed   — implementation is finished
+
   Spec type:
     cross-cutting — architectural policy, not directly plannable
     feature       — plannable feature specification
@@ -68,6 +96,8 @@ The verb in the menu depends on the plan state:
 - Plan is `in-progress` → **Continue**
 - Plan is `concluded` → **Review**
 
+Do NOT include specs with `impl_status: completed` in the menu.
+
 > *Output the next fenced block as markdown (not a code block):*
 
 ```

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}/specification.md
+Specification: .workflows/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}/specification.md
-Existing plan: docs/workflow/planning/{topic}/plan.md
+Specification: .workflows/specification/{topic}/specification.md
+Existing plan: .workflows/planning/{topic}/plan.md
 
 Invoke the technical-planning skill.
 ```

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

@@ -8,8 +8,9 @@
 
 set -eo pipefail
 
-SPEC_DIR="docs/workflow/specification"
-PLAN_DIR="docs/workflow/planning"
+SPEC_DIR=".workflows/specification"
+PLAN_DIR=".workflows/planning"
+IMPL_DIR=".workflows/implementation"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>
@@ -41,6 +42,8 @@ echo "specifications:"
 feature_count=0
 feature_ready_count=0
 feature_with_plan_count=0
+feature_actionable_with_plan_count=0
+feature_implemented_count=0
 crosscutting_count=0
 
 if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
@@ -69,12 +72,25 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
             plan_status=${plan_status:-"unknown"}
         fi
 
+        # Check if implementation tracking exists and its status
+        has_impl="false"
+        impl_status=""
+        if [ -f "$IMPL_DIR/${name}/tracking.md" ]; then
+            has_impl="true"
+            impl_status=$(extract_field "$IMPL_DIR/${name}/tracking.md" "status")
+            impl_status=${impl_status:-"unknown"}
+        fi
+
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
         echo "      has_plan: $has_plan"
         if [ "$has_plan" = "true" ]; then
             echo "      plan_status: \"$plan_status\""
         fi
+        echo "      has_impl: $has_impl"
+        if [ "$has_impl" = "true" ]; then
+            echo "      impl_status: \"$impl_status\""
+        fi
 
         feature_count=$((feature_count + 1))
         # "concluded" specs without plans are ready for planning
@@ -83,6 +99,14 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         fi
         if [ "$has_plan" = "true" ]; then
             feature_with_plan_count=$((feature_with_plan_count + 1))
+            # Track specs with plans that are still actionable (not fully implemented)
+            if [ "$impl_status" != "completed" ]; then
+                feature_actionable_with_plan_count=$((feature_actionable_with_plan_count + 1))
+            fi
+        fi
+        # Track fully implemented specs
+        if [ "$impl_status" = "completed" ]; then
+            feature_implemented_count=$((feature_implemented_count + 1))
         fi
     done
 
@@ -120,6 +144,8 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
     echo "    feature: $feature_count"
     echo "    feature_ready: $feature_ready_count"
     echo "    feature_with_plan: $feature_with_plan_count"
+    echo "    feature_actionable_with_plan: $feature_actionable_with_plan_count"
+    echo "    feature_implemented: $feature_implemented_count"
     echo "    crosscutting: $crosscutting_count"
 else
     echo "  exists: false"
@@ -129,6 +155,8 @@ else
     echo "    feature: 0"
     echo "    feature_ready: 0"
     echo "    feature_with_plan: 0"
+    echo "    feature_actionable_with_plan: 0"
+    echo "    feature_implemented: 0"
     echo "    crosscutting: 0"
 fi
 
@@ -206,9 +234,10 @@ echo "  has_specifications: $specs_exist"
 echo "  has_plans: $plans_exist"
 
 # Determine workflow state for routing
+# Actionable = ready for new plan OR has plan that's not fully implemented
 if [ "$specs_exist" = "false" ]; then
     echo "  scenario: \"no_specs\""
-elif [ "$feature_ready_count" -eq 0 ] && [ "$feature_with_plan_count" -eq 0 ]; then
+elif [ "$feature_ready_count" -eq 0 ] && [ "$feature_actionable_with_plan_count" -eq 0 ]; then
     echo "  scenario: \"nothing_actionable\""
 else
     echo "  scenario: \"has_options\""

package/skills/start-research/SKILL.md

@@ -78,7 +78,7 @@ Saving session state so Claude can pick up where it left off if the conversation
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-research/SKILL.md" \
-  "docs/workflow/research/{topic}.md"
+  ".workflows/research/{topic}.md"
 ```
 
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

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

@@ -11,7 +11,7 @@ Invoke the [technical-research](../../technical-research/SKILL.md) skill for you
 **Example handoff:**
 ```
 Research session for: {topic}
-Output: docs/workflow/research/exploration.md
+Output: .workflows/research/exploration.md
 
 Context:
 - Prompted by: {problem, opportunity, or curiosity}

package/skills/start-review/SKILL.md

@@ -107,7 +107,7 @@ No plans exist yet.
 ```
 Review Overview
 
-No plans found in docs/workflow/planning/
+No plans found in .workflows/planning/
 
 The review phase requires a completed implementation based on a plan.
 Run /start-planning first to create a plan, then /start-implementation

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

@@ -18,7 +18,7 @@ Saving session state so Claude can pick up where it left off if the conversation
 .claude/hooks/workflows/write-session-state.sh \
   "{topic}" \
   "skills/technical-review/SKILL.md" \
-  "docs/workflow/review/{scope}/r{N}/review.md"
+  ".workflows/review/{scope}/r{N}/review.md"
 ```
 
 ---
@@ -34,13 +34,13 @@ Each plan is reviewed independently. When multiple plans are selected, pass all
 Review session
 Plans to review:
   - topic: {topic-1}
-    plan: docs/workflow/planning/{topic-1}/plan.md
+    plan: .workflows/planning/{topic-1}/plan.md
     format: {format}
     plan_id: {plan_id} (if applicable)
     specification: {specification} (exists: {true|false})
     review_version: r{N}
   - topic: {topic-2}
-    plan: docs/workflow/planning/{topic-2}/plan.md
+    plan: .workflows/planning/{topic-2}/plan.md
     format: {format}
     specification: {specification} (exists: {true|false})
     review_version: r{N}
@@ -52,7 +52,7 @@ Invoke the technical-review skill.
 ```
 Analysis session for: {topic}
 Review mode: analysis-only
-Review path: docs/workflow/review/{topic}/r{N}/
+Review path: .workflows/review/{topic}/r{N}/
 Format: {format}
 Specification: {spec path}
 

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

@@ -7,10 +7,10 @@
 
 set -eo pipefail
 
-PLAN_DIR="docs/workflow/planning"
-SPEC_DIR="docs/workflow/specification"
-REVIEW_DIR="docs/workflow/review"
-IMPL_DIR="docs/workflow/implementation"
+PLAN_DIR=".workflows/planning"
+SPEC_DIR=".workflows/specification"
+REVIEW_DIR=".workflows/review"
+IMPL_DIR=".workflows/implementation"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>
@@ -78,7 +78,7 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         fi
 
         # Check implementation status
-        impl_tracking="docs/workflow/implementation/${name}/tracking.md"
+        impl_tracking=".workflows/implementation/${name}/tracking.md"
         impl_status="none"
         if [ -f "$impl_tracking" ]; then
             impl_status_val=$(extract_field "$impl_tracking" "status")

package/skills/start-specification/SKILL.md

@@ -2,7 +2,7 @@
 name: start-specification
 description: "Start a specification session from concluded discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.state), Bash(rm docs/workflow/.state/discussion-consolidation-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/discussion-consolidation-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
   PreToolUse:
     - hooks:

package/skills/start-specification/references/analysis-flow.md

@@ -65,10 +65,10 @@ When forming groupings:
 
 Create the cache directory if needed:
 ```bash
-mkdir -p docs/workflow/.state
+mkdir -p .workflows/.state
 ```
 
-Write to `docs/workflow/.state/discussion-consolidation-analysis.md`:
+Write to `.workflows/.state/discussion-consolidation-analysis.md`:
 
 ```markdown
 ---