refactor: migrate to topic-first directory structure

CLAUDE.md

@@ -29,8 +29,10 @@ commands/
 
 ## Key Conventions
 
-- Discussion docs: `docs/specs/discussions/<topic-name>/discussion.md`
-- Specification docs: `docs/specs/specifications/<topic-name>/specification.md`
-- Plan docs: `docs/specs/plans/<topic-name>/`
+- Topic directory: `docs/workflow/{topic}/`
+- Discussion: `docs/workflow/{topic}/discussion.md`
+- Specification: `docs/workflow/{topic}/specification.md`
+- Plan: `docs/workflow/{topic}/plan.md`
+- Multiple files: Use pluralized subdirectory (e.g., `discussions/`, `specifications/`, `plans/`)
 - Commit docs frequently (natural breaks, before context refresh)
 - Skills capture context, don't implement

README.md

@@ -76,19 +76,26 @@ You don't need to configure anything—just install and start discussing.
 
 ### Output Structure
 
-Discussion, specification, and planning documents are stored in your project:
+Discussion, specification, and planning documents are stored in your project using a **topic-first** organization:
 
 ```
-docs/specs/
-├── discussions/
-│   └── <topic-name>/
-│       └── discussion.md      # Phase 1 output
-├── specifications/
-│   └── <topic-name>/
-│       └── specification.md   # Phase 2 output
-└── plans/
-    └── <topic-name>/
-        └── plan.md            # Phase 3 output
+docs/workflow/
+└── {topic}/
+    ├── discussion.md      # Phase 1 output
+    ├── specification.md   # Phase 2 output
+    └── plan.md            # Phase 3 output
+```
+
+Each topic gets a single directory containing all its workflow artifacts. This keeps related documents together and makes it easy to see the complete picture for any feature.
+
+**Multiple files:** If any phase needs multiple files (e.g., multiple discussion threads), they move to a pluralized subdirectory:
+```
+docs/workflow/{topic}/
+├── discussions/           # plural = directory with multiple files
+│   ├── api-design.md
+│   └── data-model.md
+├── specification.md
+└── plan.md
 ```
 
 ## Skills
@@ -152,7 +159,7 @@ Converts specifications into structured implementation plans.
 Executes plans through strict TDD. Acts as an expert senior developer who builds quality software through disciplined test-driven development.
 
 **Use when:**
-- Implementing a plan from `docs/specs/plans/`
+- Implementing a plan from `docs/workflow/{topic}/plan.md`
 - Ad hoc coding that should follow TDD and quality standards
 - Bug fixes or features benefiting from structured implementation
 

commands/start-discussion.md

@@ -1,5 +1,5 @@
 ---
-description: Start a technical discussion using the technical-discussion skill. Gathers information about the topic and creates discussion documentation in docs/specs/discussions/<topic-name>/
+description: Start a technical discussion using the technical-discussion skill. Gathers information about the topic and creates discussion documentation in docs/workflow/{topic}/
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
@@ -8,7 +8,7 @@ Before beginning, ask the user these questions to properly set up the discussion
 
 ## Essential Information
 
-1. **Discussion Topic**: What are we discussing? (This will be used to create the directory name in `docs/specs/discussions/<topic-name>/`)
+1. **Discussion Topic**: What are we discussing? (This will be used to create the topic directory in `docs/workflow/{topic}/`)
 
 2. **Context & Background**:
    - What sparked this discussion?
@@ -28,10 +28,10 @@ Before beginning, ask the user these questions to properly set up the discussion
 ## After Gathering Information
 
 Once I have this information:
-- Create directory: `docs/specs/discussions/<topic-name>/`
+- Ensure topic directory exists: `docs/workflow/{topic}/`
 - Start documenting the discussion following the technical-discussion skill structure
-- Create initial file (e.g., `discussion.md`)
-- Add more files as the discussion evolves (research notes, supporting docs, etc.)
+- Create initial file: `docs/workflow/{topic}/discussion.md`
+- If multiple discussion files needed, move to `docs/workflow/{topic}/discussions/` with semantic names
 - Commit frequently at natural discussion breaks
 
 Ask these questions clearly and wait for responses before proceeding with the discussion.

commands/start-planning.md

@@ -18,23 +18,22 @@ Use simple, individual commands. Never combine multiple operations into bash loo
 
 Scan the codebase for specifications and plans:
 
