@leeovery/claude-technical-workflows 2.1.35 → 2.1.37

package/README.md

@@ -129,7 +129,7 @@ Not every task needs the full workflow. These skills gather inputs flexibly and
 /start-feature
     │
     ▼
-Discussion ──▶ Specification ──▶ Planning ──▶ Implementation
+Discussion ──▶ Specification ──▶ Planning ──▶ Implementation ──▶ Review
 ```
 
 **How it works:** After each phase completes, a plan mode bridge clears context and advances to the next phase automatically. You approve each transition with "clear context and continue" — this keeps each phase in a clean context window.
@@ -254,7 +254,7 @@ skills/
 │
 ├── # Entry-point skills (user-invocable)
 ├── migrate/                         # Keep workflow files in sync with system design
-├── start-feature/                   # Pipeline: discussion → spec → plan → impl
+├── start-feature/                   # Pipeline: discussion → spec → plan → impl → review
 ├── continue-feature/                # Pipeline: route feature to next phase
 ├── link-dependencies/               # Standalone: wire cross-topic deps
 ├── start-research/                  # Begin research
@@ -268,7 +268,8 @@ skills/
 │
 ├── # Bridge skills (model-invocable — pipeline pre-flight)
 ├── begin-planning/                  # Pre-flight for planning in pipeline
-└── begin-implementation/            # Pre-flight for implementation in pipeline
+├── begin-implementation/            # Pre-flight for implementation in pipeline
+└── begin-review/                    # Pre-flight for review in pipeline
 
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
@@ -334,7 +335,7 @@ Independent skills that gather inputs flexibly (inline context, files, or prompt
 
 | Skill                                                   | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-feature**](skills/start-feature/)              | Start a new feature through the full pipeline. Gathers context, creates a discussion, then bridges through specification → planning → implementation. |
+| [**/start-feature**](skills/start-feature/)              | Start a new feature through the full pipeline. Gathers context, creates a discussion, then bridges through specification → planning → implementation → review. |
 | [**/continue-feature**](skills/continue-feature/)        | Continue a feature through its next pipeline phase. Routes automatically based on artifact state. Used manually or from plan mode bridges.  |
 | [**/link-dependencies**](skills/link-dependencies/)      | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 

package/package.json

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

package/skills/begin-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: begin-review
+description: "Bridge skill for the feature pipeline. Runs pre-flight checks for review and invokes the technical-review skill. Called by continue-feature — not directly by users."
+user-invocable: false
+allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh)
+---
+
+Invoke the **technical-review** skill for this conversation with pre-flight context.
+
+> **⚠️ ZERO OUTPUT RULE**: Do not narrate your processing. Produce no output until a step or reference file explicitly specifies display content. No "proceeding with...", no discovery summaries, no routing decisions, no transition text. Your first output must be content explicitly called for by the instructions.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+This skill is a **bridge** — it runs pre-flight checks for review and hands off to the processing skill. The topic has already been selected by the caller.
+
+**CRITICAL**: This guidance is mandatory.
+
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Complete each step fully before moving to the next
+
+---
+
+## Step 1: Run Discovery
+
+!`.claude/skills/start-review/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
+
+```bash
+.claude/skills/start-review/scripts/discovery.sh
+```
+
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the output to find the plan matching the provided topic. Extract:
+
+- **Plan details**: status, format, plan_id, specification, specification_exists
+- **Implementation status**: implementation_status
+- **Review state**: review_count, latest_review_version
+
+If the plan is missing, this is an error — report it and stop.
+
+If `implementation_status` is `"none"`, this is an error:
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Pre-Flight Failed
+
+"{topic:(titlecase)}" has no implementation to review.
+
+Implementation must be completed or in-progress before review.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Determine Review Version
+
+Check the topic's review state from discovery output:
+
+- If `review_count` is 0 → review version is `r1`
+- If `review_count` > 0 → review version is `r{latest_review_version + 1}`
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Invoke the Skill
+
+Construct the handoff and invoke the [technical-review](../technical-review/SKILL.md) skill:
+
+```
+Review session
+Plans to review:
+  - topic: {topic}
+    plan: docs/workflow/planning/{topic}/plan.md
+    format: {format}
+    plan_id: {plan_id} (if applicable)
+    specification: {specification} (exists: {true|false})
+    review_version: r{N}
+
+Invoke the technical-review skill.
+```

