@leeovery/claude-technical-workflows 2.0.51 → 2.0.52

package/commands/link-dependencies.md

@@ -65,13 +65,13 @@ Stop here.
 
 ## Step 3: Extract External Dependencies
 
-For each plan, find the External Dependencies section:
+For each plan, read the `external_dependencies` field from the frontmatter:
 
-1. **Read the External Dependencies section** from each plan index file
-2. **Categorize each dependency**:
-   - **Unresolved**: `- {topic}: {description}` (no arrow, no task ID)
-   - **Resolved**: `- {topic}: {description} → {task-id}` (has task ID)
-   - **Satisfied externally**: `- ~~{topic}: {description}~~ → satisfied externally`
+1. **Read `external_dependencies`** from each plan index file's frontmatter
+2. **Categorize each dependency** by its `state` field:
+   - **Unresolved**: `state: unresolved` (no task linked)
+   - **Resolved**: `state: resolved` (has `task_id`)
+   - **Satisfied externally**: `state: satisfied_externally`
 
 3. **Build a summary**:
 
@@ -84,7 +84,7 @@ Plan: authentication (format: {format})
 
 Plan: billing-system (format: {format})
   - authentication: User context (unresolved)
-  - ~~payment-gateway: Payment processing~~ → satisfied externally
+  - payment-gateway: Payment processing (satisfied externally)
 
 Plan: notifications (format: {format})
   - authentication: User lookup (unresolved)
@@ -111,8 +111,8 @@ For each unresolved dependency:
 
 For each resolved match:
 
-1. **Update the plan index file**:
-   - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
+1. **Update the plan index file's frontmatter**:
+   - Change the dependency's `state: unresolved` to `state: resolved` and add `task_id: {task-id}`
 
 2. **Create dependency in output format**:
    - Load `skills/technical-planning/references/output-formats/output-{format}.md`
@@ -123,7 +123,7 @@ For each resolved match:
 For each plan that was a dependency target (i.e., other plans depend on it):
 
 1. **Check reverse dependencies**: Are there other plans that should have this wired up?
-2. **Offer to update**: "Plan X depends on tasks you just linked. Update its External Dependencies section?"
+2. **Offer to update**: "Plan X depends on tasks you just linked. Update its `external_dependencies` frontmatter?"
 
 ## Step 7: Report Results
 

package/commands/workflow/start-implementation.md

@@ -61,14 +61,30 @@ 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, plan_id (if present)
+- Per plan `external_deps` - array of dependencies with topic, state, task_id
+- Per plan `has_unresolved_deps` - whether plan has unresolved dependencies
+- Per plan `unresolved_dep_count` - count of unresolved dependencies
 - `count` - total number of plans
 
+**From `implementation` section:**
+- `exists` - whether any implementation tracking files exist
+- `files` - list of tracking files with: topic, status, current_phase, completed_phases, completed_tasks
+
+**From `dependency_resolution` section:**
+- Per plan `deps_satisfied` - whether all resolved deps have their tasks completed
+- Per plan `deps_blocking` - list of deps not yet satisfied with reason
+
 **From `environment` section:**
 - `setup_file_exists` - whether environment-setup.md exists
 - `requires_setup` - true, false, or unknown
 
 **From `state` section:**
 - `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+- `plans_concluded_count` - plans with status concluded
+- `plans_with_unresolved_deps` - plans with unresolved external deps
+- `plans_ready_count` - concluded plans with all deps satisfied
+- `plans_in_progress_count` - implementations in progress
+- `plans_completed_count` - implementations completed
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -102,66 +118,137 @@ Plans exist.
 
 ## Step 3: Present Plans and Select
 
-Present all discovered plans to help the user make an informed choice.
+Present all discovered plans using the icon system below. Classify each plan into one of three sections based on its state.
+
+**Classification logic:**
+
+A plan is **Implementable** if:
+- It has `status: concluded` AND all deps are satisfied (`deps_satisfied: true` or no deps) AND no tracking file or tracking `status: not-started`, OR
+- It has an implementation tracking file with `status: in-progress`
+
+A plan is **Implemented** if:
+- It has an implementation tracking file with `status: completed`
+
+A plan is **Not implementable** if:
+- It has `status: concluded` but deps are NOT satisfied (blocking deps exist)
+- It has `status: planning` or other non-concluded status
+- It has unresolved deps (`has_unresolved_deps: true`)
 
 **Present the full state:**
 
 ```
-Available Plans:
+Implementation Phase
+
+Implementable:
+  1. ▶ billing - continue [Phase 2, Task 3]
+  2. + core-features - start
 
-  1. {topic-1} (in-progress) - format: {format}
-  2. {topic-2} (concluded) - format: {format}
-  3. {topic-3} (in-progress) - format: {format}
+Implemented:
+  3. > user-auth
 
-Which plan would you like to implement? (Enter a number or name)
+Not implementable:
+  · advanced-features [blocked: core-features task core-2-3 not completed]
+  · reporting [planning]
 ```
 
-**Legend:**
-- `in-progress` = implementation ongoing or not started
-- `concluded` = implementation complete (can still be selected for review/continuation)
+**Formatting rules:**
+
+Implementable (numbered, selectable):
+- **`▶`** — implementation `status: in-progress`, show current position `[Phase N, Task M]`
+- **`+`** — concluded plan, deps met, no tracking file or tracking `status: not-started`
+
+Implemented (numbered, selectable):
+- **`>`** — implementation `status: completed`
+
+Not implementable (not numbered, not selectable):
+- **`·`** — blocked or plan not concluded
+- `[blocked: {topic} task {id} not completed]` — resolved dep, task not done
+- `[blocked: unresolved dep on {topic}]` — no task linked
+- `[planning]` — plan status is not `concluded`
+
+**Ordering:**
+1. Implementable first: `▶` in-progress, then `+` new (foundational before dependent)
+2. Implemented next: `>` completed
+3. Not implementable last
+
+Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
+
+**If Not implementable section is shown**, append after the presentation:
 
-**If single plan exists (auto-select):**
 ```
