@leeovery/claude-technical-workflows 2.0.41 → 2.0.43

package/commands/workflow/start-implementation.md

@@ -1,7 +1,10 @@
 ---
 description: Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill.
+allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
 ---
 
+Invoke the **technical-implementation** skill for this conversation.
+
 ## Workflow Context
 
 This is **Phase 5** of the six-phase workflow:
@@ -19,23 +22,19 @@ This is **Phase 5** of the six-phase workflow:
 
 ---
 
-## 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.
+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.
+**CRITICAL**: This guidance is mandatory.
 
-## Important
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+- Do not act on gathered information until the skill is loaded - it contains the instructions for how to proceed
 
-Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+---
 
 ## Step 0: Run Migrations
 
@@ -45,44 +44,101 @@ Invoke the `/migrate` command and assess its output before proceeding to Step 1.
 
 ---
 
-## Step 1: Discover Existing Plans
+## Step 1: Run Discovery Script
+
+Run the discovery script to gather current state:
+
+```bash
+.claude/scripts/discovery-for-implementation-and-review.sh
+```
+
+This outputs structured YAML. Parse it to understand:
+
+**From `plans` section:**
+- `exists` - whether any plans exist
+- `files` - list of plans with: name, topic, status, date, format, specification, specification_exists
+- `count` - total number of plans
+
+**From `environment` section:**
+- `setup_file_exists` - whether environment-setup.md exists
+- `requires_setup` - true, false, or unknown
+
+**From `state` section:**
+- `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+
+**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.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Route Based on Scenario
+
+Use `state.scenario` from the discovery output to determine the path:
+
+#### If scenario is "no_plans"
+
+No plans exist yet.
+
+```
+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.
+```
+
+**STOP.** Wait for user to acknowledge before ending.
 
-Scan the codebase for plans:
+#### If scenario is "single_plan" or "multiple_plans"
 
-1. **Find plans**: Look in `docs/workflow/planning/`
-   - Run `ls docs/workflow/planning/` to list plan files
-   - Each file is named `{topic}.md`
+Plans exist.
 
-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
+→ Proceed to **Step 3** to present options.
 
-## Step 2: Present Options to User
+---
 
-Show what you found.
+## Step 3: Present Plans and Select
 
-> **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`.
+Present all discovered plans to help the user make an informed choice.
 
-> **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.
+**Present the full state:**
 
 ```
-Plans found:
-  {topic-1}
-  {topic-2}
+Available Plans:
+
+  1. {topic-1} (in-progress) - format: local-markdown
+  2. {topic-2} (concluded) - format: local-markdown
+  3. {topic-3} (in-progress) - format: beads
 
-Which plan would you like to implement?
+Which plan would you like to implement? (Enter a number or name)
 ```
 
-## Step 3: Check External Dependencies
+**Legend:**
+- `in-progress` = implementation ongoing or not started
+- `concluded` = implementation complete (can still be selected for review/continuation)
+
+**If single plan exists (auto-select):**
+```
+Auto-selecting: {topic} (only available plan)
+```
+→ Proceed directly to **Step 4**.
+
+**If multiple plans exist:**
+
+**STOP.** Wait for user response.
+
+→ Based on user choice, proceed to **Step 4**.
+
+---
+
+## Step 4: 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:
+After the plan is selected:
 
-1. **Read the External Dependencies section** from the plan index file
+1. **Read the External Dependencies section** from the plan 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)
@@ -100,10 +156,8 @@ UNRESOLVED (not yet planned):
   → No plan exists for this topic. Create with /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.
+- authentication: User context retrieval
+  → Status: in-progress. This task must be completed first.
 
 OPTIONS:
 1. Implement the blocking dependencies first
@@ -111,61 +165,90 @@ OPTIONS:
 3. Run /link-dependencies to wire up any recently completed plans
 ```
 
+**STOP.** Wait for user response.
+
 ### 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`
