@leeovery/claude-technical-workflows 2.1.27 → 2.1.28

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

@@ -137,10 +137,10 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
         # Check if this discussion has a corresponding individual spec
         has_individual_spec="false"
         spec_status=""
-        if [ -f "$SPEC_DIR/${name}.md" ]; then
+        if [ -f "$SPEC_DIR/${name}/specification.md" ]; then
             has_individual_spec="true"
             # Extract spec status in real-time (not from cache)
-            spec_status=$(extract_field "$SPEC_DIR/${name}.md" "status")
+            spec_status=$(extract_field "$SPEC_DIR/${name}/specification.md" "status")
             spec_status=${spec_status:-"in-progress"}
         fi
 
@@ -163,10 +163,10 @@ echo ""
 echo "specifications:"
 
 if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
-    for file in "$SPEC_DIR"/*.md; do
+    for file in "$SPEC_DIR"/*/specification.md; do
         [ -f "$file" ] || continue
 
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
         status=${status:-"active"}
 
@@ -235,7 +235,7 @@ if [ -f "$CACHE_FILE" ]; then
     while IFS= read -r grouping_name; do
         # Clean the name (remove any trailing annotations, lowercase, spaces to hyphens)
         clean_name=$(echo "$grouping_name" | sed 's/[[:space:]]*(.*)//' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
-        if [ -f "$SPEC_DIR/${clean_name}.md" ]; then
+        if [ -f "$SPEC_DIR/${clean_name}/specification.md" ]; then
             echo "    - \"$clean_name\""
             anchored_found=true
         fi
@@ -285,7 +285,7 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
     # Count non-superseded specifications
     spec_count=0
     if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
-        for file in "$SPEC_DIR"/*.md; do
+        for file in "$SPEC_DIR"/*/specification.md; do
             [ -f "$file" ] || continue
             spec_status=$(extract_field "$file" "status")
             if [ "$spec_status" != "superseded" ]; then

package/skills/status/scripts/discovery.sh

@@ -251,9 +251,9 @@ spec_crosscutting=0
 if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
     echo "  exists: true"
     echo "  files:"
-    for file in "$SPEC_DIR"/*.md; do
+    for file in "$SPEC_DIR"/*/specification.md; do
         [ -f "$file" ] || continue
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
         status=${status:-"in-progress"}
         spec_type=$(extract_field "$file" "type")
@@ -316,15 +316,15 @@ plan_in_progress=0
 if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
     echo "  exists: true"
     echo "  files:"
-    for file in "$PLAN_DIR"/*.md; do
+    for file in "$PLAN_DIR"/*/plan.md; do
         [ -f "$file" ] || continue
-        name=$(basename "$file" .md)
+        name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
         format=$(extract_field "$file" "format")
         format=${format:-"unknown"}
         specification=$(extract_field "$file" "specification")
-        specification=${specification:-"${name}.md"}
+        specification=${specification:-"${name}/specification.md"}
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
@@ -389,11 +389,11 @@ if [ -d "$IMPL_DIR" ] && [ -n "$(ls -A "$IMPL_DIR" 2>/dev/null)" ]; then
 
         # Count total tasks from plan directory (local-markdown format)
         total_tasks=0
-        plan_file="$PLAN_DIR/${topic}.md"
+        plan_file="$PLAN_DIR/${topic}/plan.md"
         if [ -f "$plan_file" ]; then
             plan_format=$(extract_field "$plan_file" "format")
             if [ "$plan_format" = "local-markdown" ] && [ -d "$PLAN_DIR/${topic}" ]; then
-                total_tasks=$(ls -1 "$PLAN_DIR/${topic}/"*.md 2>/dev/null | wc -l | tr -d ' ')
+                total_tasks=$(ls -1 "$PLAN_DIR/${topic}/tasks/"*.md 2>/dev/null | wc -l | tr -d ' ')
             fi
         fi
 

package/skills/technical-discussion/SKILL.md

@@ -24,11 +24,28 @@ Either way: Capture decisions, rationale, competing approaches, and edge cases.
 
 **Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.
 
-- **No topic provided?**
-  > "What topic would you like to discuss? This could be an architectural decision, a design problem, or edge cases to work through — anything that needs structured technical discussion."
+#### If no topic provided
 
-- **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?"
+> *Output the next fenced block as a code block:*
+
+```
+What topic would you like to discuss? This could be an architectural decision,
+a design problem, or edge cases to work through — anything that needs structured
+technical discussion.
+```
+
+**STOP.** Wait for user response.
+
+#### If topic is broad or ambiguous
+
+> *Output the next fenced block as a code block:*
+
+```
+You mentioned {topic}. To keep the discussion focused, is there a specific
+aspect or decision you want to work through first?
+```
+
+**STOP.** Wait for user response.
 
 ---
 
@@ -97,7 +114,24 @@ These are natural pauses, not every exchange. Document the reasoning and context
 
 ## Concluding a Discussion
 
-When the user is ready to conclude the discussion:
+When the user indicates they want to conclude:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Conclude discussion and mark as concluded
+- **Comment** — Add context before concluding
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If comment
+
+Incorporate the user's context into the discussion, commit, then re-present the sign-off prompt above.
+
+#### If yes
 
 1. Update frontmatter `status: concluded`
 2. Final commit
@@ -105,18 +139,22 @@ When the user is ready to conclude the discussion:
 
 **If other in-progress discussions exist:**
 
+> *Output the next fenced block as a code block:*
+
 ```
 Discussion concluded: {topic}
 
 Remaining in-progress discussions:
-- {topic-1}
-- {topic-2}
+  • {topic-1}
+  • {topic-2}
 
-To continue, clear your context and run `/start-discussion` to pick up the next topic.
+To continue, clear your context and run /start-discussion to pick up the next topic.
 ```
 
 **If no in-progress discussions remain:**
 
+> *Output the next fenced block as a code block:*
+
 ```
 Discussion concluded: {topic}
 

package/skills/technical-implementation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-implementation
-description: "Orchestrate implementation of plans using agent-based TDD workflow with per-task review and approval gate (auto mode available). Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Dispatches executor and reviewer agents per task, commits after review approval."
+description: "Orchestrate implementation of plans using agent-based TDD workflow with per-task review and approval gate (auto mode available). Use when: (1) Implementing a plan from docs/workflow/planning/{topic}/plan.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Dispatches executor and reviewer agents per task, commits after review approval."
 user-invocable: false
 ---
 
@@ -30,14 +30,38 @@ Either way: dispatch agents per task — executor implements via TDD, reviewer v
 
 **Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
-- **No plan provided?**
-  "I need an implementation plan to execute. Could you point me to the plan file (e.g., `docs/workflow/planning/{topic}.md`)?"
+#### If no plan provided
 
-- **Plan has no `format` field in frontmatter?**
-  "The plan at {path} doesn't specify an output format in its frontmatter. Which format does this plan use?"
+> *Output the next fenced block as a code block:*
+
+```
+I need an implementation plan to execute. Could you point me to the plan file
+(e.g., docs/workflow/planning/{topic}/plan.md)?
+```
+
+**STOP.** Wait for user response.
+
+#### If plan has no `format` field in frontmatter
 
-- **Plan status is not `concluded`?**
-  "The plan at {path} has status '{status}' — it hasn't completed the review process. Should I proceed anyway, or should the plan be reviewed first?"
+> *Output the next fenced block as a code block:*
+
+```
+The plan at {path} doesn't specify an output format in its frontmatter.
+Which format does this plan use?
+```
+
+**STOP.** Wait for user response.
+
+#### If plan status is not `concluded`
+
+> *Output the next fenced block as a code block:*
+
+```
+The plan at {path} has status '{status}' — it hasn't completed the review
+process. Should I proceed anyway, or should the plan be reviewed first?
+```
+
+**STOP.** Wait for user response.
 
 If no specification is available, the plan becomes the sole authority for design decisions.
 
@@ -89,9 +113,12 @@ Follow them. Complete ALL steps before proceeding.
 
 #### If no setup file exists
 
-Ask:
+> *Output the next fenced block as a code block:*
 
-"No environment setup document found. Are there any setup instructions I should follow before implementing?"
+```
+No environment setup document found. Are there any setup instructions
+I should follow before implementing?
+```
 
 **STOP.** Wait for user response.
 
@@ -103,7 +130,7 @@ Save their instructions to `docs/workflow/environment-setup.md` (or "No special
 
 ## Step 2: Read Plan + Load Plan Adapter
 
-1. Read the plan from the provided location (typically `docs/workflow/planning/{topic}.md`)
+1. Read the plan from the provided location (typically `docs/workflow/planning/{topic}/plan.md`)
 2. Plans can be stored in various formats. The `format` field in the plan's frontmatter identifies which format this plan uses.
 3. Load the format's per-concern adapter files from `../technical-planning/references/output-formats/{format}/`:
    - **reading.md** — how to read tasks from the plan
@@ -131,7 +158,7 @@ Create `docs/workflow/implementation/{topic}/tracking.md`:
 ```yaml
 ---
 topic: {topic}
-plan: ../../planning/{topic}.md
+plan: ../../planning/{topic}/plan.md
 format: {format from plan}
 status: in-progress
 task_gate_mode: gated
@@ -257,7 +284,7 @@ Recommendations: {any suggested tools with install commands}
 
 ## Step 6: Task Loop
 
-Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its instructions as written.
+Load **[task-loop.md](references/task-loop.md)** and follow its instructions as written.
 
 After the loop completes:
 
@@ -269,7 +296,7 @@ After the loop completes:
 
 ## Step 7: Analysis Loop
 
-Load **[steps/analysis-loop.md](references/steps/analysis-loop.md)** and follow its instructions as written.
+Load **[analysis-loop.md](references/analysis-loop.md)** and follow its instructions as written.
 
 → If new tasks were created in the plan, return to **Step 6**.
 
@@ -279,6 +306,25 @@ Load **[steps/analysis-loop.md](references/steps/analysis-loop.md)** and follow
 
 ## Step 8: Mark Implementation Complete
 
+Before marking complete, present the sign-off:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Mark implementation as completed
+- **Comment** — Add context before completing
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If comment
+
+Discuss the user's context. If additional work is needed, route back to **Step 6** or **Step 7** as appropriate. Otherwise, re-present the sign-off prompt above.
+
+#### If yes
+
 Update the tracking file (`docs/workflow/implementation/{topic}/tracking.md`):
 - Set `status: completed`
 - Set `completed: YYYY-MM-DD` (use today's actual date)
@@ -292,13 +338,13 @@ Commit: `impl({topic}): complete implementation`
 
 - **[environment-setup.md](references/environment-setup.md)** — Environment setup before implementation
 - **[linter-setup.md](references/linter-setup.md)** — Linter discovery and configuration
-- **[steps/task-loop.md](references/steps/task-loop.md)** — Task execution loop, task gates, tracking, commits
-- **[steps/analysis-loop.md](references/steps/analysis-loop.md)** — Analysis and refinement cycle
-- **[steps/invoke-executor.md](references/steps/invoke-executor.md)** — How to invoke the executor agent
-- **[steps/invoke-reviewer.md](references/steps/invoke-reviewer.md)** — How to invoke the reviewer agent
-- **[steps/invoke-analysis.md](references/steps/invoke-analysis.md)** — How to invoke analysis agents
-- **[steps/invoke-synthesizer.md](references/steps/invoke-synthesizer.md)** — How to invoke the synthesis agent
-- **[steps/invoke-task-writer.md](references/steps/invoke-task-writer.md)** — How to invoke the task writer agent
+- **[task-loop.md](references/task-loop.md)** — Task execution loop, task gates, tracking, commits
+- **[analysis-loop.md](references/analysis-loop.md)** — Analysis and refinement cycle
+- **[invoke-executor.md](references/invoke-executor.md)** — How to invoke the executor agent
+- **[invoke-reviewer.md](references/invoke-reviewer.md)** — How to invoke the reviewer agent
+- **[invoke-analysis.md](references/invoke-analysis.md)** — How to invoke analysis agents
+- **[invoke-synthesizer.md](references/invoke-synthesizer.md)** — How to invoke the synthesis agent
+- **[invoke-task-writer.md](references/invoke-task-writer.md)** — How to invoke the task writer agent
 - **[task-normalisation.md](references/task-normalisation.md)** — Normalised task shape for agent invocation
 - **[tdd-workflow.md](references/tdd-workflow.md)** — TDD cycle (passed to executor agent)
 - **[code-quality.md](references/code-quality.md)** — Quality standards (passed to executor agent)

package/skills/technical-implementation/references/{steps/analysis-loop.md → analysis-loop.md}

@@ -1,6 +1,6 @@
 # Analysis Loop
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 

package/skills/technical-implementation/references/{steps/invoke-analysis.md → invoke-analysis.md}

@@ -1,6 +1,6 @@
 # Invoke Analysis Agents
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
@@ -27,7 +27,7 @@ Dispatch **all three in parallel** via the Task tool. Each agent receives the sa
 1. **Implementation files** — the file list from scope identification
 2. **Specification path** — from the plan's frontmatter (if available)
 3. **Project skill paths** — from `project_skills` in the implementation tracking file
-4. **code-quality.md path** — `../code-quality.md`
+4. **code-quality.md path** — `code-quality.md`
 5. **Topic name** — the implementation topic
 6. **Cycle number** — the current analysis cycle number (from `analysis_cycle` in the tracking file)
 
@@ -35,15 +35,15 @@ Each agent knows its own output path convention and writes findings independentl
 
 ### Agent 1: Duplication
 
-- **Agent path**: `../../../../agents/implementation-analysis-duplication.md`
+- **Agent path**: `../../../agents/implementation-analysis-duplication.md`
 
 ### Agent 2: Standards
 
-- **Agent path**: `../../../../agents/implementation-analysis-standards.md`
+- **Agent path**: `../../../agents/implementation-analysis-standards.md`
 
 ### Agent 3: Architecture
 
-- **Agent path**: `../../../../agents/implementation-analysis-architecture.md`
+- **Agent path**: `../../../agents/implementation-analysis-architecture.md`
 
 ---
 

package/skills/technical-implementation/references/{steps/invoke-executor.md → invoke-executor.md}

@@ -1,10 +1,10 @@
 # Invoke Executor
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
-This step invokes the `implementation-task-executor` agent (`../../../../agents/implementation-task-executor.md`) to implement one task.
+This step invokes the `implementation-task-executor` agent (`../../../agents/implementation-task-executor.md`) to implement one task.
 
 ---
 
@@ -12,11 +12,11 @@ This step invokes the `implementation-task-executor` agent (`../../../../agents/
 
 **Every invocation** — initial or re-attempt — includes these file paths:
 
-1. **tdd-workflow.md**: `../tdd-workflow.md`
-2. **code-quality.md**: `../code-quality.md`
+1. **tdd-workflow.md**: `tdd-workflow.md`
+2. **code-quality.md**: `code-quality.md`
 3. **Specification path**: from the plan's frontmatter (if available)
 4. **Project skill paths**: from `project_skills` in the implementation tracking file
-5. **Task content**: normalised task content (see [task-normalisation.md](../task-normalisation.md))
+5. **Task content**: normalised task content (see [task-normalisation.md](task-normalisation.md))
 6. **Linter commands**: from `linters` in the implementation tracking file (if configured)
 
 **Re-attempts after review feedback** additionally include:

package/skills/technical-implementation/references/{steps/invoke-reviewer.md → invoke-reviewer.md}

@@ -1,10 +1,10 @@
 # Invoke Reviewer
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
-This step invokes the `implementation-task-reviewer` agent (`../../../../agents/implementation-task-reviewer.md`) to independently verify a completed task.
+This step invokes the `implementation-task-reviewer` agent (`../../../agents/implementation-task-reviewer.md`) to independently verify a completed task.
 
 ---
 

package/skills/technical-implementation/references/{steps/invoke-synthesizer.md → invoke-synthesizer.md}

@@ -1,6 +1,6 @@
 # Invoke Synthesizer
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
@@ -10,11 +10,11 @@ This step invokes the synthesis agent to read analysis findings, deduplicate, an
 
 ## Invoke the Agent
 
-**Agent path**: `../../../../agents/implementation-analysis-synthesizer.md`
+**Agent path**: `../../../agents/implementation-analysis-synthesizer.md`
 
 Pass via the orchestrator's prompt:
 
-1. **Task normalization reference path** — `../task-normalisation.md`
+1. **Task normalization reference path** — `task-normalisation.md`
 2. **Topic name** — the implementation topic
 3. **Cycle number** — the current analysis cycle number
 4. **Specification path** — from the plan's frontmatter (if available)

package/skills/technical-implementation/references/{steps/invoke-task-writer.md → invoke-task-writer.md}

@@ -1,6 +1,6 @@
 # Invoke Task Writer
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
@@ -10,15 +10,15 @@ This step invokes the task writer agent to create plan tasks from approved analy
 
 ## Invoke the Agent
 
-**Agent path**: `../../../../agents/implementation-analysis-task-writer.md`
+**Agent path**: `../../../agents/implementation-analysis-task-writer.md`
 
 Pass via the orchestrator's prompt:
 
 1. **Topic name** — the implementation topic
 2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`
 3. **Plan path** — the implementation plan path
-4. **Plan format reading adapter path** — `../../../technical-planning/references/output-formats/{format}/reading.md`
-5. **Plan format authoring adapter path** — `../../../technical-planning/references/output-formats/{format}/authoring.md`
+4. **Plan format reading adapter path** — `../../technical-planning/references/output-formats/{format}/reading.md`
+5. **Plan format authoring adapter path** — `../../technical-planning/references/output-formats/{format}/authoring.md`
 
 ---
 

package/skills/technical-implementation/references/{steps/task-loop.md → task-loop.md}

@@ -1,6 +1,6 @@
 # Task Loop
 
-*Reference for **[technical-implementation](../../SKILL.md)***
+*Reference for **[technical-implementation](../SKILL.md)***
 
 ---
 
@@ -23,7 +23,7 @@ E. Update progress + commit
 
 1. Follow the format's **reading.md** instructions to determine the next available task.
 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)**.
+3. Normalise the task content following **[task-normalisation.md](task-normalisation.md)**.
 4. Reset `fix_attempts` to `0` in the implementation tracking file.
 
 ---
@@ -38,11 +38,13 @@ E. Update progress + commit
 
 ### Executor Blocked
 
-Present the executor's ISSUES to the user:
+> *Output the next fenced block as a code block:*
 
-**Task {id}: {Task Name} — {blocked/failed}**
+```
+Task {id}: {Task Name} — {blocked/failed}
 
 {executor's ISSUES content}
+```
 
 > *Output the next fenced block as markdown (not a code block):*
 
@@ -82,28 +84,25 @@ Present the executor's ISSUES to the user:
 
 Increment `fix_attempts` in the implementation tracking file.
 
-#### If `fix_gate_mode: auto` and `fix_attempts < 3`
-
-Announce the fix round (one line, no stop):
-
-**Review for Task {id}: {Task Name} — needs changes** (attempt {N}/{max 3}, fix analysis included). Re-invoking executor.
-
-→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
-
-#### If `fix_gate_mode: gated`, or `fix_attempts >= 3`
-
-If `fix_attempts >= 3`, the executor and reviewer have failed to converge. Prepend:
-
-The executor and reviewer have not converged after {N} attempts. Escalating for human review.
-
-Present the reviewer's findings and fix analysis to the user:
+> *Output the next fenced block as a code block:*
 
-**Review for Task {id}: {Task Name} — needs changes** (attempt {N})
+```
+@if(fix_attempts >= 3)
+  The executor and reviewer have not converged after {N} attempts. Escalating for human review.
+@endif
+Review for Task {id}: {Task Name} — needs changes (attempt {N})
 
 {ISSUES from reviewer, including FIX, ALTERNATIVE, and CONFIDENCE for each}
 
 Notes (non-blocking):
 {NOTES from reviewer}
+```
+
+#### If `fix_gate_mode: auto` and `fix_attempts < 3`
+
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
+
+#### If `fix_gate_mode: gated`, or `fix_attempts >= 3`
 
 > *Output the next fenced block as markdown (not a code block):*
 
@@ -112,7 +111,8 @@ Notes (non-blocking):
 - **`y`/`yes`** — Accept the review and fix analysis, pass to executor
 - **`a`/`auto`** — Accept and auto-approve future fix analyses
 - **`s`/`skip`** — Override the reviewer and proceed as-is
-- **Comment** — Any commentary, adjustments, alternative approaches, or questions before passing to executor
+- **Ask** — Ask questions about the review (doesn't accept or reject)
+- **Comment** — Accept with adjustments — pass your own direction to the executor alongside the review
 · · · · · · · · · · · ·
 ```
 
@@ -121,22 +121,31 @@ Notes (non-blocking):
 - **`y`/`yes`**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
 - **`auto`**: Note that `fix_gate_mode` should be updated to `auto` during the next commit step. → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
 - **`skip`**: → Proceed to **D. Task Gate**.
+- **Ask**: Answer the user's questions about the review. When complete, re-present the Review Changes options above. Repeat until the user selects a terminal option (`yes`, `auto`, `skip`, or Comment).
 - **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content, the reviewer's notes, and the user's commentary.
 
 ---
 
 ## D. Task Gate
 
-After the reviewer approves a task, check the `task_gate_mode` field in the implementation tracking file.
-
-### If `task_gate_mode: gated`
+After the reviewer approves a task, present the result:
 
-Present a summary and wait for user input:
+> *Output the next fenced block as a code block:*
 
-**Task {id}: {Task Name} — approved**
+```
+Task {id}: {Task Name} — approved
 
 Phase: {phase number} — {phase name}
 {executor's SUMMARY — brief commentary, decisions, implementation notes}
+```
+
+Check the `task_gate_mode` field in the implementation tracking file.
+
+#### If `task_gate_mode: auto`
+
+→ Proceed to **E. Update Progress and Commit**.
+
+#### If `task_gate_mode: gated`
 
 > *Output the next fenced block as markdown (not a code block):*
 
@@ -144,8 +153,9 @@ Phase: {phase number} — {phase name}
 · · · · · · · · · · · ·
 **Options:**
 - **`y`/`yes`** — Approve, commit, continue to next task
-- **`a`/`auto`** — Approve this and all future reviewer-approved tasks automatically
-- **Comment** — Feedback the reviewer missed (triggers a fix round)
+- **`a`/`auto`** — Approve this and all future tasks automatically (skips review prompts and questions)
+- **Ask** — Ask questions about the implementation (doesn't approve or reject)
+- **Comment** — Request changes — pass feedback or commentary (triggers a fix round)
 · · · · · · · · · · · ·
 ```
 
@@ -153,15 +163,8 @@ Phase: {phase number} — {phase name}
 
 - **`y`/`yes`**: → Proceed to **E. Update Progress and Commit**.
 - **`auto`**: Note that `task_gate_mode` should be updated to `auto` during the commit step. → Proceed to **E. Update Progress and Commit**.
-- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's notes.
-
-### If `task_gate_mode: auto`
-
-Announce the result (one line, no stop):
-
-**Task {id}: {Task Name} — approved** (phase {N}: {phase name}, {brief summary}). Committing.
-
-→ Proceed to **E. Update Progress and Commit**.
+- **Ask**: Answer the user's questions about the implementation. When complete, re-present the Task Gate options above. Repeat until the user selects a terminal option (`yes`, `auto`, or Comment).
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's feedback.
 
 ---
 
@@ -195,6 +198,10 @@ This is the end of this iteration.
 
 ## When All Tasks Are Complete
 
-"All tasks complete. {M} tasks implemented."
+> *Output the next fenced block as a code block:*
+
+```
+All tasks complete. {M} tasks implemented.
+```
 
 → Return to the skill for **Step 7**.