@leeovery/claude-technical-workflows 2.0.0

package/commands/start-planning.md

@@ -0,0 +1,92 @@
+---
+description: Start a planning session from an existing specification. Discovers available specifications, asks where to store the plan, and invokes the technical-planning skill.
+---
+
+Invoke the **technical-planning** skill for this conversation.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
+
+Before beginning, discover existing work and gather necessary information.
+
+## Important
+
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+
+## Step 1: Discover Existing Work
+
+Scan the codebase for specifications and plans:
+
+1. **Find specifications**: Look in `docs/workflow/specification/`
+   - Run `ls docs/workflow/specification/` to list specification files
+   - Each file is named `{topic}.md`
+
+2. **Check specification status**: For each specification file
+   - Run `head -20 docs/workflow/specification/{topic}.md` to read the frontmatter and extract the `status:` field
+   - Do NOT use bash loops - run separate `head` commands for each topic
+
+3. **Check for existing plans**: Look in `docs/workflow/planning/`
+   - Identify specifications that don't have corresponding plans
+
+## Step 2: Check Prerequisites
+
+**If no specifications exist:**
+
+```
+⚠️ No specifications found in docs/workflow/specification/
+
+The planning phase requires a completed specification. Please run /start-specification first to validate and refine the discussion content into a standalone specification before creating a plan.
+```
+
+Stop here and wait for the user to acknowledge.
+
+## Step 3: Present Options to User
+
+Show what you found using a list like below:
+
+```
+📂 Specifications found:
+  ⚠️ {topic-1} - Building specification - not ready for planning
+  ✅ {topic-2} - Complete - ready for planning
+  ✅ {topic-3} - Complete - plan exists
+
+Which specification would you like to create a plan for?
+```
+
+**Important:** Only completed specifications should proceed to planning. If a specification is still being built, advise the user to complete the specification phase first.
+
+Ask: **Which specification would you like to plan?**
+
+## Step 4: Choose Output Destination
+
+Ask: **Where should this plan live?**
+
+Load **[output-formats.md](skills/technical-planning/references/output-formats.md)** and present the available formats to help the user choose. Then load the corresponding output adapter for that format's setup requirements.
+
+## Step 5: Gather Additional Context
+
+- Any additional context or priorities to consider?
+- Any constraints since the specification was completed?
+
+## Step 6: Invoke Planning Skill
+
+Pass to the technical-planning skill with:
+- Specification path
+- Output format chosen
+- Additional context gathered
+
+**Example handoff:**
+```
+Planning session for: {topic}
+Specification: docs/workflow/specification/{topic}.md
+Output format: {format}
+
+Begin planning using the technical-planning skill.
+```
+
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- The specification is the sole source of truth for planning - do not reference discussions
+- Commit the plan files when complete

package/commands/start-research.md

@@ -0,0 +1,21 @@
+---
+description: Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.
+---
+
+Invoke the **technical-research** skill for this conversation.
+
+Then ask these questions to kickstart the exploration:
+
+1. **What's on your mind?**
+   - What idea or topic do you want to explore?
+   - What prompted this - a problem, opportunity, curiosity?
+
+2. **What do you already know?**
+   - Any initial thoughts or research you've done?
+   - Constraints or context I should be aware of?
+
+3. **Where should we start?**
+   - Technical feasibility? Market landscape? Business model?
+   - Or just talk it through and see where it goes?
+
+Ask these questions clearly and wait for responses before proceeding. The skill handles everything else.

package/commands/start-specification.md

