@leeovery/claude-technical-workflows 2.1.23 → 2.1.25

package/agents/review-task-verifier.md

@@ -1,7 +1,7 @@
 ---
 name: review-task-verifier
-description: Verifies a single plan task was implemented correctly. Checks implementation, tests, and code quality against the task's acceptance criteria and spec context. Invoked by technical-review to verify ALL plan tasks in PARALLEL.
-tools: Read, Glob, Grep
+description: Verifies a single plan task was implemented correctly. Checks implementation, tests, and code quality against the task's acceptance criteria and spec context. Writes structured findings to file, returns brief status to orchestrator.
+tools: Read, Write, Glob, Grep
 model: opus
 ---
 
@@ -17,6 +17,8 @@ You receive:
 3. **Plan path**: The full plan for additional context
 4. **Project skill paths**: Relevant `.claude/skills/` paths for framework conventions
 5. **Review checklist path**: Path to the review checklist (`skills/technical-review/references/review-checklist.md`) — read this for detailed verification criteria
+6. **Topic name**: The plan topic (used for output file path)
+7. **Task index**: Sequential number for this task (used for output file naming)
 
 ## Your Task
 
@@ -82,9 +84,9 @@ Review the implementation as a senior architect would:
 - **Security**: No obvious vulnerabilities (injection, exposure, etc.)
 - **Performance**: No obvious inefficiencies (N+1 queries, unnecessary loops, etc.)
 
-## Your Output
+## Output File Format
 
-Return a structured finding:
+Write to `docs/workflow/review/{topic}/qa-task-{index}.md`:
 
 ```
 TASK: [Task name/description]
@@ -120,11 +122,21 @@ NON-BLOCKING NOTES:
 - [Suggestions for improvement]
 ```
 
+## Your Output
+
+Return a brief status to the orchestrator:
+
+```
+STATUS: Complete | Incomplete | Issues Found
+FINDINGS_COUNT: {N blocking issues}
+SUMMARY: {1 sentence}
+```
+
 ## Rules
 
-1. **One task only** - You verify exactly one plan task per invocation
-2. **Be thorough** - Check implementation, tests, AND quality
-3. **Be specific** - Include file paths and line numbers
-4. **Balanced test review** - Flag both under-testing AND over-testing
-5. **Report findings** - Don't fix anything, just report what you find
-6. **Fast and focused** - You're one of many running in parallel
+1. **One task only** — you verify exactly one plan task per invocation
+2. **Be thorough** — check implementation, tests, AND quality
+3. **Be specific** — include file paths and line numbers
+4. **Balanced test review** — flag both under-testing AND over-testing
+5. **Report findings** — don't fix anything, just report what you find
+6. **No git writes** — writing the output file is your only file write

package/package.json

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

package/skills/link-dependencies/SKILL.md

@@ -28,23 +28,31 @@ Scan the codebase for existing plans:
 
 **If no plans exist:**
 
+> *Output the next fenced block as a code block:*
+
 ```
+Dependency Linking
+
 No plans found in docs/workflow/planning/
 
 There are no plans to link. Create plans first.
 ```
 
-Stop here.
+**STOP.** Do not proceed — terminal condition.
 
 **If only one plan exists:**
 
+> *Output the next fenced block as a code block:*
+
 ```
+Dependency Linking
+
 Only one plan found: {topic}
 
 Cross-topic dependency linking requires at least two plans.
 ```
 
-Stop here.
+**STOP.** Do not proceed — terminal condition.
 
 ## Step 2: Check Output Format Consistency
 
@@ -52,18 +60,21 @@ Compare the `format:` field across all discovered plans.
 
 **If plans use different output formats:**
 
+> *Output the next fenced block as a code block:*
+
 ```
+Dependency Linking
+
 Mixed output formats detected:
 
-- authentication: {format-a}
-- billing-system: {format-b}
-- notifications: {format-a}
+  • {topic} ({format})
+  • ...
 
-Cross-topic dependencies can only be wired within the same output format.
-Please consolidate your plans to use a single output format before linking dependencies.
+Cross-topic dependencies can only be wired within the same output
+format. Consolidate your plans to a single format before linking.
 ```
 
