@leeovery/claude-technical-workflows 2.0.16 → 2.0.17

package/commands/workflow:start-discussion.md

@@ -0,0 +1,339 @@
+---
+description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
+---
+
+Invoke the **technical-discussion** skill for this conversation.
+
+## Workflow Context
+
+This is **Phase 2** of the six-phase workflow:
+
+| Phase | Focus | You |
+|-------|-------|-----|
+| 1. Research | EXPLORE - ideas, feasibility, market, business | |
+| **2. Discussion** | WHAT and WHY - decisions, architecture, edge cases | ◀ HERE |
+| 3. Specification | REFINE - validate into standalone spec | |
+| 4. Planning | HOW - phases, tasks, acceptance criteria | |
+| 5. Implementation | DOING - tests first, then code | |
+| 6. Review | VALIDATING - check work against artifacts | |
+
+**Stay in your lane**: Capture the WHAT and WHY - decisions, rationale, competing approaches, edge cases. Don't jump to specifications, plans, or code. This is the time for debate and documentation.
+
+---
+
+## 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 determine the best entry path.
+
+## 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 research and discussions:
+
+1. **Find research**: Look in `docs/workflow/research/`
+   - Run `ls docs/workflow/research/` to list research files
+   - Note which files exist (may include `exploration.md` and semantic files like `market-landscape.md`)
+
+2. **Find discussions**: Look in `docs/workflow/discussion/`
+   - Run `ls docs/workflow/discussion/` to list discussion files
+   - Each file is named `{topic}.md`
+
+3. **Check discussion status**: For each discussion file
+   - Run `head -10 docs/workflow/discussion/{topic}.md` to extract the `Status:` field
+   - Status values: `Exploring`, `Deciding`, or `Concluded`
+   - Do NOT use bash loops - run separate commands for each file
+
+4. **Check for cached analysis** (if research files exist):
+   - Check if `docs/workflow/.cache/research-analysis.md` exists
+   - If it exists, read it to get the stored checksum from the frontmatter
+
+5. **Compute current research checksum** (if research files exist):
+   - Run exactly: `cat docs/workflow/research/*.md 2>/dev/null | md5sum | cut -d' ' -f1`
+   - IMPORTANT: Use this exact command - glob expansion is alphabetically sorted by default
+   - Do NOT modify or "simplify" this command - checksum must be deterministic
+   - Store this value to compare with the cached checksum
+
+## Step 2: Present Workflow State and Options
+
+Present the workflow state and available options based on what was discovered.
+
+**Format:**
+```
+📂 Workflow state:
+  📚 Research: {count} files found / None found
+  💬 Discussions: {count} existing / None yet
+```
+
+Then present the appropriate options:
+
+**If research AND discussions exist:**
+```
+How would you like to proceed?
+
+1. **From research** - Analyze research and suggest undiscussed topics
+2. **Continue discussion** - Resume an existing discussion
+3. **Fresh topic** - Start a new discussion
+```
+
+**If ONLY research exists:**
+```
+How would you like to proceed?
+
+1. **From research** - Analyze research and suggest topics to discuss
+2. **Fresh topic** - Start a new discussion
+```
+
+**If ONLY discussions exist:**
+```
+How would you like to proceed?
+
+1. **Continue discussion** - Resume an existing discussion
+2. **Fresh topic** - Start a new discussion
+```
+
+**If NOTHING exists:**
+```
+Starting fresh - no prior research or discussions found.
+
+What topic would you like to discuss?
+```
+Then skip to Step 5 (Fresh topic path).
+
+Wait for the user to choose before proceeding.
+
+## Step 3A: "From research" Path
+
+This step uses caching to avoid re-analyzing unchanged research documents.
+
+### Step 3A.1: Check Cache Validity
+
+Compare the current research checksum (computed in Step 1.5) with the cached checksum:
+
+**If cache exists AND checksums match:**
+```
+📋 Using cached analysis
+
+Research documents unchanged since last analysis ({date from cache}).
+Loading {count} previously identified topics...
+
+💡 To force a fresh analysis, enter: refresh
+```
+
+Then load the topics from the cache file and skip to Step 3A.3 (Cross-reference).
+
+**If cache missing OR checksums differ:**
+```
+🔍 Analyzing research documents...
+```
+
+Proceed to Step 3A.2 (Full Analysis).
+
+### Step 3A.2: Full Analysis (when cache invalid)
+
+Read each research file and analyze the content to 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 take time to identify ALL potential topics including:
+- 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
+
+**Save to cache:**
+After analysis, create/update `docs/workflow/.cache/research-analysis.md`:
+
+```markdown
+---
+checksum: {computed_checksum}
+generated: {ISO date}
+research_files:
+  - {filename1}.md
+  - {filename2}.md
+---
+
+# Research Analysis Cache
+
+## Topics
+
+### {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}
+
+[... more topics ...]
+```
+
+Ensure the `.cache` directory exists: `mkdir -p docs/workflow/.cache`
+
+### Step 3A.3: Cross-reference with Discussions
+
+**Always performed** (whether using cache or fresh analysis):
+
+For each identified topic, check if a corresponding discussion already exists in `docs/workflow/discussion/`.
+
+### Step 3A.4: Present Findings
+
+**If using cached analysis:**
+```
+📋 Cached analysis (research unchanged since {date})
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+  ✅ {Already discussed theme} → discussed in {topic}.md
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+Which topic would you like to discuss? (Or enter 'refresh' for fresh analysis)
+```
+
+**If fresh analysis:**
+```
+🔍 Analysis complete (cached for future sessions)
+
+💡 Topics identified:
+
+  ✨ {Theme name}
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+  ✅ {Already discussed theme} → discussed in {topic}.md
+     Source: {filename}.md (lines {start}-{end})
+     "{Brief summary}"
+
+Which topic would you like to discuss? (Or describe something else)
+```
+
+**Key:**
+- ✨ = Undiscussed topic (potential new discussion)
+- ✅ = Already has a corresponding discussion
+
+### Step 3A.5: Handle "refresh" Request
+
+If user enters `refresh`:
+- Delete the cache file: `rm docs/workflow/.cache/research-analysis.md`
+- Return to Step 3A.2 (Full Analysis)
+- Inform user: "Refreshing analysis..."
+
+**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+
+Wait for the user to choose before proceeding to Step 4.
+
+## Step 3B: "Continue discussion" Path
+
+List existing discussions with their status:
+
+```
+💬 Existing discussions:
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description from context section}"
+
+  ⚡ {topic}.md — {Status}
+     "{Brief description}"
+
+  ✅ {topic}.md — Concluded
+     "{Brief description}"
+
+Which discussion would you like to continue?
+```
+
+**Key:**
+- ⚡ = In progress (Exploring or Deciding)
+- ✅ = Concluded (can still be continued/reopened)
+
+Wait for the user to choose, then proceed to Step 4.
+
+## Step 3C: "Fresh topic" Path
+
+Proceed directly to Step 4.
+
+## Step 4: 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?
+```
+
+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?
+```
+
+Wait for response before proceeding.
+
+## Step 5: Invoke Discussion Skill
+
+Begin the discussion session with appropriate context based on the path taken.
+
+**If 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 Step 3A}
+
+Begin discussion using the technical-discussion skill.
+```
+
+**If continuing or fresh:**
+```
+Discussion session for: {topic}
+Source: {existing discussion | fresh}
+Output: docs/workflow/discussion/{topic}.md
+
+Begin discussion using the technical-discussion skill.
+```
+
+**Setup:**
+- Ensure discussion directory exists: `docs/workflow/discussion/`
+- If new: Create file using the template structure
+- If continuing: Work with existing file
+- Commit frequently at natural discussion breaks
+
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- Discussion captures WHAT and WHY - don't jump to specifications or implementation
+- The goal is to work through edge cases, debates, and decisions before planning
+- Commit the discussion document frequently during the session

package/commands/workflow:start-implementation.md

@@ -0,0 +1,187 @@
+---
+description: Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill.
+---
+
+## Workflow Context
+
+This is **Phase 5** of the six-phase workflow:
+
+| Phase | Focus | You |
+|-------|-------|-----|
+| 1. Research | EXPLORE - ideas, feasibility, market, business | |
+| 2. Discussion | WHAT and WHY - decisions, architecture, edge cases | |
+| 3. Specification | REFINE - validate into standalone spec | |
+| 4. Planning | HOW - phases, tasks, acceptance criteria | |
+| **5. Implementation** | DOING - tests first, then code | ◀ HERE |
+| 6. Review | VALIDATING - check work against artifacts | |
+
+**Stay in your lane**: Execute the plan via strict TDD - tests first, then code. Don't re-debate decisions from the specification or expand scope beyond the plan. The plan is your authority.
+
+---
+
+## IMPORTANT: Follow these steps EXACTLY. Do not skip steps.
+
+- Ask each question and WAIT for a response before proceeding
+- Do NOT install anything or invoke tools until Step 6
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Do NOT make assumptions about what the user wants
+- Complete each step fully before moving to the next
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+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 Plans
+
+Scan the codebase for plans:
+
+1. **Find plans**: Look in `docs/workflow/planning/`
+   - Run `ls docs/workflow/planning/` to list plan files
+   - Each file is named `{topic}.md`
+
+2. **Check plan format**: For each plan file
+   - Run `head -10 docs/workflow/planning/{topic}.md` to read the frontmatter
+   - Note the `format:` field
+   - Do NOT use bash loops - run separate `head` commands for each topic
+
+## Step 2: Present Options to User
+
+Show what you found.
+
+> **Note:** If no plans exist, inform the user that this workflow is designed to be executed in sequence. They need to create plans from specifications prior to implementation using `/workflow:start-planning`.
+
+> **Auto-select:** If exactly one plan exists, automatically select it and proceed to Step 3. Inform the user which plan was selected. Do not ask for confirmation.
+
+```
+Plans found:
+  {topic-1}
+  {topic-2}
+
+Which plan would you like to implement?
+```
+
+## Step 3: Check External Dependencies
+
+**This step is a gate.** Implementation cannot proceed if dependencies are not satisfied.
+
+See **[dependencies.md](../skills/technical-planning/references/dependencies.md)** for dependency format and states.
+
+After the user selects a plan:
+
+1. **Read the External Dependencies section** from the plan index file
+2. **Check each dependency** according to its state:
+   - **Unresolved**: Block
+   - **Resolved**: Check if task is complete (load output format reference, follow "Querying Dependencies" section)
+   - **Satisfied externally**: Proceed
+
+### Blocking Behavior
+
+If ANY dependency is unresolved or incomplete, **stop and present**:
+
+```
+⚠️ Implementation blocked. Missing dependencies:
+
+UNRESOLVED (not yet planned):
+- billing-system: Invoice generation for order completion
+  → No plan exists for this topic. Create with /workflow:start-planning or mark as satisfied externally.
+
+INCOMPLETE (planned but not implemented):
+- beads-7x2k (authentication): User context retrieval
+  → Status: in_progress. This task must be completed first.
+
+These dependencies must be completed before this plan can be implemented.
+
+OPTIONS:
+1. Implement the blocking dependencies first
+2. Mark a dependency as "satisfied externally" if it was implemented outside this workflow
+3. Run /link-dependencies to wire up any recently completed plans
+```
+
+### Escape Hatch
+
+If the user says a dependency has been implemented outside the workflow:
+
+1. Ask which dependency to mark as satisfied
+2. Update the plan index file:
+   - Change `- {topic}: {description}` to `- ~~{topic}: {description}~~ → satisfied externally`
+3. Commit the change
+4. Re-check dependencies
+
+### All Dependencies Satisfied
+
+If all dependencies are resolved and complete (or satisfied externally), proceed to Step 4.
+
+```
+✅ External dependencies satisfied:
+- billing-system: Invoice generation → beads-b7c2.1.1 (complete)
+- authentication: User context → beads-a3f8.1.2 (complete)
+
+Proceeding with environment setup...
+```
+
+## Step 4: Check Environment Setup
+
+> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The technical-implementation skill will handle execution when invoked.
+
+After the user selects a plan:
+
+1. Check if `docs/workflow/environment-setup.md` exists
+2. If it exists, note the file location for the skill handoff
+3. If missing, ask: "Are there any environment setup instructions I should follow?"
+   - If the user provides instructions, save them to `docs/workflow/environment-setup.md`, commit and push to Git
+   - If the user says no, create `docs/workflow/environment-setup.md` with "No special setup required." and commit. This prevents asking again in future sessions.
+   - See `skills/technical-implementation/references/environment-setup.md` for format guidance
+
+## Step 5: Ask About Scope
+
+Ask the user about implementation scope:
+
+```
+How would you like to proceed?
+
+1. **Implement all phases** - Work through the entire plan sequentially
+2. **Implement specific phase** - Focus on one phase (e.g., "Phase 1")
+3. **Implement specific task** - Focus on a single task
+4. **Next available task** - Auto-discover the next unblocked task
+
+Which approach?
+```
+
+If they choose a specific phase or task, ask them to specify which one.
+
+> **Note:** Do NOT verify that the phase or task exists. Accept the user's answer and pass it to the skill. Validation happens during the implementation phase.
+
+## Step 6: Invoke Implementation Skill
+
+Invoke the **technical-implementation** skill for this conversation.
+
+Pass to the technical-implementation skill:
+- Plan: `docs/workflow/planning/{topic}.md`
+- Format: (from frontmatter)
+- Scope: (all phases | specific phase | specific task | next-available)
+- Dependencies: (all satisfied - verified in Step 3)
+- Environment setup: (completed | not needed)
+
+**Example handoff:**
+```
+Implementation session for: {topic}
+Plan: docs/workflow/planning/{topic}.md
+Format: {format}
+Scope: All phases
+
+Dependencies: All satisfied ✓
+Environment setup: Completed (or: Not needed)
+
+Begin implementation using the technical-implementation skill.
+```
+
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- Execute environment setup before starting implementation

package/commands/workflow:start-planning.md

@@ -0,0 +1,111 @@
+---
+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.
+
+## Workflow Context
+
+This is **Phase 4** of the six-phase workflow:
+
+| Phase | Focus | You |
+|-------|-------|-----|
+| 1. Research | EXPLORE - ideas, feasibility, market, business | |
+| 2. Discussion | WHAT and WHY - decisions, architecture, edge cases | |
+| 3. Specification | REFINE - validate into standalone spec | |
+| **4. Planning** | HOW - phases, tasks, acceptance criteria | ◀ HERE |
+| 5. Implementation | DOING - tests first, then code | |
+| 6. Review | VALIDATING - check work against artifacts | |
+
+**Stay in your lane**: Create the plan - phases, tasks, and acceptance criteria. Don't jump to implementation or write code. The specification is your sole input; transform it into actionable work items.
+
+---
+
+## 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 /workflow: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.
+
+**Auto-select:** If exactly one specification exists, automatically select it and proceed to Step 4. Inform the user which specification was selected. Do not ask for confirmation.
+
+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/workflow:start-research.md

@@ -0,0 +1,38 @@
+---
+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.
+
+## Workflow Context
+
+This is **Phase 1** of the six-phase workflow:
+
+| Phase | Focus | You |
+|-------|-------|-----|
+| **1. Research** | EXPLORE - ideas, feasibility, market, business | ◀ HERE |
+| 2. Discussion | WHAT and WHY - decisions, architecture, edge cases | |
+| 3. Specification | REFINE - validate into standalone spec | |
+| 4. Planning | HOW - phases, tasks, acceptance criteria | |
+| 5. Implementation | DOING - tests first, then code | |
+| 6. Review | VALIDATING - check work against artifacts | |
+
+**Stay in your lane**: Explore freely. This is the time for broad thinking, feasibility checks, and learning. Don't jump to formal discussions or specifications yet.
+
+---
+
+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.