@@ -0,0 +1,89 @@
+---
+description: Start a specification session from an existing discussion. Discovers available discussions, checks for existing specifications, and invokes the technical-specification skill.
+---
+
+Invoke the **technical-specification** skill for this conversation.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
+
+Before beginning, discover existing work and gather necessary information.
+
+## Important
+
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+
+## Step 1: Discover Existing Work
+
+Scan the codebase for discussions and specifications:
+
+1. **Find discussions**: Look in `docs/workflow/discussion/`
+   - Run `ls docs/workflow/discussion/` to list discussion files
+   - Each file is named `{topic}.md`
+
+2. **Check discussion status**: For each discussion file
+   - Run `head -20 docs/workflow/discussion/{topic}.md` to read the frontmatter and extract the `status:` field
+   - Do NOT use bash loops - run separate `head` commands for each topic
+
+3. **Check for existing specifications**: Look in `docs/workflow/specification/`
+   - Identify discussions that don't have corresponding specifications
+
+## Step 2: Check Prerequisites
+
+**If no discussions exist:**
+
+```
+⚠️ No discussions found in docs/workflow/discussion/
+
+The specification phase requires a completed discussion. Please run /start-discussion first to document the technical decisions, edge cases, and rationale before creating a specification.
+```
+
+Stop here and wait for the user to acknowledge.
+
+## Step 3: Present Options to User
+
+Show what you found using a list like below:
+
+```
+📂 Discussions found:
+  ✅ {topic-1} - Concluded - ready for specification
+  ⚠️ {topic-2} - Exploring - not ready for specification
+  ✅ {topic-3} - Concluded - specification exists
+
+Which discussion would you like to create a specification for?
+```
+
+**Important:** Only concluded discussions should proceed to specification. If a discussion is still exploring, advise the user to complete the discussion phase first.
+
+Ask: **Which discussion would you like to specify?**
+
+## Step 4: Gather Additional Context
+
+Ask:
+- Any additional context or priorities to consider?
+- Any constraints or changes since the discussion concluded?
+- Are there any existing partial plans or related documentation I should review?
+
+## Step 5: Invoke Specification Skill
+
+Pass to the technical-specification skill:
+- Discussion: `docs/workflow/discussion/{topic}.md`
+- Output: `docs/workflow/specification/{topic}.md`
+- Additional context gathered
+
+**Example handoff:**
+```
+Specification session for: {topic}
+Discussion: docs/workflow/discussion/{topic}.md
+Output: docs/workflow/specification/{topic}.md
+
+Begin specification using the technical-specification skill.
+Reference: specification-guide.md
+```
+
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- The specification phase validates and refines discussion content into a standalone document
+- Commit the specification files frequently during the session

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@leeovery/claude-technical-workflows",
+  "version": "2.0.0",
+  "description": "Technical workflow skills & commands for Claude Code",
+  "license": "MIT",
+  "author": "Lee Overy <me@leeovery.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leeovery/claude-technical-workflows.git"
+  },
+  "type": "module",
+  "scripts": {
+    "postinstall": "claude-plugins add"
+  },
+  "dependencies": {
+    "@leeovery/claude-manager": "^2.0.0"
+  },
+  "files": [
+    "skills",
+    "commands",
+    "agents",
+    "hooks"
+  ]
+}

package/skills/technical-discussion/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: technical-discussion
+description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. Second phase of research-discussion-specification-plan-implement-review workflow. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/workflow/discussion/{topic}.md that technical-specification uses to build validated specifications."
+---
+
+# Technical Discussion
+
+Act as **expert software architect** participating in discussions AND **documentation assistant** capturing them. Do both simultaneously. Engage deeply while documenting for planning teams.
+
+## Six-Phase Workflow
+
+1. **Research** (previous): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (YOU): WHAT and WHY - decisions, architecture, edge cases
+3. **Specification** (next): REFINE - validate and build standalone spec
+4. **Planning** (after): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (after): DOING - tests first, then code
+6. **Review** (final): VALIDATING - check work against artifacts
+
+You're at step 2. Capture context. Don't jump to specs, plans, or code.
+
+## What to Capture
+
+- **Back-and-forth debates**: Challenging, prolonged discussions show how we decided X over Y
+- **Small details**: If discussed, it mattered - edge cases, constraints, concerns
+- **Competing solutions**: Why A won over B and C when all looked good
+- **The journey**: False paths, "aha" moments, course corrections
+- **Goal**: Solve edge cases and problems before planning
+
+**On length**: Discussions can be thousands of lines. Length = whatever needed to fully capture discussion, debates, edge cases, false paths. Terseness preferred, but comprehensive documentation more important. Don't summarize - document.
+
+See **[meeting-assistant.md](references/meeting-assistant.md)** for detailed approach.
+
+## Structure
+
+**Output**: `docs/workflow/discussion/{topic}.md`
+
+Use **[template.md](references/template.md)** for structure:
+
+- **Document-level**: Context, references, questions list
+- **Per-question**: Each question gets its own section with options, journey, and decision
+- **Summary**: Key insights, current state, next steps
+
+**Per-question structure** keeps the reasoning contextual. Options considered, false paths, debates, and "aha" moments belong with the specific question they relate to - not as separate top-level sections. This preserves the journey alongside the decision.
+
+## Do / Don't
+
+**Do**: Capture debates, edge cases, why solutions won/lost, high-level context, focus on "why"
+
+**Don't**: Transcribe verbatim, write code/implementation, create build phases, skip context
+
+See **[guidelines.md](references/guidelines.md)** for best practices and anti-hallucination techniques.
+
+## Commit Frequently
+
+**Commit discussion docs often**:
+
+- At natural breaks in discussion
+- When solutions to problems are identified
+- When discussion branches/forks to new topics
+- Before context refresh (prevents hallucination/memory loss)
+
+**Why**: You lose memory on context refresh. Commits help you track, backtrack, and fill gaps. Critical for avoiding hallucination.
+
+## Quick Reference
+
+- **Approach**: **[meeting-assistant.md](references/meeting-assistant.md)** - Dual role, workflow
+- **Template**: **[template.md](references/template.md)** - Structure
+- **Guidelines**: **[guidelines.md](references/guidelines.md)** - Best practices

