@leeovery/claude-technical-workflows 2.1.34 → 2.1.36

package/skills/technical-planning/references/author-tasks.md

@@ -4,13 +4,25 @@
 
 ---
 
-This step uses the `planning-task-author` agent (`../../../agents/planning-task-author.md`) to write full detail for a single task. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-task-author` agent (`../../../agents/planning-task-author.md`) to write full detail for all tasks in a phase. One sub-agent authors all tasks, writing to a scratch file. The orchestrator then handles per-task approval and format-specific writing to the plan.
 
 ---
 
-## Author the Task
+## Section 1: Prepare the Scratch File
 
-### Invoke the Agent
+Scratch file path: `docs/workflow/.cache/planning/{topic}/phase-{N}.md`
+
+Create the `docs/workflow/.cache/planning/{topic}/` directory if it does not exist.
+
+---
+
+## Section 2: Invoke the Agent (Batch)
+
+> *Output the next fenced block as a code block:*
+
+```
+Authoring {count} tasks for Phase {N}: {Phase Name}...
+```
 
 Invoke `planning-task-author` with these file paths:
 
@@ -19,36 +31,65 @@ Invoke `planning-task-author` with these file paths:
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
 4. **task-design.md**: `task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
-6. **Task list for current phase**: the approved task table
-7. **Target task**: the task name, edge cases, and ID from the table
-8. **Output format authoring reference**: path to the format's `authoring.md` (e.g., `output-formats/{format}/authoring.md`)
+6. **Task list for current phase**: the approved task table (ALL tasks in the phase)
+7. **Scratch file path**: `docs/workflow/.cache/planning/{topic}/phase-{N}.md`
 
-### Check Gate Mode
+The agent writes all tasks to the scratch file and returns.
 
-The agent returns complete task detail following the task template from task-design.md. What the user sees is what gets logged.
+---
 
-> *Output the next fenced block as markdown (not a code block):*
+## Section 3: Validate Scratch File
 
-```
-{task detail from planning-task-author agent}
-```
+Read the scratch file and count tasks. Verify task count matches the task table in the Plan Index File for this phase.
+
+#### If mismatch
+
+Re-invoke the agent with the same inputs.
+
+#### If valid
+
+→ Proceed to **Section 4**.
+
+---
+
+## Section 4: Check Gate Mode
 
 Check `author_gate_mode` in the Plan Index File frontmatter.
 
 #### If `author_gate_mode: auto`
 
-**Auto mode removes the approval pause — not the sequential process.** Each task is still invoked, authored, and logged one at a time, in order. Do not batch, skip ahead, or create multiple tasks concurrently.
-
 > *Output the next fenced block as a code block:*
 
 ```
-Task {M} of {total}: {Task Name} — authored. Logging to plan.
+Phase {N}: {count} tasks authored. Auto-approved. Writing to plan.
 ```
 
-→ Skip to **If approved** below.
+→ Jump to **Section 6**.
 
 #### If `author_gate_mode: gated`
 
+→ Enter **Section 5**.
+
+---
+
+## Section 5: Approval Loop
+
+For each task in the scratch file, in order:
+
+#### If task status is `approved`
+
+Skip — already approved from a previous pass.
+
+#### If task status is `pending`
+
+Present the full task content:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+{task detail from scratch file}
+```
+
 **Task {M} of {total}: {Task Name}**
 
 > *Output the next fenced block as markdown (not a code block):*
@@ -56,8 +97,8 @@ Task {M} of {total}: {Task Name} — authored. Logging to plan.
 ```
 · · · · · · · · · · · ·
 **To proceed:**
-- **`y`/`yes`** — Approved. I'll log it to the plan.
-- **`a`/`auto`** — Approve this and all remaining task authoring gates automatically
+- **`y`/`yes`** — Approved. I'll write it to the plan.
+- **`a`/`auto`** — Approve this and all remaining tasks automatically
 - **Or tell me what to change.**
 - **Or navigate** — a different phase or task, or the leading edge.
 · · · · · · · · · · · ·
@@ -65,36 +106,69 @@ Task {M} of {total}: {Task Name} — authored. Logging to plan.
 
 **STOP.** Wait for the user's response.
 
+#### If approved (`y`/`yes`)
+
+Mark the task `approved` in the scratch file. Continue to the next task.
+
+#### If `auto`
+
+Mark the task `approved` in the scratch file. Set all remaining `pending` tasks to `approved`. Update `author_gate_mode: auto` in the Plan Index File frontmatter.
+
+→ Jump to **Section 6**.
+
 #### If the user provides feedback
 
