specsmd 0.0.0-dev.6 → 0.0.0-dev.60

package/flows/fire/memory-bank.yaml

@@ -0,0 +1,164 @@
+# FIRE Flow Configuration
+# Fast Intent-Run Engineering - Simplified AI-native development
+
+# Artifact folder (created at project initialization)
+artifact_root: ".specs-fire"
+
+# Structure created at project initialization
+structure:
+  - path: intents/
+    description: "High-level objectives that deliver user value"
+  - path: runs/
+    description: "Execution logs and walkthroughs per run"
+  - path: standards/
+    description: "Project standards (tech-stack, coding-standards, testing-standards)"
+
+# Central state file (FIRE's source of truth)
+state:
+  path: ".specs-fire/state.yaml"
+  description: "Central state tracking for all FIRE operations"
+  sections:
+    project:
+      - name: "Project name"
+      - description: "Project description"
+      - created: "ISO 8601 timestamp"
+      - framework: "fire-v1"
+    workspace:
+      - type: "greenfield | brownfield"
+      - structure: "monolith | monorepo | multi-part"
+      - autonomy_bias: "autonomous | balanced | controlled"
+      - run_scope_preference: "single | batch | wide (learned from history)"
+      - run_scope_history: "List of recent scope choices for learning"
+      - scanned_at: "ISO 8601 timestamp (brownfield)"
+      - parts: "List of project parts (monorepo)"
+    intents:
+      - id: "Intent identifier"
+      - title: "Intent title"
+      - status: "pending | in_progress | completed"
+      - work_items: "List of work items"
+    active_run:
+      - id: "Current run ID"
+      - scope: "single | batch | wide"
+      - work_items: "List of work items in this run"
+      - current_item: "Work item currently being executed"
+      - started: "ISO 8601 timestamp"
+    runs:
+      - completed: "List of completed runs with id, work_item, intent, completed timestamp"
+
+# Data Conventions
+conventions:
+  timestamps:
+    format: "ISO 8601 with time and timezone"
+    pattern: "YYYY-MM-DDTHH:MM:SSZ"
+    example: "2026-01-19T10:30:00Z"
+
+# Naming Conventions
+naming:
+  intents:
+    format: "{id}"
+    example: "user-authentication"
+    note: "Kebab-case, descriptive name"
+
+  work_items:
+    format: "{id}"
+    example: "login-endpoint"
+    note: "Kebab-case, action-oriented name"
+
+  runs:
+    format: "run-{NNN}/"
+    example: "run-001/"
+    note: "Sequential 3-digit number, folder per run"
+    contents:
+      - "plan.md"         # Approved implementation plan (confirm/validate modes)
+      - "run.md"          # Run log
+      - "test-report.md"  # Test results and coverage
+      - "walkthrough.md"  # Implementation walkthrough
+
+# Schema Definition (Source of Truth for Agents)
+schema:
+  state: ".specs-fire/state.yaml"
+  intents: ".specs-fire/intents/{intent-id}/"
+  intent-brief: ".specs-fire/intents/{intent-id}/brief.md"
+  work-items: ".specs-fire/intents/{intent-id}/work-items/"
+  work-item: ".specs-fire/intents/{intent-id}/work-items/{work-item-id}.md"
+  runs: ".specs-fire/runs/"
+  run-folder: ".specs-fire/runs/{run-id}/"
+  plan: ".specs-fire/runs/{run-id}/plan.md"
+  run-log: ".specs-fire/runs/{run-id}/run.md"
+  test-report: ".specs-fire/runs/{run-id}/test-report.md"
+  walkthrough: ".specs-fire/runs/{run-id}/walkthrough.md"
+  standards: ".specs-fire/standards/"
+  tech-stack: ".specs-fire/standards/tech-stack.md"
+  coding-standards: ".specs-fire/standards/coding-standards.md"
+  testing-standards: ".specs-fire/standards/testing-standards.md"
+  system-architecture: ".specs-fire/standards/system-architecture.md"
+
+  # Agent Ownership
+  ownership:
+    orchestrator: [state]
+    planner: [intents, work-items, state]
+    builder: [runs, state]
+
+# Execution Modes
+execution_modes:
+  autopilot:
+    checkpoints: 0
+    complexity: low
+    description: "Direct execution, walkthrough generated after"
+
+  confirm:
+    checkpoints: 1
+    complexity: medium
+    description: "Plan shown, user confirms, then execution"
+
+  validate:
+    checkpoints: 2
+    complexity: high
+    description: "Design doc review, then plan confirmation, then execution"
+
+# Work Item Complexity Mapping (default, when autonomy_bias = balanced)
+complexity_modes:
+  low: autopilot
+  medium: confirm
+  high: validate
+
+# Autonomy Bias - Shifts complexity→mode thresholds
+# User preference captured at project init, stored in workspace.autonomy_bias
+autonomy_bias:
+  autonomous:
+    description: "AI executes more freely, fewer checkpoints"
+    mapping:
+      low: autopilot
+      medium: autopilot   # shifted down
+      high: confirm       # shifted down
+  balanced:
+    description: "Standard checkpoints based on complexity"
+    mapping:
+      low: autopilot
+      medium: confirm
+      high: validate
+  controlled:
+    description: "More human oversight, more checkpoints"
+    mapping:
+      low: confirm        # shifted up
+      medium: validate    # shifted up
+      high: validate
+
+# Run Scope - How many work items to execute in a single run
+# Learned from user choices, stored in workspace.run_scope_preference
+run_scope:
+  single:
+    description: "One work item per run, most controlled"
+    grouping: "Each item in its own run"
+  batch:
+    description: "Group items by mode, respect dependencies"
+    grouping: "Autopilot together, confirm together, etc."
+  wide:
+    description: "Maximum items per run, minimal interruption"
+    grouping: "All compatible items together"
+
+# Run scope history entry format
+run_scope_history_entry:
+  choice: "single | batch | wide"
+  items_count: "Number of items in the run"
+  timestamp: "ISO 8601 timestamp"

package/flows/fire/quick-start.md

@@ -0,0 +1,130 @@
+# 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 |
+
+## 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.