package/skills/technical-discussion/references/guidelines.md

@@ -0,0 +1,86 @@
+# Discussion Documentation Guidelines
+
+*Part of **[technical-discussion](../SKILL.md)** | See also: **[meeting-assistant.md](meeting-assistant.md)** · **[template.md](template.md)***
+
+---
+
+Best practices for documenting discussions. For DOCUMENTATION only - no plans or code.
+
+## Core Principles
+
+**One question at a time**: Don't overwhelm with multiple questions. Focus on single issue, get answer, move forward.
+
+**Multiple-choice preferred**: Easier to answer than open-ended. Present 2-3 options with trade-offs.
+
+**YAGNI ruthlessly**: Remove unnecessary features from all designs. If not discussed, don't add it.
+
+**Explore alternatives**: Always propose 2-3 approaches before settling. Show trade-offs.
+
+**Be flexible**: Go back and clarify when something doesn't make sense. Don't forge ahead on assumptions.
+
+**Ask questions**: Clarify ambiguity. Better to ask than assume.
+
+**Journey over destination**: "Explored MySQL, PostgreSQL, MongoDB. MySQL familiar but PostgreSQL better for JSON + ACID. Deciding factor: complex joins + JSON support" not just "Use PostgreSQL"
+
+**"Why" over "what"**: "Repository pattern lets us swap data sources (DB/API/cache) without changing actions. Eloquent would tightly couple us" not just "Use repository"
+
+**False paths valuable**: "Tried query scopes - don't cascade to relationships, security hole. Learning: need global scopes for isolation"
+
+## Anti-Hallucination
+
+**Don't assume**: If uncertain, say "Need to research cache race conditions" not "Cache handles race conditions with atomic locks"
+
+**Document uncertainty**: "Confidence: Medium. Confirmed throughput OK. Uncertain on memory/cost at scale"
+
+**Facts vs assumptions**: Label what's verified, what's assumed, what needs validation
+
+## When to Document
+
+**Create discussion doc when**:
+- Multiple valid approaches exist
+- Architectural/technical decisions needed
+- User explicitly asks to "discuss" or "explore"
+
+**Skip for**:
+- Obvious/trivial decisions
+- Following established patterns
+- Pure implementation tasks
+
+## Structure
+
+**Context**: Why discussing, problem, pain point
+**Options**: Approaches with trade-offs
+**Debates**: Back-and-forth, what mattered
+**Decisions**: What chosen, why, deciding factor
+**False Paths**: What didn't work, why
+**Impact**: Who benefits, what enabled
+
+## Update as Discussing
+
+- Check off answered questions
+- Add options as explored
+- Document false paths immediately
+- Record decisions with rationale
+- Keep "Current Thinking" updated
+
+## Common Pitfalls
+
+**Jumping to implementation**: Discussion ends at decisions, not at "here's how to build it"
+
+**Erasing false paths**: "Tried file cache, too slow for 1000+ users. Redis 10x faster. Lesson: file cache doesn't scale for high-frequency reads"
+
+**Missing "why"**: "Chose PostgreSQL because need JSON queries + ACID at scale + complex joins. MySQL JSON support limited" not just "Use PostgreSQL"
+
+**Too much detail too soon**: "Need user-specific cache keys with query params" not "Cache key: metrics:{user_id}:{date}:{SHA256(params)}"
+
+## Quality Check
+
+Before marking discussion complete:
+- ✅ Context clear
+- ✅ Questions answered (or parked)
+- ✅ Options explored with trade-offs
+- ✅ False paths documented
+- ✅ Decisions have rationale
+- ✅ Impact explained
+- ✅ Confidence stated
+- ✅ No hallucination