-Stop here.
+**STOP.** Do not proceed — terminal condition.
 
 ## Step 3: Extract External Dependencies
 
@@ -77,20 +88,28 @@ For each plan, read the `external_dependencies` field from the frontmatter:
 
 3. **Build a summary**:
 
+> *Output the next fenced block as a code block:*
+
 ```
 Dependency Summary
 
-Plan: authentication (format: {format})
-  - billing-system: Invoice generation (unresolved)
-  - user-management: User profiles → {task-id} (resolved)
+{N} plans found. {M} unresolved dependencies.
+
+Plan: {topic:(titlecase)} (format: {format})
+  • {dependency}: {description} ({state:[unresolved|resolved|satisfied externally]})
+
+Plan: ...
+```
+
+> *Output the next fenced block as a code block:*
 
-Plan: billing-system (format: {format})
-  - authentication: User context (unresolved)
-  - payment-gateway: Payment processing (satisfied externally)
+```
+Key:
 
-Plan: notifications (format: {format})
-  - authentication: User lookup (unresolved)
-  - billing-system: Invoice events (unresolved)
+  Dependency state:
+    unresolved           — no task linked yet
+    resolved             — linked to a task in another plan
+    satisfied externally — implemented outside this workflow
 ```
 
 ## Step 4: Match Dependencies to Plans
@@ -131,35 +150,43 @@ For each plan that was a dependency target (i.e., other plans depend on it):
 
 Present a summary:
 
+> *Output the next fenced block as a code block:*
+
 ```
 Dependency Linking Complete
 
-RESOLVED (newly linked):
-  - authentication → billing-system: {task-id} (Invoice generation)
-  - notifications → authentication: {task-id} (Session management)
+Resolved (newly linked):
+  • {source} → {target}: {task-id} ({description})
 
-ALREADY RESOLVED (no action needed):
-  - authentication → user-management: {task-id}
+Already resolved (no action needed):
+  • {source} → {target}: {task-id}
 
-SATISFIED EXTERNALLY (no action needed):
-  - billing-system → payment-gateway
+Satisfied externally (no action needed):
+  • {source} → {target}
 
-UNRESOLVED (no matching plan exists):
-  - notifications → email-service: Email delivery
+Unresolved (no matching plan exists):
+  • {source} → {target}: {description}
 
-  These dependencies have no corresponding plan. Either:
-  - Create a plan for the topic
-  - Mark as "satisfied externally" if already implemented
+Updated files:
+  • docs/workflow/planning/{topic}.md
+```
+
+If any dependencies remain unresolved:
+
+> *Output the next fenced block as a code block:*
 
-UPDATED FILES:
-  - docs/workflow/planning/authentication.md
-  - docs/workflow/planning/notifications.md
+```
+Unresolved dependencies have no corresponding plan. Either:
+  • Create a plan for the topic
+  • Mark as "satisfied externally" if already implemented
 ```
 
 ## Step 8: Commit Changes
 
 If any files were updated:
 
+> *Output the next fenced block as markdown (not a code block):*
+
 ```
 · · · · · · · · · · · ·
 Shall I commit these dependency updates?
@@ -168,7 +195,7 @@ Shall I commit these dependency updates?
 · · · · · · · · · · · ·
 ```
 
-**Do not wrap the above in a code block** — output as raw markdown so bold styling renders.
+**STOP.** Wait for user response.
 
 If yes, commit with message:
 ```

package/skills/start-discussion/references/display-options.md

@@ -8,34 +8,54 @@ Present everything discovered to help the user make an informed choice.
 
 **Present the full state:**
 
+> *Output the next fenced block as a code block:*
+
 ```
-Workflow Status: Discussion Phase
+Discussion Overview
+
+{N} research topics found. {M} existing discussions.
 
 Research topics:
-  1. · {Theme name} - undiscussed
-       Source: {filename}.md (lines {start}-{end})
-       "{Brief summary}"
 