+2. Update the plan 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.
+If all dependencies are resolved and complete (or satisfied externally), proceed to Step 5.
 
 ```
-✅ External dependencies satisfied:
-- billing-system: Invoice generation → beads-b7c2.1.1 (complete)
-- authentication: User context → beads-a3f8.1.2 (complete)
+✅ External dependencies satisfied.
+```
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 5: Check Environment Setup
+
+> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The skill contains instructions for handling environment setup.
+
+Use the `environment` section from the discovery output:
 
-Proceeding with environment setup...
+**If `setup_file_exists: true` and `requires_setup: false`:**
 ```
+Environment: No special setup required.
+```
+→ Proceed to **Step 6**.
+
+**If `setup_file_exists: true` and `requires_setup: true`:**
+```
+Environment setup file found: docs/workflow/environment-setup.md
+```
+→ Proceed to **Step 6**.
 
-## Step 4: Check Environment Setup
+**If `setup_file_exists: false` or `requires_setup: unknown`:**
 
-> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. Execution instructions are in the technical-implementation skill.
+Ask:
+```
+Are there any environment setup instructions I should follow before implementation?
+(Or "none" if no special setup is needed)
+```
 
-After the user selects a plan:
+**STOP.** Wait for user response.
 
-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
+- If the user provides instructions, save them to `docs/workflow/environment-setup.md`, commit and push
+- If the user says no/none, create `docs/workflow/environment-setup.md` with "No special setup required." and commit
 
-## Step 5: Ask About Scope
+→ Proceed to **Step 6**.
+
+---
+
+## Step 6: 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
+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 incomplete task
 
 Which approach?
 ```
 
+**STOP.** Wait for user response.
+
 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.
+> **Note:** Do NOT verify that the phase or task exists at this stage. Record the user's answer in the handoff context. Validation happens when the skill is invoked.
 
-## Step 6: Invoke the Skill
+→ Proceed to **Step 7**.
+
+---
+
+## Step 7: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -176,14 +259,11 @@ Invoke the [technical-implementation](../../skills/technical-implementation/SKIL
 Implementation session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
-Scope: {all phases | specific phase | specific task | next-available}
+Specification: {specification} (exists: {true|false})
+Scope: {all phases | Phase N | Task N.M | next-available}
 
-Dependencies: All satisfied ✓
-Environment setup: {completed | not needed}
+Dependencies: {All satisfied ✓ | List any notes}
+Environment: {Setup required | No special setup required}
 
 Invoke the technical-implementation skill.
 ```
-
-## Notes
-
-- Ask questions clearly and wait for responses before proceeding

package/commands/workflow/start-planning.md

@@ -1,5 +1,6 @@
 ---
 description: Start a planning session from an existing specification. Discovers available specifications, asks where to store the plan, and invokes the technical-planning skill.
+allowed-tools: Bash(.claude/scripts/discovery-for-planning.sh)
 ---
 
 Invoke the **technical-planning** skill for this conversation.
@@ -25,11 +26,15 @@ This is **Phase 4** of the six-phase workflow:
 
 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.
+**CRITICAL**: This guidance is mandatory.
 
-## Important
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+- Do not act on gathered information until the skill is loaded - it contains the instructions for how to proceed
 
-Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+---
 
 ## Step 0: Run Migrations
 
@@ -39,64 +44,121 @@ Invoke the `/migrate` command and assess its output before proceeding to Step 1.
 
 ---
 
-## Step 1: Discover Existing Work
+## Step 1: Run Discovery Script
+
+Run the discovery script to gather current state:
+
+```bash
+.claude/scripts/discovery-for-planning.sh
+```
+
+This outputs structured YAML. Parse it to understand:
+
+**From `specifications` section:**
+- `exists` - whether any specifications exist
+- `feature` - list of feature specs (name, status, has_plan)
+- `crosscutting` - list of cross-cutting specs (name, status)
+- `counts.feature` - total feature specifications
+- `counts.feature_ready` - feature specs ready for planning (concluded + no plan)
+- `counts.crosscutting` - total cross-cutting specifications
+
+**From `plans` section:**
+- `exists` - whether any plans exist
+- `files` - each plan's name, format, and status
+
+**From `state` section:**
+- `scenario` - one of: `"no_specs"`, `"no_ready_specs"`, `"single_ready_spec"`, `"multiple_ready_specs"`
+
+**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.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Route Based on Scenario
+
+Use `state.scenario` from the discovery output to determine the path:
+
+#### If scenario is "no_specs"
+
+No specifications exist yet.
+
+```
+No specifications found in docs/workflow/specification/
+
+The planning phase requires a concluded specification. Please run /start-specification first.
+```
+
+**STOP.** Wait for user to acknowledge before ending.
 
