diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 2aef50a..29634ef 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,10 +4,10 @@ * [Getting Started](getting-started.md) * [Guides](guides/README.md) * [Project Setup](guides/project-setup.md) + * [Reliable Engineering through Spec-Driven Development](guides/spec-driven-development.md) * [File Structure Context](guides/file-structure-context.md) * [Feature Development](guides/feature-development.md) - * [Reliable Engineering](guides/reliable-engineering.md) - * [Spec-Driven Development](guides/spec-driven-development.md) + * [Competitive Multi-Agent Code Generation](guides/competitivy-generation.md) * [Decision Making](guides/decision-making.md) * [PR Review](guides/pr-review.md) * [Brainstorming Complex Feature](guides/brainstorming-to-implementation.md) @@ -90,14 +90,12 @@ * [subagent-driven-development](plugins/sadd/subagent-driven-development.md) * [Usage Examples](plugins/sadd/usage-examples.md) * [Spec-Driven Development](plugins/sdd/README.md) - * [00-setup](plugins/sdd/00-setup.md) - * [01-specify](plugins/sdd/01-specify.md) - * [02-plan](plugins/sdd/02-plan.md) - * [03-tasks](plugins/sdd/03-tasks.md) - * [04-implement](plugins/sdd/04-implement.md) - * [05-document](plugins/sdd/05-document.md) + * [add-task](plugins/sdd/add-task.md) + * [plan](plugins/sdd/plan.md) + * [implement](plugins/sdd/implement.md) * [brainstorm](plugins/sdd/brainstorm.md) * [create-ideas](plugins/sdd/create-ideas.md) + * [customization](plugins/sdd/customization.md) * [Usage Examples](plugins/sdd/usage-examples.md) * [Test-Driven Development](plugins/tdd/README.md) * [fix-tests](plugins/tdd/fix-tests.md) diff --git a/docs/guides/brainstorming-to-implementation.md b/docs/guides/brainstorming-to-implementation.md index 2f83a3a..68ff156 100644 --- a/docs/guides/brainstorming-to-implementation.md +++ b/docs/guides/brainstorming-to-implementation.md @@ -45,14 +45,14 @@ For well-defined requirements, skip brainstorming and use [Spec-Driven Developme │ validated design saved to docs/plans/ ▼ ┌─────────────────────────────────────────────┐ -│ 4. Create Specification │ -│ (formal feature spec from design) │ +│ 4. Create Task & Plan Specification │ +│ (formal spec from design) │ └────────────────────┬────────────────────────┘ │ │ continue with SDD workflow ▼ ┌─────────────────────────────────────────────┐ -│ 5-8. Plan, Implement, Review, Document │ +│ 5-6. Implement, Review │ │ (standard SDD phases) │ └─────────────────────────────────────────────┘ ``` @@ -66,6 +66,7 @@ Use the `/sdd:brainstorm` command to start a collaborative dialogue. The LLM wil ``` After starting, the LLM will: + - Review your project structure, docs, and recent commits - Ask focused questions (preferring multiple choice when possible) - Help you define purpose, constraints, and success criteria @@ -103,6 +104,7 @@ For architectural decisions with long-term consequences, consider using the [FPF ``` FPF provides: + - **Structured hypothesis generation** - Multiple competing options with diverse perspectives - **Logical verification** - Check each option against project constraints - **Evidence validation** - Empirical testing with trust scores @@ -136,57 +138,45 @@ The LLM will cover: After each section, confirm it matches your expectations or request changes. Once complete, the design is saved to `docs/plans/YYYY-MM-DD--design.md`. -### 4. Create specification +### 4. Create task and plan specification -Use the `/sdd:01-specify` command to create a formal specification from the refined design. +Use the `/sdd:add-task` command to create a task file from the refined design, then `/sdd:plan` to generate a detailed specification with architecture, implementation steps, and verification criteria. ```bash -/sdd:01-specify Implement faceted search with Elasticsearch, filters, and autocomplete +/sdd:add-task "Implement faceted search with Elasticsearch, filters, and autocomplete" ``` -After LLM completes, review the specification in the `specs/` directory. This becomes the foundation for implementation planning. - -### 5. Plan architecture - -Use the `/sdd:02-plan` command to create the implementation plan based on your specification. - -```bash -/sdd:02-plan -``` - -After LLM completes, review the proposed architecture and technical decisions. - -### 6. Break down into tasks +After LLM completes, review the task file in `.specs/tasks/draft/`. You can adjust the task file to incorporate additional details from the brainstorming session. -Use the `/sdd:03-tasks` command to create actionable implementation tasks. +Then run planning to generate the full specification: ```bash -/sdd:03-tasks +/sdd:plan ``` -After LLM completes, review the task list and adjust priorities as needed. +After LLM completes, review the refined specification in `.specs/tasks/todo/`. The plan includes architecture design, implementation steps with parallelization, and verification rubrics. You can adjust and run `/sdd:plan --refine` to iterate. -### 7. Implement features +### 5. Implement features -Use the `/sdd:04-implement` command to execute the implementation. +Use the `/sdd:implement` command to execute the implementation. This produces working code with tests and verification. ```bash -/sdd:04-implement +/sdd:implement ``` -During implementation, the LLM updates task progress and follows TDD approach with quality review. +During implementation, the LLM executes each step with quality gates, writes tests, and verifies the solution works as expected. More info in [Spec-Driven Development](./spec-driven-development.md) workflow. -### 8. Review and document +### 6. Review and ship -Complete the workflow with code review, documentation, and pull request creation. More info in [Spec-Driven Development](./spec-driven-development.md) workflow. +Complete the workflow with code review and pull request creation. ```bash /code-review:review-local-changes -/sdd:05-document +/git:commit /git:create-pr ``` -After completion, your feature is ready for merge with full documentation in the `docs/` directory. +After completion, your feature is ready for merge. ## Key Principles diff --git a/docs/guides/decision-making.md b/docs/guides/decision-making.md index c5246c0..cc6e43b 100644 --- a/docs/guides/decision-making.md +++ b/docs/guides/decision-making.md @@ -83,6 +83,7 @@ Use the `/fpf:propose-hypotheses` command to start the FPF cycle. The FPF agent ``` After starting, the FPF agent will: + - Initialize `.fpf/` directory structure if needed - Frame your problem in the bounded context - Generate diverse L0 hypotheses (conservative + radical approaches) @@ -111,6 +112,7 @@ If you have additional approaches to consider, describe them. The FPF agent will The workflow launches parallel FPF agents to verify each L0 hypothesis against logical constraints. For each hypothesis: + - Check internal consistency - Apply first-principles reasoning - Verify against project constraints @@ -123,6 +125,7 @@ Hypotheses that pass verification are promoted to `.fpf/knowledge/L1/`. Failed h The workflow launches parallel FPF agents to gather empirical evidence for each L1 hypothesis. For each substantiated hypothesis: + - Search codebase for similar patterns - Review documentation and external sources - Run tests or benchmarks if applicable @@ -135,6 +138,7 @@ Validated hypotheses are promoted to `.fpf/knowledge/L2/` with confidence scores The workflow launches parallel FPF agents to compute effective reliability (R_eff) for each L2 hypothesis using the Weakest Link (WLNK) principle. For each corroborated hypothesis: + - Apply evidence decay factors for freshness - Consider congruence levels (CL1/CL2/CL3) - Compute R_eff = min(evidence_scores) @@ -145,6 +149,7 @@ The trust audit produces ranked hypotheses with their R_eff scores. ### 6. Make decision The FPF agent creates a Decision Readiness Report (DRR) with: + - Ranked hypotheses by R_eff and confidence - Comparison table showing trade-offs - Recommended action with rationale @@ -155,6 +160,7 @@ You review the DRR and select the winning hypothesis. The decision is documented ### 7. Present results The workflow presents the final summary: + - Selected hypothesis with rationale - R_eff score and confidence interval - Supporting evidence @@ -388,7 +394,8 @@ Use FPF to decide on architecture approach before creating the spec: ```bash /fpf:propose-hypotheses What architecture pattern should we use for this feature? # Review DRR and select approach -/sdd:01-specify Implement feature using [selected approach] +/sdd:add-task "Implement feature using [selected approach]" +/sdd:plan ``` ### During brainstorming @@ -400,7 +407,8 @@ Use FPF to evaluate alternative designs: # After exploring approaches, use FPF to decide /fpf:propose-hypotheses Which search implementation should we choose? # Continue with selected approach -/sdd:01-specify Implement search with [selected approach] +/sdd:add-task "Implement search with [selected approach]" +/sdd:plan ``` ### For technical decisions diff --git a/docs/guides/project-setup.md b/docs/guides/project-setup.md index ea3b23d..011cd6a 100644 --- a/docs/guides/project-setup.md +++ b/docs/guides/project-setup.md @@ -11,7 +11,6 @@ Initialize new projects with established best practices, coding standards, and t ## Plugins needed for this workflow -- [SDD](../plugins/sdd/README.md) - [Tech Stack](../plugins/tech-stack/README.md) - [DDD](../plugins/ddd/README.md) - [MCP](../plugins/mcp/README.md) @@ -23,35 +22,28 @@ Initialize new projects with established best practices, coding standards, and t ```md ┌─────────────────────────────────────────────┐ -│ 1. Establish Project Constitution │ -│ (create specs/constitution.md) │ -└────────────────────┬────────────────────────┘ - │ - │ define tech stack and architecture principles - ▼ -┌─────────────────────────────────────────────┐ -│ 2. Setup Language Best Practices │ +│ 1. Setup Language Best Practices │ │ (update CLAUDE.md) │ └────────────────────┬────────────────────────┘ │ │ add language-specific guidelines ▼ ┌─────────────────────────────────────────────┐ -│ 3. Setup Code Quality Standards │ +│ 2. Setup Code Quality Standards │ │ (update CLAUDE.md) │ └────────────────────┬────────────────────────┘ │ │ add formatting and style rules ▼ ┌─────────────────────────────────────────────┐ -│ 4. Setup MCP Servers (optional) │ +│ 3. Setup MCP Servers (optional) │ │ (configure external tools) │ └────────────────────┬────────────────────────┘ │ │ enable documentation and code retrieval ▼ ┌─────────────────────────────────────────────┐ -│ 5. Document Project Setup │ +│ 4. Document Project Setup │ │ (update docs/ directory) │ └─────────────────────────────────────────────┘ ``` @@ -64,19 +56,9 @@ Use the `/init` command to initialize your project. claude /init ``` -After LLM completes, review the `CLAUDE.md` file and adjust any principles or constraints. - -### 1. Establish project constitution - -Use the `/sdd:00-setup` command to create your project's governing principles and development guidelines. This creates `specs/constitution.md` which guides all subsequent development. - -```bash -/sdd:00-setup Use FastAPI, PostgreSQL, pytest, follow Clean Architecture -``` - -After LLM completes, review `specs/constitution.md` and adjust any principles or constraints. This file serves as the source of truth for architectural decisions. +After LLM completes, review the `CLAUDE.md` file and adjust any principles or constraints. -### 2. Setup language best practices +### 1. Setup language best practices Use the `/tech-stack:add-typescript-best-practices` command to add language-specific coding standards to your `CLAUDE.md` file. @@ -86,7 +68,7 @@ Use the `/tech-stack:add-typescript-best-practices` command to add language-spec After LLM completes, review the added guidelines in `CLAUDE.md`. These rules ensure consistent code style and patterns across all AI-assisted development. -### 3. Setup code quality standards +### 2. Setup code quality standards Use the `/ddd:setup-code-formating` command to establish code formatting rules and style guidelines. @@ -96,7 +78,7 @@ Use the `/ddd:setup-code-formating` command to establish code formatting rules a After LLM completes, review the formatting rules added to `CLAUDE.md`. These standards ensure consistent code structure following Clean Architecture and SOLID principles. -### 4. Setup MCP servers (optional) +### 3. Setup MCP servers (optional) Use MCP commands to integrate external tools that enhance AI capabilities. Choose based on your project needs: @@ -114,7 +96,7 @@ Use MCP commands to integrate external tools that enhance AI capabilities. Choos After LLM completes for each command, follow the setup instructions provided. MCP servers extend Claude's capabilities with project-specific context. -### 5. Document project setup +### 4. Document project setup Use the `/docs:update-docs` command to generate initial project documentation based on your setup. @@ -128,7 +110,6 @@ After LLM completes, review the generated documentation in the `docs/` directory After completing this workflow, your project will have: -- **`specs/constitution.md`** - Project principles and architectural guidelines - **`CLAUDE.md`** - AI assistant configuration with coding standards - **`docs/`** - Initial project documentation - **MCP integrations** - Enhanced tooling for documentation and code retrieval (if configured)