-Re-invoke `planning-task-author` with all original inputs PLUS:
-- **Previous output**: the current task detail
-- **User feedback**: what the user wants changed
+Mark the task `rejected` in the scratch file and add the feedback as a blockquote:
 
-Present the revised task in full. Ask the same choice again. Repeat until approved.
+```markdown
+## {task-id} | rejected
+
+> **Feedback**: {user's feedback here}
+
+### Task {seq}: {Task Name}
+...
+```
+
+Continue to the next task.
 
 #### If the user navigates
 
-→ Return to **Plan Construction**.
+→ Return to **Plan Construction**. The scratch file preserves approval state.
 
-#### If `auto`
+---
+
+### Section 5b: Revision
 
-Note that `author_gate_mode` should be updated to `auto` during the commit step below.
+After completing the approval loop, check for rejected tasks.
 
-→ Proceed to **If approved** below.
+#### If no rejected tasks
 
-#### If approved (`y`/`yes` or `auto`)
+→ Proceed to **Section 6**.
 
-> **CHECKPOINT**: If `author_gate_mode: gated`, verify before logging: (1) You presented this exact content, (2) The user explicitly approved with `y`/`yes` or equivalent — not a question, comment, or "okay" in passing, (3) You are writing exactly what was approved with no modifications.
+#### If rejected tasks exist
 
-See **[plan-index-schema.md](plan-index-schema.md)** for field definitions and lifecycle.
+> *Output the next fenced block as a code block:*
+
+```
+{N} tasks need revision. Re-invoking author agent...
+```
+
+→ Return to **Section 2**. The agent receives the scratch file with rejected tasks and feedback, rewrites only those, and the flow continues through validation, gate check, and approval as normal.
+
+---
+
+## Section 6: Write to Plan
 
