@leeovery/claude-technical-workflows 2.0.15 → 2.0.17

package/README.md

@@ -59,8 +59,8 @@ You have two entry points:
 
 | Start here... | When... | Command |
 |---------------|---------|---------|
-| **Research** | You have a fresh idea to explore: feasibility, market, viability, early thoughts | `/start-research` |
-| **Discussion** | You already know what you're building and need to iron out the details | `/start-discussion` |
+| **Research** | You have a fresh idea to explore: feasibility, market, viability, early thoughts | `/workflow:start-research` |
+| **Discussion** | You already know what you're building and need to iron out the details | `/workflow:start-discussion` |
 
 **Research** is a free-for-all. Explore broadly, follow tangents, challenge assumptions. Not everything researched gets built, and that's fine. Use this for ideas that need validating before you commit.
 
@@ -76,15 +76,16 @@ Each phase builds on the previous. Specification validates your discussions into
 
 ### Commands
 
-Each phase has a command designed as its entry point:
+Each phase has a command designed as its entry point. Commands are prefixed with `workflow:` to indicate they're part of the sequential workflow system:
 
-| Phase          | Command                 |
-|----------------|-------------------------|
-| Research       | `/start-research`       |
-| Discussion     | `/start-discussion`     |
-| Specification  | `/start-specification`  |
-| Planning       | `/start-planning`       |
-| Implementation | `/start-implementation` |
+| Phase          | Command                          |
+|----------------|----------------------------------|
+| Research       | `/workflow:start-research`       |
+| Discussion     | `/workflow:start-discussion`     |
+| Specification  | `/workflow:start-specification`  |
+| Planning       | `/workflow:start-planning`       |
+| Implementation | `/workflow:start-implementation` |
+| Review         | `/workflow:start-review`         |
 
 Run the command directly or ask Claude to run it. Each command gathers the context it needs, asking what you're researching, discussing, or planning. Where relevant, it looks at outputs from the previous phase and offers you a choice from the list.
 
@@ -213,11 +214,15 @@ skills/
 └── technical-review/          # Phase 6: Validate against artifacts
 
 commands/
-├── start-research.md          # Begin research exploration
-├── start-discussion.md        # Begin technical discussions
-├── start-specification.md     # Begin specification building
-├── start-planning.md          # Begin implementation planning
-└── interview.md               # Focused questioning mode
+├── workflow:start-research.md       # Begin research exploration
+├── workflow:start-discussion.md     # Begin technical discussions
+├── workflow:start-specification.md  # Begin specification building
+├── workflow:start-planning.md       # Begin implementation planning
+├── workflow:start-implementation.md # Begin implementing a plan
+├── workflow:start-review.md         # Begin reviewing completed work
+├── link-dependencies.md             # Link dependencies across topics
+├── start-feature.md                 # Create spec directly from inline context
+└── interview.md                     # Focused questioning mode (general purpose)
 
 agents/
 └── chain-verifier.md          # Parallel task verification for review
@@ -329,16 +334,28 @@ Reviews completed work with fresh perspective. Validates implementation against
 
 ## Commands
 
-Slash commands to quickly invoke the workflow.
+### Workflow Commands
 
-| Command                                                       | Description                                                                                                                                                                                                |
-|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-research**](commands/start-research.md)             | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
-| [**/start-discussion**](commands/start-discussion.md)         | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
-| [**/start-specification**](commands/start-specification.md)   | Start a specification session from an existing discussion. Validates and refines discussion content into a standalone specification.                                                                       |
-| [**/start-planning**](commands/start-planning.md)             | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (markdown, Linear, Backlog.md, Beads). |
-| [**/start-implementation**](commands/start-implementation.md) | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
-| [**/interview**](commands/interview.md)                       | Shift into focused questioning mode during research or discussion. Probes ideas with non-obvious questions, challenges assumptions, and surfaces concerns.                                                 |
+Sequential workflow commands are prefixed with `workflow:` and expect files from previous phases.
+
+| Command                                                                              | Description                                                                                                                                                                                                |
+|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/workflow:start-research**](commands/workflow:start-research.md)                  | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
+| [**/workflow:start-discussion**](commands/workflow:start-discussion.md)              | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
+| [**/workflow:start-specification**](commands/workflow:start-specification.md)        | Start a specification session from an existing discussion. Validates and refines discussion content into a standalone specification.                                                                       |
+| [**/workflow:start-planning**](commands/workflow:start-planning.md)                  | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (markdown, Linear, Backlog.md, Beads). |
+| [**/workflow:start-implementation**](commands/workflow:start-implementation.md)      | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
+| [**/workflow:start-review**](commands/workflow:start-review.md)                      | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
+
+### Standalone Commands
+
+These commands can be used independently, without the full workflow.
+
+| Command                                                 | Description                                                                                                                                 |
+|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/start-feature**](commands/start-feature.md)         | Create a specification directly from inline context. For adding features to existing projects when you already know what you're building.  |
+| [**/interview**](commands/interview.md)                 | Shift into focused questioning mode. Probes ideas with non-obvious questions, challenges assumptions, and surfaces concerns.               |
+| [**/link-dependencies**](commands/link-dependencies.md) | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 
 ## Agents
 