package/skills/continue-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: continue-feature
 description: "Continue a feature through the pipeline. Routes to the next phase (specification, planning, or implementation) based on artifact state. Can be invoked manually or from plan mode bridges."
-allowed-tools: Bash(.claude/skills/continue-feature/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/continue-feature/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(.claude/skills/start-review/scripts/discovery.sh)
 hooks:
   PreToolUse:
     - hooks:
@@ -33,7 +33,8 @@ Context refresh (compaction) summarizes the conversation, losing procedural deta
 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, ask the user.
 3. **Determine current step from artifacts** (check top-down, first match wins):
-   - Implementation tracking exists with `status: completed` → resume at **Step 6** (phase bridge — feature is done)
+   - Review exists for topic → resume at **Step 7** (phase bridge — pipeline complete)
+   - Implementation tracking exists with `status: completed`, no review → resume at **Step 6** (invoke begin-review)
    - Implementation tracking exists with `status: in-progress` → resume at **Step 5** (re-invoke begin-implementation)
    - Plan exists with `status: concluded` → resume at **Step 5** (invoke begin-implementation)
    - Plan exists with other status → resume at **Step 4** (re-invoke begin-planning)
@@ -109,7 +110,7 @@ Present the discovered state as context, then ask the user to select:
 Continue Feature
 
 This skill continues a feature through the pipeline phases:
-Discussion → Specification → Planning → Implementation
+Discussion → Specification → Planning → Implementation → Review
 
 It's designed for features started with /start-feature, but works
 with any topic that has workflow artifacts.
@@ -142,7 +143,7 @@ Select by number, or enter a topic name directly:
 
 Load **[detect-phase.md](references/detect-phase.md)** and follow its instructions.
 
-→ The reference file will route you to **Step 3**, **Step 4**, **Step 5**, or a terminal condition. Follow its routing.
+→ The reference file will route you to **Step 3**, **Step 4**, **Step 5**, **Step 6**, or a terminal condition. Follow its routing.
 
 ---
 
@@ -150,7 +151,7 @@ Load **[detect-phase.md](references/detect-phase.md)** and follow its instructio
 
 Load **[invoke-specification.md](references/invoke-specification.md)** and follow its instructions.
 
-**CRITICAL**: When the specification concludes (status becomes "concluded"), you MUST proceed to **Step 6** below. Do not end the session — the feature pipeline continues to the phase bridge.
+**CRITICAL**: When the specification concludes (status becomes "concluded"), you MUST proceed to **Step 7** below. Do not end the session — the feature pipeline continues to the phase bridge.
 
 ---
 
@@ -158,7 +159,7 @@ Load **[invoke-specification.md](references/invoke-specification.md)** and follo
 
 Load **[invoke-planning.md](references/invoke-planning.md)** and follow its instructions.
 
-**CRITICAL**: When the plan concludes (status becomes "concluded"), you MUST proceed to **Step 6** below. Do not end the session — the feature pipeline continues to the phase bridge.
+**CRITICAL**: When the plan concludes (status becomes "concluded"), you MUST proceed to **Step 7** below. Do not end the session — the feature pipeline continues to the phase bridge.
 
 ---
 
@@ -166,12 +167,20 @@ Load **[invoke-planning.md](references/invoke-planning.md)** and follow its inst
 
 Load **[invoke-implementation.md](references/invoke-implementation.md)** and follow its instructions.
 
-**CRITICAL**: When implementation completes (tracking status becomes "completed"), you MUST proceed to **Step 6** below. Do not end the session — the feature pipeline continues to the phase bridge.
+**CRITICAL**: When implementation completes (tracking status becomes "completed"), you MUST proceed to **Step 7** below. Do not end the session — the feature pipeline continues to the phase bridge.
 
 ---
 
-## Step 6: Phase Bridge
+## Step 6: Review Phase
+
+Load **[invoke-review.md](references/invoke-review.md)** and follow its instructions.
+
+**CRITICAL**: When review concludes, you MUST proceed to **Step 7** below. Do not end the session — the feature pipeline continues to the phase bridge.
+
+---
+
+## Step 7: Phase Bridge
 
 Load **[phase-bridge.md](references/phase-bridge.md)** and follow its instructions.
 
-The bridge will enter plan mode with instructions to invoke continue-feature for the topic in the next session.
+The bridge will enter plan mode with instructions to invoke continue-feature for the topic in the next session, or show a terminal message if the pipeline is complete.

package/skills/continue-feature/references/detect-phase.md

@@ -14,23 +14,26 @@ Either use the `next_phase` from discovery output (if discovery was run), or com
 
 Check artifacts in this order (first match wins):
 
-1. Read `docs/workflow/implementation/{topic}/tracking.md`
-   - If exists with `status: completed` → next_phase is **"done"**
+1. Check `docs/workflow/review/{topic}/r*/review.md`
+   - If any review exists → next_phase is **"done"**
+
+2. Read `docs/workflow/implementation/{topic}/tracking.md`
+   - If exists with `status: completed` → next_phase is **"review"**
    - If exists with `status: in-progress` → next_phase is **"implementation"**
 
-2. Read `docs/workflow/planning/{topic}/plan.md`
+3. Read `docs/workflow/planning/{topic}/plan.md`
    - If exists with `status: concluded` → next_phase is **"implementation"**
    - If exists with other status → next_phase is **"planning"**
 
-3. Read `docs/workflow/specification/{topic}/specification.md`
+4. Read `docs/workflow/specification/{topic}/specification.md`
    - If exists with `status: concluded` → next_phase is **"planning"**
    - If exists with other status → next_phase is **"specification"**
 
-4. Check `docs/workflow/discussion/{topic}.md`
+5. Check `docs/workflow/discussion/{topic}.md`
    - If exists with `status: concluded` → next_phase is **"specification"**
    - If exists with other status → next_phase is **"discussion"**
 
-5. If none found → next_phase is **"unknown"**
+6. If none found → next_phase is **"unknown"**
 
 ## Routing
 
@@ -46,17 +49,21 @@ Check artifacts in this order (first match wins):
 
 → Proceed to **Step 5**.
 
+#### If next_phase is "review"
+
+→ Proceed to **Step 6**.
+
 #### If next_phase is "done"
 
 > *Output the next fenced block as a code block:*
 
 ```
-Feature Complete
+Pipeline Complete
 
-"{topic:(titlecase)}" has completed implementation.
+"{topic:(titlecase)}" has completed all pipeline phases
+(implementation and review).
 
-Run /start-review to validate the implementation against the
-specification and plan.
+Use /start-review to re-review or synthesize findings.
 ```
 
 **STOP.** Do not proceed — terminal condition.

package/skills/continue-feature/references/invoke-implementation.md

@@ -21,7 +21,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
   "{topic}" \
   "skills/technical-implementation/SKILL.md" \
   "docs/workflow/implementation/{topic}/tracking.md" \
-  --pipeline "This session is part of the feature pipeline. After implementation completes, return to the continue-feature skill and execute Step 6 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
+  --pipeline "This session is part of the feature pipeline. After implementation completes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
 ## Handoff
@@ -33,7 +33,7 @@ Implementation pre-flight for: {topic}
 Plan: docs/workflow/planning/{topic}/plan.md
 
 PIPELINE CONTINUATION — When implementation completes (tracking status: completed),
-you MUST return to the continue-feature skill and execute Step 6 (Phase Bridge).
+you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).
 Load: skills/continue-feature/references/phase-bridge.md
 Do not end the session after implementation — the feature pipeline continues.
 