package/skills/technical-discussion/references/meeting-assistant.md

@@ -0,0 +1,102 @@
+# Discussion Documentation Approach
+
+*Part of **[technical-discussion](../SKILL.md)** | See also: **[template.md](template.md)** · **[guidelines.md](guidelines.md)***
+
+---
+
+Capture technical discussions for planning teams to build from.
+
+## Dual Role
+
+Wear **two hats simultaneously**:
+
+1. **Expert Architect** - Participate deeply, challenge approaches, identify edge cases, provide insights
+2. **Documentation Assistant** - Capture discussion, decisions, debates, rationale, edge cases, false paths
+
+You're an AI - do both. Engage fully while documenting. Don't dumb down.
+
+## Workflow
+
+**Your role: phases 1-2 only**
+
+1. **Discuss** - Participate
+2. **Document** - Capture
+3. **Plan** - ❌ Planning team's job
+4. **Implement** - ❌ Developers' job
+
+Stop after documentation. No plans, implementation steps, or code.
+
+## Capture Debates
+
+When discussions are challenging/prolonged - document thoroughly. Back-and-forth shows:
+- How we challenged approaches
+- Why solutions won over alternatives
+- Small details that mattered
+- Edge cases identified
+
+**More discussion = More documentation.**
+
+## What You Are / Aren't
+
+**Active Participant**: Architect providing insights, challenging approaches, identifying edge cases, solving problems
+
+**Documentation**: Capturing debates, decisions, rationale, "why", edge cases
+
+**NOT**: Verbatim transcriber, planner, coder (unless examples discussed)
+
+## What to Capture
+
+### Context
+Problem, why now, pain point.
+
+Example: "Slow dashboards (3-5s) affecting 200 enterprise users. Impacting renewals. Need fix before Q1."
+
+### Options
+Approaches, pros/cons, trade-offs.
+
+Example:
+- DB optimization: Helps but only gets to 2s
+- Caching: <500ms, users OK with staleness
+- Pre-aggregates: Fastest but months of work
+
+### Journey
+What didn't work, what changed thinking, "aha" moments.
+
+Example: "Thought DB optimization was answer. Profiling showed queries optimal - volume is problem. User research revealed they check every 10-15min, making caching viable."
+
+### Decisions
+What chosen, why, deciding factor, trade-offs.
+
+Example: "Redis caching with 5min TTL. Why: Gets target perf in 1 week vs months for alternatives. Trade-off: stale data acceptable per users."
+
+### Impact
+Who affected, problem solved, what enabled.
+
+Example: "200 enterprise users + sales get performant experience. Enables Q1 renewals."
+
+## Commit Often
+
+**Git commit discussion docs frequently:**
+
+- Natural breaks in discussion
+- When problems solved
+- When discussion forks to new topics
+- Before context refresh
+
+**Why**: Memory loss on context refresh causes hallucination. Commits help track, backtrack, fill gaps.
+
+## Principles
+
+**High-level over detailed**: "Queries taking 3-5s for 200 users" not "At 10:15am query took 3.2s average..."
+
+**Context over transcript**: "Explored caching. Key question: TTL length. Users check every 10-15min, so 5min TTL works" not verbatim dialogue.
+
+**Reasoning over conclusions**: "Redis caching because: users accept staleness, 4-week timeline, reversible" not just "Use Redis"
+
+**Journey over destination**: "Thought DB optimization was answer. Profiling showed queries optimal. User research revealed periodic checks, making caching viable" not just "Using caching"
+
+## For Planning Team
+
+Give them: Context (why), direction (what), trade-offs (constraints), rationale (why X over Y), false paths (what not to try)
+
+Your job ends at documentation. Planning team creates implementation plan.

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