package/commands/link-dependencies.md

@@ -0,0 +1,170 @@
+---
+description: Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format.
+---
+
+Link cross-topic dependencies across all existing plans.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+## Important
+
+Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
+
+## Step 1: Discover All Plans
+
+Scan the codebase for existing plans:
+
+1. **Find plan files**: Look in `docs/workflow/planning/`
+   - Run `ls docs/workflow/planning/` to list plan files
+   - Each file is named `{topic}.md`
+
+2. **Extract plan metadata**: For each plan file
+   - Read the frontmatter to get the `format:` field
+   - Note the format used by each plan
+
+**If no plans exist:**
+
+```
+No plans found in docs/workflow/planning/
+
+There are no plans to link. Create plans first.
+```
+
+Stop here.
+
+**If only one plan exists:**
+
+```
+Only one plan found: {topic}
+
+Cross-topic dependency linking requires at least two plans.
+```
+
+Stop here.
+
+## Step 2: Check Output Format Consistency
+
+Compare the `format:` field across all discovered plans.
+
+**If plans use different output formats:**
+
+```
+Mixed output formats detected:
+
+- authentication: beads
+- billing-system: linear
+- notifications: beads
+
+Cross-topic dependencies can only be wired within the same output format.
+Please consolidate your plans to use a single output format before linking dependencies.
+```
+
+Stop here.
+
+## Step 3: Extract External Dependencies
+
+For each plan, find the External Dependencies section:
+
+1. **Read the External Dependencies section** from each plan index file
+2. **Categorize each dependency**:
+   - **Unresolved**: `- {topic}: {description}` (no arrow, no task ID)
+   - **Resolved**: `- {topic}: {description} → {task-id}` (has task ID)
+   - **Satisfied externally**: `- ~~{topic}: {description}~~ → satisfied externally`
+
+3. **Build a summary**:
+
+```
+Dependency Summary
+
+Plan: authentication (format: beads)
+  - billing-system: Invoice generation (unresolved)
+  - user-management: User profiles → beads-7x2k (resolved)
+
+Plan: billing-system (format: beads)
+  - authentication: User context (unresolved)
+  - ~~payment-gateway: Payment processing~~ → satisfied externally
+
+Plan: notifications (format: beads)
+  - authentication: User lookup (unresolved)
+  - billing-system: Invoice events (unresolved)
+```
+
+## Step 4: Match Dependencies to Plans
+
+For each unresolved dependency:
+
+1. **Search for matching plan**: Does `docs/workflow/planning/{dependency-topic}.md` exist?
+   - If no match: Mark as "no plan exists" - cannot resolve yet
+
+2. **If plan exists**: Load the output format reference file
+   - Read `format:` from the dependency plan's frontmatter
+   - Load `skills/technical-planning/references/output-{format}.md`
+   - Follow the "Querying Dependencies" section to search for matching tasks
+
+3. **Handle ambiguous matches**:
+   - If multiple tasks could satisfy the dependency, present options to user
+   - Allow selecting multiple if the dependency requires multiple tasks
+
+## Step 5: Wire Up Dependencies
+
+For each resolved match:
+
+1. **Update the plan index file**:
+   - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
+
+2. **Create dependency in output format**:
+   - Load `skills/technical-planning/references/output-{format}.md`
+   - Follow the "Cross-Epic Dependencies" or equivalent section to create the blocking relationship
+
+## Step 6: Bidirectional Check
+
+For each plan that was a dependency target (i.e., other plans depend on it):
+
+1. **Check reverse dependencies**: Are there other plans that should have this wired up?
+2. **Offer to update**: "Plan X depends on tasks you just linked. Update its External Dependencies section?"
+
+## Step 7: Report Results
+
+Present a summary:
+
+```
+Dependency Linking Complete
+
+RESOLVED (newly linked):
+  - authentication → billing-system: beads-b7c2.1.1 (Invoice generation)
+  - notifications → authentication: beads-a3f8.1.2 (Session management)
+
+ALREADY RESOLVED (no action needed):
+  - authentication → user-management: beads-9m3p
+
+SATISFIED EXTERNALLY (no action needed):
+  - billing-system → payment-gateway
+
+UNRESOLVED (no matching plan exists):
+  - notifications → email-service: Email delivery
+
+  These dependencies have no corresponding plan. Either:
+  - Create a plan for the topic
+  - Mark as "satisfied externally" if already implemented
+
+UPDATED FILES:
+  - docs/workflow/planning/authentication.md
+  - docs/workflow/planning/notifications.md
+```
+
+## Step 8: Commit Changes
+
+If any files were updated:
+
+```
+Shall I commit these dependency updates? (y/n)
+```
+
+If yes, commit with message:
+```
+Link cross-topic dependencies
+
+- {summary of what was linked}
+```