package/skills/continue-feature/references/invoke-planning.md

@@ -21,7 +21,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
   "{topic}" \
   "skills/technical-planning/SKILL.md" \
   "docs/workflow/planning/{topic}/plan.md" \
-  --pipeline "This session is part of the feature pipeline. After the plan concludes, return to the continue-feature skill and execute Step 6 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
+  --pipeline "This session is part of the feature pipeline. After the plan concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
 ## Handoff
@@ -33,7 +33,7 @@ Planning pre-flight for: {topic}
 Specification: docs/workflow/specification/{topic}/specification.md
 
 PIPELINE CONTINUATION — When planning concludes (plan status: concluded),
-you MUST return to the continue-feature skill and execute Step 6 (Phase Bridge).
+you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).
 Load: skills/continue-feature/references/phase-bridge.md
 Do not end the session after planning — the feature pipeline continues.
 

package/skills/continue-feature/references/invoke-review.md

@@ -0,0 +1,43 @@
+# Invoke Review
+
+*Reference for **[continue-feature](../SKILL.md)***
+
+---
+
+Invoke the begin-review bridge skill for this topic.
+
+## Save Session State
+
+Before invoking the processing skill, save a session bookmark.
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state so Claude can pick up where it left off and continue the feature pipeline if the conversation is compacted.
+```
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-review/SKILL.md" \
+  "docs/workflow/review/{topic}/r{N}/review.md" \
+  --pipeline "This session is part of the feature pipeline. After the review concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
+```
+
+## Handoff
+
+Invoke the [begin-review](../../begin-review/SKILL.md) skill:
+
+```
+Review pre-flight for: {topic}
+Plan: docs/workflow/planning/{topic}/plan.md
+
+PIPELINE CONTINUATION — When review concludes,
+you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).
+Load: skills/continue-feature/references/phase-bridge.md
+Do not end the session after review — the feature pipeline continues.
+
+Invoke the begin-review skill.
+```
+
+The bridge skill handles discovery, validation, version detection, and the handoff to technical-review.