-Auto-selecting: {topic} (only available plan)
+If a blocked dependency has been resolved outside this workflow, name the plan and the dependency to unblock it.
+```
+
+**Then prompt based on what's actionable:**
+
+**If single implementable plan and no implemented plans (auto-select):**
+```
+Auto-selecting: {topic} (only implementable plan)
 ```
 → Proceed directly to **Step 4**.
 
-**If multiple plans exist:**
+**If nothing selectable (no implementable or implemented):**
+Show Not implementable section only (with unblock hint above).
+
+```
+No implementable plans.
+
+To proceed:
+- Complete blocking dependencies first
+- Or finish plans still in progress with /start-planning
+```
 
 **STOP.** Wait for user response.
 
+**Otherwise (multiple selectable plans, or implemented plans exist):**
+```
+Select a plan (enter number):
+```
+
+**STOP.** Wait for user response.
+
+#### If the user requests an unblock
+
+1. Identify the plan and the specific dependency
+2. Confirm with the user which dependency to mark as satisfied
+3. Update the plan's `external_dependencies` frontmatter: set `state` to `satisfied_externally`
+4. Commit the change
+5. Re-run classification and re-present Step 3
+
 → Based on user choice, proceed to **Step 4**.
 
 ---
 
 ## Step 4: Check External Dependencies
 
-**This step is a gate.** Implementation cannot proceed if dependencies are not satisfied.
-
-See **[dependencies.md](../../skills/technical-planning/references/dependencies.md)** for dependency format and states.
+**This step is a confirmation gate.** Dependencies have been pre-analyzed by the discovery script.
 
 After the plan is selected:
 
-1. **Read the External Dependencies section** from the plan file
-2. **Check each dependency** according to its state:
-   - **Unresolved**: Block
-   - **Resolved**: Check if task is complete (load output format reference, follow "Querying Dependencies" section)
-   - **Satisfied externally**: Proceed
+1. **Check the plan's `external_deps` and `dependency_resolution`** from the discovery output
+
+#### If all deps satisfied (or no deps)
+
+```
+External dependencies satisfied.
+```
+
+→ Proceed to **Step 5**.
 
-### Blocking Behavior
+#### If any deps are blocking
 
-If ANY dependency is unresolved or incomplete, **stop and present**:
+This should not normally happen for plans classified as "Implementable" in Step 3. However, as an escape hatch:
 
 ```
-⚠️ Implementation blocked. Missing dependencies:
+Missing dependencies:
 
 UNRESOLVED (not yet planned):
-- billing-system: Invoice generation for order completion
-  → No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
+- {topic}: {description}
+  -> No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
 
 INCOMPLETE (planned but not implemented):
-- authentication: User context retrieval
-  → Status: in-progress. This task must be completed first.
+- {topic}: task {task_id} not yet completed
+  -> This task must be completed first.
 
 OPTIONS:
 1. Implement the blocking dependencies first
@@ -171,23 +258,15 @@ OPTIONS:
 
 **STOP.** Wait for user response.
 
-### Escape Hatch
+#### Escape Hatch
 
 If the user says a dependency has been implemented outside the workflow:
 
 1. Ask which dependency to mark as satisfied
-2. Update the plan file: Change `- {topic}: {description}` to `- ~~{topic}: {description}~~ → satisfied externally`
+2. Update the plan frontmatter: Change the dependency's `state` to `satisfied_externally`
 3. Commit the change
 4. Re-check dependencies
 
-### All Dependencies Satisfied
-
-If all dependencies are resolved and complete (or satisfied externally), proceed to Step 5.
-
-```
-✅ External dependencies satisfied.
-```
-
 → Proceed to **Step 5**.
 
 ---
@@ -227,32 +306,7 @@ Are there any environment setup instructions I should follow before implementati
 
 ---
 
-## Step 6: Ask About Scope
-
-Ask the user about implementation scope:
-
-```
-How would you like to proceed?
-
-1. Implement all phases - Work through the entire plan sequentially
-2. Implement specific phase - Focus on one phase (e.g., "Phase 1")
-3. Implement specific task - Focus on a single task
-4. Next available task - Auto-discover the next incomplete task
-
-Which approach?
-```
-
-**STOP.** Wait for user response.
-
-If they choose a specific phase or task, ask them to specify which one.
-
-> **Note:** Do NOT verify that the phase or task exists at this stage. Record the user's answer in the handoff context. Validation happens when the skill is invoked.
-
-→ Proceed to **Step 7**.
-
----
-
-## Step 7: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -265,9 +319,9 @@ 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}
+Implementation tracking: {exists | new} (status: {in-progress | not-started | completed})
 
-Dependencies: {All satisfied ✓ | List any notes}
+Dependencies: {All satisfied | List any notes}
 Environment: {Setup required | No special setup required}
 
 Invoke the technical-implementation skill.

package/package.json

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

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

@@ -9,6 +9,7 @@ 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"
 
 # Helper: Extract a frontmatter field value from a file
@@ -28,6 +29,117 @@ extract_field() {
     echo "$value"
 }
 
