@ydtb/specsmd 0.1.22

package/flows/fire/quick-start.md

@@ -0,0 +1,146 @@
+# FIRE Flow
+
+**Fast Intent-Run Engineering** — A simplified AI-native development methodology.
+
+## Overview
+
+FIRE reduces the complexity of AI-assisted development by flattening the hierarchy:
+
+```
+Intent → Work Item → Run
+```
+
+Unlike traditional methodologies with 10-26 checkpoints, FIRE uses adaptive checkpoints (0-2) based on work item complexity.
+
+## Quick Start
+
+```bash
+# Initialize FIRE in your project
+/specsmd-fire
+
+# Or directly invoke specific agents
+/specsmd-fire-planner    # For planning work
+/specsmd-fire-builder    # For executing work
+```
+
+## Execution Modes
+
+| Mode | Checkpoints | Complexity | Use For |
+|------|-------------|------------|---------|
+| **Autopilot** | 0 | Low | Bug fixes, minor updates |
+| **Confirm** | 1 | Medium | Standard features |
+| **Validate** | 2 | High | Security, payments, architecture |
+
+## Run Scope
+
+Run scope determines how many work items execute in a single run:
+
+| Scope | Description | Grouping |
+|-------|-------------|----------|
+| **Single** | One work item per run, most controlled | Each item in its own run |
+| **Batch** | Group items by mode, respect dependencies | Autopilot together, confirm together |
+| **Wide** | Maximum items per run, minimal interruption | All compatible items together |
+
+The system learns your preference from run history and stores it in `workspace.run_scope_preference`.
+
+## Project Structure
+
+When initialized, FIRE creates:
+
+```
+.specs-fire/
+├── state.yaml           # Central state (source of truth)
+├── intents/             # Intent briefs and work items
+│   └── {intent-id}/
+│       ├── brief.md
+│       └── work-items/
+│           └── {work-item-id}.md
+├── runs/                # Run logs and walkthroughs
+│   └── {run-id}/
+│       ├── run.md
+│       └── walkthrough.md
+└── standards/           # Project standards
+    ├── tech-stack.md
+    └── coding-standards.md
+```
+
+## Agents
+
+### Orchestrator (`/specsmd-fire`)
+
+Routes users based on project state:
+
+- New project → Initialize
+- No intent → Capture intent
+- No work items → Decompose
+- Pending work → Execute
+
+### Planner (`/specsmd-fire-planner`)
+
+Handles planning:
+
+- **intent-capture** — Capture user intent through conversation
+- **work-item-decompose** — Break intent into executable work items
+- **design-doc-generate** — Create design docs for Validate mode
+
+### Builder (`/specsmd-fire-builder`)
+
+Handles execution:
+
+- **run-execute** — Execute work items with mode-appropriate checkpoints
+- **walkthrough-generate** — Generate implementation documentation
+- **run-status** — Show current run progress
+
+## Flow Directory Structure
+
+```
+src/flows/fire/
+├── agents/
+│   ├── orchestrator/
+│   │   ├── agent.md
+│   │   └── skills/
+│   │       ├── project-init/
+│   │       ├── route/
+│   │       └── status/
+│   ├── planner/
+│   │   ├── agent.md
+│   │   └── skills/
+│   │       ├── intent-capture/
+│   │       ├── work-item-decompose/
+│   │       └── design-doc-generate/
+│   └── builder/
+│       ├── agent.md
+│       └── skills/
+│           ├── run-execute/
+│           ├── walkthrough-generate/
+│           └── run-status/
+├── commands/
+│   ├── fire.md
+│   ├── fire-planner.md
+│   └── fire-builder.md
+├── templates/
+│   ├── intents/
+│   ├── runs/
+│   └── standards/
+├── memory-bank.yaml
+└── quick-start.md
+```
+
+## Comparison with AI-DLC
+
+| Aspect | AI-DLC | FIRE |
+|--------|--------|------|
+| Hierarchy | Intent → Unit → Story | Intent → Work Item |
+| Checkpoints | 10-26 per feature | 0-2 per work item |
+| Phases | Inception → Construction → Operations | Plan → Execute |
+| Artifacts | Extensive | Minimal |
+| Best for | Large initiatives, teams | Rapid delivery, individuals |
+
+## Configuration
+
+See `memory-bank.yaml` for:
+
+- Artifact paths
+- Naming conventions
+- Execution modes
+- Agent ownership

package/flows/simple/README.md

