@leeovery/claude-technical-workflows 2.1.23 → 2.1.25

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

@@ -4,7 +4,7 @@
 
 ---
 
-This step dispatches `review-task-verifier` agents in parallel to verify ALL tasks across the selected plan(s). Each verifier independently checks one task for implementation, tests, and code quality.
+This step dispatches `review-task-verifier` agents in batches to verify ALL tasks across the selected plan(s). Each verifier independently checks one task for implementation, tests, and code quality, writing its full findings to a file and returning a brief status.
 
 ---
 
@@ -26,15 +26,33 @@ From each plan in scope, list every task across all phases:
 - Note each task's description
 - Note each task's acceptance criteria
 - Note expected micro acceptance (test name)
+- Assign each task a sequential **index** (1, 2, 3...) for file naming
 
 ---
 
-## Dispatch Verifiers
+## Create Output Directory
 
-Dispatch **one verifier per task, all in parallel** via the Task tool.
+For each topic in scope, ensure the review output directory exists:
+
+```bash
+mkdir -p docs/workflow/review/{topic}
+```
+
+---
+
+## Batch Dispatch
+
+Dispatch verifiers in **batches of 5** via the Task tool.
 
 - **Agent path**: `../../../agents/review-task-verifier.md`
 
+1. Group tasks into batches of 5
+2. For each batch:
+   - Dispatch all agents in the batch in parallel
+   - Wait for all agents in the batch to return
+   - Record statuses
+3. After all batches complete, proceed to aggregation
+
 Each verifier receives:
 
 1. **Plan task** — the specific task with acceptance criteria
@@ -42,63 +60,35 @@ 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...)
 
----
-
-## Wait for Completion
-
-**STOP.** Do not proceed until all verifiers have returned.
-
-Each verifier returns a structured finding. If any verifier fails (error, timeout), record the failure and continue — aggregate what's available.
+If any verifier fails (error, timeout), record the failure and continue — aggregate what's available.
 
 ---
 
 ## Expected Result
 
-Each verifier returns:
+Each verifier returns a brief status:
 
 ```
-TASK: [Task name/description]
-
-ACCEPTANCE CRITERIA: [List from plan]
-
 STATUS: Complete | Incomplete | Issues Found
-
-SPEC CONTEXT: [Brief summary of relevant spec context]
-
-IMPLEMENTATION:
-- Status: [Implemented/Missing/Partial/Drifted]
-- Location: [file:line references]
-- Notes: [Any concerns]
-
-TESTS:
-- Status: [Adequate/Under-tested/Over-tested/Missing]
-- Coverage: [What is/isn't tested]
-- Notes: [Specific issues]
-
-CODE QUALITY:
-- Project conventions: [Followed/Violations/N/A]
-- SOLID principles: [Good/Concerns]
-- Complexity: [Low/Acceptable/High]
-- Modern idioms: [Yes/Opportunities]
-- Readability: [Good/Concerns]
-- Issues: [Specific problems if any]
-
-BLOCKING ISSUES:
-- [List any issues that must be fixed]
-
-NON-BLOCKING NOTES:
-- [Suggestions for improvement]
+FINDINGS_COUNT: {N blocking issues}
+SUMMARY: {1 sentence}
 ```
 
+Full findings are written to `docs/workflow/review/{topic}/qa-task-{index}.md`.
+
 ---
 
 ## Aggregate Findings
 
-Once all verifiers have returned, synthesize their reports:
+Once all batches have completed:
 