-  2. ✓ {Theme name} → {topic}.md
-       Source: {filename}.md (lines {start}-{end})
-       "{Brief summary}"
+1. {theme_name}
+   └─ Source: {filename}.md (lines {start}-{end})
+   └─ Discussion: @if(has_discussion) {topic}.md ({status:[in-progress|concluded]}) @else (no discussion) @endif
+   └─ "{summary}"
 
-Discussions:
-  - {topic}.md (in-progress)
-  - {topic}.md (concluded)
+2. ...
+```
+
+If discussions exist that are NOT linked to a research topic, list them separately:
+
+> *Output the next fenced block as a code block:*
 
----
-Key:
-  · = undiscussed topic (potential new discussion)
-  ✓ = already has a corresponding discussion
 ```
+Existing discussions:
 
-**Output in a fenced code block exactly as shown above.**
+  • {topic}.md ({status:[in-progress|concluded]})
+```
+
+### Key/Legend
+
+No `---` separator before this section.
+
+> *Output the next fenced block as a code block:*
+
+```
+Key:
+
+  Discussion status:
+    in-progress — discussion is ongoing
+    concluded   — discussion is complete
+```
 
 **Then present the options based on what exists:**
 
 #### If research and discussions exist
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 How would you like to proceed?
 
@@ -44,9 +64,13 @@ How would you like to proceed?
 - Continue discussion — name one above (e.g., "continue {topic}")
 - Fresh topic — describe what you want to discuss
 · · · · · · · · · · · ·
+```
 
 #### If only research exists
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 How would you like to proceed?
 
@@ -54,14 +78,19 @@ How would you like to proceed?
 - From research — pick a topic number above (e.g., "1" or "research 1")
 - Fresh topic — describe what you want to discuss
 · · · · · · · · · · · ·
+```
 
 #### If only discussions exist
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 · · · · · · · · · · · ·
 How would you like to proceed?
 
 - Continue discussion — name one above (e.g., "continue {topic}")
 - Fresh topic — describe what you want to discuss
 · · · · · · · · · · · ·
+```
 
 **STOP.** Wait for user response before proceeding.

package/skills/start-discussion/references/gather-context-continue.md

@@ -6,6 +6,8 @@
 
 Read the existing discussion document first, then ask:
 
+> *Output the next fenced block as a code block:*
+
 ```
 Continuing: {topic}
 

package/skills/start-discussion/references/gather-context-fresh.md

@@ -10,6 +10,8 @@ Ask each question below **one at a time**. After each, **STOP** and wait for the
 
 ## Core Problem
 
+> *Output the next fenced block as a code block:*
+
 ```
 New discussion: {topic}
 
@@ -22,6 +24,8 @@ What's the core problem or decision we need to work through?
 
 ## Constraints
 
+> *Output the next fenced block as a code block:*
+
 ```
 Any constraints or context I should know about?
 ```
@@ -32,6 +36,8 @@ Any constraints or context I should know about?
 
 ## Codebase
 
+> *Output the next fenced block as a code block:*
+
 ```
 Are there specific files in the codebase I should review first?
 

package/skills/start-discussion/references/gather-context-research.md

@@ -6,6 +6,8 @@
 
 Summarise the selected research topic in 2-5 lines, drawing from the source, summary, and key questions in the research analysis.
 
+> *Output the next fenced block as markdown (not a code block):*
+
 ```
 New discussion: {topic}
 
@@ -22,6 +24,4 @@ research you'd like to include — drop them in now.
 · · · · · · · · · · · ·
 ```
 
-**Do not wrap the above in a code block** — output as raw markdown so bold styling renders.
-
 **STOP.** Wait for user response before proceeding.

package/skills/start-implementation/SKILL.md

@@ -108,13 +108,18 @@ Use `state.scenario` from the discovery output to determine the path:
 
 No plans exist yet.
 
+> *Output the next fenced block as a code block:*
+
 ```
+Implementation Overview
+
 No plans found in docs/workflow/planning/
 