@@ -0,0 +1,127 @@
+# Discussion Document Template
+
+*Part of **[technical-discussion](../SKILL.md)** | See also: **[meeting-assistant.md](meeting-assistant.md)** · **[guidelines.md](guidelines.md)***
+
+---
+
+Standard structure for `docs/workflow/discussion/{topic}.md`. DOCUMENT only - no plans or code.
+
+This is a single file per topic.
+
+**This is a guide, not a form.** Use the structure to capture what naturally emerges from discussion. Don't force sections that didn't come up. The goal is to document the reasoning journey, not fill in every field.
+
+## Template
+
+```markdown
+# Discussion: {Topic}
+
+**Date**: YYYY-MM-DD
+**Status**: Exploring | Deciding | Concluded
+
+## Context
+
+What this is about, why we're discussing it, the problem or opportunity, current state.
+
+### References
+
+- [Related spec or doc](link)
+- [Prior discussion](link)
+
+## Questions
+
+- [ ] How should we handle X?
+      - Sub-question about edge case
+      - Context: brief note if needed
+- [ ] What's the right approach for Y?
+- [ ] Should Z be separate or combined with W?
+      - Related: how does this affect A?
+- [ ] ...
+
+---
+
+*Each question above gets its own section below. Check off as concluded.*
+
+---
+
+## How should we handle X?
+
+### Context
+Why this question matters, what's at stake.
+
+### Options Considered
+The approaches we looked at. If pros/cons naturally emerged:
+
+**Option A**
+- Pros: ...
+- Cons: ...
+
+**Option B**
+- Pros: ...
+- Cons: ...
+
+### Journey
+The back-and-forth exploration. What we initially thought. What changed our thinking. False paths - "We considered A but realised B because C." The "aha" moments. Small details that mattered.
+
+If there was notable debate:
+- **Positions**: What each side argued
+- **Resolution**: What made us choose, what detail tipped it
+
+### Decision
+What we chose, why, the deciding factor, trade-offs accepted, confidence level.
+
+---
+
+## What's the right approach for Y?
+
+*(Same structure: Context → Options → Journey → Decision)*
+
+---
+
+## Summary
+
+### Key Insights
+1. Cross-cutting learning from the discussion
+2. Something that applies broadly
+
+### Current State
+- What's resolved
+- What's still uncertain
+
+### Next Steps
+- [ ] Research X
+- [ ] Validate Y
+```
+
+## Usage Notes
+
+**When creating**:
+1. Ensure discussion directory exists: `docs/workflow/discussion/`
+2. Create file: `{topic}.md`
+3. Fill header: date, status
+4. Start with context: why discussing?
+5. List questions: what needs deciding?
+
+**During discussion**:
+- Work through questions one at a time
+- Document options, journey, and decision for each
+- Check off questions as concluded
+- Keep journey contextual - false paths, debates, and "aha" moments belong with the question they relate to
+
+**Per-question structure**:
+- **Context**: Why this specific question matters
+- **Options Considered**: Approaches explored - include pros/cons if they naturally emerged
+- **Journey**: The exploration - what we thought, what changed, false paths, debates, insights
+- **Decision**: What we chose, why, the deciding factor
+
+**Flexibility**: Not every question needs all sections. Some questions have clear options with pros/cons. Some have heated debate worth capturing. Some are straightforward. Document what naturally came up - don't force structure onto a simple discussion.
+
+**Anti-patterns**:
+- Don't pull false paths into a separate top-level section - keep them with the question they relate to
+- Don't turn into plan (no implementation steps)
+- Don't write code - unless it came up in discussion (e.g., API shape, pattern example) and is relevant to capture
+- Don't summarise the journey - document it
+
+**Complete when**:
+- Major questions concluded with rationale
+- Trade-offs understood
+- Path forward clear