diff --git a/CLAUDE.md b/CLAUDE.md index cf6db3dd1..d2fa89d1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,8 +29,10 @@ commands/ ## Key Conventions -- Discussion docs: `docs/specs/discussions//discussion.md` -- Specification docs: `docs/specs/specifications//specification.md` -- Plan docs: `docs/specs/plans//` +- 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 diff --git a/README.md b/README.md index d2154c2cb..e2c0c13df 100644 --- a/README.md +++ b/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/ -│ └── / -│ └── discussion.md # Phase 1 output -├── specifications/ -│ └── / -│ └── specification.md # Phase 2 output -└── plans/ - └── / - └── 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 diff --git a/commands/start-discussion.md b/commands/start-discussion.md index 8a3e8fa87..3521daf8b 100644 --- a/commands/start-discussion.md +++ b/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// +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//`) +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//` +- 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. diff --git a/commands/start-planning.md b/commands/start-planning.md index 72e389943..e5bba75fe 100644 --- a/commands/start-planning.md +++ b/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,16 +90,19 @@ 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 @@ -108,8 +110,9 @@ 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 diff --git a/commands/start-specification.md b/commands/start-specification.md index b847dcccd..6951d93ba 100644 --- a/commands/start-specification.md +++ b/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 diff --git a/skills/technical-discussion/SKILL.md b/skills/technical-discussion/SKILL.md index c08e4d802..544b2b435 100644 --- a/skills/technical-discussion/SKILL.md +++ b/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//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//`: +**Commit discussion docs often** to `docs/workflow/{topic}/`: - At natural breaks in discussion - When solutions to problems are identified diff --git a/skills/technical-discussion/references/template.md b/skills/technical-discussion/references/template.md index 657fb1f4f..4ccc91f39 100644 --- a/skills/technical-discussion/references/template.md +++ b/skills/technical-discussion/references/template.md @@ -4,7 +4,11 @@ --- -Standard structure for `docs/specs/discussions//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//` +1. Ensure topic directory exists: `docs/workflow/{topic}/` 2. Create file: `discussion.md` 3. Fill header: date, status 4. Start with context: why discussing? diff --git a/skills/technical-implementation/SKILL.md b/skills/technical-implementation/SKILL.md index ed8382424..39ca1ed54 100644 --- a/skills/technical-implementation/SKILL.md +++ b/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 diff --git a/skills/technical-implementation/references/plan-execution.md b/skills/technical-implementation/references/plan-execution.md index 99c0003bb..62ae10290 100644 --- a/skills/technical-implementation/references/plan-execution.md +++ b/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 diff --git a/skills/technical-implementation/references/plan-sources.md b/skills/technical-implementation/references/plan-sources.md index 76b38bb35..4c2e231bd 100644 --- a/skills/technical-implementation/references/plan-sources.md +++ b/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 diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index 1de7a0444..b22ada3b5 100644 --- a/skills/technical-planning/SKILL.md +++ b/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. diff --git a/skills/technical-planning/references/formal-planning.md b/skills/technical-planning/references/formal-planning.md index 7a6b68be5..8b907cbd8 100644 --- a/skills/technical-planning/references/formal-planning.md +++ b/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 diff --git a/skills/technical-planning/references/output-backlog-md.md b/skills/technical-planning/references/output-backlog-md.md index b51b05d48..bd58027ff 100644 --- a/skills/technical-planning/references/output-backlog-md.md +++ b/skills/technical-planning/references/output-backlog-md.md @@ -19,7 +19,7 @@ See: https://github.com/MrLesk/Backlog.md ## Output Location -For Backlog.md integration, use the project's `backlog/` directory (not `docs/specs/plans/`): +For Backlog.md integration, use the project's `backlog/` directory: ``` backlog/ @@ -27,15 +27,15 @@ backlog/ ├── task-2 - Implement login endpoint.md ├── task-3 - Add session management.md └── docs/ - └── {topic-name}/ - └── plan-reference.md # Links back to discussion + └── {topic}/ + └── plan-reference.md # Links back to topic ``` -The `plan.md` file in `docs/specs/plans/{topic}/` serves as the reference pointer. +The `plan.md` file in `docs/workflow/{topic}/` serves as the reference pointer. ## File Structure -### Plan Reference File (`docs/specs/plans/{topic}/plan.md`) +### Plan Reference File (`docs/workflow/{topic}/plan.md`) ```markdown --- @@ -45,7 +45,7 @@ project: {TOPIC_NAME} # Plan Reference: {Topic Name} -**Discussion**: `docs/specs/discussions/{topic-name}/` +**Topic**: `docs/workflow/{topic}/` **Created**: {DATE} ## About This Plan @@ -104,7 +104,7 @@ labels: [phase-1, api] ## Notes -- Discussion: `docs/specs/discussions/{topic-name}/discussion.md` +- Topic: `docs/workflow/{topic}/` - Related decisions: [link if applicable] ``` @@ -170,13 +170,11 @@ project/ │ └── docs/ │ └── {topic}/ │ └── reference.md -├── docs/specs/ -│ ├── discussions/ -│ │ └── {topic}/ -│ │ └── discussion.md -│ └── plans/ -│ └── {topic}/ -│ └── plan.md # format: backlog-md +├── docs/workflow/ +│ └── {topic}/ +│ ├── discussion.md # Phase 1 output +│ ├── specification.md # Phase 2 output +│ └── plan.md # Phase 3 output (format: backlog-md - pointer) ``` ## Implementation Reading diff --git a/skills/technical-planning/references/output-linear.md b/skills/technical-planning/references/output-linear.md index bba83b09b..c5a160076 100644 --- a/skills/technical-planning/references/output-linear.md +++ b/skills/technical-planning/references/output-linear.md @@ -72,7 +72,7 @@ For each task, create an issue and apply the appropriate phase label: - [Specific edge cases for this task] ## Context -Discussion: `docs/specs/discussions/{topic-name}/discussion.md` +Topic: `docs/workflow/{topic}/` [Optional: link to specific decision if relevant] ``` @@ -97,7 +97,7 @@ This allows iterative refinement. Create all issues, identify gaps, circle back ### 4. Create Local Plan File -Create `docs/specs/plans/{topic-name}/plan.md`: +Create `docs/workflow/{topic}/plan.md`: ```markdown --- @@ -109,7 +109,7 @@ team: {TEAM_NAME} # Plan Reference: {Topic Name} -**Discussion**: `docs/specs/discussions/{topic-name}/` +**Topic**: `docs/workflow/{topic}/` **Created**: {DATE} ## About This Plan @@ -157,7 +157,7 @@ Issues should be **self-contained for execution**: - Any code examples for complex patterns **Link to (don't copy)**: -- Discussion document (for "why" context) +- Discussion document in same topic directory (for "why" context) - Specific decision sections if particularly relevant The goal: anyone (Claude or human) could pick up the issue and execute it. @@ -174,16 +174,14 @@ The goal: anyone (Claude or human) could pick up the issue and execute it. After planning: ``` -docs/specs/ -├── discussions/ -│ └── {topic-name}/ -│ └── discussion.md # Source decisions -└── plans/ - └── {topic-name}/ - └── plan.md # format: linear (pointer) +docs/workflow/ +└── {topic}/ + ├── discussion.md # Phase 1 output + ├── specification.md # Phase 2 output + └── plan.md # Phase 3 output (format: linear - pointer) Linear: -└── Project: {topic-name} +└── Project: {topic} ├── Issue: Task 1 [label: phase-1] ├── Issue: Task 2 [label: phase-1] └── Issue: Task 3 [label: phase-2] diff --git a/skills/technical-planning/references/output-local-markdown.md b/skills/technical-planning/references/output-local-markdown.md index 01c71fa94..3d2d87863 100644 --- a/skills/technical-planning/references/output-local-markdown.md +++ b/skills/technical-planning/references/output-local-markdown.md @@ -9,11 +9,15 @@ Use this format for simple features or when you want everything in a single vers ## Output Location ``` -docs/specs/plans/{topic-name}/ +docs/workflow/{topic}/ └── plan.md ``` -Directory name should match the discussion topic from `docs/specs/discussions/{topic-name}/`. +The topic directory contains all workflow artifacts (discussion, specification, plan). + +**Single file (default):** `docs/workflow/{topic}/plan.md` + +**Multiple files (when needed):** Move to `docs/workflow/{topic}/plans/` with semantically named files. ## Template @@ -28,7 +32,7 @@ format: local-markdown **Date**: YYYY-MM-DD **Status**: Draft | Ready | In Progress | Completed -**Discussion**: `docs/specs/discussions/{topic-name}/` +**Topic**: `docs/workflow/{topic}/` ## Overview @@ -153,13 +157,11 @@ When information is missing, mark clearly with `[needs-info]`: After planning: ``` -docs/specs/ -├── discussions/ -│ └── {topic-name}/ -│ └── discussion.md # Source decisions -└── plans/ - └── {topic-name}/ - └── plan.md # format: local-markdown +docs/workflow/ +└── {topic}/ + ├── discussion.md # Phase 1 output + ├── specification.md # Phase 2 output + └── plan.md # Phase 3 output (format: local-markdown) ``` Implementation reads `plan.md`, sees `format: local-markdown`, and executes directly from file content. diff --git a/skills/technical-review/SKILL.md b/skills/technical-review/SKILL.md index 353a4a5f6..c0b1216f7 100644 --- a/skills/technical-review/SKILL.md +++ b/skills/technical-review/SKILL.md @@ -53,20 +53,20 @@ Flag anything that: - Was planned but wasn't implemented - Drifted from the original intent -### 2. Discussion Compliance (`docs/specs/discussions/{topic}/`) +### 2. Discussion Compliance (`docs/workflow/{topic}/discussion.md`) - Were decisions followed? - Were edge cases handled as discussed? - Any deviations from agreed approach? - Were rejected alternatives accidentally implemented? -### 3. Specification Coverage (`docs/specs/specifications/{topic}/specification.md`) +### 3. Specification Coverage (`docs/workflow/{topic}/specification.md`) - Were all validated requirements implemented? - Any gaps between specification and implementation? - Did anything in the spec get missed? -### 4. Plan Completion (`docs/specs/plans/{topic}/plan.md`) +### 4. Plan Completion (`docs/workflow/{topic}/plan.md`) - Check `format` frontmatter to determine source (local-markdown, linear, backlog-md) - Were all phase acceptance criteria actually met? diff --git a/skills/technical-review/references/review-checklist.md b/skills/technical-review/references/review-checklist.md index c1c1432d4..0a17b2ef6 100644 --- a/skills/technical-review/references/review-checklist.md +++ b/skills/technical-review/references/review-checklist.md @@ -6,11 +6,12 @@ ## Before Starting -1. Locate discussion doc: `docs/specs/discussions/{topic}/` -2. Locate specification: `docs/specs/specifications/{topic}/specification.md` -3. Locate plan doc: `docs/specs/plans/{topic}/` -4. Identify what code/files were changed -5. Check for project-specific skills in `.claude/skills/` +1. Locate topic directory: `docs/workflow/{topic}/` +2. Read discussion: `docs/workflow/{topic}/discussion.md` +3. Read specification: `docs/workflow/{topic}/specification.md` +4. Read plan: `docs/workflow/{topic}/plan.md` +5. Identify what code/files were changed +6. Check for project-specific skills in `.claude/skills/` ## Chain Verification diff --git a/skills/technical-specification/SKILL.md b/skills/technical-specification/SKILL.md index 81de860fb..b54c56dfe 100644 --- a/skills/technical-specification/SKILL.md +++ b/skills/technical-specification/SKILL.md @@ -1,6 +1,6 @@ --- name: technical-specification -description: "Build validated specifications from discussion documents through collaborative refinement. Second phase of discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/build a specification from discussions, (2) User wants to validate and refine discussion content before planning, (3) Converting discussion documents into standalone specifications, (4) User says 'specify this' or 'create a spec' after discussions, (5) Need to filter hallucinations and enrich gaps before formal planning. Creates specifications in docs/specs/specifications/{topic-name}/ that technical-planning uses to build implementation plans." +description: "Build validated specifications from discussion documents through collaborative refinement. Second phase of discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/build a specification from discussions, (2) User wants to validate and refine discussion content before planning, (3) Converting discussion documents into standalone specifications, (4) User says 'specify this' or 'create a spec' after discussions, (5) Need to filter hallucinations and enrich gaps before formal planning. Creates specifications in docs/workflow/{topic}/ that technical-planning uses to build implementation plans." --- # Technical Specification @@ -23,7 +23,11 @@ You're at step 2. Build the specification. Don't jump to phases, tasks, or code. **Load**: [specification-guide.md](references/specification-guide.md) -**Output**: `specification.md` in `docs/specs/specifications/{topic-name}/` +**Output**: `docs/workflow/{topic}/specification.md` + +**Single file (default):** `docs/workflow/{topic}/specification.md` + +**Multiple files (when needed):** Move to `docs/workflow/{topic}/specifications/` with semantically named files. **When complete**: User signs off, then proceed to technical-planning. diff --git a/skills/technical-specification/references/specification-guide.md b/skills/technical-specification/references/specification-guide.md index 8ae827fba..5eb92e522 100644 --- a/skills/technical-specification/references/specification-guide.md +++ b/skills/technical-specification/references/specification-guide.md @@ -70,7 +70,11 @@ This is encouraged. Better to resurface and confirm "already covered" than let s ## The Specification Document -Create `specification.md` in `docs/specs/specifications/{topic-name}/` +Create `docs/workflow/{topic}/specification.md` + +**Single file (default):** `docs/workflow/{topic}/specification.md` + +**Multiple files (when needed):** Move to `docs/workflow/{topic}/specifications/` with semantically named files. Structure is **flexible** - organize around phases and subject matter, not rigid sections. This is a working document.