@leeovery/claude-technical-workflows 2.0.15 → 2.0.17

package/commands/start-implementation.md

@@ -1,109 +1,15 @@
 ---
-description: Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill.
+description: "[DEPRECATED] Use /workflow:start-implementation instead"
 ---
 
-## IMPORTANT: Follow these steps EXACTLY. Do not skip steps.
+# Deprecated Command
 
-- Ask each question and WAIT for a response before proceeding
-- Do NOT install anything or invoke tools until Step 5
-- 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
+⚠️ **`/start-implementation` is deprecated.** Use `/workflow:start-implementation` instead.
 
-## Instructions
+The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
 
-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 `/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 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 4: 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 5: 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)
-- Environment setup: (completed | not needed)
-
-**Example handoff:**
-```
-Implementation session for: {topic}
-Plan: docs/workflow/planning/{topic}.md
-Format: {format}
-Scope: All phases
-
-Environment setup: Completed (or: Not needed)
-
-Begin implementation using the technical-implementation skill.
-```
+---
 
-## Notes
+**Forwarding to `/workflow:start-implementation`...**
 
-- Ask questions clearly and wait for responses before proceeding
-- Execute environment setup before starting implementation
+Run the `/workflow:start-implementation` command now.

package/commands/start-planning.md

@@ -1,94 +1,15 @@
 ---
-description: Start a planning session from an existing specification. Discovers available specifications, asks where to store the plan, and invokes the technical-planning skill.
+description: "[DEPRECATED] Use /workflow:start-planning instead"
 ---
 
-Invoke the **technical-planning** skill for this conversation.
+# Deprecated Command
 
-## Instructions
+⚠️ **`/start-planning` is deprecated.** Use `/workflow:start-planning` instead.
 
-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.
+The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
 
-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.
-
-**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
+**Forwarding to `/workflow:start-planning`...**
 
-- 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
+Run the `/workflow:start-planning` command now.

package/commands/start-research.md

@@ -1,21 +1,15 @@
 ---
-description: Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.
+description: "[DEPRECATED] Use /workflow:start-research instead"
 ---
 
-Invoke the **technical-research** skill for this conversation.
+# Deprecated Command
 
-Then ask these questions to kickstart the exploration:
+⚠️ **`/start-research` is deprecated.** Use `/workflow:start-research` instead.
 
-1. **What's on your mind?**
-   - What idea or topic do you want to explore?
-   - What prompted this - a problem, opportunity, curiosity?
+The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
 
-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?
+**Forwarding to `/workflow:start-research`...**
 
-Ask these questions clearly and wait for responses before proceeding. The skill handles everything else.
+Run the `/workflow:start-research` command now.

package/commands/start-specification.md

@@ -1,89 +1,15 @@
 ---
-description: Start a specification session from an existing discussion. Discovers available discussions, checks for existing specifications, and invokes the technical-specification skill.
+description: "[DEPRECATED] Use /workflow:start-specification instead"
 ---
 
-Invoke the **technical-specification** skill for this conversation.
+# Deprecated Command
 
-## Instructions
+⚠️ **`/start-specification` is deprecated.** Use `/workflow:start-specification` instead.
 
-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.
+The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
 
-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
+**Forwarding to `/workflow:start-specification`...**
 
-- 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
+Run the `/workflow:start-specification` command now.

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