-The implementation phase requires a plan. Please run /start-planning first to create a plan from a specification.
+The implementation phase requires a plan.
+Run /start-planning first to create a plan from a specification.
 ```
 
-**STOP.** Wait for user to acknowledge before ending.
+**STOP.** Do not proceed — terminal condition.
 
 #### If scenario is "single_plan" or "multiple_plans"
 
@@ -126,7 +131,7 @@ Plans exist.
 
 ## Step 3: Present Plans and Select
 
-Present all discovered plans using the icon system below. Classify each plan into one of three sections based on its state.
+Present all discovered plans. Classify each plan into one of three categories based on its state.
 
 **Classification logic:**
 
@@ -144,80 +149,124 @@ A plan is **Not implementable** if:
 
 **Present the full state:**
 
+Show implementable and implemented plans as numbered tree items.
+
+> *Output the next fenced block as a code block:*
+
 ```
-Implementation Phase
+Implementation Overview
+
+{N} plans found. {M} implementations in progress.
+
+1. {topic:(titlecase)}
+   └─ Plan: {plan_status:[concluded]} ({format})
+   └─ Implementation: @if(has_implementation) {impl_status:[in-progress|completed]} @else (not started) @endif
+
+2. ...
+```
+
+**Tree rules:**
 
 Implementable:
-  1. ▶ billing - continue [Phase 2, Task 3]
-  2. + core-features - start
+- Implementation `status: in-progress` → `Implementation: in-progress (Phase N, Task M)`
+- Concluded plan, deps met, not started → `Implementation: (not started)`
 
 Implemented:
-  3. > user-auth
+- Implementation `status: completed` → `Implementation: completed`
 
-Not implementable:
-  · advanced-features [blocked: core-features task core-2-3 not completed]
-  · reporting [planning]
-```
+**Ordering:**
+1. Implementable first: in-progress, then new (foundational before dependent)
+2. Implemented next: completed
+3. Not implementable last (separate block below)
 
-**Output in a fenced code block exactly as shown above.**
+Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
 
-**Formatting rules:**
+**If non-implementable plans exist**, show them in a separate code block:
 
-Implementable (numbered, selectable):
-- **`▶`** — implementation `status: in-progress`, show current position `[Phase N, Task M]`
-- **`+`** — concluded plan, deps met, no tracking file or tracking `status: not-started`
+> *Output the next fenced block as a code block:*
 
-Implemented (numbered, selectable):
-- **`>`** — implementation `status: completed`
+```
+Plans not ready for implementation:
+These plans are either still in progress or have unresolved
+dependencies that must be addressed first.
 
-Not implementable (not numbered, not selectable):
-- **`·`** — blocked or plan not concluded
-- `[blocked: {topic} task {id} not completed]` — resolved dep, task not done
-- `[blocked: unresolved dep on {topic}]` — no task linked
-- `[planning]` — plan status is not `concluded`
+  • advanced-features (blocked by core-features:core-2-3)
+  • reporting (in-progress)
+```
 
-**Ordering:**
-1. Implementable first: `▶` in-progress, then `+` new (foundational before dependent)
-2. Implemented next: `>` completed
-3. Not implementable last
+> *Output the next fenced block as a code block:*
 
-Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
+```
+If a blocked dependency has been resolved outside this workflow,
+name the plan and the dependency to unblock it.
+```
+
+**Key/Legend** — show only statuses that appear in the current display. No `---` separator before this section.
 
-**If Not implementable section is shown**, append after the presentation:
+> *Output the next fenced block as a code block:*
 
 ```
-If a blocked dependency has been resolved outside this workflow, name the plan and the dependency to unblock it.
+Key:
+
+  Implementation status:
+    in-progress — work is ongoing
+    completed   — all tasks implemented
+
+  Blocking reason:
+    blocked     — depends on another plan's task
+    in-progress — plan not yet concluded
 ```
 
 **Then prompt based on what's actionable:**
 
 **If single implementable plan and no implemented plans (auto-select):**