@@ -0,0 +1,190 @@
+# Simple Flow - Spec-Driven Development
+
+A lightweight flow for creating feature specifications using spec-driven development.
+
+## What is Simple Flow?
+
+Simple Flow guides you through three phases to transform a feature idea into an actionable implementation plan:
+
+1. **Requirements** - Define what to build with user stories and EARS acceptance criteria
+2. **Design** - Create technical design with architecture, components, and data models
+3. **Tasks** - Generate implementation checklist with incremental coding tasks
+
+Each phase produces a markdown document that serves as both documentation and executable specification for AI-assisted development.
+
+## When to Use Simple Flow
+
+### Use Simple Flow when
+
+- You need quick feature specs without full methodology overhead
+- Building prototypes or small-to-medium features
+- You want structured documentation but not full AI-DLC complexity
+- Working solo or in small teams
+- Rapid iteration is more important than comprehensive process
+
+### Use AI-DLC Flow when
+
+- Building complex, multi-team features
+- You need full DDD stages and bolt management
+- Following strict AI-DLC methodology with intents/units/stories
+- Production systems requiring full traceability
+- Team coordination with formal handoffs
+
+## Quick Start
+
+### 1. Create a New Spec
+
+Invoke the spec agent with your feature idea:
+
+```text
+/specsmd-agent Create a user authentication system with email login
+```
+
+### 2. Review and Approve Requirements
+
+The agent generates a requirements document with:
+
+- Introduction summarizing the feature
+- Glossary of domain terms
+- User stories with EARS acceptance criteria
+
+Review and provide feedback, or approve to continue.
+
+### 3. Review and Approve Design
+
+After requirements approval, the agent generates:
+
+- Architecture overview with diagrams
+- Component interfaces
+- Data models with validation rules
+- Error handling strategies
+- Testing strategy
+
+Review and provide feedback, or approve to continue.
+
+### 4. Review and Approve Tasks
+
+After design approval, the agent generates:
+
+- Numbered checkbox task list
+- Incremental implementation steps
+- Requirement references for traceability
+- Checkpoint tasks for verification
+
+### 5. Execute Tasks
+
+Once all three documents are approved:
+
+```text
+/specsmd-agent --spec="user-auth" --execute
+```
+
+Or ask: "What's the next task for user-auth?"
+
+## Output Structure
+
+```text
+specs/
+└── {feature-name}/
+    ├── requirements.md    # Phase 1: What to build
+    ├── design.md          # Phase 2: How to build it
+    └── tasks.md           # Phase 3: Step-by-step plan
+```
+
+## EARS Format
+
+Requirements use EARS (Easy Approach to Requirements Syntax) patterns:
+
+| Pattern | Format | Example |
+|---------|--------|---------|
+| **Event-driven** | WHEN [trigger], THE [system] SHALL [response] | WHEN user clicks login, THE Auth_System SHALL validate credentials |
+| **State-driven** | WHILE [condition], THE [system] SHALL [response] | WHILE session is active, THE Auth_System SHALL refresh tokens |
+| **Unwanted** | IF [condition], THEN THE [system] SHALL [response] | IF password is invalid, THEN THE Auth_System SHALL display error |
+| **Optional** | WHERE [option], THE [system] SHALL [response] | WHERE MFA is enabled, THE Auth_System SHALL require second factor |
+
+## Key Principles
+
+### Generate First, Ask Later
+
+The agent generates a draft document immediately based on your feature idea. This serves as a starting point for discussion rather than requiring extensive Q&A upfront.
+
+### Explicit Approval Gates
+
+You must explicitly approve each phase before proceeding. Say "yes", "approved", or "looks good" to continue. Any feedback triggers revision.
+
+### One Phase at a Time
+
+The agent focuses on one document per interaction. This ensures thorough review and prevents overwhelming changes.
+
+### One Task at a Time
+
+During execution, only one task is implemented per interaction. This allows careful review of each change.
+
+## File Structure
+
+```text
+src/flows/simple/
+├── README.md                    # This file
+├── memory-bank.yaml             # Storage configuration
+├── context-config.yaml          # Context loading rules
+├── agents/
+│   └── agent.md                 # Agent definition
+├── commands/
+│   └── agent.md                 # Command definition
+├── skills/
+│   ├── requirements.md          # Phase 1 skill
+│   ├── design.md                # Phase 2 skill
+│   ├── tasks.md                 # Phase 3 skill
+│   └── execute.md               # Task execution skill
+└── templates/
+    ├── requirements-template.md
+    ├── design-template.md
+    └── tasks-template.md
+```
+
+## Comparison with AI-DLC
+
+| Aspect | Simple Flow | AI-DLC Flow |
+|--------|-------------|-------------|
+| **Target** | Quick feature specs | Full development lifecycle |
+| **Phases** | 3: Requirements → Design → Tasks | 3: Inception → Construction → Operations |
+| **Agents** | 1 (Agent) | 4 (Master, Inception, Construction, Operations) |
+| **Output** | 3 markdown files | Full artifact hierarchy |
+| **DDD Stages** | Not included | Full DDD stages in Construction |
+| **Bolts** | No concept | Time-boxed execution sessions |
+| **Hierarchy** | Flat (specs/) | Nested (intents/units/stories) |
+| **Overhead** | Minimal | Significant structure |
+
+## Tips for Success
+
+### Requirements Phase
+
+- Be specific about user roles and their needs
+- Include edge cases in acceptance criteria
+- Define all domain terms in the glossary
+- Aim for 3-7 requirements per feature
+
+### Design Phase
+
+- Ensure every requirement is addressed
+- Use Mermaid diagrams for architecture
+- Be explicit about error handling
+- Define validation rules for all data
+
+### Tasks Phase
+
+- Each task should be completable in one session
+- Include test tasks (mark optional with *)
+- Add checkpoint tasks to verify progress
+- Reference specific requirements for traceability
+
+### Execution Phase
+
+- Read all three spec files before starting
+- Execute tasks in order (prerequisites first)
+- Review changes after each task
+- Update task status as you complete
+
+## Attribution
+
+Simple Flow implements spec-driven development for the specsmd framework.