@leeovery/claude-technical-workflows 2.0.28 → 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}

@@ -296,7 +296,7 @@ Wait for response before proceeding.
 
 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):**
 ```

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:**
 ```

package/commands/workflow/start-specification.md

@@ -0,0 +1,613 @@
+---
+description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
+allowed-tools: Bash(./scripts/specification-discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
+---
+
+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 standalone specifications. 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.
+
+**CRITICAL**: After each user interaction, STOP and wait for their response before proceeding. Never assume or anticipate user choices.
+
+---
+
+## Step 1: Run Discovery Script
+
+Run the discovery script to gather current state:
+
+```bash
+./scripts/specification-discovery.sh
+```
+
+This outputs structured YAML. Parse it to understand:
+
+**From `discussions` array:**
+- Each discussion's name, status, and whether it has an individual specification
+
+**From `specifications` array:**
+- Each specification's name, status, sources, and superseded_by (if applicable)
+- Specifications with `status: superseded` should be noted but excluded from active counts
+
+**From `cache` section:**
+- Whether a consolidation analysis cache exists
+- The `anchored_names` list - these are grouping names that have existing specifications and MUST be preserved in any regeneration
+
+**From `cache_validity` section:**
+- Whether the cache is still valid (`is_valid: true/false`)
+- The reason if invalid
+
+**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: 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.** Wait for user acknowledgment. Do not proceed.
+
+#### If discussions exist but none are concluded
+
+```
+No concluded discussions found.
+
+The following discussions are still exploring:
+  - {topic-1} (exploring)
+  - {topic-2} (exploring)
+
+Please complete the discussion phase before creating specifications. Run /workflow:start-discussion to continue a discussion.
+```
+
+**STOP.** Wait for user acknowledgment. Do not proceed.
+
+#### Otherwise
+
+At least one concluded discussion exists.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Present Status & Route
+
+Show the current state clearly. Use this EXACT format:
+
+```
+Workflow Status: Specification Phase
+
+Discussions:
+  ✓ {topic-1} - concluded - ready
+  ✓ {topic-2} - concluded - ready
+  ○ {topic-3} - concluded - has individual spec
+  · {topic-4} - exploring - not ready
+
+Specifications:
+  • {spec-1} (active) - sources: {topic-1}
+  • {spec-2} (superseded → {other-spec}) - sources: {topic-x}
+
+{N} concluded discussions available.
+```
+
+**Legend:**
+- `✓` = concluded, no spec yet (ready to specify)
+- `○` = concluded, has individual spec (can be combined or continued)
+- `·` = not concluded (not ready)
+
+#### Routing Based on State
+
+#### If only ONE concluded discussion exists
+
+This is the simple path - no choices needed.
+
+```
+Single concluded discussion found: {topic}
+{If has spec: "An existing specification will be continued/refined."}
+
+Proceeding with this discussion.
+```
+
+→ Skip to **Step 9: Confirm Selection** with that discussion as the source.
+
+#### If MULTIPLE concluded discussions exist with NO existing specifications
+
+No existing specs to continue - proceed directly to analysis.
+
+```
+{N} concluded discussions found.
+
+Analyzing discussions for natural groupings...
+```
+
+→ Proceed to **Step 4: Gather Analysis Context**.
+
+#### If MULTIPLE concluded discussions exist WITH existing specifications
+
+```
+What would you like to do?
+
+1. **Continue an existing specification** - Resume work on a spec in progress
+2. **Assess for groupings** - Analyze discussions for combinations
+
+Which approach?
+```
+
+**STOP.** Wait for user response.
+
+#### If "Continue an existing specification"
+
+```
+Which specification would you like to continue?
+
+1. {spec-1} ({status}) - sources: {topics}
+2. {spec-2} ({status}) - sources: {topics}
+```
+
+**STOP.** Wait for user to pick, then skip to **Step 9**.
+
+#### If "Assess for groupings"
+
+→ Proceed to **Step 4: Gather Analysis Context**.
+
+---
+
+## Step 4: Gather Analysis Context
+
+```
+Before I analyze the discussions, is there anything about your project structure or how these topics relate that would help me group them appropriately?
+
+For example:
+- Are certain topics part of the same feature or subsystem?
+- Are there dependencies I should know about?
+- Any topics that MUST stay separate?
+```
+
+**STOP.** Wait for user response. Note their input for the analysis.
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 5: Check Cache Validity
+
+Check the `cache_validity.is_valid` value from the discovery state.
+
+#### If cache is valid
+
+```
+Using cached analysis
+
+Discussion documents unchanged since last analysis ({cached_date}).
+Loading previously identified groupings...
+```
+
+Load groupings from cache and → Skip to **Step 7: Present Grouping Options**.
+
+#### If cache is invalid or missing
+
+```
+{Reason from cache_validity.reason}
+
+Analyzing discussions...
+```
+
+→ Proceed to **Step 6: Analyze Discussions**.
+
+---
+
+## Step 6: Analyze Discussions
+
+**This step is critical. You MUST read every concluded discussion document thoroughly.**
+
+For each concluded discussion:
+1. Read the ENTIRE document using the Read tool (not just frontmatter)
+2. Understand the decisions, systems, and concepts it defines
+3. Note dependencies on or references to other discussions
+4. Identify shared data structures, entities, or behaviors
+
+Then analyze coupling between discussions:
+- **Data coupling**: Discussions that define or depend on the same data structures
+- **Behavioral coupling**: Discussions where one's implementation requires another
+- **Conceptual coupling**: Discussions that address different facets of the same problem
+
+Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
+
+#### Preserve Anchored Names
+
+**CRITICAL**: Check the `cache.anchored_names` from discovery state. These are grouping names that have existing specifications.
+
+When forming groupings:
+- If a grouping contains a majority of the same discussions as an anchored name's spec, you MUST reuse that anchored name
+- Only create new names for genuinely new groupings with no overlap
+- If an anchored spec's discussions are now scattered across multiple new groupings, note this as a **naming conflict** to present to the user
+
+#### Save to Cache
+
+After analysis, create the cache directory if needed:
+```bash
+mkdir -p docs/workflow/.cache
+```
+
+Write to `docs/workflow/.cache/discussion-consolidation-analysis.md`:
+
+```markdown
+---
+checksum: {checksum from current_state.discussions_checksum}
+generated: {ISO date}
+discussion_files:
+  - {topic1}.md
+  - {topic2}.md
+---
+
+# Discussion Consolidation Analysis
+
+## Recommended Groupings
+
+### {Suggested Specification Name}
+- **{topic-a}**: {why it belongs in this group}
+- **{topic-b}**: {why it belongs in this group}
+- **{topic-c}**: {why it belongs in this group}
+
+**Coupling**: {Brief explanation of what binds these together}
+
+### {Another Specification Name}
+- **{topic-d}**: {why it belongs}
+- **{topic-e}**: {why it belongs}
+
+**Coupling**: {Brief explanation}
+
+## Independent Discussions
+- **{topic-f}**: {Why this stands alone - no strong coupling to others}
+
+## Analysis Notes
+{Any additional context about the relationships discovered}
+{Note any naming conflicts with anchored specs here}
+```
+
+→ Proceed to **Step 7**.
+
+---
+
+## Step 7: Present Grouping Options
+
+Present the groupings with FULL status information.
+
+For each grouping, show:
+- The grouping name
+- Whether a specification already exists for this grouping
+- Each discussion in the grouping and whether it has an individual spec
+
+**Format:**
+
+```
+{Fresh analysis / Cached analysis} complete
+
+Recommended Groupings:
+
+### 1. {Grouping Name} {if spec exists: "(specification exists)"}
+| Discussion | Status |
+|------------|--------|
+| {topic-a} | discussion only |
+| {topic-b} | has individual spec |
+| {topic-c} | discussion only |
+
+Coupling: {explanation}
+
+### 2. {Another Grouping}
+| Discussion | Status |
+|------------|--------|
+| {topic-d} | discussion only |
+
+Coupling: {explanation}
+
+### Independent
+- {topic-f}: standalone
+
+---
+
+How would you like to proceed?
+
+1. **Combine as recommended** - I'll ask which grouping to start with
+2. **Combine differently** - Tell me your preferred groupings
+3. **Single specification** - Consolidate ALL into one unified spec
+4. **Individual specifications** - Create 1:1 specs (I'll ask which to start)
+
+(Enter 'refresh' to re-analyze)
+```
+
+**STOP.** Wait for user to choose.
+
+→ Based on choice, proceed to **Step 8**.
+
+---
+
+## Step 8: Select Grouping
+
+Based on user's choice from Step 7:
+
+#### If "Combine as recommended"
+
+```
+Which grouping would you like to start with?
+
+1. {Grouping Name A} - {N} discussions
+2. {Grouping Name B} - {N} discussions (specification exists)
+3. {Grouping Name C} - {N} discussions
+```
+
+**STOP.** Wait for user to pick a number, then proceed to **Step 9**.
+
+#### If "Combine differently"
+
+```
+Please describe your preferred groupings. Which discussions should be combined together?
+```
+
+**STOP.** Wait for user to describe their groupings.
+
+Confirm understanding and present as a numbered list. Check if any grouping names match existing specifications.
+
+```
+Based on your description, here are the groupings:
+
+1. {User's Grouping A} - {topics}
+2. {User's Grouping B} - {topics}
+
+Which grouping would you like to start with?
+```
+
+**STOP.** Wait for user to pick, then proceed to **Step 9**.
+
+#### If "Single specification"
+
+Use "unified" as the specification name.
+Check if `docs/workflow/specification/unified.md` already exists.
+
+```
+{If exists: "A unified specification already exists. Proceeding will continue/refine it."}
+
+This will consolidate ALL {N} concluded discussions into a single specification.
+
+Proceed with unified specification? (y/n)
+```
+
+**STOP.** Wait for user to confirm, then proceed to **Step 9** with all discussions as sources.
+
+#### If "Individual specifications"
+
+```
+Which discussion would you like to specify?
+
+1. {topic-1}
+2. {topic-2} (has individual spec - will continue/refine)
+3. {topic-3}
+```
+
+**STOP.** Wait for user to pick, then proceed to **Step 9**.
+
+#### If "refresh"
+
+```
+Refreshing analysis...
+```
+
+Delete the cache file:
+```bash
+rm docs/workflow/.cache/discussion-consolidation-analysis.md
+```
+
+→ Return to **Step 6: Analyze Discussions**.
+
+---
+
+## Step 9: Confirm Selection
+
+Present what will happen based on the selection:
+
+#### If creating a NEW grouped specification (with individual specs to incorporate)
+
+```
+Creating specification: {grouping-name}
+
+Sources:
+| Type | File | Action |
+|------|------|--------|
+| Discussion | {topic-a}.md | Extract content |
+| Discussion | {topic-b}.md | Extract content |
+| Existing Spec | specification/{topic-c}.md | Incorporate and supersede |
+
+Output: docs/workflow/specification/{grouping-name}.md
+
+After completion:
+- specification/{topic-c}.md will be marked as superseded
+
+Proceed? (y/n)
+```
+
+#### If creating a NEW grouped specification (no existing specs)
+
+```
+Creating specification: {grouping-name}
+
+Sources:
+- docs/workflow/discussion/{topic-a}.md
+- docs/workflow/discussion/{topic-b}.md
+- docs/workflow/discussion/{topic-c}.md
+
+Output: docs/workflow/specification/{grouping-name}.md
+
+Proceed? (y/n)
+```
+
+#### If CONTINUING an existing grouped specification
+
+```
+Continuing specification: {grouping-name}
+
+Existing: docs/workflow/specification/{grouping-name}.md (will be refined)
+
+Sources:
+- docs/workflow/discussion/{topic-a}.md
+- docs/workflow/discussion/{topic-b}.md
+
+Proceed? (y/n)
+```
+
+#### If creating/continuing an INDIVIDUAL specification
+
+```
+{Creating / Continuing} specification: {topic}
+
+Source: docs/workflow/discussion/{topic}.md
+Output: docs/workflow/specification/{topic}.md
+
+Proceed? (y/n)
+```
+
+**STOP.** Wait for user confirmation.
+
+**If user confirms (y):** → Proceed to **Step 10**.
+**If user declines (n):** → Return to **Step 8** to select a different grouping or discussion.
+
+---
+
+## Step 10: Gather Additional Context
+
+```
+Before invoking the specification skill:
+
+1. Any additional context or priorities to consider?
+2. Any constraints or changes since the discussion(s) concluded?
+3. Are there existing partial implementations or related documentation I should review?
+
+(Press enter to skip if none)
+```
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 11**.
+
+---
+
+## Step 11: Invoke the Skill
+
+After completing all steps above, this command's purpose is fulfilled.
+
+Invoke the [technical-specification](../../skills/technical-specification/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.
+
+#### Handoff Format
+
+**Single source (individual specification):**
+
+```
+Specification session for: {topic}
+
+Source: docs/workflow/discussion/{topic}.md
+Output: docs/workflow/specification/{topic}.md
+
+Additional context: {summary of user's answers from Step 10}
+
+---
+Invoke the technical-specification skill.
+```
+
+**Multiple sources (grouped specification, no existing specs to incorporate):**
+
+```
+Specification session for: {specification-name}
+
+Sources:
+- docs/workflow/discussion/{topic-1}.md
+- docs/workflow/discussion/{topic-2}.md
+- docs/workflow/discussion/{topic-3}.md
+
+Output: docs/workflow/specification/{specification-name}.md
+
+Additional context: {summary of user's answers from Step 10}
+
+---
+Invoke the technical-specification skill.
+```
+
+**Multiple sources WITH existing specs to incorporate:**
+
+```
+Specification session for: {specification-name}
+
+Source discussions:
+- docs/workflow/discussion/{topic-1}.md
+- docs/workflow/discussion/{topic-2}.md
+
+Existing specifications to incorporate:
+- docs/workflow/specification/{topic-3}.md (covers: {topic-3} discussion)
+
+Output: docs/workflow/specification/{specification-name}.md
+
+Context: This consolidates multiple sources. The existing {topic-3}.md specification should be incorporated - extract and adapt its content alongside the discussion material. The result should be a unified specification, not a simple merge.
+
+After the {specification-name} specification is complete, mark the incorporated specs as superseded by updating their frontmatter:
+
+    status: superseded
+    superseded_by: {specification-name}
+
+Additional context: {summary of user's answers from Step 10}
+
+---
+Invoke the technical-specification skill.
+```
+
+**Continuing an existing specification:**
+
+```
+Specification session for: {specification-name}
+
+Continuing existing: docs/workflow/specification/{specification-name}.md
+
+Sources for reference:
+- docs/workflow/discussion/{topic-1}.md
+- docs/workflow/discussion/{topic-2}.md
+
+Context: This specification already exists. Review and refine it based on the source discussions and any new context provided.
+
+Additional context: {summary of user's answers from Step 10}
+
+---
+Invoke the technical-specification skill.
+```
+
+---
+
+## Notes
+
+- Ask questions clearly and STOP after each to wait for responses
+- Only concluded discussions should proceed to specification
+- When multiple sources are provided, the skill will extract exhaustively from ALL of them
+- Attribution in the specification should trace content back to its source discussion(s)
+- Superseded specifications are excluded from future planning phases
+- The specification is the "line in the sand" - be thorough, not hasty

package/package.json

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

package/skills/technical-specification/SKILL.md

@@ -38,6 +38,18 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **When complete**: User signs off on the specification.
 
+### Post-Completion: Handle Source Specifications
+
+If any of your sources were **existing specifications** (as opposed to discussions, research, or other reference material), these have now been consolidated into the new specification.
+
+After user signs off:
+1. Mark each source specification as superseded by updating its frontmatter:
+   ```yaml
+   status: superseded
+   superseded_by: {new-specification-name}
+   ```
+2. Inform the user which files were updated
+
 ## CRITICAL: You Do NOT Create or Update the Specification Autonomously
 
 **This is a collaborative, interactive process. You MUST wait for explicit user approval before writing ANYTHING to the specification file.**

package/commands/start-discussion.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-discussion instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-discussion` is deprecated.** Use `/workflow:start-discussion` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-discussion`...**
-
-Run the `/workflow:start-discussion` command now.

package/commands/start-implementation.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-implementation instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-implementation` is deprecated.** Use `/workflow:start-implementation` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-implementation`...**
-
-Run the `/workflow:start-implementation` command now.

package/commands/start-planning.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-planning instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-planning` is deprecated.** Use `/workflow:start-planning` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-planning`...**
-
-Run the `/workflow:start-planning` command now.

package/commands/start-research.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-research instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-research` is deprecated.** Use `/workflow:start-research` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-research`...**
-
-Run the `/workflow:start-research` command now.

package/commands/start-specification.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-specification instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-specification` is deprecated.** Use `/workflow:start-specification` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-specification`...**
-
-Run the `/workflow:start-specification` command now.

package/commands/workflow:start-specification.md

@@ -1,304 +0,0 @@
----
-description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, 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 standalone specifications. 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
-
-4. **Check for cached consolidation analysis** (if multiple discussions):
-   - Check if `docs/workflow/.cache/discussion-consolidation-analysis.md` exists
-   - If it exists, read it to get the stored checksum from the frontmatter
-
-5. **Compute current discussions checksum** (if multiple concluded discussions):
-   - Run exactly: `cat docs/workflow/discussion/*.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: 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
-
-Show what you found:
-
-```
-Discussions found:
-  {topic-1} - Concluded - ready for specification
-  {topic-2} - Exploring - not ready for specification
-  {topic-3} - Concluded - specification exists
-```
-
-**Important:** Only concluded discussions should proceed to specification. If a discussion is still exploring, advise the user to complete the discussion phase first.
-
-**If only ONE concluded discussion is ready:** Skip to Step 4 (single-source path).
-
-**If MORE THAN ONE concluded discussion is ready:** Proceed to Step 3A (consolidation assessment).
-
----
-
-## Step 3A: Consolidation Assessment (Multiple Discussions)
-
-When multiple concluded discussions exist, offer to assess how they should be organized into specifications.
-
-```
-You have {N} concluded discussions ready for specification.
-
-Would you like me to assess how these might be combined into specifications?
-
-1. **Yes, assess them** - I'll analyze all discussions for natural groupings
-2. **No, proceed individually** - Create specifications 1:1 with discussions
-
-Which approach?
-```
-
-**If user chooses individual:** Skip to Step 4 and ask which discussion to specify.
-
-**If user chooses assessment:** Proceed to Step 3A.1.
-
-### Step 3A.1: Gather Context for Analysis
-
-Before analyzing, ask:
-
-```
-Before I analyze the discussions, is there anything about your project structure or how these topics relate that would help me group them appropriately?
-```
-
-Wait for response.
-
-### Step 3A.2: Check Cache Validity
-
-Compare the current discussions checksum (computed in Step 1.5) with the cached checksum:
-
-**If cache exists AND checksums match:**
-```
-Using cached analysis
-
-Discussion documents unchanged since last analysis ({date from cache}).
-Loading previously identified groupings...
-
-To force a fresh analysis, enter: refresh
-```
-
-Then load the groupings from the cache file and skip to Step 3A.4 (Present Options).
-
-**If cache missing OR checksums differ:**
-```
-Analyzing discussions...
-```
-
-Proceed to Step 3A.3 (Full Analysis).
-
-### Step 3A.3: Full Analysis (when cache invalid)
-
-**This step is critical. You MUST read every concluded discussion document thoroughly.**
-
-For each concluded discussion:
-1. Read the ENTIRE document (not just frontmatter)
-2. Understand the decisions, systems, and concepts it defines
-3. Note dependencies on or references to other discussions
-4. Identify shared data structures, entities, or behaviors
-
-Then analyze coupling between discussions:
-- **Data coupling**: Discussions that define or depend on the same data structures
-- **Behavioral coupling**: Discussions where one's implementation requires another
-- **Conceptual coupling**: Discussions that address different facets of the same problem
-
-Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
-
-**Save to cache:**
-After analysis, ensure `.cache` directory exists: `mkdir -p docs/workflow/.cache`
-
-Create/update `docs/workflow/.cache/discussion-consolidation-analysis.md`:
-
-```markdown
----
-checksum: {computed_checksum}
-generated: {ISO date}
-discussion_files:
-  - {topic1}.md
-  - {topic2}.md
----
-
-# Discussion Consolidation Analysis
-
-## Recommended Groupings
-
-### {Suggested Specification Name}
-- **{topic-a}**: {why it belongs in this group}
-- **{topic-b}**: {why it belongs in this group}
-- **{topic-c}**: {why it belongs in this group}
-
-**Coupling**: {Brief explanation of what binds these together - shared data, dependencies, etc.}
-
-### {Another Specification Name}
-- **{topic-d}**: {why it belongs}
-- **{topic-e}**: {why it belongs}
-
-**Coupling**: {Brief explanation}
-
-## Independent Discussions
-- **{topic-f}**: {Why this stands alone - no strong coupling to others}
-
-## Analysis Notes
-{Any additional context about the relationships discovered}
-```
-
-### Step 3A.4: Present Options
-
-Present the analysis and options:
-
-**If using cached analysis:**
-```
-Cached analysis (discussions unchanged since {date})
-
-{Display the Recommended Groupings section from cache}
-
-How would you like to proceed?
-
-1. **Combine as recommended** - Create specifications per the groupings above
-2. **Combine differently** - Tell me your preferred groupings
-3. **Single specification** - Consolidate all discussions into one spec
-4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
-
-(Or enter 'refresh' to re-analyze)
-```
-
-**If fresh analysis:**
-```
-Analysis complete (cached for future sessions)
-
-{Display the Recommended Groupings section}
-
-How would you like to proceed?
-
-1. **Combine as recommended** - Create specifications per the groupings above
-2. **Combine differently** - Tell me your preferred groupings
-3. **Single specification** - Consolidate all discussions into one spec
-4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
-```
-
-Wait for user to choose.
-
-### Step 3A.5: Handle Choices
-
-**If "Combine as recommended":**
-- Confirm the first specification to create
-- Proceed to Step 4 with the grouped sources
-
-**If "Combine differently":**
-- Ask user to describe their preferred groupings
-- Confirm understanding
-- Proceed to Step 4 with user-specified sources
-
-**If "Single specification":**
-- Use "unified" as the specification name (output: `docs/workflow/specification/unified.md`)
-- Proceed to Step 4 with all discussions as sources
-
-**If "Individual specifications":**
-- Ask which discussion to specify first
-- Proceed to Step 4 with single source
-
-**If "refresh":**
-- Delete the cache file: `rm docs/workflow/.cache/discussion-consolidation-analysis.md`
-- Return to Step 3A.3 (Full Analysis)
-- Inform user: "Refreshing analysis..."
-
----
-
-## Step 4: Gather Additional Context
-
-Ask:
-- Any additional context or priorities to consider?
-- Any constraints or changes since the discussion(s) concluded?
-- Are there any existing partial plans or related documentation I should review?
-
-## Step 5: Invoke the Skill
-
-After completing the steps above, this command's purpose is fulfilled.
-
-Invoke the [technical-specification](../skills/technical-specification/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 (single source):**
-```
-Specification session for: {topic}
-Source: docs/workflow/discussion/{topic}.md
-Output: docs/workflow/specification/{topic}.md
-Additional context: {summary of user's answers from Step 4}
-
-Invoke the technical-specification skill.
-```
-
-**Example handoff (multiple sources):**
-```
-Specification session for: {specification-name}
-
-Sources:
-- docs/workflow/discussion/{topic-1}.md
-- docs/workflow/discussion/{topic-2}.md
-- docs/workflow/discussion/{topic-3}.md
-
-Output: docs/workflow/specification/{specification-name}.md
-Additional context: {summary of user's answers from Step 4}
-
-Invoke the technical-specification skill.
-```
-
----
-
-## Notes
-
-- Ask questions clearly and wait for responses before proceeding
-- The specification phase validates and refines discussion content into standalone documents
-- When multiple sources are provided, the skill will extract exhaustively from ALL of them
-- Attribution in the specification should trace content back to its source discussion(s)