-Scan the codebase for specifications and plans:
+#### If scenario is "no_ready_specs"
 
-1. **Find specifications**: Look in `docs/workflow/specification/`
-   - Run `ls docs/workflow/specification/` to list specification files
-   - Each file is named `{topic}.md`
+Specifications exist but none are ready for planning (either still in-progress, or already have plans).
 
-2. **Check specification metadata**: For each specification file
-   - Run `head -20 docs/workflow/specification/{topic}.md` to read the frontmatter
-   - Extract the `status:` field (Building specification | Complete)
-   - Extract the `type:` field (feature | cross-cutting) - if not present, default to `feature`
-   - Do NOT use bash loops - run separate `head` commands for each topic
+→ Proceed to **Step 3** to show the state.
 
-3. **Categorize specifications**:
-   - **Feature specifications** (`type: feature` or unspecified): Candidates for planning
-   - **Cross-cutting specifications** (`type: cross-cutting`): Reference context only - do NOT offer for planning
+#### If scenario is "single_ready_spec" or "multiple_ready_specs"
 
-4. **Check for existing plans**: Look in `docs/workflow/planning/`
-   - Identify feature specifications that don't have corresponding plans
+Specifications are ready for planning.
 
-## Step 2: Check Prerequisites
+→ Proceed to **Step 3** to present options.
 
-**If no specifications exist:**
+## Step 3: Present Workflow State and Options
+
+Present everything discovered to help the user make an informed choice.
+
+**Present the full state:**
 
 ```
-⚠️ No specifications found in docs/workflow/specification/
+Workflow Status: Planning Phase
+
+Feature specifications:
+  1. · {topic-1} (in-progress) - not ready
+  2. ✓ {topic-2} (concluded) - ready for planning
+  3. - {topic-3} (concluded) → plan exists
 
-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.
+Cross-cutting specifications (reference context):
+  - {caching-strategy} (concluded)
+  - {rate-limiting} (concluded)
+
+Existing plans:
+  - {topic-3}.md (in-progress, local-markdown)
 ```
 
-Stop here and wait for the user to acknowledge.
+**Legend:**
+- `·` = not ready for planning (still in-progress)
+- `✓` = ready for planning (concluded, no plan yet)
+- `-` = already has a plan
 
-## Step 3: Present Options to User
+**Then present options based on what's ready:**
 
-Show what you found, separating feature specs (planning targets) from cross-cutting specs (reference context):
+**If multiple specs ready for planning:**
+```
+Which specification would you like to plan? (Enter a number or name)
+```
 
+**STOP.** Wait for user response.
+
+**If single spec ready for planning (auto-select):**
+```
+Auto-selecting: {topic} (only ready specification)
 ```
-📂 Feature Specifications (planning targets):
-  ⚠️ {topic-1} - Building specification - not ready for planning
-  ✅ {topic-2} - Complete - ready for planning
-  ✅ {topic-3} - Complete - plan exists
+→ Proceed directly to **Step 4**.
 
-📚 Cross-Cutting Specifications (reference context):
-  ✅ {caching-strategy} - Complete - will inform planning
-  ✅ {rate-limiting} - Complete - will inform planning
+**If no specs ready for planning:**
+```
+No specifications ready for planning.
 
-Which feature specification would you like to create a plan for?
+To proceed:
+- Complete any "in-progress" specifications with /start-specification
+- Or create a new specification first
 ```
 
-**Important:**
-- Only completed **feature** specifications should proceed to planning
-- **Cross-cutting** specifications are NOT planning targets - they inform feature plans
-- If a specification is still being built, advise the user to complete the specification phase first
+**STOP.** Wait for user response before ending.
 
