@leeovery/claude-technical-workflows 2.0.27 → 2.0.29

package/README.md

@@ -183,7 +183,7 @@ When using the full workflow, it progresses through six distinct phases:
 
 **Phase 2 - Discussion:** Captures the back-and-forth exploration of a problem. Documents competing solutions, why certain approaches won or lost, edge cases discovered, and the journey to decisions, not just the decisions themselves.
 
-**Phase 3 - Specification:** Transforms discussion documentation into a validated, standalone specification. Filters hallucinations and inaccuracies, enriches gaps through discussion, and builds a document that planning can execute against without referencing other sources.
+**Phase 3 - Specification:** Transforms discussion(s) into validated, standalone specifications. Automatically analyses multiple discussions for natural groupings, filters hallucinations and inaccuracies, enriches gaps, and builds documents that planning can execute against without referencing other sources.
 
 **Phase 4 - Planning:** Converts specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear, Backlog.md).
 
@@ -225,19 +225,23 @@ skills/                              # Input-agnostic processors
 └── technical-review/                # Validate against artefacts
 
 commands/                            # Input layer (gather context → invoke skills)
-├── workflow:start-research.md       # Sequential: begin research
-├── workflow:start-discussion.md     # Sequential: begin discussions
-├── workflow:start-specification.md  # Sequential: begin specification
-├── workflow:start-planning.md       # Sequential: begin planning
-├── workflow:start-implementation.md # Sequential: begin implementation
-├── workflow:start-review.md         # Sequential: begin review
-├── workflow:status.md               # Utility: show workflow status and next steps
-├── workflow:view-plan.md            # Utility: view plan tasks and progress
 ├── start-feature.md                 # Standalone: spec from inline context
-└── link-dependencies.md             # Standalone: wire cross-topic deps
+├── link-dependencies.md             # Standalone: wire cross-topic deps
+└── workflow/                        # Sequential workflow commands
+    ├── start-research.md            # Begin research
+    ├── start-discussion.md          # Begin discussions
+    ├── start-specification.md       # Begin specification
+    ├── start-planning.md            # Begin planning
+    ├── start-implementation.md      # Begin implementation
+    ├── start-review.md              # Begin review
+    ├── status.md                    # Show workflow status
+    └── view-plan.md                 # View plan tasks
 
 agents/
 └── chain-verifier.md                # Parallel task verification for review
+
+scripts/                             # Helper scripts for commands
+└── specification-discovery.sh       # Discovery for specification command
 ```
 
 ## Skills
@@ -263,12 +267,12 @@ Sequential commands prefixed with `workflow:`. They expect files from previous p
 
 | 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.                                                                                                        |
+| [**/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 existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
+| [**/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.                                                                                                        |
 
 ### Utility Commands
 
@@ -276,8 +280,8 @@ Helpers for navigating and understanding the workflow.
 
 | Command                                                                              | Description                                                                                                                                 |
 |--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/workflow:status**](commands/workflow:status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
-| [**/workflow:view-plan**](commands/workflow:view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
+| [**/workflow:status**](commands/workflow/status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
+| [**/workflow:view-plan**](commands/workflow/view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
 
 ### Standalone Commands
 

package/commands/{workflow:start-discussion.md → workflow/start-discussion.md}

@@ -58,82 +58,31 @@ Scan the codebase for research and discussions:
    - 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
+## Step 2: Analyze Research (if exists)
 
-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
+Skip this step if no research files were found in Step 1.
 
 This step uses caching to avoid re-analyzing unchanged research documents.
 
-### Step 3A.1: Check Cache Validity
+### Step 2.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
+📋 Using cached research analysis (unchanged since {date from cache})
 ```
 
-Then load the topics from the cache file and skip to Step 3A.3 (Cross-reference).
+Load the topics from the cache file and proceed to Step 2.3.
 
 **If cache missing OR checksums differ:**
 ```
 🔍 Analyzing research documents...
 ```
 