-- Collect all tasks with `STATUS: Incomplete` or `STATUS: Issues Found` as blocking issues
-- Collect all test issues (under/over-tested)
-- Collect all code quality concerns
-- Include specific file:line references
-- Check overall plan completion (see [review-checklist.md](review-checklist.md) — Plan Completion Check)
+1. Read all `docs/workflow/review/{topic}/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)
+   - Collect all code quality concerns
+   - Include specific file:line references
+   - Check overall plan completion (see [review-checklist.md](review-checklist.md) — Plan Completion Check)

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

@@ -72,19 +72,19 @@ For each topic or subtopic, perform exhaustive extraction:
 ### 2. Synthesize and Present
 Present your understanding to the user **in the format it would appear in the specification**. Output the content as rendered markdown (not in a code block) — the user needs to read it naturally, not inspect raw formatting:
 
-> "Here's what I understand about [topic] based on the reference material. This is exactly what I'll write into the specification:
->
-> [content as rendered markdown]
+"Here's what I understand about [topic] based on the reference material. This is exactly what I'll write into the specification:
+
+[content as rendered markdown]
 
 Then, **separately from the content above** (clear visual break), present the choices as raw markdown:
 
-> · · · · · · · · · · · ·
-> **To proceed:**
-> - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim** (exactly as shown, no modifications).
-> - **Or tell me what to change.**
-> · · · · · · · · · · · ·
+· · · · · · · · · · · ·
+**To proceed:**
+- **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim** (exactly as shown, no modifications).
+- **Or tell me what to change.**
+· · · · · · · · · · · ·
 
-**Do not wrap content or choices in a code block** — both must render as styled markdown. The content and choices must be visually distinct (not run together).
+Content and choices must be visually distinct (not run together).
 
 > **CHECKPOINT**: After presenting, you MUST STOP and wait for the user's response. Do NOT proceed to logging. Do NOT present the next topic. WAIT.
 
@@ -491,18 +491,18 @@ After completing your review (steps 1-7):
 
 Present a numbered summary of everything you found (from your tracking file):
 
-> "I've completed my final review against all source material. I found [N] items:
->
-> 1. **[Brief title]**
->    [2-4 line explanation: what was missed, where it came from, what it affects]
->
-> 2. **[Brief title]**
->    [2-4 line explanation]
->
-> 3. **[Brief title]**
->    [2-4 line explanation]
->
-> Let's work through these one at a time, starting with #1."
+"I've completed my final review against all source material. I found [N] items:
+
+1. **[Brief title]**
+   [2-4 line explanation: what was missed, where it came from, what it affects]
+
+2. **[Brief title]**
+   [2-4 line explanation]
+
+3. **[Brief title]**
+   [2-4 line explanation]
+
+Let's work through these one at a time, starting with #1."
 
 Each item should have enough context that the user understands what they're about to discuss - not just a label, but clarity on what was missed and why it matters.
 
@@ -514,17 +514,21 @@ For each item, follow the **same workflow as the main specification process**:
 2. **Discuss** if needed - clarify ambiguities, answer questions, refine the content
 3. **Present for approval** - show as rendered markdown (not a code block) exactly what will be written to the specification. Then, separately, show the choices:
 
-   > "Here's what I'll add to the specification:
-   >
-   > [content as rendered markdown]
-   >
-   > · · · · · · · · · · · ·
-   > **To proceed:**
-   > - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
-   > - **Or tell me what to change.**
-   > · · · · · · · · · · · ·
+   "Here's what I'll add to the specification:
 
-   **Do not wrap content or choices in a code block.** Content and choices must be visually distinct.
+   [content as rendered markdown]
+
+   > *Output the next fenced block as markdown (not a code block):*
+
+   ```
+   · · · · · · · · · · · ·
+   **To proceed:**
+   - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
+   - **Or tell me what to change.**
+   · · · · · · · · · · · ·
+   ```
+
+   Content and choices must be visually distinct.
 
 4. **Wait for explicit approval** - same rules as always: `y`/`yes` or equivalent before writing
 5. **Log verbatim** when approved
@@ -630,15 +634,15 @@ Follow the same two-stage presentation as Phase 1:
 
 **Stage 1: Summary**
 
-> "I've completed the gap analysis of the specification. I found [N] items:
->
-> 1. **[Brief title]** (Critical/Important/Minor)
->    [2-4 line explanation: what the gap is, why it matters for implementation]
->
-> 2. **[Brief title]** (Critical/Important/Minor)
->    [2-4 line explanation]
->
-> Let's work through these one at a time, starting with #1."
+"I've completed the gap analysis of the specification. I found [N] items:
+
+1. **[Brief title]** (Critical/Important/Minor)
+   [2-4 line explanation: what the gap is, why it matters for implementation]
+
+2. **[Brief title]** (Critical/Important/Minor)
+   [2-4 line explanation]
+
+Let's work through these one at a time, starting with #1."
 
 **Stage 2: Process One Item at a Time**
 
@@ -648,17 +652,21 @@ For each item:
 2. **Discuss** - work with the user to determine the correct specification content
 3. **Present for approval** - show as rendered markdown (not a code block) exactly what will be written. Then, separately, show the choices:
 
-   > "Here's what I'll add to the specification:
-   >
-   > [content as rendered markdown]
-   >
-   > · · · · · · · · · · · ·
-   > **To proceed:**
-   > - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
-   > - **Or tell me what to change.**
-   > · · · · · · · · · · · ·
+   "Here's what I'll add to the specification:
+
+   [content as rendered markdown]
+
+   > *Output the next fenced block as markdown (not a code block):*
 
-   **Do not wrap content or choices in a code block.** Content and choices must be visually distinct.
+   ```
+   · · · · · · · · · · · ·
+   **To proceed:**
+   - **`y`/`yes`** — Approved. I'll add the above to the specification **verbatim**.
+   - **Or tell me what to change.**
+   · · · · · · · · · · · ·
+   ```
+
+   Content and choices must be visually distinct.
 
 4. **Wait for explicit approval**
 5. **Log verbatim** when approved
@@ -703,14 +711,14 @@ Before asking for sign-off, assess whether this is a **feature** or **cross-cutt
 
 Present your assessment to the user:
 
-> "This specification appears to be a **[feature/cross-cutting]** specification.
->
-> [Brief rationale - e.g., "It defines a caching strategy that will inform how multiple features handle data retrieval, rather than being a standalone piece of functionality to build."]
->
-> - **Feature specs** proceed to planning and implementation
-> - **Cross-cutting specs** are referenced by feature plans but don't have their own implementation plan
->
-> Does this assessment seem correct?"
+"This specification appears to be a **[feature/cross-cutting]** specification.
+
+[Brief rationale - e.g., "It defines a caching strategy that will inform how multiple features handle data retrieval, rather than being a standalone piece of functionality to build."]
+
+- **Feature specs** proceed to planning and implementation
+- **Cross-cutting specs** are referenced by feature plans but don't have their own implementation plan
+
+Does this assessment seem correct?"
 
 Wait for user confirmation before proceeding.
 
@@ -729,14 +737,14 @@ If either file still exists, delete it now. These are temporary working files th
 
 Once the type is confirmed and tracking files are removed, ask for final sign-off:
 
-> "The specification is ready for sign-off:
-> - **Type**: [feature/cross-cutting]
-> - **Status**: Complete
->
-> [If feature]: This specification can proceed to planning
-> [If cross-cutting]: This specification will be surfaced as reference context when planning features
->
-> Ready to mark as complete?"
+"The specification is ready for sign-off:
+- **Type**: [feature/cross-cutting]
+- **Status**: Complete
+
+[If feature]: This specification can proceed to planning
+[If cross-cutting]: This specification will be surfaced as reference context when planning features
+
+Ready to mark as complete?"
 
 ### Step 4: Update Frontmatter
 

package/skills/view-plan/SKILL.md

@@ -38,8 +38,10 @@ Follow the reading reference to locate and read the actual plan content.
 
 Display a readable summary:
 
+> *Output the next fenced block as a code block:*
+
 ```
-## Plan: {topic}
+Plan: {topic}
 
 **Format:** {format}