+# Helper: Extract frontmatter content (between first pair of --- delimiters)
+extract_frontmatter() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Extract external_dependencies from plan frontmatter
+# Outputs individual dep entries as: topic|description|state|task_id
+extract_external_deps() {
+    local file="$1"
+    local frontmatter
+    frontmatter=$(extract_frontmatter "$file")
+
+    # Check if external_dependencies exists and is not empty array
+    if ! echo "$frontmatter" | grep -q "^external_dependencies:" 2>/dev/null; then
+        return 0
+    fi
+
+    # Check for empty array format
+    if echo "$frontmatter" | grep -q "^external_dependencies:[[:space:]]*\[\]" 2>/dev/null; then
+        return 0
+    fi
+
+    # Extract the external_dependencies block
+    echo "$frontmatter" | awk '
+/^external_dependencies:/ { in_block=1; next }
+in_block && /^[a-z_]+:/ && !/^[[:space:]]/ { exit }
+in_block && /^[[:space:]]*- topic:/ {
+    # Print previous entry if we have one
+    if (topic != "" && state != "") {
+        print topic "|" desc "|" state "|" task_id
+    }
+    # Start new entry
+    line=$0; gsub(/^[[:space:]]*- topic:[[:space:]]*/, "", line)
+    topic=line; desc=""; state=""; task_id=""
+    next
+}
+in_block && /^[[:space:]]*description:/ {
+    line=$0; gsub(/^[[:space:]]*description:[[:space:]]*/, "", line)
+    desc=line; next
+}
+in_block && /^[[:space:]]*state:/ {
+    line=$0; gsub(/^[[:space:]]*state:[[:space:]]*/, "", line)
+    state=line; next
+}
+in_block && /^[[:space:]]*task_id:/ {
+    line=$0; gsub(/^[[:space:]]*task_id:[[:space:]]*/, "", line)
+    task_id=line; next
+}
+END {
+    if (topic != "" && state != "") {
+        print topic "|" desc "|" state "|" task_id
+    }
+}
+'
+}
+
+# Helper: Extract completed_tasks from implementation tracking file
+# Returns space-separated list of task IDs
+extract_completed_tasks() {
+    local file="$1"
+    local frontmatter
+    frontmatter=$(extract_frontmatter "$file")
+
+    # Check for empty array
+    if echo "$frontmatter" | grep -q "^completed_tasks:[[:space:]]*\[\]" 2>/dev/null; then
+        return 0
+    fi
+
+    echo "$frontmatter" | awk '
+/^completed_tasks:/ { in_block=1; next }
+in_block && /^[a-z_]+:/ { exit }
+in_block && /^[[:space:]]*-[[:space:]]/ {
+    gsub(/^[[:space:]]*-[[:space:]]*/, "")
+    gsub(/"/, "")
+    print
+}
+'
+}
+
+# Helper: Extract completed_phases from implementation tracking file
+# Returns space-separated list of phase numbers
+extract_completed_phases() {
+    local file="$1"
+    local frontmatter
+    frontmatter=$(extract_frontmatter "$file")
+
+    # Check for inline array format: [1, 2, 3]
+    local inline
+    inline=$(echo "$frontmatter" | grep "^completed_phases:" | sed 's/^completed_phases:[[:space:]]*//' || true)
+    if echo "$inline" | grep -q '^\['; then
+        echo "$inline" | tr -d '[]' | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | grep -v '^$'
+        return 0
+    fi
+
+    # Check for empty array
+    if echo "$frontmatter" | grep -q "^completed_phases:[[:space:]]*\[\]" 2>/dev/null; then
+        return 0
+    fi
+
+    echo "$frontmatter" | awk '
+/^completed_phases:/ { in_block=1; next }
+in_block && /^[a-z_]+:/ { exit }
+in_block && /^[[:space:]]*-[[:space:]]/ {
+    gsub(/^[[:space:]]*-[[:space:]]*/, "")
+    print
+}
+'
+}
+
+
 # Start YAML output
 echo "# Implementation Command State Discovery"
 echo "# Generated: $(date -Iseconds)"
@@ -39,6 +151,12 @@ echo ""
 echo "plans:"
 
 plan_count=0
+plans_concluded_count=0
+plans_with_unresolved_deps=0
+
+# Arrays to store plan data for cross-referencing
+declare -a plan_names=()
+declare -a plan_statuses=()
 
 if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
     echo "  exists: true"
@@ -60,6 +178,14 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         specification=${specification:-"${name}.md"}
         plan_id=$(extract_field "$file" "plan_id")
 
+        # Track plan data
+        plan_names+=("$name")
+        plan_statuses+=("$status")
+
+        if [ "$status" = "concluded" ]; then
+            plans_concluded_count=$((plans_concluded_count + 1))
+        fi
+
         # Check if linked specification exists
         spec_exists="false"
         spec_file="$SPEC_DIR/$specification"
@@ -78,6 +204,39 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
             echo "      plan_id: \"$plan_id\""
         fi
 
+        #
+        # External dependencies from frontmatter
+        #
+        deps_output=$(extract_external_deps "$file")
+        has_unresolved="false"
+        unresolved_count=0
+        dep_count=0
+
+        echo "      external_deps:"
+        if [ -z "$deps_output" ]; then
+            echo "        []"
+        else
+            while IFS='|' read -r dep_topic dep_desc dep_state dep_task_id; do
+                [ -z "$dep_topic" ] && continue
+                dep_count=$((dep_count + 1))
+                echo "        - topic: \"$dep_topic\""
+                echo "          state: \"$dep_state\""
+                if [ -n "$dep_task_id" ]; then
+                    echo "          task_id: \"$dep_task_id\""
+                fi
+                if [ "$dep_state" = "unresolved" ]; then
+                    has_unresolved="true"
+                    unresolved_count=$((unresolved_count + 1))
+                fi
+            done <<< "$deps_output"
+        fi
+        echo "      has_unresolved_deps: $has_unresolved"
+        echo "      unresolved_dep_count: $unresolved_count"
+
+        if [ "$has_unresolved" = "true" ]; then
+            plans_with_unresolved_deps=$((plans_with_unresolved_deps + 1))
+        fi
+
         plan_count=$((plan_count + 1))
     done
 
@@ -90,6 +249,145 @@ fi
 
 echo ""
 
+#
+# IMPLEMENTATION TRACKING
+#
+echo "implementation:"
+
+impl_count=0
+plans_in_progress_count=0
+plans_completed_count=0
+
+if [ -d "$IMPL_DIR" ] && [ -n "$(ls -A "$IMPL_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+
+    for file in "$IMPL_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        impl_name=$(basename "$file" .md)
+        impl_status=$(extract_field "$file" "status")
+        impl_status=${impl_status:-"unknown"}
+        current_phase=$(extract_field "$file" "current_phase")
+        current_task=$(extract_field "$file" "current_task")
+
+        echo "    - topic: \"$impl_name\""
+        echo "      status: \"$impl_status\""
+
+        if [ -n "$current_phase" ] && [ "$current_phase" != "~" ]; then
+            echo "      current_phase: $current_phase"
+        fi
+
+        # Completed phases
+        completed_phases_list=$(extract_completed_phases "$file")
+        if [ -n "$completed_phases_list" ]; then
+            phases_inline=$(echo "$completed_phases_list" | tr '\n' ',' | sed 's/,$//' | sed 's/,/, /g')
+            echo "      completed_phases: [$phases_inline]"
+        else
+            echo "      completed_phases: []"
+        fi
+
+        # Completed tasks
+        completed_tasks_list=$(extract_completed_tasks "$file")
+        if [ -n "$completed_tasks_list" ]; then
+            echo "      completed_tasks:"
+            while IFS= read -r task_id; do
+                [ -z "$task_id" ] && continue
+                echo "        - \"$task_id\""
+            done <<< "$completed_tasks_list"
+        else
+            echo "      completed_tasks: []"
+        fi
+
+        # Track counts
+        if [ "$impl_status" = "in-progress" ]; then
+            plans_in_progress_count=$((plans_in_progress_count + 1))
+        elif [ "$impl_status" = "completed" ]; then
+            plans_completed_count=$((plans_completed_count + 1))
+        fi
+
+        impl_count=$((impl_count + 1))
+    done
+else
+    echo "  exists: false"
+    echo "  files: []"
+fi
+
+echo ""
+
+#
+# DEPENDENCY RESOLUTION (cross-reference resolved deps against tracking files)
+#
+# For each plan with resolved deps, check if the referenced tasks are actually completed
+# by reading the dependency topic's tracking file
+#
+echo "dependency_resolution:"
+
+if [ "$plan_count" -gt 0 ] && [ -d "$PLAN_DIR" ]; then
+    has_resolution_data=false
+
+    for file in "$PLAN_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        deps_output=$(extract_external_deps "$file")
+        [ -z "$deps_output" ] && continue
+
+        all_satisfied=true
+        has_resolved_deps=false
+        blocking_entries=""
+
+        while IFS='|' read -r dep_topic dep_desc dep_state dep_task_id; do
+            [ -z "$dep_topic" ] && continue
+
+            if [ "$dep_state" = "resolved" ] && [ -n "$dep_task_id" ]; then
+                has_resolved_deps=true
+                # Check if the dependency topic has a tracking file
+                tracking_file="$IMPL_DIR/${dep_topic}.md"
+                task_completed=false
+
+                if [ -f "$tracking_file" ]; then
+                    # Check if task_id is in completed_tasks
+                    completed=$(extract_completed_tasks "$tracking_file")
+                    if echo "$completed" | grep -qx "$dep_task_id" 2>/dev/null; then
+                        task_completed=true
+                    fi
+                fi
+
+                if ! $task_completed; then
+                    all_satisfied=false
+                    blocking_entries="${blocking_entries}      - topic: \"$dep_topic\"\n        task_id: \"$dep_task_id\"\n        reason: \"task not yet completed\"\n"
+                fi
+            elif [ "$dep_state" = "unresolved" ]; then
+                has_resolved_deps=true
+                all_satisfied=false
+                blocking_entries="${blocking_entries}      - topic: \"$dep_topic\"\n        reason: \"dependency unresolved\"\n"
+            fi
+            # satisfied_externally deps don't block
+        done <<< "$deps_output"
+
+        if $has_resolved_deps || [ -n "$blocking_entries" ]; then
+            if ! $has_resolution_data; then
+                has_resolution_data=true
+            fi
+            echo "  - plan: \"$name\""
+            echo "    deps_satisfied: $all_satisfied"
+            if [ -n "$blocking_entries" ]; then
+                echo "    deps_blocking:"
+                echo -e "$blocking_entries" | sed '/^$/d'
+            fi
+        fi
+    done
+
+    if ! $has_resolution_data; then
+        echo "  []"
+    fi
+else
+    echo "  []"
+fi
+
+echo ""
+
 #
 # ENVIRONMENT
 #
@@ -120,6 +418,54 @@ echo "state:"
 
 echo "  has_plans: $([ "$plan_count" -gt 0 ] && echo "true" || echo "false")"
 echo "  plan_count: $plan_count"
+echo "  plans_concluded_count: $plans_concluded_count"
+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
+        [ -f "$file" ] || continue
+        name=$(basename "$file" .md)
+        status=$(extract_field "$file" "status")
+
+        if [ "$status" = "concluded" ]; then
+            deps_output=$(extract_external_deps "$file")
+            is_ready=true
+
+            if [ -n "$deps_output" ]; then
+                while IFS='|' read -r dep_topic dep_desc dep_state dep_task_id; do
+                    [ -z "$dep_topic" ] && continue
+
+                    if [ "$dep_state" = "unresolved" ]; then
+                        is_ready=false
+                        break
+                    elif [ "$dep_state" = "resolved" ] && [ -n "$dep_task_id" ]; then
+                        tracking_file="$IMPL_DIR/${dep_topic}.md"
+                        if [ -f "$tracking_file" ]; then
+                            completed=$(extract_completed_tasks "$tracking_file")
+                            if ! echo "$completed" | grep -qx "$dep_task_id" 2>/dev/null; then
+                                is_ready=false
+                                break
+                            fi
+                        else
+                            is_ready=false
+                            break
+                        fi
+                    fi
+                done <<< "$deps_output"
+            fi
+
+            if $is_ready; then
+                plans_ready_count=$((plans_ready_count + 1))
+            fi
+        fi
+    done
+fi
+
+echo "  plans_ready_count: $plans_ready_count"
+echo "  plans_in_progress_count: $plans_in_progress_count"
+echo "  plans_completed_count: $plans_completed_count"
 
 # Determine workflow state for routing
 if [ "$plan_count" -eq 0 ]; then

package/scripts/migrations/005-plan-external-deps-frontmatter.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+#
+# 005-plan-external-deps-frontmatter.sh
+#
+# Migrates external dependencies from body markdown section to plan frontmatter.
+#
+# Previous format (body section):
+#   ## External Dependencies
+#
+#   - billing-system: Invoice generation for order completion
+#   - user-authentication: User context for permissions → auth-1-3 (resolved)
+#   - ~~payment-gateway: Payment processing~~ → satisfied externally
+#
+# New format (frontmatter):
+#   external_dependencies:
+#     - topic: billing-system
+#       description: Invoice generation for order completion
+#       state: unresolved
+#     - topic: user-authentication
+#       description: User context for permissions
+#       state: resolved
+#       task_id: auth-1-3
+#     - topic: payment-gateway
+#       description: Payment processing
+#       state: satisfied_externally
+#
+# Body formats handled:
+#   - "- {topic}: {description}" → state: unresolved
+#   - "- {topic}: {description} → {task-id}" or with "(resolved)" → state: resolved, task_id
+#   - "- ~~{topic}: {description}~~ → satisfied externally" → state: satisfied_externally
+#
+# 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="005"
+PLAN_DIR="docs/workflow/planning"
+
+# Skip if no planning directory
+if [ ! -d "$PLAN_DIR" ]; then
+    return 0
+fi
+
+# Helper: Extract ONLY the frontmatter content (between first pair of --- delimiters)
+extract_frontmatter_005() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Extract content after frontmatter (preserving all body ---)
+extract_body_005() {
+    local file="$1"
+    awk '/^---$/ && c<2 {c++; next} c>=2 {print}' "$file"
+}
+
+# Helper: Extract the External Dependencies section from body content
+# Returns only the direct content (list items, "None." text) — stops at subsections (###) or next section (##)
+extract_ext_deps_section() {
+    local body="$1"
+    echo "$body" | awk '
+/^## External Dependencies/ { found=1; next }
+found && /^## [^#]/ { exit }
+found && /^### / { exit }
+found { print }
+'
+}
+
+# Helper: Parse a single dependency line into topic, description, state, task_id
+# Sets global variables: DEP_TOPIC, DEP_DESC, DEP_STATE, DEP_TASK_ID
+parse_dep_line() {
+    local line="$1"
+    DEP_TOPIC=""
+    DEP_DESC=""
+    DEP_STATE=""
+    DEP_TASK_ID=""
+
+    # Strip leading "- " or "  - "
+    line=$(echo "$line" | sed 's/^[[:space:]]*-[[:space:]]*//')
+
+    # Check for satisfied_externally: ~~{topic}: {description}~~ → satisfied externally
+    if echo "$line" | grep -q '^\~\~.*\~\~.*satisfied externally'; then
+        # Remove ~~ markers
+        local inner
+        inner=$(echo "$line" | sed 's/^\~\~//' | sed 's/\~\~.*//')
+        DEP_TOPIC=$(echo "$inner" | sed 's/:.*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        DEP_DESC=$(echo "$inner" | sed 's/^[^:]*:[[:space:]]*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        DEP_STATE="satisfied_externally"
+        return 0
+    fi
+
+    # Check for resolved: {topic}: {description} → {task-id} (with optional "(resolved)")
+    if echo "$line" | grep -qE '→|->'; then
+        local before_arrow after_arrow
+        # Split on → or ->
+        before_arrow=$(echo "$line" | sed -E 's/[[:space:]]*(→|->).*//')
+        after_arrow=$(echo "$line" | sed -E 's/.*[[:space:]]*(→|->)[[:space:]]*//')
+        # Remove "(resolved)" suffix if present
+        after_arrow=$(echo "$after_arrow" | sed 's/[[:space:]]*(resolved)[[:space:]]*$//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        DEP_TOPIC=$(echo "$before_arrow" | sed 's/:.*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        DEP_DESC=$(echo "$before_arrow" | sed 's/^[^:]*:[[:space:]]*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+        DEP_STATE="resolved"
+        DEP_TASK_ID="$after_arrow"
+        return 0
+    fi
+
+    # Unresolved: {topic}: {description}
+    DEP_TOPIC=$(echo "$line" | sed 's/:.*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    DEP_DESC=$(echo "$line" | sed 's/^[^:]*:[[:space:]]*//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    DEP_STATE="unresolved"
+    return 0
+}
+
+# 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 has YAML frontmatter
+    if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if external_dependencies already exists in frontmatter
+    frontmatter=$(extract_frontmatter_005 "$file")
+    if echo "$frontmatter" | grep -q "^external_dependencies:"; then
+        record_migration "$file" "$MIGRATION_ID"
+        report_skip "$file"
+        continue
+    fi
+
+    # Extract body and look for External Dependencies section
+    body=$(extract_body_005 "$file")
+    deps_section=$(extract_ext_deps_section "$body")
+
+    # Build the new frontmatter field
+    new_deps_block=""
+    has_deps=false
+
+    # Check if section exists and has content beyond "No external dependencies."
+    if [ -n "$deps_section" ]; then
+        # Get only lines that look like list items
+        dep_lines=$(echo "$deps_section" | grep -E '^[[:space:]]*-[[:space:]]' || true)
+
+        if [ -n "$dep_lines" ]; then
+            new_deps_block="external_dependencies:"
+            while IFS= read -r dep_line; do
+                [ -z "$dep_line" ] && continue
+                parse_dep_line "$dep_line"
+                if [ -n "$DEP_TOPIC" ]; then
+                    has_deps=true
+                    new_deps_block="${new_deps_block}
+  - topic: $DEP_TOPIC
+    description: $DEP_DESC
+    state: $DEP_STATE"
+                    if [ -n "$DEP_TASK_ID" ]; then
+                        new_deps_block="${new_deps_block}
+    task_id: $DEP_TASK_ID"
+                    fi
+                fi
+            done <<< "$dep_lines"
+        fi
+    fi
+
+    # If no deps found, use empty array
+    if ! $has_deps; then
+        new_deps_block="external_dependencies: []"
+    fi
+
+    # Remove the External Dependencies body section
+    # Only remove the h2 heading and its direct content (list items, "None."/"No external dependencies.")
+    # Preserve any subsections (### headings) that may follow within the section
+    new_body=$(echo "$body" | awk '
+/^## External Dependencies/ { skip=1; next }
+skip && /^## [^#]/ { skip=0 }
+skip && /^### / { skip=0 }
+skip { next }
+{ print }
+')
+
+    # Clean up: remove consecutive blank lines left from section removal (keep max 1)
+    new_body=$(echo "$new_body" | awk '
+/^$/ { blank++; if (blank <= 1) print; next }
+{ blank=0; print }
+')
+
+    # Remove existing external_dependencies from frontmatter if somehow partially there
+    new_frontmatter=$(echo "$frontmatter" | awk '
+/^external_dependencies:/ { skip=1; next }
+/^[a-z_]+:/ && skip { skip=0 }
+skip == 0 { print }
+')
+
+    # Insert external_dependencies before the planning: block (or at end if no planning:)
+    if echo "$new_frontmatter" | grep -q "^planning:"; then
+        # Split at planning: line, insert deps block before it
+        before_planning=$(echo "$new_frontmatter" | sed -n '/^planning:/q;p')
+        planning_block=$(echo "$new_frontmatter" | sed -n '/^planning:/,$ p')
+        final_frontmatter="${before_planning}
+${new_deps_block}
+${planning_block}"
+    else
+        final_frontmatter="${new_frontmatter}
+${new_deps_block}"
+    fi
+
+    # Write the updated file
+    {
+        echo "---"
+        echo "$final_frontmatter"
+        echo "---"
+        echo "$new_body"
+    } > "$file"
+
+    record_migration "$file" "$MIGRATION_ID"
+
+    if $has_deps; then
+        report_update "$file" "migrated external dependencies to frontmatter"
+    else
+        report_update "$file" "added empty external_dependencies to frontmatter"
+    fi
+done

package/skills/technical-discussion/SKILL.md

@@ -29,6 +29,21 @@ Either way: Capture decisions, rationale, competing approaches, and edge cases.
 - **Topic is broad or ambiguous?**
   > "You mentioned {topic}. To keep the discussion focused, is there a specific aspect or decision you want to work through first?"
 
+---
+
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## What to Capture
 
 - **Back-and-forth debates**: Challenging, prolonged discussions show how we decided X over Y

package/skills/technical-implementation/SKILL.md

@@ -23,7 +23,6 @@ Either way: Execute via strict TDD - tests first, implementation second.
 - **Plan format** (required) - How to parse tasks (from plan frontmatter)
 - **Specification content** (optional) - For context when task rationale is unclear
 - **Environment setup** (optional) - First-time setup instructions
-- **Scope** (optional) - Specific phase/task to work on
 
 **Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
@@ -38,6 +37,21 @@ Either way: Execute via strict TDD - tests first, implementation second.
 
 If no specification is available, the plan becomes the sole authority for design decisions.
 
+---
+
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Hard Rules
 
 **MANDATORY. No exceptions. Violating these rules invalidates the work.**
@@ -77,19 +91,90 @@ Complete ALL setup steps before proceeding to implementation work.
 
 3. **Read the TDD workflow** - Load **[tdd-workflow.md](references/tdd-workflow.md)** before writing any code. This is mandatory.
 
-4. **Validate scope** (if specific phase or task was requested)
-   - If the requested phase or task doesn't exist in the plan, STOP immediately
-   - Ask the user for clarification - don't assume or proceed with a different scope
-   - Wait for the user to either correct the scope or ask you to stop
+4. **Initialize or resume implementation tracking**
+   - Check if `docs/workflow/implementation/{topic}.md` exists
+   - **If not**: Create it with the initial tracking frontmatter (see [Implementation Tracking](#implementation-tracking) below), set `status: in-progress`, `started: {today}`. Commit: `impl({topic}): start implementation`
+   - **If exists**: Read it to determine current position (see [Resuming After Context Refresh](#resuming-after-context-refresh) below)
 
-5. **For each phase**:
+5. **For each phase** (working through phases and tasks in plan order):
    - Announce phase start and review acceptance criteria
    - For each task: follow the TDD cycle loaded in step 3
+   - After each task completes: update progress in **both** the output format (as loaded in step 2) **and** the implementation tracking file (see below)
    - Verify all phase acceptance criteria met
    - **Ask user before proceeding to next phase**
 
 6. **Reference specification** when rationale unclear
 
+## Implementation Tracking
+
+Each topic has a tracking file at `docs/workflow/implementation/{topic}.md` that records progress programmatically (frontmatter) and as a human-readable summary (body).
+
+### Initial Tracking File
+
+When starting implementation for a topic, create:
+
+```yaml
+---
+topic: {topic}
+plan: ../planning/{topic}.md
+format: {format from plan}
+status: in-progress
+current_phase: 1
+current_task: ~
+completed_phases: []
+completed_tasks: []
+started: YYYY-MM-DD
+updated: YYYY-MM-DD
+completed: ~
+---
+
+# Implementation: {Topic Name}
+
+Implementation started.
+```
+
+### Updating Progress
+
+When a task or phase completes, update **two** things:
+
+1. **Output format progress** — Follow the output adapter's Implementation section (loaded in workflow step 2) to mark tasks/phases complete in the plan index file and any format-specific files. This is the plan's own progress tracking.
+
+2. **Implementation tracking file** — Update `docs/workflow/implementation/{topic}.md` as described below. This enables cross-topic dependency resolution and resume detection.
+
+**After each task completes (tracking file):**
+- Append the task ID to `completed_tasks`
+- Update `current_task` to the next task (or `~` if phase done)
+- Update `updated` date
+- Update the body progress section
+
+**After each phase completes (tracking file):**
+- Append the phase number to `completed_phases`
+- Update `current_phase` to the next phase (or leave as last)
+- Update the body progress section
+
+**On implementation completion (tracking file):**
+- Set `status: completed`
+- Set `completed: {today}`
+- Commit: `impl({topic}): complete implementation`
+
+Task IDs in `completed_tasks` use whatever ID format the output format assigns -- the same IDs used in dependency references.
+
+### Body Progress Section
+
+The body provides a human-readable summary for context refresh:
+
+```markdown
+# Implementation: {Topic Name}
+
+## Phase 1: Foundation
+All tasks completed.
+
+## Phase 2: Core Logic (current)
+- Task 2.1: Service layer - done
+- Task 2.2: Validation - done
+- Task 2.3: Controllers (next)
+```
+
 ## Progress Announcements
 
 Keep user informed of progress:

package/skills/technical-planning/SKILL.md

@@ -35,6 +35,19 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 ---
 
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## The Process
 
 This process constructs a plan from a specification. A plan consists of:
@@ -133,6 +146,7 @@ cross_cutting_specs:              # Omit if none
 spec_commit: {output of git rev-parse HEAD}
 created: YYYY-MM-DD  # Use today's actual date
 updated: YYYY-MM-DD  # Use today's actual date
+external_dependencies: []
 planning:
   phase: 1
   task: ~

package/skills/technical-planning/references/dependencies.md

@@ -18,22 +18,26 @@ External dependencies are things a feature needs from other topics or systems th
 
 ## Format
 
-In Plan Index Files, external dependencies appear in a dedicated section:
-
-```markdown
-## External Dependencies
-
-- billing-system: Invoice generation for order completion
-- user-authentication: User context for permissions → {task-id} (resolved)
-- ~~payment-gateway: Payment processing~~ → satisfied externally
+In Plan Index Files, external dependencies are stored in the **frontmatter** as a YAML array:
+
+```yaml
+external_dependencies:
+  - topic: billing-system
+    description: Invoice generation for order completion
+    state: unresolved
+  - topic: user-authentication
+    description: User context for permissions
+    state: resolved
+    task_id: auth-1-3
+  - topic: payment-gateway
+    description: Payment processing
+    state: satisfied_externally
 ```
 
-If there are no external dependencies, still include the section:
-
-```markdown
-## External Dependencies
+If there are no external dependencies, use an empty array:
 
-No external dependencies.
+```yaml
+external_dependencies: []
 ```
 
 This makes it explicit for downstream stages that dependencies were considered and none exist.
@@ -42,16 +46,16 @@ This makes it explicit for downstream stages that dependencies were considered a
 
 | State | Format | Meaning |
 |-------|--------|---------|
-| Unresolved | `- {topic}: {description}` | Dependency exists but not yet linked to a task |
-| Resolved | `- {topic}: {description} → {task-id}` | Linked to specific task in another plan |
-| Satisfied externally | `- ~~{topic}: {description}~~ → satisfied externally` | Implemented outside workflow |
+| `unresolved` | `state: unresolved` | Dependency exists but not yet linked to a task |
+| `resolved` | `state: resolved` + `task_id: {id}` | Linked to specific task in another plan |
+| `satisfied_externally` | `state: satisfied_externally` | Implemented outside workflow |
 
 ## Lifecycle
 
 ```
 SPECIFICATION                    PLANNING
 ───────────────────────────────────────────────────────────────────
-Dependencies section    →    Copied to Plan Index File as unresolved
+Dependencies section    →    Added to plan frontmatter as unresolved
 (natural language)                      ↓
                              Resolved when linked to specific task ID
                              (via planning or /link-dependencies)
@@ -59,11 +63,11 @@ Dependencies section    →    Copied to Plan Index File as unresolved
 
 ## Resolution
 
-Dependencies move from unresolved → resolved when:
+Dependencies move from `unresolved` → `resolved` when:
 - The dependency topic is planned and you identify the specific task
 - The `/link-dependencies` command finds and wires the match
 
-Dependencies become "satisfied externally" when:
+Dependencies become `satisfied_externally` when:
 - The user confirms it was implemented outside the workflow
 - It already exists in the codebase
 - It's a third-party system that's already available

package/skills/technical-planning/references/steps/resolve-dependencies.md

@@ -10,29 +10,29 @@ Orient the user:
 
 After all phases are detailed and written, handle external dependencies — things this plan needs from other topics or systems.
 
+Dependencies are stored in the plan's **frontmatter** as `external_dependencies`. See [dependencies.md](../dependencies.md) for the format and states.
+
 #### If the specification has a Dependencies section
 
 The specification's Dependencies section lists what this feature needs from outside its own scope. These must be documented in the plan so implementation knows what is blocked and what is available.
 
-1. **Document each dependency** in the plan's External Dependencies section using the format described in [dependencies.md](../dependencies.md). Initially, record each as unresolved.
+1. **Document each dependency** in the plan's `external_dependencies` frontmatter field using the format described in [dependencies.md](../dependencies.md). Initially, record each as `state: unresolved`.
 
 2. **Resolve where possible** — For each dependency, check whether a plan already exists for that topic:
-   - If a plan exists, identify the specific task(s) that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply. Update the dependency entry from unresolved → resolved with the task reference.
-   - If no plan exists, leave the dependency as unresolved. It will be linked later via `/link-dependencies` or when that topic is planned.
+   - If a plan exists, identify the specific task(s) that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply. Update the dependency entry from `state: unresolved` → `state: resolved` with the `task_id`.
+   - If no plan exists, leave the dependency as `state: unresolved`. It will be linked later via `/link-dependencies` or when that topic is planned.
 
-3. **Reverse check** — Check whether any existing plans have unresolved dependencies that reference *this* topic. Now that this plan exists with specific tasks:
-   - Scan other plan files for External Dependencies entries that mention this topic
+3. **Reverse check** — Check whether any existing plans have unresolved dependencies in their `external_dependencies` frontmatter that reference *this* topic. Now that this plan exists with specific tasks:
+   - Scan other plan files' `external_dependencies` for entries that mention this topic
    - For each match, identify which task(s) in the current plan satisfy that dependency
-   - Update the other plan's dependency entry with the task reference (unresolved → resolved)
+   - Update the other plan's `external_dependencies` entry with the task reference (`state: resolved`, `task_id`)
 
 #### If the specification has no Dependencies section
 
-Document this explicitly in the plan:
-
-```markdown
-## External Dependencies
+Set the frontmatter field to an empty array:
 
-No external dependencies.
+```yaml
+external_dependencies: []
 ```
 
 This makes it clear that dependencies were considered and none exist — not that they were overlooked.

package/skills/technical-research/SKILL.md

@@ -28,6 +28,21 @@ Either way: Explore feasibility (technical, business, market), validate assumpti
 - **Topic is vague or could go many directions?**
   > "You mentioned {topic}. That could cover a lot of ground — is there a specific angle you'd like to start with, or should I explore broadly?"
 
+---
+
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Your Expertise
 
 You bring knowledge across the full landscape:

package/skills/technical-review/SKILL.md

@@ -41,6 +41,21 @@ Either way: Verify every plan task was implemented, tested adequately, and meets
 
 The specification is optional — the review can proceed with just the plan.
 
+---
+
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Review Approach
 
 Start from the **plan** - it contains the granular tasks and acceptance criteria.

package/skills/technical-specification/SKILL.md

@@ -39,6 +39,21 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **Multiple sources:** When multiple sources are provided, extract exhaustively from ALL of them. Content may be scattered across sources - a decision in one may have constraints or details in another. The specification consolidates everything into a single standalone document.
 
+---
+
+## Resuming After Context Refresh
+
+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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## The Process
 
 **Load**: [specification-guide.md](references/specification-guide.md)

package/skills/technical-specification/references/specification-guide.md

@@ -295,12 +295,6 @@ Ask: **"Is there a standalone thing to build, or does this inform how we build o
 
 **Trust nothing without validation**: Synthesize and present, but never assume source material is correct.
 
-## After Context Refresh
-
-Read the specification. It contains validated, approved content. Trust it - you built it together with the user.
-
-If working notes exist, they show where you left off.
-
 ## Dependencies Section
 
 At the end of every specification, add a **Dependencies** section that identifies **prerequisites** - systems that must exist before this feature can be built.