-Proceed to Step 3A.2 (Full Analysis).
+Proceed to Step 2.2 (Full Analysis).
 
-### Step 3A.2: Full Analysis (when cache invalid)
+### Step 2.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
@@ -180,93 +129,136 @@ research_files:
 
 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):
+### Step 2.3: Cross-reference with Discussions
 
 For each identified topic, check if a corresponding discussion already exists in `docs/workflow/discussion/`.
 
-### Step 3A.4: Present Findings
+## Step 3: Present Workflow State and Options
 
-**If using cached analysis:**
-```
-📋 Cached analysis (research unchanged since {date})
+Present everything discovered to help the user make an informed choice.
 
-💡 Topics identified:
+**If NOTHING exists (no research, no discussions):**
+```
+Starting fresh - no prior research or discussions found.
 
-  ✨ {Theme name}
-     Source: {filename}.md (lines {start}-{end})
-     "{Brief summary}"
+What topic would you like to discuss?
+```
+Then skip to Step 5 (Gather Context) with the fresh topic path.
 
-  ✅ {Already discussed theme} → discussed in {topic}.md
-     Source: {filename}.md (lines {start}-{end})
-     "{Brief summary}"
+**Otherwise, present the full state:**
 
-Which topic would you like to discuss? (Or enter 'refresh' for fresh analysis)
 ```
-
-**If fresh analysis:**
+📂 Workflow state:
 ```
-🔍 Analysis complete (cached for future sessions)
 
-💡 Topics identified:
+**If research exists, show the topics:**
+```
+📚 Research topics:
 
-  ✨ {Theme name}
+  1. ✨ {Theme name}
      Source: {filename}.md (lines {start}-{end})
      "{Brief summary}"
 
-  ✅ {Already discussed theme} → discussed in {topic}.md
+  2. ✅ {Theme name} → discussed in {topic}.md
      Source: {filename}.md (lines {start}-{end})
      "{Brief summary}"
 
-Which topic would you like to discuss? (Or describe something else)
+  [... more topics ...]
 ```
 
 **Key:**
 - ✨ = Undiscussed topic (potential new discussion)
 - ✅ = Already has a corresponding discussion
 
-### Step 3A.5: Handle "refresh" Request
+**If discussions exist, show them:**
+```
+💬 Existing discussions:
 
-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..."
+  • {topic}.md — {Status}
+    "{Brief description from context section}"
 
-**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+  • {topic}.md — Concluded
+    "{Brief description}"
+```
 
-Wait for the user to choose before proceeding to Step 4.
+**Key:**
+- Exploring/Deciding = In progress
+- Concluded = Complete (can still be reopened)
 
-## Step 3B: "Continue discussion" Path
+**Then present the options based on what exists:**
 
-List existing discussions with their status:
+**If research AND discussions exist:**
+```
+How would you like to proceed?
 
+  • **From research** - Pick a topic number above (e.g., "research 1" or "1")
+  • **Continue discussion** - Name one above (e.g., "continue {topic}")
+  • **Fresh topic** - Describe what you want to discuss
+  • **refresh** - Force fresh research analysis
 ```
-💬 Existing discussions:
 
-  ⚡ {topic}.md — {Status}
-     "{Brief description from context section}"
+**If ONLY research exists:**
+```
+How would you like to proceed?
 
-  ⚡ {topic}.md — {Status}
-     "{Brief description}"
+  • **From research** - Pick a topic number above (e.g., "research 1" or "1")
+  • **Fresh topic** - Describe what you want to discuss
+  • **refresh** - Force fresh research analysis
+```
 
-  ✅ {topic}.md — Concluded
-     "{Brief description}"
+**If ONLY discussions exist:**
+```
+How would you like to proceed?
 
