@leeovery/claude-technical-workflows 2.1.18 → 2.1.20

package/agents/implementation-analysis-architecture.md

@@ -29,6 +29,7 @@ You receive via the orchestrator's prompt:
 - Over/under-engineering — are abstractions justified by usage? Is raw code crying out for structure?
 - Missed composition opportunities — are new abstractions independently implemented when they could be derived from existing ones? If two queries are logical inverses, one should be defined in terms of the other.
 - Type safety at boundaries — are interfaces or function signatures using untyped parameters when the concrete types are known? Runtime type checks inside implementations signal the signature should be more specific.
+- Design decision soundness — are there foundational choices that introduce unnecessary complexity or latent risk? Look for: layers that mirror each other when the domain type could own the transformation; correctness that depends on caller discipline rather than being self-contained; struct tags, type annotations, or interface contracts that would produce wrong results if used outside their current narrow context. Only flag decisions that create latent bugs, unnecessary indirection, or fragile assumptions — not merely different-but-working approaches.
 
 ## Your Process
 

package/agents/review-product-assessor.md

@@ -0,0 +1,112 @@
+---
+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/agents/review-task-verifier.md

@@ -15,7 +15,8 @@ You receive:
 1. **Plan task**: A specific task with its acceptance criteria
 2. **Specification path**: For loading context about this task's feature/requirement
 3. **Plan path**: The full plan for additional context
-4. **Implementation scope**: Files or directories to check
+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
 
 ## Your Task
 

package/package.json

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

package/skills/start-discussion/SKILL.md

@@ -88,6 +88,8 @@ Parse the discovery output to understand:
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
+**Silent processing**: Do NOT output your assessment of the discovery state. Parse it internally and proceed to the next step without narrating field values, routing decisions, or prerequisites. The first user-visible output should be the display content itself.
+
 → Proceed to **Step 2**.
 
 ---
@@ -96,263 +98,63 @@ Parse the discovery output to understand:
 
 Use `state.scenario` from the discovery output to determine the path:
 
-#### If scenario is "fresh"
-
-No research or discussions exist yet.
-
-```
-Starting fresh - no prior research or discussions found.
-
-What topic would you like to discuss?
-```
-
-**STOP.** Wait for user response, then skip to **Step 6** (Gather Context) with their topic.
-
-#### If scenario is "discussions_only"
-
-No research exists, but discussions do. Skip research analysis.
-
-→ Proceed to **Step 4**.
-
 #### If scenario is "research_only" or "research_and_discussions"
 
 Research exists and may need analysis.
 
 → Proceed to **Step 3**.
 
----
+#### If scenario is "discussions_only"
 
-## Step 3: Handle Research Analysis
+No research exists, but discussions do. Skip research analysis.
 
-This step only runs when research files exist.
+→ Proceed to **Step 4**.
 
-Use `cache.status` from discovery to determine the approach:
+#### If scenario is "fresh"
 
-#### If cache.status is "valid"
+No research or discussions exist yet.
 
 ```
-Using cached research analysis (unchanged since {cache.generated})
-```
-
-Load the topics from `docs/workflow/.cache/research-analysis.md` and proceed.
-
-→ Proceed to **Step 4**.
-
-#### If cache.status is "stale" or "none"
+Starting fresh - no prior research or discussions found.
 
+What topic would you like to discuss?
 ```
-Analyzing research documents...
-```
-
-Read each research file and extract key themes and potential discussion topics. For each theme:
-- Note the source file and relevant line numbers
-- Summarize what the theme is about in 1-2 sentences
-- Identify key questions or decisions that need discussion
 
-**Be thorough**: This analysis will be cached, so identify ALL potential topics:
-- Major architectural decisions
-- Technical trade-offs mentioned
-- Open questions or concerns raised
-- Implementation approaches discussed
-- Integration points with external systems
-- Security or performance considerations
-- Edge cases or error handling mentioned
+**STOP.** Wait for user response.
 
-**Save to cache:**
+When user responds, proceed with their topic.
 
-Ensure the cache directory exists:
-```bash
-mkdir -p docs/workflow/.cache
-```
-
-Create/update `docs/workflow/.cache/research-analysis.md`:
+→ Proceed to **Step 6**.
 