package/skills/continue-feature/references/invoke-specification.md

@@ -31,7 +31,7 @@ Saving session state so Claude can pick up where it left off and continue the fe
   "{topic}" \
   "skills/technical-specification/SKILL.md" \
   "docs/workflow/specification/{topic}/specification.md" \
-  --pipeline "This session is part of the feature pipeline. After the specification concludes, return to the continue-feature skill and execute Step 6 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
+  --pipeline "This session is part of the feature pipeline. After the specification concludes, return to the continue-feature skill and execute Step 7 (Phase Bridge). Load: skills/continue-feature/references/phase-bridge.md"
 ```
 
 ## Handoff
@@ -47,7 +47,7 @@ Source material:
 Topic name: {topic}
 
 PIPELINE CONTINUATION — When this specification concludes (status: concluded),
-you MUST return to the continue-feature skill and execute Step 6 (Phase Bridge).
+you MUST return to the continue-feature skill and execute Step 7 (Phase Bridge).
 Load: skills/continue-feature/references/phase-bridge.md
 Do not end the session after the specification — the feature pipeline continues.
 

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

@@ -12,9 +12,10 @@ Check which step just completed to determine what continue-feature will route to
 
 - Just completed **specification** (Step 3) → next session routes to planning
 - Just completed **planning** (Step 4) → next session routes to implementation
-- Just completed **implementation** (Step 5) → feature is done
+- Just completed **implementation** (Step 5) → next session routes to review
+- Just completed **review** (Step 6) → pipeline is done
 
-#### If implementation just completed
+#### If review just completed
 
 > *Output the next fenced block as a code block:*
 
@@ -22,8 +23,6 @@ Check which step just completed to determine what continue-feature will route to
 Feature Complete
 
 "{topic:(titlecase)}" has completed all pipeline phases.
-
-Run /start-review to validate the implementation.
 ```
 
 **STOP.** Do not proceed — terminal condition.

package/skills/continue-feature/scripts/discovery.sh

@@ -15,6 +15,7 @@ DISC_DIR="docs/workflow/discussion"
 SPEC_DIR="docs/workflow/specification"
 PLAN_DIR="docs/workflow/planning"
 IMPL_DIR="docs/workflow/implementation"
+REVIEW_DIR="docs/workflow/review"
 
 # Helper: Extract a frontmatter field value from a file
 # Usage: extract_field <file> <field_name>
@@ -132,13 +133,26 @@ else
             impl_status=${impl_status:-"in-progress"}
         fi
 
+        # Review state
+        review_exists="false"
+        if [ -d "$REVIEW_DIR/${topic}" ]; then
+            for rdir in "$REVIEW_DIR/${topic}"/r*/; do
+                [ -d "$rdir" ] || continue
+                [ -f "${rdir}review.md" ] || continue
+                review_exists="true"
+                break
+            done
+        fi
+
         #
         # Compute next_phase (check from top down, first match wins)
         #
         next_phase=""
 