-1. Write the task to the output format (format-specific — see authoring.md)
-2. If the Plan Index File frontmatter `ext_id` is empty, set it to the external identifier for the plan as exposed by the output format.
-3. If the current phase's `ext_id` is empty, set it to the external identifier for the phase as exposed by the output format.
-4. Update the task table in the Plan Index File: set `status: authored` and set `Ext ID` to the external identifier for the task as exposed by the output format.
-5. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
-6. If user chose `auto` at this gate: update `author_gate_mode: auto` in the Plan Index File frontmatter
+> **CHECKPOINT**: If `author_gate_mode: gated`, verify all tasks in the scratch file are marked `approved` before writing.
+
+For each approved task in the scratch file, in order:
+
+1. Read the task content from the scratch file
+2. Write to the output format (format-specific — see the format's **[authoring.md](output-formats/{format}/authoring.md)**)
+3. Update the task table in the Plan Index File: set `status: authored` and set `Ext ID` to the external identifier for the task as exposed by the output format
+4. If the Plan Index File frontmatter `ext_id` is empty, set it to the external identifier for the plan as exposed by the output format
+5. If the current phase's `ext_id` is empty, set it to the external identifier for the phase as exposed by the output format
+6. Advance the `planning:` block in frontmatter to the next pending task (or next phase if this was the last task)
 7. Commit: `planning({topic}): author task {task-id} ({task name})`
 
 > *Output the next fenced block as a code block:*
@@ -103,4 +177,14 @@ See **[plan-index-schema.md](plan-index-schema.md)** for field definitions and l
 Task {M} of {total}: {Task Name} — authored.
 ```
 
+Repeat for each task.
+
+---
+
+## Section 7: Cleanup
+
+Delete the scratch file: `rm docs/workflow/.cache/planning/{topic}/phase-{N}.md`
+
+Remove the `docs/workflow/.cache/planning/{topic}/` directory if empty.
+
 → Return to **Plan Construction**.

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

@@ -39,8 +39,9 @@ tick init
 Add to `.gitignore`:
 
 ```
-.tick/.store
+.tick/cache.db
 .tick/lock
+.tick/.tasks-*.jsonl.tmp
 ```
 
 ## Structure Mapping
@@ -66,7 +67,7 @@ Tasks are stored in a `.tick/` directory at the project root:
 ```
 .tick/
 ├── tasks.jsonl     # Append-only source of truth (git-friendly)
-├── .store          # SQLite cache (auto-rebuilt, do not commit)
+├── cache.db        # SQLite query cache (auto-rebuilt, do not commit)
 └── lock            # File lock for concurrent access
 ```
 

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

@@ -2,6 +2,8 @@
 
 Tick has native support for priority and blocking dependencies with cycle detection. This file is used by the graphing agent after all tasks have been authored.
 
+**Natural ordering principle**: Tasks execute in natural order (by priority, then creation date) when no dependencies override it. The dependency grapher only adds edges that change execution order — if tasks are already in the right sequence, explicit dependencies add noise without value. See also the dependency grapher agent's "When NOT to add a dependency" rules.
+
 ## Priority
 
 | Level | Name | Value |

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

@@ -59,3 +59,5 @@ tick ready --parent <topic-id>
 ```
 
 If `tick ready` returns no results, either all tasks are complete or remaining tasks are blocked.
+
+**Natural ordering convention**: `tick ready` always returns results in the correct execution order — by priority, then creation date. Consumers should take the first result as the next task. Because creation date preserves authoring order, sequential intra-phase tasks execute in natural order without needing explicit dependencies. Only add dependencies when the correct order differs from the natural order.

package/skills/technical-planning/references/plan-construction.md

@@ -118,31 +118,27 @@ Phase {N}: {Phase Name} — task list confirmed. Proceeding to authoring.
 
 ## Author Tasks for the Phase
 
-Work through each task in the phase's task table, in order.
+Tasks are authored in a single batch per phase. One sub-agent authors all tasks for the phase, writing to a scratch file. The orchestrator then handles approval and writing to the plan format. Never invoke multiple authoring agents concurrently. Never batch beyond a single phase.
 
-### Sequential authoring (mandatory)
+#### If all tasks in the phase have status `authored`
 
-Tasks **must** be authored one at a time, in order. Each task's authored detail builds context for the next — later tasks benefit from decisions, patterns, and structure established by earlier ones. This applies regardless of gate mode. Auto-gate removes the approval pause, not the sequential process.
-
-**Never** invoke multiple Step B agents concurrently. **Never** batch or skip ahead.
-
-#### If the task status is `authored`
-
-Already written.
+All tasks already written.
 
 > *Output the next fenced block as a code block:*
 
 ```
-Task {M} of {total}: {Task Name} — already authored.
+Phase {N}: {Phase Name} — all tasks already authored.
 ```
 
-Continue to the next task.
+→ Continue to the next phase.
+
+#### If any tasks in the phase have status `pending`
 
-#### If the task status is `pending`
+→ Go to **Step B** for the entire phase.
 
-→ Go to **Step B** with this task.
+After Step B returns, all tasks in the phase are authored.
 
-After Step B returns, the task is authored. Continue to the next task.
+If the user navigates mid-approval, the scratch file preserves approval state. On return, resume from the first non-approved task.
 
 #### When all tasks in the phase are authored
 
@@ -178,4 +174,4 @@ Load **[define-tasks.md](define-tasks.md)** and follow its instructions as writt
 
 ## Step B: Author Tasks
 
-Load **[author-tasks.md](author-tasks.md)** and follow its instructions as written. This step authors **one task** and returns.
+Load **[author-tasks.md](author-tasks.md)** and follow its instructions as written. This step authors **all tasks for the phase** via a batch agent and returns.

package/skills/technical-planning/references/review-integrity.md

@@ -47,7 +47,7 @@ Read the plan end-to-end — carefully, as if you were about to implement it. Fo
    - Task dependencies are explicit and correct — each dependency reflects a genuine data or capability requirement
    - No circular dependencies exist in the task graph
    - Priority assignments reflect graph position — foundation tasks and tasks that unblock others are prioritised appropriately
-   - An implementer can determine execution order from the dependency graph and priorities alone
+   - Tasks within a phase execute in natural order (by task ID) unless dependencies or priorities override it. Do not flag missing dependencies for sequential intra-phase tasks where natural order already produces the correct sequence. Only flag dependency issues where: execution would happen in the wrong order without an explicit dependency, a cross-phase dependency is missing, or a convergence point (task needing multiple predecessors) lacks explicit edges.
 
 5. **Task Self-Containment**
    - Each task contains all context needed for execution

package/skills/technical-review/SKILL.md

@@ -129,25 +129,15 @@ Load **[invoke-task-verifiers.md](references/invoke-task-verifiers.md)** and fol
 
 ---
 
-## Step 4: Product Assessment
-
-Load **[invoke-product-assessor.md](references/invoke-product-assessor.md)** and follow its instructions as written.
-
-**STOP.** Do not proceed until the product assessor has returned.
-
-→ Proceed to **Step 5**.
-
----
-
-## Step 5: Produce Review
+## Step 4: Produce Review
 
 Load **[produce-review.md](references/produce-review.md)** and follow its instructions as written.
 
-→ Proceed to **Step 6**.
+→ Proceed to **Step 5**.
 
 ---
 
-## Step 6: Review Actions
+## Step 5: Review Actions
 
 Load **[review-actions-loop.md](references/review-actions-loop.md)** and follow its instructions.
 

package/skills/technical-review/references/invoke-review-synthesizer.md

@@ -26,9 +26,9 @@ Dispatch **one agent** via the Task tool.
 
 The synthesizer receives:
 
-1. **Review scope** — single or multi, with plan list
-2. **Review paths** — paths to `r{N}/` directories (include summary, QA directory, product assessment)
-3. **Specification path(s)** — from each plan's frontmatter
+1. **Plan topic** — the plan being synthesized
+2. **Review path** — path to `r{N}/` directory (review summary + QA files)
+3. **Specification path** — from the plan's frontmatter
 4. **Cycle number** — the review remediation cycle number
 
 ---

package/skills/technical-review/references/invoke-task-verifiers.md

@@ -35,13 +35,7 @@ From each plan in scope, list every task across all phases:
 Ensure the review output directory exists:
 
 ```bash
-mkdir -p docs/workflow/review/{scope}/r{N}
-```
-
-For multi-plan reviews, also create per-plan subdirectories:
-
-```bash
-mkdir -p docs/workflow/review/{scope}/r{N}/{plan-topic}
+mkdir -p docs/workflow/review/{topic}/r{N}
 ```
 
 ---
@@ -66,10 +60,9 @@ Each verifier receives:
 3. **Plan path** — the full plan for phase context
 4. **Project skill paths** — from Step 2 discovery
 5. **Review checklist path** — `skills/technical-review/references/review-checklist.md`
-6. **Review scope** — scope directory name for output path
+6. **Topic** — the plan topic name (used for output directory)
 7. **Review number** — version number (e.g., 1 for `r1/`)
-8. **Plan topic** — for multi-plan reviews, the plan-specific subdirectory name
-9. **Task index** — sequential number for file naming (1, 2, 3...)
+8. **Task index** — sequential number for file naming (1, 2, 3...)
 
 If any verifier fails (error, timeout), record the failure and continue — aggregate what's available.
 
@@ -85,7 +78,7 @@ FINDINGS_COUNT: {N blocking issues}
 SUMMARY: {1 sentence}
 ```
 
-Full findings are written to `docs/workflow/review/{scope}/r{N}/qa-task-{index}.md` (single-plan) or `docs/workflow/review/{scope}/r{N}/{plan-topic}/qa-task-{index}.md` (multi-plan).
+Full findings are written to `docs/workflow/review/{topic}/r{N}/qa-task-{index}.md`.
 
 ---
 
@@ -93,7 +86,7 @@ Full findings are written to `docs/workflow/review/{scope}/r{N}/qa-task-{index}.
 
 Once all batches have completed:
 
-1. Read all `docs/workflow/review/{scope}/r{N}/qa-task-*.md` files (and `{scope}/r{N}/{plan-topic}/qa-task-*.md` for multi-plan)
+1. Read all `docs/workflow/review/{topic}/r{N}/qa-task-*.md` files
 2. Synthesize findings from file contents:
    - Collect all tasks with `STATUS: Incomplete` or `STATUS: Issues Found` as blocking issues
    - Collect all test issues (under/over-tested)

package/skills/technical-review/references/produce-review.md

@@ -4,17 +4,15 @@
 
 ---
 
-Aggregate findings from both stages into a review document using the **[template.md](template.md)**.
+Aggregate QA findings into a review document using the **[template.md](template.md)**.
 
-Write the review to `docs/workflow/review/{scope}/r{N}/review.md`. The review scope `{scope}` is the topic name (single) or a descriptive scope name (multi/all). The review number `r{N}` is passed in from the entry point.
+Write the review to `docs/workflow/review/{topic}/r{N}/review.md`. The review is always per-plan. The review number `r{N}` is passed in from the entry point.
 
 **QA Verdict** (from Step 3):
 - **Approve** — All acceptance criteria met, no blocking issues
 - **Request Changes** — Missing requirements, broken functionality, inadequate tests
 - **Comments Only** — Minor suggestions, non-blocking observations
 
-**Product Assessment** (from Step 4) — always advisory, presented alongside the verdict.
-
 Commit: `review({topic}): complete review`
 
 Present the review to the user.

package/skills/technical-review/references/review-actions-loop.md

@@ -122,23 +122,19 @@ No actionable tasks synthesized.
 
 ## C. Approval Gate
 
-Read the staging file from `docs/workflow/implementation/{primary-topic}/review-tasks-c{cycle-number}.md`.
+Read the staging file from `docs/workflow/implementation/{topic}/review-tasks-c{cycle-number}.md`.
 
 Check `gate_mode` in the staging file frontmatter (`gated` or `auto`).
 
-Present an overview. For multi-plan reviews, group tasks by plan:
+Present an overview:
 
 > *Output the next fenced block as a code block:*
 
 ```
 Review synthesis cycle {N}: {K} proposed tasks
 
-{plan-topic}:
   1. {title} ({severity})
   2. {title} ({severity})
-
-{plan-topic-2}:
-  3. {title} ({severity})
 ```
 
 Then present each task with `status: pending` individually:
@@ -146,7 +142,7 @@ Then present each task with `status: pending` individually:
 > *Output the next fenced block as markdown (not a code block):*
 
 ```
-**Task {current}/{total}: {title}** ({severity}) — Plan: {plan-topic}
+**Task {current}/{total}: {title}** ({severity})
 Sources: {sources}
 
 **Problem**: {problem}
@@ -225,7 +221,7 @@ After all tasks processed:
 Commit the staging file updates:
 
 ```
-review({scope}): synthesis cycle {N} — tasks skipped
+review({topic}): synthesis cycle {N} — tasks skipped
 ```
 
 **STOP.** Do not proceed — terminal condition.
@@ -234,22 +230,18 @@ review({scope}): synthesis cycle {N} — tasks skipped
 
 ## D. Create Tasks in Plan
 
-For each plan that has approved tasks in the staging file, invoke the task writer.
-
-Process plans sequentially — each writes to a different plan.
-
-For each plan:
+For approved tasks in the staging file, invoke the task writer.
 
-1. Filter staging file to tasks with `plan: {plan-topic}` and `status: approved`
+1. Filter staging file to tasks with `status: approved`
 2. Load **[invoke-review-task-writer.md](invoke-review-task-writer.md)** and follow its instructions
-3. Wait for the task writer to return before processing the next plan
+3. Wait for the task writer to return
 
-**STOP.** Do not proceed until all task writers have returned.
+**STOP.** Do not proceed until the task writer has returned.
 
 Commit all changes (staging file, plan tasks, Plan Index Files):
 
 ```
-review({scope}): add review remediation ({K} tasks across {P} plans)
+review({topic}): add review remediation ({K} tasks)
 ```
 
 → Proceed to **E. Re-open Implementation + Plan Mode Handoff**.
@@ -269,19 +261,19 @@ For each plan that received new tasks:
 3. Commit tracking changes:
 
 ```
-review({scope}): re-open implementation tracking
+review({topic}): re-open implementation tracking
 ```
 
 Then enter plan mode and write the following plan:
 
 ```
-# Review Actions Complete: {scope}
+# Review Actions Complete: {topic}
 
 Review findings have been synthesized into {N} implementation tasks.
 
 ## Summary
 
-{Per-plan summary, e.g., "tick-core: 3 tasks in Phase 9", "installation: 1 task in Phase 6"}
+{Summary, e.g., "tick-core: 3 tasks in Phase 9"}
 
 ## Instructions
 
@@ -290,9 +282,9 @@ Review findings have been synthesized into {N} implementation tasks.
 
 ## Context
 
-- Plans updated: {list of plan topics}
+- Plan updated: {topic}
 - Tasks created: {total count}
-- Implementation tracking: re-opened for each plan
+- Implementation tracking: re-opened
 
 ## How to proceed
 

package/skills/technical-review/references/template.md

@@ -9,7 +9,7 @@
 ```markdown
 # Implementation Review: {Topic / Product}
 
-**Scope**: Single Plan ({plan}) | Multi-Plan ({plans}) | Full Product
+**Plan**: {topic}
 **QA Verdict**: Approve | Request Changes | Comments Only
 
 ## Summary
@@ -34,26 +34,6 @@
 ### Required Changes (if any)
 1. [Specific actionable change]
 
-## Product Assessment
-
-### Robustness
-[Where would this break under real-world usage?]
-
-### Gaps
-[What's obviously missing now the product exists?]
-
-### Cross-Plan Consistency (multi/all only)
-[Are patterns consistent across features?]
-
-### Integration Seams (multi/all only)
-[Do independently-built features connect cleanly?]
-
-### Strengthening Opportunities
-[Priority improvements for production readiness]
-
-### What's Next
-[What does this enable? What should be built next?]
-
 ## Recommendations
 [Combined non-blocking suggestions]
 ```