-**Auto-select:** If exactly one completed feature specification exists, automatically select it and proceed to Step 4. Inform the user which specification was selected. Do not ask for confirmation.
+→ Based on user choice, proceed to **Step 4**.
 
-Ask: **Which feature specification would you like to plan?**
+---
 
 ## Step 4: Choose Output Destination
 
@@ -104,14 +166,27 @@ 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.
 
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 5**.
+
+---
+
 ## Step 5: Gather Additional Context
 
+Ask:
 - Any additional context or priorities to consider?
-- Any constraints since the specification was completed?
+- Any constraints since the specification was concluded?
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 6**.
 
-## Step 5b: Surface Cross-Cutting Context
+---
+
+## Step 6: Surface Cross-Cutting Context
 
-If any **completed cross-cutting specifications** exist, surface them as reference context for planning:
+If any **concluded cross-cutting specifications** exist (from `specifications.crosscutting` in discovery), surface them as reference context for planning:
 
 1. **List applicable cross-cutting specs**:
    - Read each cross-cutting specification
@@ -129,7 +204,11 @@ These specifications contain validated architectural decisions that should infor
 
 **If no cross-cutting specifications exist**: Skip this step.
 
-## Step 6: Invoke the Skill
+→ Proceed to **Step 7**.
+
+---
+
+## Step 7: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 

package/commands/workflow/start-research.md

@@ -23,32 +23,109 @@ This is **Phase 1** of the six-phase workflow:
 
 ## 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.
+
+**CRITICAL**: This guidance is mandatory.
+
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+- Do not act on gathered information until the skill is loaded - it contains the instructions for how to proceed
+
+---
+
 ## Step 0: Run Migrations
 
 **This step is mandatory. You must complete it before proceeding.**
 
-Invoke the `/migrate` command and assess its output before proceeding.
+Invoke the `/migrate` command and assess its output before proceeding to Step 1.
+
+---
+
+## Step 1: Get the Seed Idea
+
+Ask:
+
+```
+What's on your mind?
+
+- What idea or topic do you want to explore?
+- What prompted this - a problem, opportunity, curiosity?
+```
+
+**STOP.** Wait for user response before proceeding.
+
+→ Proceed to **Step 2**.
 
 ---
 
-Ask these questions to gather context:
+## Step 2: Understand Current Knowledge
+
+Ask:
 
-1. **What's on your mind?**
-   - What idea or topic do you want to explore?
-   - What prompted this - a problem, opportunity, curiosity?
+```
+What do you already know?
 
-2. **What do you already know?**
-   - Any initial thoughts or research you've done?
-   - Constraints or context I should be aware of?
+- Any initial thoughts or research you've done?
+- Constraints or context I should be aware of?
+```
+
+**STOP.** Wait for user response before proceeding.
+
+→ Proceed to **Step 3**.
+
+---
 
-3. **Where should we start?**
-   - Technical feasibility? Market landscape? Business model?
-   - Or just talk it through and see where it goes?
+## Step 3: Determine Starting Point
 
-Ask these questions clearly and wait for responses before proceeding.
+Ask:
 
-## Invoke the Skill
+```
+Where should we start?
+
+- Technical feasibility? Market landscape? Business model?
+- Or just talk it through and see where it goes?
+```
+
+**STOP.** Wait for user response before proceeding.
+
+→ Proceed to **Step 4**.
+
+---
+
+## Step 4: Gather Final Context
+
+Ask:
+
+```
+Any constraints or context I should know about upfront?
+
+(Or "none" if we're starting fresh)
+```
+
+**STOP.** Wait for user response before proceeding.
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 5: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
 Invoke the [technical-research](../../skills/technical-research/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:**
+```
+Research session for: {topic}
+Output: docs/workflow/research/exploration.md
+
+Context:
+- Prompted by: {problem, opportunity, or curiosity}
+- Already knows: {any initial thoughts or research, or "starting fresh"}
+- Starting point: {technical feasibility, market, business model, or "open exploration"}
+- Constraints: {any constraints mentioned, or "none"}
+
+Invoke the technical-research skill.
+```