Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
50 changes: 20 additions & 30 deletions docs/guides/brainstorming-to-implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) │
└─────────────────────────────────────────────┘
```
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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-<topic>-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

Expand Down
12 changes: 10 additions & 2 deletions docs/guides/decision-making.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
37 changes: 9 additions & 28 deletions docs/guides/project-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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) │
└─────────────────────────────────────────────┘
```
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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)