-```markdown
 ---
-checksum: {research.checksum from discovery}
-generated: YYYY-MM-DDTHH:MM:SS  # Use current ISO timestamp
-research_files:
-  - {filename1}.md
-  - {filename2}.md
----
-
-# Research Analysis Cache
 
-## Topics
+## Step 3: Research Analysis
 
-### {Theme name}
-- **Source**: {filename}.md (lines {start}-{end})
-- **Summary**: {1-2 sentence summary}
-- **Key questions**: {what needs deciding}
-
-### {Another theme}
-- **Source**: {filename}.md (lines {start}-{end})
-- **Summary**: {1-2 sentence summary}
-- **Key questions**: {what needs deciding}
-```
-
-**Cross-reference**: For each topic, note if a discussion already exists (from `discussions.files` in discovery).
+Load **[research-analysis.md](references/research-analysis.md)** and follow its instructions as written.
 
 → Proceed to **Step 4**.
 
 ---
 
-## Step 4: Present Workflow State and Options
-
-Present everything discovered to help the user make an informed choice.
+## Step 4: Present Options
 
-**Present the full state:**
+Load **[display-options.md](references/display-options.md)** and follow its instructions as written.
 
-```
-Workflow Status: Discussion Phase
-
-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}"
-
-Discussions:
-  - {topic}.md (in-progress)
-  - {topic}.md (concluded)
-```
-
-**Legend:**
-- `·` = undiscussed topic (potential new discussion)
-- `✓` = already has a corresponding discussion
-
-**Then present the options based on what exists:**
-
-**If research AND discussions exist:**
-```
-· · · · · · · · · · · ·
-How would you like to proceed?
-
-- **`r`/`refresh`** — Force fresh research analysis
-- From research — pick a topic number above (e.g., "1" or "research 1")
-- Continue discussion — name one above (e.g., "continue {topic}")
-- Fresh topic — describe what you want to discuss
-· · · · · · · · · · · ·
-```
-
-**If ONLY research exists:**
-```
-· · · · · · · · · · · ·
-How would you like to proceed?
-
-- **`r`/`refresh`** — Force fresh research analysis
-- 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:**
-```
-· · · · · · · · · · · ·
-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.
-
-→ Based on user choice, proceed to **Step 5**.
+→ Proceed to **Step 5**.
 
 ---
 
-## Step 5: Handle User Selection
-
-Route based on the user's choice from Step 4.
-
-#### If user chose "From research"
-
-User chose to start from research (e.g., "research 1", "1", "from research", or a topic name).
-
-**If user specified a topic inline** (e.g., "research 2", "2", or topic name):
-- Identify the selected topic from Step 4's numbered list
-- → Proceed to **Step 6**
-
-**If user just said "from research" without specifying:**
-```
-Which research topic would you like to discuss? (Enter a number or topic name)
-```
-
-**STOP.** Wait for response, then proceed to **Step 6**.
-
-#### If user chose "Continue discussion"
-
-User chose to continue a discussion (e.g., "continue auth-flow" or "continue discussion").
+## Step 5: Handle Selection
 
-**If user specified a discussion inline** (e.g., "continue auth-flow"):
-- Identify the selected discussion from Step 4's list
-- → Proceed to **Step 6**
-
-**If user just said "continue discussion" without specifying:**
-```
-Which discussion would you like to continue?
-```
-
-**STOP.** Wait for response, then proceed to **Step 6**.
-
-#### If user chose "Fresh topic"
-
-User wants to start a fresh discussion.
+Load **[handle-selection.md](references/handle-selection.md)** and follow its instructions as written.
 
 → Proceed to **Step 6**.
 
-#### If user chose "refresh"
-
-```
-Refreshing analysis...
-```
-
-Delete the cache file:
-```bash
-rm docs/workflow/.cache/research-analysis.md
-```
-
-→ Return to **Step 3** to re-analyze, then back to **Step 4**.
-
 ---
 
 ## Step 6: Gather Context
 
-Gather context based on the chosen path.
-
-#### If starting new discussion (from research or fresh)
-
-```
-## New discussion: {topic}
-
-Before we begin:
-
-1. What's the core problem or decision we need to work through?
-
-2. Any constraints or context I should know about?
-
-3. Are there specific files in the codebase I should review first?
-```
-
-**STOP.** Wait for responses before proceeding.
-
-#### If continuing existing discussion
-
-Read the existing discussion document first, then ask:
-
-```
-## Continuing: {topic}
-
-I've read the existing discussion.
-
-What would you like to focus on in this session?
-```
-
-**STOP.** Wait for response before proceeding.
+Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
 
 → Proceed to **Step 7**.
 