-        if [ "$impl_exists" = "true" ] && [ "$impl_status" = "completed" ]; then
+        if [ "$impl_exists" = "true" ] && [ "$impl_status" = "completed" ] && [ "$review_exists" = "true" ]; then
             next_phase="done"
+        elif [ "$impl_exists" = "true" ] && [ "$impl_status" = "completed" ] && [ "$review_exists" = "false" ]; then
+            next_phase="review"
         elif [ "$impl_exists" = "true" ] && [ "$impl_status" = "in-progress" ]; then
             next_phase="implementation"
         elif [ "$plan_exists" = "true" ] && [ "$plan_status" = "concluded" ]; then
@@ -191,6 +205,9 @@ else
             echo "      status: \"$impl_status\""
         fi
 
+        echo "    review:"
+        echo "      exists: $review_exists"
+
         echo "    next_phase: \"$next_phase\""
         echo "    actionable: $actionable"
 

package/skills/migrate/scripts/migrate.sh

@@ -38,7 +38,7 @@ mkdir -p "$(dirname "$TRACKING_FILE")"
 OLD_CACHE_LOG="docs/workflow/.cache/migrations.log"
 OLD_CACHE_FILE="docs/workflow/.cache/migrations"
 if [ -f "$OLD_CACHE_LOG" ] || [ -f "$OLD_CACHE_FILE" ]; then
-    { cat "$OLD_CACHE_LOG" 2>/dev/null; cat "$OLD_CACHE_FILE" 2>/dev/null; cat "$TRACKING_FILE" 2>/dev/null; } | sort -u > "${TRACKING_FILE}.tmp"
+    { cat "$OLD_CACHE_LOG" 2>/dev/null || true; cat "$OLD_CACHE_FILE" 2>/dev/null || true; cat "$TRACKING_FILE" 2>/dev/null || true; } | sort -u > "${TRACKING_FILE}.tmp"
     mv "${TRACKING_FILE}.tmp" "$TRACKING_FILE"
     rm -f "$OLD_CACHE_LOG" "$OLD_CACHE_FILE"
 fi

package/skills/start-review/SKILL.md

@@ -128,7 +128,7 @@ Review Overview
 All {N} implemented plans have been reviewed.
 
 1. {topic:(titlecase)}
-   └─ Review: r{N} ({verdict})
+   └─ Review: x{review_count} — r{latest_review_version} ({latest_review_verdict})
    └─ Synthesis: @if(has_synthesis) completed @else pending @endif
 
 2. ...

package/skills/start-review/references/display-plans.md

@@ -21,7 +21,7 @@ Review Overview
    └─ Plan: concluded ({format})
    └─ Implementation: {impl_status:[completed|in-progress]}
    └─ Spec: {spec:[exists|missing]}
-   └─ Review: @if(has_review) r{N} ({verdict}) @else (none) @endif
+   └─ Review: @if(review_count > 0) x{review_count} — r{latest_review_version} ({latest_review_verdict}) @else (no review) @endif
 
 2. ...
 ```
@@ -57,8 +57,8 @@ Key:
     in-progress — implementation still ongoing
 
   Review status:
-    r{N}        — review version number
-    (none)      — not yet reviewed
+    x{N}        — number of reviews completed
+    (no review) — not yet reviewed
 ```
 
 **Then route based on what's reviewable:**

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

@@ -85,6 +85,25 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
             impl_status=${impl_status_val:-"in-progress"}
         fi
 
