@leeovery/claude-technical-workflows 2.1.33 → 2.1.35

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

@@ -0,0 +1,64 @@
+# Invoke Review Synthesizer
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step dispatches a `review-findings-synthesizer` agent to read review findings, deduplicate, group, and normalize them into proposed tasks.
+
+---
+
+## Determine Cycle Number
+
+Count existing `review-tasks-c*.md` files in `docs/workflow/implementation/{primary-topic}/` and add 1.
+
+```bash
+ls docs/workflow/implementation/{primary-topic}/review-tasks-c*.md 2>/dev/null | wc -l
+```
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../agents/review-findings-synthesizer.md`
+
+Dispatch **one agent** via the Task tool.
+
+The synthesizer receives:
+
+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
+
+---
+
+## Wait for Completion
+
+**STOP.** Do not proceed until the synthesizer has returned.
+
+If the agent fails (error, timeout), record the failure and report "synthesis failed" to the user.
+
+---
+
+## Commit Findings
+
+Commit the report and staging file (if created):
+
+```
+review({scope}): synthesis cycle {N} — findings
+```
+
+---
+
+## Expected Result
+
+The synthesizer returns:
+
+```
+STATUS: tasks_proposed | clean
+TASKS_PROPOSED: {N}
+SUMMARY: {1-2 sentences}
+```
+
+The full report is at `docs/workflow/implementation/{primary-topic}/review-report-c{N}.md`. If tasks were proposed, the staging file is at `docs/workflow/implementation/{primary-topic}/review-tasks-c{N}.md`.

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

@@ -0,0 +1,44 @@
+# Invoke Review Task Writer
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+This step invokes the task writer agent to create plan tasks from approved review findings. It reuses the `implementation-analysis-task-writer` agent with a review-specific phase label.
+
+---
+
+## Determine Format
+
+Read the `format` field from the plan's frontmatter (`docs/workflow/planning/{topic}/plan.md`). This determines which output format adapters to pass to the agent.
+
+---
+
+## Invoke the Agent
+
+**Agent path**: `../../../agents/implementation-analysis-task-writer.md`
+
+Pass via the orchestrator's prompt:
+
+1. **Topic name** — the implementation topic (scopes tasks to correct plan)
+2. **Staging file path** — `docs/workflow/implementation/{topic}/review-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`
+6. **plan-index-schema.md** — `../../technical-planning/references/plan-index-schema.md`
+7. **Phase label** — `Review Remediation (Cycle {N})`
+
+---
+
+## Expected Result
+
+The agent creates tasks in the plan for all approved entries in the staging file.
+
+Returns a brief status:
+
+```
+STATUS: complete
+TASKS_CREATED: {N}
+PHASE: {N}
+SUMMARY: {1 sentence}
+```

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

@@ -32,10 +32,10 @@ From each plan in scope, list every task across all phases:
 
 ## Create Output Directory
 
-For each topic in scope, ensure the review output directory exists:
+Ensure the review output directory exists:
 
 ```bash
-mkdir -p docs/workflow/review/{topic}
+mkdir -p docs/workflow/review/{topic}/r{N}
 ```
 
 ---
@@ -60,8 +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. **Topic name** — for output file path
-7. **Task index** — sequential number for file naming (1, 2, 3...)
+6. **Topic** — the plan topic name (used for output directory)
+7. **Review number** — version number (e.g., 1 for `r1/`)
+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.
 
@@ -77,7 +78,7 @@ FINDINGS_COUNT: {N blocking issues}
 SUMMARY: {1 sentence}
 ```
 
-Full findings are written to `docs/workflow/review/{topic}/qa-task-{index}.md`.
+Full findings are written to `docs/workflow/review/{topic}/r{N}/qa-task-{index}.md`.
 
 ---
 
@@ -85,7 +86,7 @@ Full findings are written to `docs/workflow/review/{topic}/qa-task-{index}.md`.
 
 Once all batches have completed:
 
-1. Read all `docs/workflow/review/{topic}/qa-task-*.md` files
+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

