diff --git a/docs/guides/spec-driven-development.md b/docs/guides/spec-driven-development.md index 6bc789e..6132558 100644 --- a/docs/guides/spec-driven-development.md +++ b/docs/guides/spec-driven-development.md @@ -47,68 +47,72 @@ Run the planning process: It will perform the following refinement process to update the task file with a more detailed specification: -```mermaid -flowchart TB - subgraph Input - A[๐Ÿ“„ Draft Task File
.specs/tasks/draft/*.md] - end - - subgraph Phase2["Phase 2: Parallel Analysis"] - direction LR - B1[๐Ÿ”ฌ Research
researcher ยท sonnet] - B2[๐Ÿ“‚ Codebase Analysis
code-explorer ยท sonnet] - B3[๐Ÿ’ผ Business Analysis
business-analyst ยท opus] - - J1[โš–๏ธ Judge 2a] - J2[โš–๏ธ Judge 2b] - J3[โš–๏ธ Judge 2c] - - B1 --> J1 - B2 --> J2 - B3 --> J3 - end - - subgraph Phase3["Phase 3: Architecture Synthesis"] - C[๐Ÿ—๏ธ Architecture Synthesis
software-architect ยท opus] - JC[โš–๏ธ Judge 3] - C --> JC - end - - subgraph Phase4["Phase 4: Decomposition"] - D[๐Ÿ“‹ Decomposition
tech-lead ยท opus] - JD[โš–๏ธ Judge 4] - D --> JD - end - - subgraph Phase5["Phase 5: Parallelize"] - E[๐Ÿ”€ Parallelize Steps
team-lead ยท opus] - JE[โš–๏ธ Judge 5] - E --> JE - end - - subgraph Phase6["Phase 6: Verifications"] - F[โœ… Define Verifications
qa-engineer ยท opus] - JF[โš–๏ธ Judge 6] - F --> JF - end - - subgraph Output - G[๐Ÿ“„ Refined Task File
.specs/tasks/todo/*.md] - H[๐Ÿ“š Skill File
.claude/skills/*/SKILL.md] - I[๐Ÿ“Š Analysis File
.specs/analysis/*.md] - end - - A --> Phase2 - J1 & J2 & J3 --> Phase3 - JC --> Phase4 - JD --> Phase5 - JE --> Phase6 - JF --> G & H & I - - style A fill:#e1f5fe - style G fill:#c8e6c9 - style H fill:#c8e6c9 - style I fill:#c8e6c9 +``` + +----------------------------+ + | Draft Task File | + | .specs/tasks/draft/*.md | + +-------------+--------------+ + | + v ++----------------------------------------------------------+ +| Phase 2: Parallel Analysis | +| | +| +----------------+ +------------------+ +-------------+| +| | Research | | Codebase | | Business || +| | researcher | | Analysis | | Analysis || +| | (sonnet) | | code-explorer | | business- || +| | | | | (sonnet) | | analyst || +| | v | | | | | (opus) || +| | Judge 2a | | Judge 2b | | | || +| +------+---------+ +--------+---------+ +------+------+| +| | | | | ++----------------------------------------------------------+ + | | | + +----------+----------+--------------------+ + | + v + +-----------------------------+ + | Phase 3: Architecture | + | software-architect (opus) | + | | | + | v | + | Judge 3 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 4: Decomposition | + | tech-lead (opus) | + | | | + | v | + | Judge 4 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 5: Parallelize | + | team-lead (opus) | + | | | + | v | + | Judge 5 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 6: Verifications | + | qa-engineer (opus) | + | | | + | v | + | Judge 6 | + +--------------+--------------+ + | + +-----------------+-----------------+ + | | | + v v v ++--------------+ +--------------+ +---------------+ +| Refined Task | | Skill File | | Analysis File | +| todo/*.md | | SKILL.md | | analysis-*.md | ++--------------+ +--------------+ +---------------+ ``` It will output the updated task file to `.specs/tasks/todo/design-implement-authentication-middleware-with-jwt-support.feature.md` and create new skills if needed. It also produces scratchpads and verification reports along the way to properly evaluate each step of the process. You can safely ignore all of them. @@ -125,66 +129,68 @@ Once you are happy with the specification, you can run the implementation proces It will perform the following actions: -```mermaid -flowchart TB - subgraph Phase0["Phase 0: Select Task"] - A[๐Ÿ“„ Task from todo/
or in-progress/] - A --> B[๐Ÿ“ Move to in-progress/] - end - - subgraph Phase1["Phase 1: Load Task"] - C[๐Ÿ“– Parse Implementation Steps
& Verification Requirements] - end - - subgraph Phase2["Phase 2: Execute Steps"] - D[๐Ÿ”„ For Each Step] - - subgraph StepExec["Step Execution Loop"] - E[๐Ÿ‘จโ€๐Ÿ’ป Developer Agent
Implement Step] - F{Verification
Level?} - - G1[โญ๏ธ None
Skip Judge] - G2[โš–๏ธ Single Judge
threshold: 4.0] - G3[โš–๏ธโš–๏ธ Panel of 2
threshold: 4.5] - G4[โš–๏ธ Per-Item
Parallel Judges] - - H{PASS?} - I[๐Ÿ”ง Fix & Retry
with feedback] - J[โœ… Mark Step DONE] - end - - D --> E - E --> F - F -->|None| G1 --> J - F -->|Single| G2 --> H - F -->|Panel| G3 --> H - F -->|Per-Item| G4 --> H - H -->|Yes| J - H -->|No| I --> E - J --> D - end - - subgraph Phase3["Phase 3: Final Verification"] - K[๐Ÿ“‹ Verify Definition of Done] - L{All DoD
PASS?} - M[๐Ÿ”ง Fix Failing Items] - end - - subgraph Phase4["Phase 4: Complete"] - N[๐Ÿ“ Move to done/] - O[๐Ÿ“Š Final Report] - end - - Phase0 --> Phase1 - Phase1 --> Phase2 - Phase2 --> Phase3 - K --> L - L -->|No| M --> K - L -->|Yes| Phase4 - - style A fill:#e1f5fe - style N fill:#c8e6c9 - style O fill:#c8e6c9 +``` ++--------------------------------------+ +| Phase 0: Select Task | +| Task from todo/ or in-progress/ | +| | | +| v | +| Move to in-progress/ | ++------------------+-------------------+ + | + v ++--------------------------------------+ +| Phase 1: Load Task | +| Parse Implementation Steps | +| & Verification Requirements | ++------------------+-------------------+ + | + v ++------------------------------------------------------+ +| Phase 2: Execute Steps | +| | +| For Each Step: | +| | +| Developer Agent: Implement Step <--+ | +| | | | +| v | | +| Verification Level? | | +| | | | | | | +| None Single Panel Per-Item | | +| | (4.0) (4.5) (Parallel) | | +| | | | | | | +| | +---+---+-------+ | | +| | | | | +| | v | | +| | PASS? --No--> Fix & Retry | +| | | | +| | Yes | +| +-----+-----+ | +| | | +| v | +| Mark Step DONE | ++----------------------+-------------------------------+ + | + v ++--------------------------------------+ +| Phase 3: Final Verification | +| | +| Verify Definition of Done <--+ | +| | | | +| v | | +| All DoD PASS? | | +| / \ | | +| Yes No | | +| | \ | | +| | Fix Failing Items--+ | ++--------+-----------------------------+ + | + v ++--------------------------------------+ +| Phase 4: Complete | +| Move to done/ | +| Final Report | ++--------------------------------------+ ``` It will automatically write tests, verify them, build the solution, and confirm it works as expected. diff --git a/docs/plugins/sdd/README.md b/docs/plugins/sdd/README.md index 2a8de4b..d506a79 100644 --- a/docs/plugins/sdd/README.md +++ b/docs/plugins/sdd/README.md @@ -8,7 +8,7 @@ This plugin is designed to consistently and reproducibly produce working code. I - **Development as compilation** โ€” The plugin works like a "compilation" or "nightly build" for your development process: `task specs โ†’ run /sdd:implement โ†’ working code`. After writing your prompt, you can launch the plugin and expect a working result when you come back. The time it takes depends on task complexity โ€” simple tasks may finish in 30 minutes, while complex ones can take a few days. - **Benchmark-level quality in real life** โ€” Model benchmarks improve with each release, yet real-world results usually stay the same. That's because benchmarks reflect the best possible output a model can achieve, whereas in practice LLMs tend to drift toward sub-optimal solutions that can be wrong or non-functional. This plugin uses a variety of patterns to keep the model working at its peak performance. -- **Customizable** โ€” Balance between result quality and process speed by adjusting command parameters. Learn more in the [Customization](./customization) section. +- **Customizable** โ€” Balance between result quality and process speed by adjusting command parameters. Learn more in the [Customization](customization.md) section. - **Developer time-efficient** โ€” The overall process is designed to minimize developer time and reduce the number of interactions, while still producing results better than what a model can generate from scratch. However, overall quality is highly proportional to the time you invest in iterating and refining the specification. - **Industry-standard** โ€” The plugin's specification template is based on the arc42 standard, adjusted for LLM capabilities. Arc42 is a widely adopted, high-quality standard for software development documentation used by many companies and organizations. - **Works best in complex or large codebases** โ€” While most other frameworks work best for new projects and greenfield development, this plugin is designed to perform better the more existing code and well-structured architecture you have. At each planning phase it includes a **codebase impact analysis** step that evaluates which files may be affected and which patterns to follow to achieve the desired result. @@ -46,12 +46,12 @@ Restart the Claude Code session to clear context and start fresh. Then run the f # produces working implementation and moves the task to .specs/tasks/done/ folder ``` -- [Detailed guide](../../guides/spec-driven-development) -- [Usage Examples](./usage-examples) +- [Detailed guide](../../guides/spec-driven-development.md) +- [Usage Examples](usage-examples.md) ## Overall Flow -End-to-end task implementation process from initial prompt to pull request, including commands from the [git](../git) plugin: +End-to-end task implementation process from initial prompt to pull request, including commands from the [git](../git/README.md) plugin: - `/sdd:add-task` โ†’ creates a `.specs/tasks/draft/..md` file with the initial task description. - `/sdd:plan` โ†’ generates a `.claude/skills//SKILL.md` file with skills needed to implement the task (by analyzing library and framework documentation used in the codebase), then updates the task file with a refined specification and moves it to `.specs/tasks/todo/`. @@ -59,58 +59,34 @@ End-to-end task implementation process from initial prompt to pull request, incl - `/git:commit` โ†’ commits changes. - `/git:create-pr` โ†’ creates a pull request. -```mermaid -flowchart LR - subgraph Create["1. Create"] - A["/sdd:add-task"] - end - - subgraph Plan["2. Plan"] - B["/sdd:plan"] - end - - subgraph Implement["3. Implement"] - C["/sdd:implement"] - end - - subgraph Ship["4. Ship"] - D["/git:commit"] - E["/git:create-pr"] - end - - subgraph Files["Task Lifecycle"] - F1[๐Ÿ“„ draft/*.md] - F2[๐Ÿ“„ todo/*.md] - F3[๐Ÿ“„ in-progress/*.md] - F4[๐Ÿ“„ done/*.md] - end - - A --> F1 - F1 --> B - B --> F2 - F2 --> C - C --> F3 - F3 --> F4 - F4 --> D --> E - - style F1 fill:#ffecb3 - style F2 fill:#e1f5fe - style F3 fill:#fff3e0 - style F4 fill:#c8e6c9 +``` + 1. Create 2. Plan 3. Implement 4. Ship ++-------------+ +-----------+ +---------------+ +-----------------+ +|/sdd:add-task| | /sdd:plan | |/sdd:implement | | /git:commit | ++------+------+ +-----+-----+ +------+--------+ | | | + | | | | v | + v v v |/git:create-pr | + +-------+---------+ + | + Task Lifecycle | + +----------+ +----------+ +--------------+ +---------+ + | draft/ +-->| todo/ +-->| in-progress/ +-->| done/ | + | *.md | | *.md | | *.md | | *.md | + +----------+ +----------+ +--------------+ +---------+ ``` ## Commands Core workflow commands: -- [/sdd:add-task](./add-task) - Create task template file with initial prompt -- [/sdd:plan](./plan) - Analyze prompt, generate required skills and refine task specification -- [/sdd:implement](./implement) - Produce working implementation of the task and verify it +- [/sdd:add-task](add-task.md) - Create task template file with initial prompt +- [/sdd:plan](plan.md) - Analyze prompt, generate required skills and refine task specification +- [/sdd:implement](implement.md) - Produce working implementation of the task and verify it Additional commands useful before creating a task: -- [/sdd:create-ideas](./create-ideas) - Generate diverse ideas on a given topic using creative sampling techniques -- [/sdd:brainstorm](./brainstorm) - Refine vague ideas into fully-formed designs through collaborative dialogue +- [/sdd:create-ideas](create-ideas.md) - Generate diverse ideas on a given topic using creative sampling techniques +- [/sdd:brainstorm](brainstorm.md) - Refine vague ideas into fully-formed designs through collaborative dialogue ## Available Agents @@ -149,7 +125,7 @@ Our tests showed that even when the initially generated specification was incorr Even if you don't want to spend much time on this process, you can still use the plugin for complex tasks without decomposition or human verification โ€” but you will likely need tools like ralph-loop to keep the agent running for a longer time. -Learn more about available customization options in [Customization](./customization). +Learn more about available customization options in [Customization](customization.md). ## Theoretical Foundation diff --git a/docs/plugins/sdd/add-task.md b/docs/plugins/sdd/add-task.md index 57be8eb..adc686c 100644 --- a/docs/plugins/sdd/add-task.md +++ b/docs/plugins/sdd/add-task.md @@ -18,42 +18,47 @@ Create a draft task file that captures the user's intent with structured metadat ## Workflow Diagram -```mermaid -flowchart TB - subgraph Input - A[๐Ÿ’ฌ User Prompt] - B[๐Ÿ“„ Dependencies] - end - - subgraph Phase1[Phase 1: Setup] - C[๐Ÿ“ Ensure Directory Structure] - end - - subgraph Phase2[Phase 2: Analyze] - D[๐Ÿ” Parse User Request] - E[๐Ÿท๏ธ Classify Type] - F[โœ๏ธ Create Action-Oriented Title] - end - - subgraph Phase3[Phase 3: Generate] - G[๐Ÿ“ Generate File Name] - H[๐Ÿ”Ž Verify Uniqueness] - I[๐Ÿ’พ Write Task File] - end - - subgraph Output - J[๐Ÿ“„ Draft Task File] - end - - A & B --> Phase1 - Phase1 --> Phase2 - D --> E --> F - Phase2 --> Phase3 - G --> H --> I - Phase3 --> Output - - style A fill:#e1f5fe - style J fill:#c8e6c9 +``` + +--------------+ +---------------+ + | User Prompt | | Dependencies | + +------+-------+ +-------+-------+ + | | + +-------+-----------+ + | + v + +------------------------+ + | Phase 1: Setup | + | Ensure Dir Structure | + +-----------+------------+ + | + v + +------------------------+ + | Phase 2: Analyze | + | Parse User Request | + | | | + | v | + | Classify Type | + | | | + | v | + | Create Action Title | + +-----------+------------+ + | + v + +------------------------+ + | Phase 3: Generate | + | Generate File Name | + | | | + | v | + | Verify Uniqueness | + | | | + | v | + | Write Task File | + +-----------+------------+ + | + v + +------------------------+ + | Draft Task File | + +------------------------+ ``` ## How It Works diff --git a/docs/plugins/sdd/implement.md b/docs/plugins/sdd/implement.md index 048ae4c..d9c0562 100644 --- a/docs/plugins/sdd/implement.md +++ b/docs/plugins/sdd/implement.md @@ -23,66 +23,68 @@ Execute task implementation steps with automated LLM-as-Judge quality verificati ## Workflow Diagram -```mermaid -flowchart TB - subgraph Phase0["Phase 0: Select Task"] - A[๐Ÿ“„ Task from todo/
or in-progress/] - A --> B[๐Ÿ“ Move to in-progress/] - end - - subgraph Phase1["Phase 1: Load Task"] - C[๐Ÿ“– Parse Implementation Steps
& Verification Requirements] - end - - subgraph Phase2["Phase 2: Execute Steps"] - D[๐Ÿ”„ For Each Step] - - subgraph StepExec["Step Execution Loop"] - E[๐Ÿ‘จโ€๐Ÿ’ป Developer Agent
Implement Step] - F{Verification
Level?} - - G1[โญ๏ธ None
Skip Judge] - G2[โš–๏ธ Single Judge
threshold: 4.0] - G3[โš–๏ธโš–๏ธ Panel of 2
threshold: 4.5] - G4[โš–๏ธ Per-Item
Parallel Judges] - - H{PASS?} - I[๐Ÿ”ง Fix & Retry
with feedback] - J[โœ… Mark Step DONE] - end - - D --> E - E --> F - F -->|None| G1 --> J - F -->|Single| G2 --> H - F -->|Panel| G3 --> H - F -->|Per-Item| G4 --> H - H -->|Yes| J - H -->|No| I --> E - J --> D - end - - subgraph Phase3["Phase 3: Final Verification"] - K[๐Ÿ“‹ Verify Definition of Done] - L{All DoD
PASS?} - M[๐Ÿ”ง Fix Failing Items] - end - - subgraph Phase4["Phase 4: Complete"] - N[๐Ÿ“ Move to done/] - O[๐Ÿ“Š Final Report] - end - - Phase0 --> Phase1 - Phase1 --> Phase2 - Phase2 --> Phase3 - K --> L - L -->|No| M --> K - L -->|Yes| Phase4 - - style A fill:#e1f5fe - style N fill:#c8e6c9 - style O fill:#c8e6c9 +``` ++--------------------------------------+ +| Phase 0: Select Task | +| Task from todo/ or in-progress/ | +| | | +| v | +| Move to in-progress/ | ++------------------+-------------------+ + | + v ++--------------------------------------+ +| Phase 1: Load Task | +| Parse Implementation Steps | +| & Verification Requirements | ++------------------+-------------------+ + | + v ++------------------------------------------------------+ +| Phase 2: Execute Steps | +| | +| For Each Step: | +| | +| Developer Agent: Implement Step <--+ | +| | | | +| v | | +| Verification Level? | | +| | | | | | | +| None Single Panel Per-Item | | +| | (4.0) (4.5) (Parallel) | | +| | | | | | | +| | +---+---+-------+ | | +| | | | | +| | v | | +| | PASS? --No--> Fix & Retry | +| | | | +| | Yes | +| +-----+-----+ | +| | | +| v | +| Mark Step DONE | ++----------------------+-------------------------------+ + | + v ++--------------------------------------+ +| Phase 3: Final Verification | +| | +| Verify Definition of Done <--+ | +| | | | +| v | | +| All DoD PASS? | | +| / \ | | +| Yes No | | +| | \ | | +| | Fix Failing Items--+ | ++--------+-----------------------------+ + | + v ++--------------------------------------+ +| Phase 4: Complete | +| Move to done/ | +| Final Report | ++--------------------------------------+ ``` ## How It Works diff --git a/docs/plugins/sdd/plan.md b/docs/plugins/sdd/plan.md index 7303c64..bb7dac6 100644 --- a/docs/plugins/sdd/plan.md +++ b/docs/plugins/sdd/plan.md @@ -39,68 +39,72 @@ Refine a draft task specification into a fully planned, implementation-ready tas ## Workflow Diagram -```mermaid -flowchart TB - subgraph Input - A[๐Ÿ“„ Draft Task File
.specs/tasks/draft/*.md] - end - - subgraph Phase2["Phase 2: Parallel Analysis"] - direction LR - B1[๐Ÿ”ฌ Research
researcher ยท sonnet] - B2[๐Ÿ“‚ Codebase Analysis
code-explorer ยท sonnet] - B3[๐Ÿ’ผ Business Analysis
business-analyst ยท opus] - - J1[โš–๏ธ Judge 2a] - J2[โš–๏ธ Judge 2b] - J3[โš–๏ธ Judge 2c] - - B1 --> J1 - B2 --> J2 - B3 --> J3 - end - - subgraph Phase3["Phase 3: Architecture Synthesis"] - C[๐Ÿ—๏ธ Architecture Synthesis
software-architect ยท opus] - JC[โš–๏ธ Judge 3] - C --> JC - end - - subgraph Phase4["Phase 4: Decomposition"] - D[๐Ÿ“‹ Decomposition
tech-lead ยท opus] - JD[โš–๏ธ Judge 4] - D --> JD - end - - subgraph Phase5["Phase 5: Parallelize"] - E[๐Ÿ”€ Parallelize Steps
team-lead ยท opus] - JE[โš–๏ธ Judge 5] - E --> JE - end - - subgraph Phase6["Phase 6: Verifications"] - F[โœ… Define Verifications
qa-engineer ยท opus] - JF[โš–๏ธ Judge 6] - F --> JF - end - - subgraph Output - G[๐Ÿ“„ Refined Task File
.specs/tasks/todo/*.md] - H[๐Ÿ“š Skill File
.claude/skills/*/SKILL.md] - I[๐Ÿ“Š Analysis File
.specs/analysis/*.md] - end - - A --> Phase2 - J1 & J2 & J3 --> Phase3 - JC --> Phase4 - JD --> Phase5 - JE --> Phase6 - JF --> G & H & I - - style A fill:#e1f5fe - style G fill:#c8e6c9 - style H fill:#c8e6c9 - style I fill:#c8e6c9 +``` + +----------------------------+ + | Draft Task File | + | .specs/tasks/draft/*.md | + +-------------+--------------+ + | + v ++----------------------------------------------------------+ +| Phase 2: Parallel Analysis | +| | +| +----------------+ +------------------+ +-------------+| +| | Research | | Codebase | | Business || +| | researcher | | Analysis | | Analysis || +| | (sonnet) | | code-explorer | | business- || +| | | | | (sonnet) | | analyst || +| | v | | | | | (opus) || +| | Judge 2a | | Judge 2b | | | || +| +------+---------+ +--------+---------+ +------+------+| +| | | | | ++----------------------------------------------------------+ + | | | + +----------+----------+--------------------+ + | + v + +-----------------------------+ + | Phase 3: Architecture | + | software-architect (opus) | + | | | + | v | + | Judge 3 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 4: Decomposition | + | tech-lead (opus) | + | | | + | v | + | Judge 4 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 5: Parallelize | + | team-lead (opus) | + | | | + | v | + | Judge 5 | + +--------------+--------------+ + | + v + +-----------------------------+ + | Phase 6: Verifications | + | qa-engineer (opus) | + | | | + | v | + | Judge 6 | + +--------------+--------------+ + | + +-----------------+-----------------+ + | | | + v v v ++--------------+ +--------------+ +---------------+ +| Refined Task | | Skill File | | Analysis File | +| todo/*.md | | SKILL.md | | analysis-*.md | ++--------------+ +--------------+ +---------------+ ``` ## How It Works