+
+> *Output the next fenced block as a code block:*
+
 ```
-Auto-selecting: {topic} (only implementable plan)
+Automatically proceeding with "{topic:(titlecase)}".
 ```
+
 → Proceed directly to **Step 4**.
 
 **If nothing selectable (no implementable or implemented):**
-Show Not implementable section only (with unblock hint above).
+
+Show "not ready" block only (with unblock hint above).
+
+> *Output the next fenced block as a code block:*
 
 ```
-No implementable plans.
+Implementation Overview
 
-Before you can start implementation:
-- Complete blocking dependencies first, or
-- Finish plans still in progress with /start-planning
+No implementable plans found.
 
-Then re-run /start-implementation.
+Complete blocking dependencies first, or finish plans still
+in progress with /start-planning. Then re-run /start-implementation.
 ```
 
-**STOP.** This workflow cannot continue — do not proceed.
+**STOP.** Do not proceed — terminal condition.
 
 **Otherwise (multiple selectable plans, or implemented plans exist):**
+
+The verb in the menu depends on the implementation state:
+- Implementation in-progress → **Continue**
+- Not yet started → **Start**
+- Completed → **Re-review**
+
+> *Output the next fenced block as markdown (not a code block):*
+
 ```
 · · · · · · · · · · · ·
-Select a plan (enter number):
+1. Continue "Billing" — in-progress (Phase 2, Task 3)
+2. Start "Core Features" — not yet started
+3. Re-review "User Auth" — completed
+
+Select an option (enter number):
+· · · · · · · · · · · ·
 ```
 
+Recreate with actual topics and states from discovery.
+
 **STOP.** Wait for user response.
 
 #### If the user requests an unblock
@@ -242,6 +291,8 @@ After the plan is selected:
 
 #### If all deps satisfied (or no deps)
 
+> *Output the next fenced block as a code block:*
+
 ```
 External dependencies satisfied.
 ```
@@ -252,21 +303,28 @@ External dependencies satisfied.
 
 This should not normally happen for plans classified as "Implementable" in Step 3. However, as an escape hatch:
 
+> *Output the next fenced block as a code block:*
+
 ```
-Missing dependencies:
+Missing Dependencies
+
+Unresolved (not yet planned):
+  • {topic}: {description}
+    No plan exists. Create with /start-planning or mark as
+    satisfied externally.
 
-UNRESOLVED (not yet planned):
-- {topic}: {description}
-  -> No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
+Incomplete (planned but not implemented):
+  • {topic}: {plan}:{task-id} not yet completed
+    This task must be completed first.
+```
 
-INCOMPLETE (planned but not implemented):
-- {topic}: task {task_id} not yet completed
-  -> This task must be completed first.
+> *Output the next fenced block as markdown (not a code block):*
 
+```
 · · · · · · · · · · · ·
 - **`i`/`implement`** — Implement the blocking dependencies first
 - **`l`/`link`** — Run /link-dependencies to wire up recently completed plans
-- Mark as "satisfied externally" — tell me which dependency was implemented outside this workflow
+- **`s`/`satisfied`** — Mark a dependency as satisfied externally
 · · · · · · · · · · · ·
 ```
 
@@ -292,12 +350,18 @@ If the user says a dependency has been implemented outside the workflow:
 Use the `environment` section from the discovery output:
 
 **If `setup_file_exists: true` and `requires_setup: false`:**
+
+> *Output the next fenced block as a code block:*
+
 ```
 Environment: No special setup required.
 ```
 → Proceed to **Step 6**.
 
 **If `setup_file_exists: true` and `requires_setup: true`:**
+
+> *Output the next fenced block as a code block:*
+
 ```
 Environment setup file found: docs/workflow/environment-setup.md
 ```
@@ -306,6 +370,9 @@ Environment setup file found: docs/workflow/environment-setup.md
 **If `setup_file_exists: false` or `requires_setup: unknown`:**
 
 Ask:
+
+> *Output the next fenced block as a code block:*
+
 ```
 Are there any environment setup instructions I should follow before implementation?
 (Or "none" if no special setup is needed)