@@ -0,0 +1,25 @@
+# Produce Review
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+Aggregate QA findings into a review document using the **[template.md](template.md)**.
+
+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
+
+Commit: `review({topic}): complete review`
+
+Present the review to the user.
+
+Your review feedback can be:
+- Addressed by implementation (same or new session)
+- Delegated to an agent for fixes
+- Overridden by user ("ship it anyway")
+
+You produce feedback. User decides what to do with it.

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

@@ -0,0 +1,295 @@
+# Review Actions Loop
+
+*Reference for **[technical-review](../SKILL.md)***
+
+---
+
+After a review is complete, this loop synthesizes findings into actionable tasks.
+
+Stages A through E run sequentially. Always start at **A. Verdict Gate**.
+
+```
+A. Verdict gate (check verdicts, offer synthesis)
+B. Dispatch review synthesizer → invoke-review-synthesizer.md
+C. Approval gate (present tasks, approve/skip/comment)
+D. Create tasks in plan → invoke-review-task-writer.md
+E. Re-open implementation + plan mode handoff
+```
+
+---
+
+## A. Verdict Gate
+
+Check the verdict(s) from the review(s) being analyzed.
+
+#### If all verdicts are "Approve" with no required changes
+
+> *Output the next fenced block as a code block:*
+
+```
+No actionable findings. All reviews passed with no required changes.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If any verdict is "Request Changes"
+
+Blocking issues exist. Synthesis is strongly recommended.
+
+> *Output the next fenced block as a code block:*
+
+```
+The review found blocking issues that require changes.
+Synthesizing findings into actionable tasks is recommended.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Synthesize findings into tasks *(recommended)*
+- **`n`/`no`** — Skip synthesis
+
+Proceed with synthesis?
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If yes
+
+→ Proceed to **B. Dispatch Review Synthesizer**.
+
+#### If no
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If verdict is "Comments Only"
+
+Non-blocking improvements only. Synthesis is optional.
+
+> *Output the next fenced block as a code block:*
+
+```
+The review found non-blocking suggestions only.
+You can synthesize these into tasks or skip.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`y`/`yes`** — Synthesize findings into tasks
+- **`n`/`no`** — Skip synthesis *(default)*
+
+Synthesize non-blocking findings?
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If yes
+
+→ Proceed to **B. Dispatch Review Synthesizer**.
+
+#### If no
+
+**STOP.** Do not proceed — terminal condition.
+
+---
+
+## B. Dispatch Review Synthesizer
+
+Load **[invoke-review-synthesizer.md](invoke-review-synthesizer.md)** and follow its instructions.
+
+**STOP.** Do not proceed until the synthesizer has returned.
+
+#### If STATUS is "clean"
+
+> *Output the next fenced block as a code block:*
+
+```
+No actionable tasks synthesized.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If STATUS is "tasks_proposed"
+
+→ Proceed to **C. Approval Gate**.
+
+---
+
+## C. Approval Gate
+
+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:
+
+> *Output the next fenced block as a code block:*
+
+```
+Review synthesis cycle {N}: {K} proposed tasks
+
+  1. {title} ({severity})
+  2. {title} ({severity})
+```
+
+Then present each task with `status: pending` individually:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+**Task {current}/{total}: {title}** ({severity})
+Sources: {sources}
+
+**Problem**: {problem}
+**Solution**: {solution}
+**Outcome**: {outcome}
+
+**Do**:
+{steps}
+
+**Acceptance Criteria**:
+{criteria}
+
+**Tests**:
+{tests}
+```
+
+#### If gate_mode is "gated"
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`a`/`approve`** — Approve this task
+- **`auto`** — Approve this and all remaining tasks automatically
+- **`s`/`skip`** — Skip this task
+- **Comment** — Revise based on feedback
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user input.
+
+#### If gate_mode is "auto"
+
+> *Output the next fenced block as a code block:*
+
+```
+Task {current} of {total}: {title} — approved (auto).
+```
+
+→ Continue to next task without stopping.
+
+---
+
+Process user input:
+
+#### If `approve`
+
+Update `status: approved` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If `auto`
+
+Update `status: approved` in the staging file. Update `gate_mode: auto` in the staging file frontmatter.
+
+→ Continue processing remaining tasks without stopping.
+
+#### If `skip`
+
+Update `status: skipped` in the staging file.
+
+→ Present the next pending task, or proceed to routing below if all tasks processed.
+
+#### If comment
+
+Revise the task content in the staging file based on the user's feedback. Re-present this task.
+
+---
+
+After all tasks processed:
+
+→ If any tasks have `status: approved`, proceed to **D. Create Tasks in Plan**.
+
+→ If all tasks were skipped:
+
+Commit the staging file updates:
+
+```
+review({topic}): synthesis cycle {N} — tasks skipped
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+---
+
+## D. Create Tasks in Plan
+
+For approved tasks in the staging file, invoke the task writer.
+
+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
+
+**STOP.** Do not proceed until the task writer has returned.
+
+Commit all changes (staging file, plan tasks, Plan Index Files):
+
+```
+review({topic}): add review remediation ({K} tasks)
+```
+
+→ Proceed to **E. Re-open Implementation + Plan Mode Handoff**.
+
+---
+
+## E. Re-open Implementation + Plan Mode Handoff
+
+For each plan that received new tasks:
+
+1. Read the implementation tracking file at `docs/workflow/implementation/{topic}/tracking.md`
+2. Update frontmatter:
+   - `status: in-progress`
+   - Remove `completed` field (if present)
+   - `updated: {today's date}`
+   - `analysis_cycle: 0`
+3. Commit tracking changes:
+
+```
+review({topic}): re-open implementation tracking
+```
+
+Then enter plan mode and write the following plan:
+
+```
+# Review Actions Complete: {topic}
+
+Review findings have been synthesized into {N} implementation tasks.
+
+## Summary
+
+{Summary, e.g., "tick-core: 3 tasks in Phase 9"}
+
+## Instructions
+
+1. Invoke `/start-implementation`
+2. The skill will detect the new tasks and start executing them
+
+## Context
+
+- Plan updated: {topic}
+- Tasks created: {total count}
+- Implementation tracking: re-opened
+
+## How to proceed
+
+Clear context and continue. Claude will start implementation
+and pick up the new review remediation tasks automatically.
+```
+
+Exit plan mode. The user will approve and clear context, and the fresh session will pick up with `/start-implementation` routing to the new tasks.

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]
 ```

package/agents/review-product-assessor.md

@@ -1,112 +0,0 @@
----
-name: review-product-assessor
-description: Evaluates implementation holistically as a product — robustness, gaps, cross-plan consistency, and forward-looking assessment. Invoked by technical-review skill during product assessment stage.
-tools: Read, Glob, Grep, Bash
-model: opus
----
-
-# Review: Product Assessor
-
-You are evaluating an implementation as a product. Not task-by-task correctness (QA handles that) — you're assessing whether the product is robust, complete, and ready. You bring a holistic, forward-looking perspective.
-
-## Your Input
-
-You receive via the orchestrator's prompt:
-
-1. **Implementation files** — all files in scope
-2. **Specification path(s)** — validated specification(s) for design context
-3. **Plan path(s)** — implementation plan(s) for scope context
-4. **Project skill paths** — relevant `.claude/skills/` paths for framework conventions
-5. **Review scope** — one of: `single-plan`, `multi-plan`, `full-product`
-
-## Your Focus
-
-### For all scopes:
-
-- **Robustness** — Where would this break under real-world usage? Missing error handling, untested failure modes, fragile assumptions, edge cases the spec didn't cover
-- **Gaps** — What's obviously missing now the product exists? Things a real user would expect
-- **Strengthening** — Performance, security, scalability concerns visible only at the whole-product level
-- **What's next** — What does this enable? What should be built next?
-
-### Additional for multi-plan / full-product scope:
-
-- **Cross-plan consistency** — Are patterns consistent across independently-planned features? Same error handling, logging, configuration approaches?
-- **Integration seams** — Do the independently-built features connect cleanly? Shared types, compatible APIs, no conflicting assumptions?
-- **Missing shared concerns** — Are there utilities, middleware, or abstractions that should exist but don't because each plan was developed independently?
-- **Architectural coherence** — Does the product feel like one system or a collection of separate features?
-
-## Your Process
-
-1. **Read project skills** — understand framework conventions and architecture patterns
-2. **Read specification(s)** — understand design intent and boundaries
-3. **Read plan(s)** — understand what was built and the scope of each plan
-4. **Read all implementation files** — understand the full picture
-5. **Assess as a product** — evaluate holistically against focus areas
-6. **Write findings** to `docs/workflow/review/{topic-or-scope}/product-assessment.md`
-
-For multi-plan/full-product scope, use a descriptive scope name (e.g., `full-product` or a hyphenated list of topic names).
-
-## Hard Rules
-
-**MANDATORY. No exceptions.**
-
-1. **No git writes** — do not commit or stage. Writing the output file is your only file write.
-2. **No code edits** — read-only analysis. Do not modify implementation files.
-3. **Holistic perspective** — evaluate as a product, not task-by-task
-4. **Forward-looking** — assess the product as it stands. Do not re-litigate implementation decisions.
-5. **Proportional** — high-impact observations only. Not minor preferences.
-6. **Scope-aware** — cross-plan findings only for multi-plan/full-product scope. Don't fabricate cross-cutting issues for single-plan reviews.
-
-## Output File Format
-
-Write to `docs/workflow/review/{topic-or-scope}/product-assessment.md`:
-
-```
-SCOPE: {single-plan | multi-plan | full-product}
-PLANS_REVIEWED: {list}
-
-ROBUSTNESS:
-- {observation with file:line references}
-
-GAPS:
-- {what's missing with reasoning}
-
-INTEGRATION: (multi-plan/full-product only)
-- {cross-plan observations}
-
-CONSISTENCY: (multi-plan/full-product only)
-- {pattern inconsistencies across plans}
-
-STRENGTHENING:
-- {priority improvements}
-
-NEXT_STEPS:
-- {recommendations with priority}
-
-SUMMARY: {1-2 paragraph product readiness assessment}
-```
-
-If no significant findings:
-
-```
-SCOPE: {scope}
-PLANS_REVIEWED: {list}
-
-ROBUSTNESS: No significant concerns
-GAPS: No obvious gaps
-STRENGTHENING: No priority improvements identified
-NEXT_STEPS:
-- {recommendations}
-
-SUMMARY: {1-2 paragraph assessment}
-```
-
-## Your Output
-
-Return a brief status to the orchestrator:
-
-```
-STATUS: findings | clean
-FINDINGS_COUNT: {N}
-SUMMARY: {1 sentence}
-```

package/skills/technical-review/references/invoke-product-assessor.md

@@ -1,57 +0,0 @@
-# Invoke Product Assessor
-
-*Reference for **[technical-review](../SKILL.md)***
-
----
-
-This step dispatches a single `review-product-assessor` agent to evaluate the implementation holistically as a product. This is not task-by-task — the assessor evaluates robustness, gaps, and product readiness.
-
----
-
-## Identify Scope
-
-Determine the review scope indicator to pass to the assessor:
-
-- **single-plan** — one plan selected
-- **multi-plan** — multiple plans selected
-- **full-product** — all implemented plans
-
-Build the full list of implementation files across all plans in scope (same git history approach as QA verification).
-
----
-
-## Dispatch Assessor
-
-Dispatch **one agent** via the Task tool.
-
-- **Agent path**: `../../../agents/review-product-assessor.md`
-
-The assessor receives:
-
-1. **Implementation files** — all files in scope (the full list, not summarized)
-2. **Specification path(s)** — from each plan's frontmatter
-3. **Plan path(s)** — all plans in scope
-4. **Project skill paths** — from Step 2 discovery
-5. **Review scope** — one of: `single-plan`, `multi-plan`, `full-product`
-
----
-
-## Wait for Completion
-
-**STOP.** Do not proceed until the assessor has returned.
-
-The assessor writes its findings to `docs/workflow/review/{topic-or-scope}/product-assessment.md` and returns a brief status. If the agent fails (error, timeout), record the failure and continue to the review production step with QA findings only.
-
----
-
-## Expected Result
-
-The assessor returns:
-
-```
-STATUS: findings | clean
-FINDINGS_COUNT: {N}
-SUMMARY: {1 sentence}
-```
-
-The full findings are in the output file. Read `docs/workflow/review/{topic-or-scope}/product-assessment.md` to incorporate into the review document.