@leeovery/claude-technical-workflows 2.0.15 → 2.0.17

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.

package/commands/workflow:start-review.md

@@ -0,0 +1,112 @@
+---
+description: Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill.
+---
+
+Invoke the **technical-review** skill for this conversation.
+
+## Workflow Context
+
+This is **Phase 6** 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 | |
+| **6. Review** | VALIDATING - check work against artifacts | HERE |
+
+**Stay in your lane**: Verify that every plan task was implemented, tested adequately, and meets quality standards. Don't fix code - identify problems. You're reviewing, not building.
+
+---
+
+## 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: Check Prerequisites
+
+**If no plans exist:**
+
+```
+No plans found in docs/workflow/planning/
+
+The review phase requires a completed implementation based on a plan. Please run /workflow:start-planning first to create a plan, then /workflow:start-implementation to build it.
+```
+
+Stop here and wait for the user to acknowledge.
+
+## Step 3: Present Options to User
+
+Show what you found:
+
+```
+Plans found:
+  {topic-1} (format: {format})
+  {topic-2} (format: {format})
+
+Which plan would you like to review the implementation for?
+```
+
+**Auto-select:** If exactly one plan exists, automatically select it and proceed to Step 4. Inform the user which plan was selected. Do not ask for confirmation.
+
+## Step 4: Identify Implementation Scope
+
+Determine what code to review:
+
+1. **Check git status** - See what files have changed
+2. **Ask user** if unclear:
+   - "What code should I review? (all changes, specific directories, or specific files)"
+
+## Step 5: Locate Specification (Optional)
+
+Check if a specification exists:
+
+1. **Look for specification**: Check `docs/workflow/specification/{topic}.md`
+2. **If exists**: Note the path for context
+3. **If missing**: Proceed without - the plan is the primary review artifact
+
+## Step 6: Invoke Review Skill
+
+Pass to the technical-review skill:
+- Plan: `docs/workflow/planning/{topic}.md`
+- Format: (from frontmatter)
+- Specification: `docs/workflow/specification/{topic}.md` (if exists)
+- Implementation scope: (files/directories to review)
+
+**Example handoff:**
+```
+Review session for: {topic}
+Plan: docs/workflow/planning/{topic}.md
+Format: {format}
+Specification: docs/workflow/specification/{topic}.md (or: Not available)
+Scope: {implementation scope}
+
+Begin review using the technical-review skill.
+```
+
+## Notes
+
+- Ask questions clearly and wait for responses before proceeding
+- Review produces feedback (approve, request changes, or comments) - it does NOT fix code
+- Verify ALL plan tasks, don't sample

package/commands/workflow:start-specification.md

@@ -0,0 +1,106 @@
+---
+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.
+
+## Workflow Context
+
+This is **Phase 3** 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 | ◀ HERE |
+| 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**: Validate and refine discussion content into a standalone specification. Don't jump to planning, phases, tasks, or code. The specification is the "line in the sand" - everything after this has hard dependencies on it.
+
+---
+
+## 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 /workflow: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:
+- Source: `docs/workflow/discussion/{topic}.md`
+- Output: `docs/workflow/specification/{topic}.md`
+- Additional context gathered
+
+**Example handoff:**
+```
+Specification session for: {topic}
+Source: 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

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

package/skills/technical-discussion/SKILL.md

@@ -7,16 +7,21 @@ description: "Document technical discussions as expert architect and meeting ass
 
 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
+## Purpose in the 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
+This skill can be used:
+- **Sequentially** (Phase 2): After research to debate and document decisions
+- **Standalone** (Contract entry): To document technical decisions from any source
 
-You're at step 2. Capture context. Don't jump to specs, plans, or code.
+Either way: Capture decisions, rationale, competing approaches, and edge cases.
+
+### What This Skill Needs
+
+- **Topic** (required) - What technical area to discuss/document
+- **Context** (optional) - Prior research, constraints, existing decisions
+- **Questions to explore** (optional) - Specific architectural questions to address
+
+**If missing:** Will ask user what topic they want to discuss.
 
 ## What to Capture
 

package/skills/technical-implementation/SKILL.md

@@ -9,16 +9,23 @@ Act as **expert senior developer** who builds quality software through disciplin
 
 Execute plans through strict TDD. Write tests first, then code to pass them.
 
-## Six-Phase Workflow
+## Purpose in the Workflow
 
-1. **Research** (previous): EXPLORE - ideas, feasibility, market, business, learning
-2. **Discussion** (previous): WHAT and WHY - decisions, architecture, rationale
-3. **Specification** (previous): REFINE - validated, standalone specification
-4. **Planning** (previous): HOW - phases, tasks, acceptance criteria
-5. **Implementation** (YOU): DOING - tests first, then code
-6. **Review** (next): VALIDATING - check work against artifacts
+This skill can be used:
+- **Sequentially** (Phase 5): To execute a plan created by technical-planning
+- **Standalone** (Contract entry): To execute any plan that follows plan-format conventions
 
-You're at step 5. Execute the plan. Don't re-debate decisions.
+Either way: Execute via strict TDD - tests first, implementation second.
+
+### What This Skill Needs
+
+- **Plan content** (required) - Phases, tasks, and acceptance criteria to execute
+- **Plan format** (required) - How to parse tasks (from plan frontmatter)
+- **Specification content** (optional) - For context when task rationale is unclear
+- **Environment setup** (optional) - First-time setup instructions
+- **Scope** (optional) - Specific phase/task to work on
+
+**If missing:** Will ask user for plan location. If no specification, plan becomes sole authority.
 
 ## Hard Rules
 
@@ -51,9 +58,10 @@ Complete ALL setup steps before proceeding to implementation work.
 
    See **[environment-setup.md](references/environment-setup.md)** for details.
 
-2. **Read the plan** from `docs/workflow/planning/{topic}.md`
+2. **Read the plan** from the provided location (typically `docs/workflow/planning/{topic}.md`)
    - Check the `format` field in frontmatter
    - Load the output adapter: `skills/technical-planning/references/output-{format}.md`
+   - If no format field, ask user which format the plan uses
    - Follow the **Implementation** section for how to read tasks and update progress
 
 3. **Read the TDD workflow** - Load **[tdd-workflow.md](references/tdd-workflow.md)** before writing any code. This is mandatory.
@@ -85,14 +93,18 @@ Keep user informed of progress:
 
 ## When to Reference Specification
 
-Check the specification (`docs/workflow/specification/{topic}.md`) when:
+Check the specification when:
 
 - Task rationale is unclear
 - Multiple valid approaches exist
 - Edge case handling not specified in plan
 - You need the "why" behind a decision
 
-The specification is the source of truth. Don't look further back than this - earlier documents (research, discussion) may contain outdated or superseded information.
+**Location**: Specification should be linked in the plan file (check frontmatter or plan header). Ask user if not found.
+
+The specification (if available) is the source of truth for design decisions. If no specification exists, the plan is the authority.
+
+**Important:** If research or discussion documents exist from earlier workflow phases, ignore them during implementation. They may contain outdated ideas, rejected approaches, or superseded decisions. The specification filtered and validated that content - refer only to the specification and plan.
 
 ## Project-Specific Conventions