-1. **Find specifications**: Look in `docs/specs/specifications/*/specification.md`
-   - First, run `ls docs/specs/specifications/` to list topic directories
-   - Then, for each topic, run `head -20 docs/specs/specifications/{topic}/specification.md` to read the frontmatter and extract the `status:` field
-   - Do NOT use bash loops - run separate `head` commands for each topic
+1. **Find topic directories**: Look in `docs/workflow/*/`
+   - First, run `ls docs/workflow/` to list topic directories
+   - Then, for each topic, check for `specification.md` and `plan.md`
 
-2. **Find existing plans**: Look in `docs/specs/plans/*/`
-   - Run `ls docs/specs/plans/` to list existing plans
-   - For each plan, run `ls docs/specs/plans/{topic}/` to see what files exist
+2. **Check specification status**: For each topic with a specification
+   - Run `head -20 docs/workflow/{topic}/specification.md` to read the frontmatter and extract the `status:` field
+   - Do NOT use bash loops - run separate `head` commands for each topic
 
-3. **Identify gaps**: Specifications without corresponding plans
+3. **Identify gaps**: Topics with specifications but no plans
 
 ## Step 2: Check Prerequisites
 
 **If no specifications exist:**
 
 ```
-⚠️ No specifications found in docs/specs/specifications/
+⚠️ No specifications found in docs/workflow/
 
 The planning phase requires a completed specification. Please run /start-specification first to validate and refine the discussion content into a standalone specification before creating a plan.
 ```
@@ -62,7 +61,7 @@ Ask: **Which specification would you like to plan?**
 
 Ask: **Where should this plan live?**
 
-1. **Local Markdown** - Simple `plan.md` file in `docs/specs/plans/`
+1. **Local Markdown** - Simple `plan.md` file in `docs/workflow/{topic}/`
    - Best for: Small features, solo work, quick iterations
    - Everything in one version-controlled file
 
@@ -91,25 +90,29 @@ Ask: **Where should this plan live?**
 ## Step 6: Invoke Planning Skill
 
 Pass to the technical-planning skill:
-- Specification path: `docs/specs/specifications/{topic-name}/specification.md`
+- Topic directory: `docs/workflow/{topic}/`
+- Specification: `docs/workflow/{topic}/specification.md`
+- Output: `docs/workflow/{topic}/plan.md`
 - Output destination: (local-markdown | linear | backlog-md)
 - Additional context gathered
 
 **Example handoff:**
 ```
-Planning session for: {topic-name}
-Specification: docs/specs/specifications/{topic-name}/specification.md
+Planning session for: {topic}
+Topic directory: docs/workflow/{topic}/
+Specification: docs/workflow/{topic}/specification.md
 Output destination: Local Markdown
-Output path: docs/specs/plans/{topic-name}/plan.md
+Output path: docs/workflow/{topic}/plan.md
 
 Begin planning using the technical-planning skill.
 Reference: formal-planning.md, then output-local-markdown.md
 ```
 
 **Example handoff for Linear:**
 ```
-Planning session for: {topic-name}
-Specification: docs/specs/specifications/{topic-name}/specification.md
+Planning session for: {topic}
+Topic directory: docs/workflow/{topic}/
+Specification: docs/workflow/{topic}/specification.md
 Output destination: Linear
 Team: Engineering
 

commands/start-specification.md

@@ -18,23 +18,22 @@ Use simple, individual commands. Never combine multiple operations into bash loo
 
 Scan the codebase for discussions and specifications:
 
-1. **Find discussions**: Look in `docs/specs/discussions/*/discussion.md`
-   - First, run `ls docs/specs/discussions/` to list topic directories
-   - Then, for each topic, run `head -20 docs/specs/discussions/{topic}/discussion.md` to read the frontmatter and extract the `status:` field
-   - Do NOT use bash loops - run separate `head` commands for each topic
+1. **Find topic directories**: Look in `docs/workflow/*/`
+   - First, run `ls docs/workflow/` to list topic directories
+   - Then, for each topic, check for `discussion.md` and `specification.md`
 
-2. **Find existing specifications**: Look in `docs/specs/specifications/*/`
-   - Run `ls docs/specs/specifications/` to list existing specifications
-   - For each specification, run `ls docs/specs/specifications/{topic}/` to see what files exist
+2. **Check discussion status**: For each topic with a discussion
+   - Run `head -20 docs/workflow/{topic}/discussion.md` to read the frontmatter and extract the `status:` field
+   - Do NOT use bash loops - run separate `head` commands for each topic
 
-3. **Identify gaps**: Discussions without corresponding specifications
+3. **Identify gaps**: Topics with discussions but no specifications
 
 ## Step 2: Check Prerequisites
 
 **If no discussions exist:**
 
 ```
-⚠️ No discussions found in docs/specs/discussions/
+⚠️ No discussions found in docs/workflow/
 
 The specification phase requires a completed discussion. Please run /start-discussion first to document the technical decisions, edge cases, and rationale before creating a specification.
 ```
@@ -68,15 +67,17 @@ Ask:
 ## Step 5: Invoke Specification Skill
 
 Pass to the technical-specification skill:
-- Discussion path: `docs/specs/discussions/{topic-name}/`
-- Specification path: `docs/specs/specifications/{topic-name}/`
+- Topic directory: `docs/workflow/{topic}/`
+- Discussion: `docs/workflow/{topic}/discussion.md`
+- Output: `docs/workflow/{topic}/specification.md`
 - Additional context gathered
 
 **Example handoff:**
 ```
-Specification session for: {topic-name}
-Discussion: docs/specs/discussions/{topic-name}/discussion.md
-Output: docs/specs/specifications/{topic-name}/specification.md
+Specification session for: {topic}
+Topic directory: docs/workflow/{topic}/
+Discussion: docs/workflow/{topic}/discussion.md
+Output: docs/workflow/{topic}/specification.md
 
 Begin specification using the technical-specification skill.
 Reference: specification-guide.md

skills/technical-discussion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-discussion
-description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. First phase of discussion-specification-plan-implement-review workflow. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/specs/discussions/ that technical-specification uses to build validated specifications."
+description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. First phase of discussion-specification-plan-implement-review workflow. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/workflow/{topic}/ that technical-specification uses to build validated specifications."
 ---
 
 # Technical Discussion
@@ -31,7 +31,11 @@ See **[meeting-assistant.md](references/meeting-assistant.md)** for detailed app
 
 ## Structure
 
-Discussions are stored in `docs/specs/discussions/<topic-name>/discussion.md`. Each discussion gets its own directory with a single markdown file.
+Discussions are stored in `docs/workflow/{topic}/discussion.md`. Each topic gets its own directory containing all workflow artifacts (discussion, specification, plan).
+
+**Single file (default):** `docs/workflow/{topic}/discussion.md`
+
+**Multiple files (when needed):** If a discussion needs to be split across multiple files, move them to a pluralized subdirectory: `docs/workflow/{topic}/discussions/` with semantically named files (e.g., `api-design.md`, `data-model.md`).
 
 Use **[template.md](references/template.md)** for structure:
 
@@ -51,7 +55,7 @@ See **[guidelines.md](references/guidelines.md)** for best practices and anti-ha
 
 ## Commit Frequently
 
-**Commit discussion docs often** to `docs/specs/discussions/<topic-name>/`:
+**Commit discussion docs often** to `docs/workflow/{topic}/`:
 
 - At natural breaks in discussion
 - When solutions to problems are identified

skills/technical-discussion/references/template.md

@@ -4,7 +4,11 @@
 
 ---
 
-Standard structure for `docs/specs/discussions/<topic-name>/discussion.md`. Each discussion gets its own directory with a single markdown file. DOCUMENT only - no plans or code.
+Standard structure for `docs/workflow/{topic}/discussion.md`. Each topic gets its own directory containing all workflow artifacts. DOCUMENT only - no plans or code.
+
+**Single file (default):** `docs/workflow/{topic}/discussion.md`
+
+**Multiple files (when needed):** Move to `docs/workflow/{topic}/discussions/` with semantically named files.
 
 **This is a guide, not a form.** Use the structure to capture what naturally emerges from discussion. Don't force sections that didn't come up. The goal is to document the reasoning journey, not fill in every field.
 
@@ -93,7 +97,7 @@ What we chose, why, the deciding factor, trade-offs accepted, confidence level.
 ## Usage Notes
 
 **When creating**:
-1. Create directory: `docs/specs/discussions/<topic-name>/`
+1. Ensure topic directory exists: `docs/workflow/{topic}/`
 2. Create file: `discussion.md`
 3. Fill header: date, status
 4. Start with context: why discussing?

skills/technical-implementation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-implementation
-description: "Execute implementation plans using strict TDD workflow with quality gates. Fourth phase of discussion-specification-plan-implement-review workflow. Use when: (1) Implementing a plan from docs/specs/plans/, (2) User says 'implement', 'build', or 'code this' after planning, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Writes tests first, implements to pass, commits frequently, stops for user approval between phases."
+description: "Execute implementation plans using strict TDD workflow with quality gates. Fourth phase of discussion-specification-plan-implement-review workflow. Use when: (1) Implementing a plan from docs/workflow/{topic}/, (2) User says 'implement', 'build', or 'code this' after planning, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Writes tests first, implements to pass, commits frequently, stops for user approval between phases."
 ---
 
 # Technical Implementation
@@ -31,7 +31,7 @@ You're at step 4. Execute the plan. Don't re-debate decisions.
 
 ### With a Plan
 
-1. **Read the plan** from `docs/specs/plans/{topic}/plan.md`
+1. **Read the plan** from `docs/workflow/{topic}/plan.md`
    - Check the `format` field in frontmatter:
      - `local-markdown` → content is in this file
      - `linear` → query Linear via MCP using frontmatter project_id
@@ -80,7 +80,7 @@ Keep user informed of progress:
 
 ## When to Reference Discussion
 
-Check the discussion doc (`docs/specs/discussions/{topic}/`) when:
+Check the discussion doc (`docs/workflow/{topic}/discussion.md`) when:
 
 - Task rationale is unclear
 - Multiple valid approaches exist

skills/technical-implementation/references/plan-execution.md

@@ -6,7 +6,7 @@
 
 ## Plan Structure
 
-Plans live in `docs/specs/plans/{topic}/` with phases and tasks.
+Plans live in `docs/workflow/{topic}/plan.md` with phases and tasks.
 
 **Phase** = grouping with acceptance criteria
 **Task** = single TDD cycle = one commit
@@ -27,7 +27,7 @@ For each phase:
 
 ## Referencing Discussion
 
-Check `docs/specs/discussions/{topic}/` when:
+Check `docs/workflow/{topic}/discussion.md` when:
 - Task rationale unclear
 - Multiple valid approaches
 - Edge case handling not specified

skills/technical-implementation/references/plan-sources.md

@@ -4,7 +4,7 @@
 
 ---
 
-Plans are always stored in `docs/specs/plans/{topic}/plan.md`. The file's frontmatter declares the format.
+Plans are always stored in `docs/workflow/{topic}/plan.md`. The file's frontmatter declares the format.
 
 ## Detecting Plan Format
 

skills/technical-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-planning
-description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Third phase of discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation after specification is complete, (3) Converting specifications from docs/specs/specifications/ into implementation plans, (4) User says 'plan this' or 'create a plan' after specification, (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/specs/plans/{topic-name}/ that implementation phase executes via strict TDD."
+description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Third phase of discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation after specification is complete, (3) Converting specifications from docs/workflow/{topic}/ into implementation plans, (4) User says 'plan this' or 'create a plan' after specification, (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/{topic}/ that implementation phase executes via strict TDD."
 ---
 
 # Technical Planning
@@ -22,7 +22,7 @@ You're at step 3. Create the plan. Don't jump to implementation.
 ## Source Material
 
 Plans are built **exclusively** from the specification:
-- **Specification** (`docs/specs/specifications/{topic-name}/specification.md`)
+- **Specification** (`docs/workflow/{topic}/specification.md`)
 
 The specification is the **sole source of truth**. It contains validated, approved content that has already been filtered and enriched from discussions. Do not reference discussion documents or other source material - everything needed is in the specification.
 

skills/technical-planning/references/formal-planning.md

@@ -19,7 +19,7 @@ If you don't know which format, ask.
 
 ### 1. Read Specification
 
-From the specification (`docs/specs/specifications/{topic-name}/specification.md`), extract:
+From the specification (`docs/workflow/{topic}/specification.md`), extract:
 - Key decisions and rationale
 - Architectural choices
 - Edge cases identified