+        # Check review status for this plan
+        review_count=0
+        latest_review_version=0
+        latest_review_verdict=""
+        if [ -d "$REVIEW_DIR/$name" ]; then
+            for rdir in "$REVIEW_DIR/$name"/r*/; do
+                [ -d "$rdir" ] || continue
+                [ -f "${rdir}review.md" ] || continue
+                rnum=${rdir##*r}
+                rnum=${rnum%/}
+                review_count=$((review_count + 1))
+                if [ "$rnum" -gt "$latest_review_version" ] 2>/dev/null; then
+                    latest_review_version=$rnum
+                    latest_review_verdict=$(grep -m1 '\*\*QA Verdict\*\*:' "${rdir}review.md" 2>/dev/null | \
+                        sed -E 's/.*\*\*QA Verdict\*\*:[[:space:]]*//' || true)
+                fi
+            done
+        fi
+
         echo "    - name: \"$name\""
         echo "      topic: \"$topic\""
         echo "      status: \"$status\""
@@ -96,6 +115,11 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
             echo "      plan_id: \"$plan_id\""
         fi
         echo "      implementation_status: \"$impl_status\""
+        echo "      review_count: $review_count"
+        if [ "$review_count" -gt 0 ]; then
+            echo "      latest_review_version: $latest_review_version"
+            echo "      latest_review_verdict: \"$latest_review_verdict\""
+        fi
 
         plan_count=$((plan_count + 1))
         if [ "$impl_status" != "none" ]; then

package/skills/technical-implementation/references/task-loop.md

@@ -7,13 +7,13 @@
 Follow stages A through E sequentially for each task. Do not abbreviate, skip, or compress stages based on previous iterations.
 
 ```
-A. Retrieve next task
+A. Retrieve next task + mark in-progress
 B. Execute task → invoke-executor.md
    → Executor Blocked (conditional)
 C. Review task → invoke-reviewer.md
    → Review Changes with fix analysis (conditional, fix_gate_mode)
 D. Task gate (gated → prompt user / auto → announce)
-E. Update progress + commit
+E. Update progress + phase check + commit
 → loop back to A until done
 ```
 
@@ -25,6 +25,8 @@ E. Update progress + commit
 2. If no available tasks remain → skip to **When All Tasks Are Complete**.
 3. Normalise the task content following **[task-normalisation.md](task-normalisation.md)**.
 4. Reset `fix_attempts` to `0` in the implementation tracking file.
+5. Mark the task as **in-progress** — follow the format's **updating.md** "In Progress" status transition.
+6. If the format's updating.md includes a **Phase / Parent Status** section: check whether the task's phase parent needs to be started. If so, follow the format's phase start instructions.
 
 ---
 
@@ -172,10 +174,15 @@ Check the `task_gate_mode` field in the implementation tracking file.
 
 **Update task progress in the plan** — follow the format's **updating.md** instructions to mark the task complete.
 
+**Check for phase completion** — use the format's **reading.md** to list remaining tasks in the current phase. If no tasks remain open or in-progress:
+- If the format's updating.md includes a **Phase / Parent Status** section, follow its phase completion instructions
+- Append the phase number to `completed_phases` in the tracking file
+
 **Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}/tracking.md`):
 - Append the task ID to `completed_tasks`
 - Update `current_phase` if phase changed
 - Update `current_task` to the next task (or `~` if done)
+- Update `completed_phases` if a phase completed this iteration
 - Update `updated` to today's date
 - If user chose `auto` at the task gate this turn: update `task_gate_mode: auto`
 - If user chose `auto` at the fix gate this turn: update `fix_gate_mode: auto`

package/skills/technical-planning/references/output-formats/tick/updating.md

@@ -25,3 +25,35 @@ To update a task's properties:
 - **Priority**: `tick update <task-id> --priority 1`
 - **Parent**: `tick update <task-id> --parent <new-parent-id>` (pass empty string to clear)
 - **Dependencies**: See [graph.md](graph.md)
+
+## Phase / Parent Status
+
+Phase tasks are parent tasks in the tick hierarchy. Update their status to reflect child task progress.
+
+### Start Phase
+
+When the first task in a phase begins and the phase parent is still `open`:
+
+```bash
+tick start <phase-id>
+```
+
+Check the phase parent's status with `tick show <phase-id>`. If status is `open`, start it.
+
+### Complete Phase
+
+When all child tasks in a phase are `done` or `cancelled` (none remain `open` or `in_progress`):
+
+```bash
+tick done <phase-id>
+```
+
+After completing a task, check: `tick list --parent <phase-id> --status open` and `tick list --parent <phase-id> --status in_progress`. If both return empty, the phase is complete.
+
+### Cancel Phase
+
+If all child tasks are `cancelled` (none `done`):
+
+```bash
+tick cancel <phase-id>
+```