-Which discussion would you like to continue?
+  • **Continue discussion** - Name one above (e.g., "continue {topic}")
+  • **Fresh topic** - Describe what you want to discuss
 ```
 
-**Key:**
-- ⚡ = In progress (Exploring or Deciding)
-- ✅ = Concluded (can still be continued/reopened)
+Wait for the user to respond before proceeding.
+
+## Step 4A: "From research" Path
 
-Wait for the user to choose, then proceed to Step 4.
+User chose to start from research (e.g., "research 1", "1", "from research", or a topic name).
+
+**If user specified a topic inline** (e.g., "research 2", "2", or topic name):
+- Identify the selected topic from Step 3's numbered list
+- Proceed to Step 5 (Gather Context)
+
+**If user just said "from research" without specifying:**
+```
+Which research topic would you like to discuss? (Enter a number or topic name)
+```
+Wait for response, then proceed to Step 5.
+
+### Handle "refresh" Request
+
+If user enters `refresh`:
+- Delete the cache file: `rm docs/workflow/.cache/research-analysis.md`
+- Return to Step 2.2 (Full Analysis)
+- Inform user: "Refreshing analysis..."
+- After analysis, return to Step 3 to present updated findings
+
+**Important:** Keep track of the source file and line numbers for the chosen topic - this will be passed to the skill.
+
+## Step 4B: "Continue discussion" Path
+
+User chose to continue a discussion (e.g., "continue auth-flow" or "continue discussion").
+
+**If user specified a discussion inline** (e.g., "continue auth-flow"):
+- Identify the selected discussion from Step 3's list
+- Proceed to Step 5 (Gather Context)
+
+**If user just said "continue discussion" without specifying:**
+```
+Which discussion would you like to continue?
+```
+Wait for response, then proceed to Step 5.
 
-## Step 3C: "Fresh topic" Path
+## Step 4C: "Fresh topic" Path
 
-Proceed directly to Step 4.
+User wants to start a fresh discussion. Proceed directly to Step 5.
 
-## Step 4: Gather Context
+## Step 5: Gather Context
 
 Gather context based on the chosen path.
 
@@ -300,11 +292,11 @@ What would you like to focus on in this session?
 
 Wait for response before proceeding.
 
-## Step 5: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
-Invoke the [technical-discussion](../skills/technical-discussion/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.
+Invoke the [technical-discussion](../../skills/technical-discussion/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 (from research):**
 ```
@@ -313,7 +305,7 @@ 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}
+Summary: {the 1-2 sentence summary from the research analysis}
 
 Invoke the technical-discussion skill.
 ```

package/commands/{workflow:start-implementation.md → workflow/start-implementation.md}

@@ -70,7 +70,7 @@ Which plan would you like to implement?
 
 **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.
+See **[dependencies.md](../../skills/technical-planning/references/dependencies.md)** for dependency format and states.
 
 After the user selects a plan:
 
@@ -161,7 +161,7 @@ If they choose a specific phase or task, ask them to specify which one.
 
 After completing the steps above, this command's purpose is fulfilled.
 
-Invoke the [technical-implementation](../skills/technical-implementation/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.
+Invoke the [technical-implementation](../../skills/technical-implementation/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:**
 ```

package/commands/{workflow:start-planning.md → workflow/start-planning.md}

@@ -94,7 +94,7 @@ Ask: **Which feature specification would you like to plan?**
 
 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.
+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
 
@@ -125,7 +125,7 @@ These specifications contain validated architectural decisions that should infor
 
 After completing the steps above, this command's purpose is fulfilled.
 
-Invoke the [technical-planning](../skills/technical-planning/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.
+Invoke the [technical-planning](../../skills/technical-planning/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:**
 ```

package/commands/{workflow:start-research.md → workflow/start-research.md}

@@ -43,4 +43,4 @@ Ask these questions clearly and wait for responses before proceeding.
 
 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.
+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.

package/commands/{workflow:start-review.md → workflow/start-review.md}

@@ -90,7 +90,7 @@ Check if a specification exists:
 
 After completing the steps above, this command's purpose is fulfilled.
 
-Invoke the [technical-review](../skills/technical-review/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.
+Invoke the [technical-review](../../skills/technical-review/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:**
 ```