@@ -360,32 +162,5 @@ What would you like to focus on in this session?
 
 ## Step 7: Invoke the Skill
 
-After completing the steps above, this skill's purpose is fulfilled.
-
-Invoke the [technical-discussion](../technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
-
-**Example handoff (from research):**
-```
-Discussion session for: {topic}
-Output: docs/workflow/discussion/{topic}.md
-
-Research reference:
-Source: docs/workflow/research/{filename}.md (lines {start}-{end})
-Summary: {the 1-2 sentence summary from the research analysis}
-
-Invoke the technical-discussion skill.
-```
-
-**Example handoff (continuing or fresh):**
-```
-Discussion session for: {topic}
-Source: {existing discussion | fresh}
-Output: docs/workflow/discussion/{topic}.md
-
-Invoke the technical-discussion skill.
-```
-
-## Notes
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.
 
-- Ask questions clearly and wait for responses before proceeding
-- Discussion captures WHAT and WHY - don't jump to specifications or implementation

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

@@ -0,0 +1,71 @@
+# Present Options
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Present everything discovered to help the user make an informed choice.
+
+**Present the full state:**
+
+```
+Workflow Status: Discussion Phase
+
+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}"
+
+Discussions:
+  - {topic}.md (in-progress)
+  - {topic}.md (concluded)
+
+---
+Key:
+  · = undiscussed topic (potential new discussion)
+  ✓ = already has a corresponding discussion
+```
+
+**Then present the options based on what exists:**
+
+#### If research and discussions exist
+
+```
+· · · · · · · · · · · ·
+How would you like to proceed?
+
+- **`r`/`refresh`** — Force fresh research analysis
+- From research — pick a topic number above (e.g., "1" or "research 1")
+- Continue discussion — name one above (e.g., "continue {topic}")
+- Fresh topic — describe what you want to discuss
+· · · · · · · · · · · ·
+```
+
+#### If only research exists
+
+```
+· · · · · · · · · · · ·
+How would you like to proceed?
+
+- **`r`/`refresh`** — Force fresh research analysis
+- 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
+
+```
+· · · · · · · · · · · ·
+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

@@ -0,0 +1,17 @@
+# Gather Context: Continue Discussion
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Read the existing discussion document first, then ask:
+
+```
+Continuing: {topic}
+
+I've read the existing discussion.
+
+What would you like to focus on in this session?
+```
+
+**STOP.** Wait for response before proceeding.

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

@@ -0,0 +1,41 @@
+# Gather Context: Fresh Topic
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Ask each question below **one at a time**. After each, **STOP** and wait for the user's response before proceeding.
+
+---
+
+## Core Problem
+
+```
+New discussion: {topic}
+
+What's the core problem or decision we need to work through?
+```
+
+**STOP.** Wait for user response before proceeding.
+
+---
+
+## Constraints
+
+```
+Any constraints or context I should know about?
+```
+
+**STOP.** Wait for user response before proceeding.
+
+---
+
+## Codebase
+
+```
+Are there specific files in the codebase I should review first?
+
+(Or "none" if not applicable)
+```
+
+**STOP.** Wait for user response before proceeding.

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

@@ -0,0 +1,25 @@
+# Gather Context: From Research
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Summarise the selected research topic in 2-5 lines, drawing from the source, summary, and key questions in the research analysis.
+
+```
+New discussion: {topic}
+
+Based on research: docs/workflow/research/{filename}.md (lines {start}-{end})
+
+{2-5 line summary of the topic and what needs discussing}
+
+· · · · · · · · · · · ·
+Do you have anything to add? Extra context, files, or additional
+research you'd like to include — drop them in now.
+
+- **`n`/`no`** — Continue as-is
+- Describe what you'd like to add
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response before proceeding.

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

@@ -0,0 +1,31 @@
+# Gather Context
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Route based on the chosen path from earlier steps.
+
+#### If starting from research
+
+→ Load **[gather-context-research.md](gather-context-research.md)** and follow its instructions.
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 7** with the gathered context.
+
+#### If starting fresh topic
+
+→ Load **[gather-context-fresh.md](gather-context-fresh.md)** and follow its instructions.
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 7** with the gathered context.
+
+#### If continuing existing discussion
+
+→ Load **[gather-context-continue.md](gather-context-continue.md)** and follow its instructions.
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 7** with the gathered context.