package/commands/start-discussion.md

@@ -1,322 +1,15 @@
 ---
-description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
+description: "[DEPRECATED] Use /workflow:start-discussion instead"
 ---
 
-Invoke the **technical-discussion** skill for this conversation.
+# Deprecated Command
 
-## Instructions
+⚠️ **`/start-discussion` is deprecated.** Use `/workflow:start-discussion` 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 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
+**Forwarding to `/workflow:start-discussion`...**
 
-- 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
+Run the `/workflow:start-discussion` command now.

package/commands/start-feature.md

@@ -0,0 +1,80 @@
+---
+description: Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building.
+---
+
+Invoke the **technical-specification** skill for this conversation with inline feature context.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+This command is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
+
+## Step 1: Gather Feature Context
+
+Ask the user these questions (can be combined into one prompt):
+
+1. **What feature are you adding?**
+   - Brief description of what you're building
+
+2. **What's the scope?**
+   - Core functionality to implement
+   - Edge cases you're already aware of
+
+3. **Any constraints or integration points?**
+   - How this integrates with existing code
+   - Technical decisions already made
+   - Conventions to follow
+
+**Note**: If the user has already provided this context in their initial message, don't ask again - acknowledge what they've shared and proceed.
+
+## Step 2: Suggest a Topic Name
+
+Based on the feature description, suggest a topic name for the specification file:
+
+```
+Based on what you've described, I'd suggest the topic name: {suggested-topic}
+
+This will create: docs/workflow/specification/{suggested-topic}.md
+
+Is this name okay, or would you prefer something else?
+```
+
+## Step 3: Check for Existing Specifications
+
+Look in `docs/workflow/specification/` for naming conflicts:
+
+```bash
+ls docs/workflow/specification/
+```
+
+If a specification with the same name exists, inform the user and ask how to proceed:
+- Append to existing specification
+- Choose a different name
+- Replace existing specification
+
+## Step 4: Invoke Specification Skill
+
+Pass the gathered context to the technical-specification skill:
+
+```
+Feature specification for: {topic}
+
+## Feature Context (from user)
+
+{paste the gathered feature description, scope, and constraints}
+
+---
+
+Begin specification building using the technical-specification skill.
+
+This is feature mode - there is no discussion document to reference.
+Work from the inline context provided above.
+```
+
+## Notes
+
+- The specification skill will synthesize the inline context, present it for validation, and build the specification
+- Output is a standard specification file at `docs/workflow/specification/{topic}.md`
+- From there, the user can proceed to `/workflow:start-planning` as normal
+- This path skips formal discussion documentation - use the full workflow for complex features that need debate captured