specsmd 0.0.0-dev.21 → 0.0.0-dev.23

package/flows/aidlc/commands/construction-agent.md

@@ -29,7 +29,7 @@ You are now the **Construction Agent** for specsmd AI-DLC.
 1. **Read Schema**: `.specsmd/aidlc/memory-bank.yaml`
 2. **Verify Unit**: Check unit exists and has completed inception
 3. **Load Bolts**: Find bolts for this unit
-4. **Determine State**: Check which bolts are planned/in-progress/completed
+4. **Determine State**: Check which bolts are planned/in-progress/complete
 5. **Present Menu or Continue**: Show status or continue active bolt
 
 ---

package/flows/aidlc/memory-bank.yaml

@@ -81,13 +81,14 @@ schema:
   story-index: "memory-bank/story-index.md"
   inception-log: "memory-bank/intents/{intent-name}/inception-log.md"
   construction-log: "memory-bank/intents/{intent-name}/units/{unit-name}/construction-log.md"
+  decision-index: "memory-bank/standards/decision-index.md"
 
   # Agent Ownership
   # Note: Both Inception and Construction can plan/create bolts
   # Inception: initial planning, Construction: replanning during execution
   ownership:
     inception: [intents, units, stories, story-index, bolts]  # Plans bolts initially
-    construction: [units, bolts]                               # Executes and can replan bolts
+    construction: [units, bolts, decision-index]               # Executes, can replan bolts, maintains decision index
     operations: [operations]
 
 # Global Story Index Options

package/flows/aidlc/skills/construction/bolt-list.md

@@ -52,7 +52,7 @@ For each bolt, determine progress:
 
 - **planned**: 0% - Not started
 - **in-progress**: `stages_completed / total_stages`
-- **completed**: 100%
+- **complete**: 100%
 - **blocked**: Show blocker reason
 
 ### 5. Display Results

package/flows/aidlc/skills/construction/bolt-status.md

@@ -81,7 +81,7 @@ Check for issues:
 - **Unit**: `{unit-name}`
 - **Intent**: `{intent-name}`
 - **Type**: {bolt-type}
-- **Status**: {planned|in-progress|completed|blocked}
+- **Status**: {planned|in-progress|complete|blocked}
 
 ### Progress
 [██████████░░░░░░░░░░] 50% (2/4 stages)

package/flows/aidlc/skills/master/analyze-context.md

@@ -53,7 +53,7 @@ For recent/active intents:
 Check `schema.bolts` directory:
 
 - Are there bolt instance files?
-- What is their status? (planned, in-progress, completed)
+- What is their status? (planned, in-progress, complete)
 - What stage are in-progress bolts at?
 
 ### 5. Determine Phase

package/flows/aidlc/templates/construction/bolt-template.md

@@ -67,7 +67,7 @@ Before creating a bolt, verify ALL required fields are present:
 | `unit` | **YES** | Parent unit ID |
 | `intent` | **YES** | Parent intent ID |
 | `type` | **YES** | Bolt type (`ddd-construction-bolt` or `simple-construction-bolt`) |
-| `status` | **YES** | Current status (`planned`, `in-progress`, `completed`, `blocked`) |
+| `status` | **YES** | Current status (`planned`, `in-progress`, `complete`, `blocked`) |
 | `stories` | **YES** | Array of story IDs included in this bolt |
 | `created` | **YES** | Creation timestamp |
 | `requires_bolts` | **YES** | Array of bolt IDs this depends on (can be empty `[]`) |
@@ -134,7 +134,7 @@ Before creating a bolt, verify ALL required fields are present:
 
 - **planned**: Bolt created, not started
 - **in-progress**: Currently being executed
-- **completed**: All stages done
+- **complete**: All stages done
 - **blocked**: Cannot proceed due to dependency
 
 ---

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt.md

@@ -272,6 +272,7 @@ Suggest an ADR when you identify:
 3 - **Identify ADR-worthy decisions**: Create decision list
 4 - **Present opportunities to user**: Get user selection
 5 - **Create ADR documents**: Generate selected ADRs
+6 - **Update decision index**: Add entries to `memory-bank/standards/decision-index.md`
 
 **Artifact**: `adr-{number}-{slug}.md` (zero or more)
 **Template**: `.specsmd/aidlc/templates/construction/bolt-types/ddd-construction-bolt/adr-template.md`
@@ -282,7 +283,8 @@ Suggest an ADR when you identify:
 1. Review stories, domain model, and technical design
 2. Compare against loaded project standards
 3. If decision-worthy patterns detected, present opportunities to user
-4. Handle user response and proceed to checkpoint
+4. Handle user response (create selected ADRs or skip)
+5. Update decision index (if ADRs created) and proceed to checkpoint
 
 **Step 3 Output Format**:
 
@@ -299,10 +301,35 @@ Would you like to create ADRs for any of these? (Enter numbers, "all", or "skip"
 
 **Step 4 Decision Handling**:
 
-- **User selects numbers or "all"** → Generate ADRs using template, then proceed to checkpoint
+- **User selects numbers or "all"** → Generate ADRs using template, then update decision index
 - **User selects "skip"** → Proceed to checkpoint with "No ADRs created"
 - **No ADR opportunities identified** → Auto-proceed to checkpoint with "No ADR-worthy decisions found"
 
+**Step 5 Decision Index Update**:
+
+For each ADR created, add an entry to `memory-bank/standards/decision-index.md`:
+
+1. If `decision-index.md` doesn't exist, create it from template: `.specsmd/aidlc/templates/standards/decision-index-template.md`
+2. Add entry for each ADR in the following format:
+
+```markdown
+### ADR-{n}: {title}
+- **Status**: {status from ADR frontmatter}
+- **Date**: {YYYY-MM-DD from ADR created timestamp}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context section}. {First sentence from Decision section}.
+- **Read when**: {Generate guidance based on the ADR's domain - describe scenarios when agents should read this ADR}
+```
+
+3. Update frontmatter: increment `total_decisions`, update `last_updated` timestamp
+
+**"Read when" Guidance Examples**:
+- "Working on authentication flows or session management"
+- "Implementing caching strategies or data persistence patterns"
+- "Designing API contracts or integration points"
+- "Handling error cases or implementing retry logic"
+
 **Example ADR**:
 
 ```markdown
@@ -330,6 +357,7 @@ Implement CQRS pattern with separate read models for task queries.
 - [ ] Project standards compared
 - [ ] User presented with ADR opportunities (if any)
 - [ ] Selected ADRs created (or explicitly skipped)
+- [ ] Decision index updated (if ADRs were created)
 
 **Important**: Do not force ADRs. Only suggest when there's genuine value. Simple bolts with straightforward decisions don't need ADRs.
 
@@ -495,6 +523,34 @@ status: in-progress
 
 ## Bolt Context Loading
 
+### Prior Decision Lookup (All Stages)
+
+**Before starting any stage**, scan the decision index for relevant prior ADRs:
+
+1. Read `memory-bank/standards/decision-index.md` (if it exists)
+2. Match the current bolt's domain/scope against "Read when" fields
+3. Load full ADRs for any matching entries
+4. Consider these decisions as constraints or guidance for the current work
+
+**Example**: If working on a bolt for "user-service" and the decision index contains:
+```
+### ADR-001: Use JWT for Authentication
+- **Read when**: Working on authentication flows or user services
+```
+→ Load and consider `ADR-001` before starting design work.
+
+**Present relevant ADRs to user** at bolt start:
+```
+## Relevant Prior Decisions
+
+Found {n} ADR(s) that may apply to this bolt:
+- ADR-001: Use JWT for Authentication → [View](bolts/001-auth-service/adr-001-jwt-auth.md)
+
+These decisions may constrain or guide your approach. Proceed? (y/n)
+```
+
+### Bolt Folder Artifacts (Stages 4-5)
+
 For stages that build on previous work (Stage 4: Implement, Stage 5: Test), load all artifacts from the bolt folder:
 
 **Location**: `memory-bank/bolts/{bolt-id}/`
@@ -515,14 +571,16 @@ This ensures the implementation and test stages have full context from earlier d
 1. **Load bolt instance** from path defined by `schema.bolts`
 2. **Read `bolt_type` field** (e.g., `ddd-construction-bolt`)
 3. **Load this definition** from `.specsmd/aidlc/templates/construction/bolt-types/`
-4. **Check `current_stage`** in bolt instance
-5. **Load bolt folder artifacts** if stage requires previous context (see Bolt Context Loading)
-6. **Execute stage** following activities defined here
-7. **Create artifacts** using templates
-8. **⛔ STOP and present completion summary** - DO NOT continue automatically
-9. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
-10. **Only after approval**: Update bolt state and advance to next stage
-
-**⛔ CRITICAL**: Steps 8-9 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
+4. **Scan decision index** for relevant prior ADRs (see Prior Decision Lookup)
+5. **Present relevant ADRs** to user if any found, get confirmation to proceed
+6. **Check `current_stage`** in bolt instance
+7. **Load bolt folder artifacts** if stage requires previous context (see Bolt Folder Artifacts)
+8. **Execute stage** following activities defined here
+9. **Create artifacts** using templates
+10. **⛔ STOP and present completion summary** - DO NOT continue automatically
+11. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
+12. **Only after approval**: Update bolt state and advance to next stage
+
+**⛔ CRITICAL**: Steps 10-11 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
 
 The Construction Agent is **bolt-type agnostic** - it reads stages from this file and executes them.

package/flows/aidlc/templates/standards/decision-index-template.md

@@ -0,0 +1,32 @@
+---
+last_updated: {YYYY-MM-DDTHH:MM:SSZ}
+total_decisions: 0
+---
+
+# Decision Index
+
+This index tracks all Architecture Decision Records (ADRs) created during Construction bolts.
+Use this to find relevant prior decisions when working on related features.
+
+## How to Use
+
+**For Agents**: Scan the "Read when" fields below to identify decisions relevant to your current task. Before implementing new features, check if existing ADRs constrain or guide your approach. Load the full ADR for matching entries.
+
+**For Humans**: Browse decisions chronologically or search for keywords. Each entry links to the full ADR with complete context, alternatives considered, and consequences.
+
+---
+
+## Decisions
+
+<!-- Entries are appended below in reverse chronological order (newest first) -->
+<!-- Format for each entry:
+
+### ADR-{n}: {title}
+- **Status**: {proposed|accepted|deprecated|superseded}
+- **Date**: {YYYY-MM-DD}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context}. {First sentence from Decision}.
+- **Read when**: {Agent guidance - domain keywords and scenarios when this ADR is relevant}
+
+-->

package/flows/simple/README.md

@@ -0,0 +1,178 @@
+# Simple Flow - Spec-Driven Development
+
+A lightweight flow for creating feature specifications, inspired by Amazon Kiro's spec-driven development approach.
+
+## 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:
+
+```
+/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:
+
+```
+/specsmd-agent --spec="user-auth" --execute
+```
+
+Or ask: "What's the next task for user-auth?"
+
+## Output Structure
+
+```
+memory-bank/
+└── 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
+
+```
+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 memory-bank 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 is inspired by [Amazon Kiro](https://kiro.dev)'s spec-driven development approach, adapted for the specsmd framework.

package/flows/simple/agents/agent.md

@@ -0,0 +1,134 @@
+# Agent
+
+## Persona
+
+You are the **Agent**, a specialist in spec-driven development. You guide users through the process of transforming feature ideas into structured specifications with requirements, design, and implementation tasks.
+
+You follow a three-phase workflow inspired by Amazon Kiro:
+1. **Requirements** - Define what to build with EARS-format acceptance criteria
+2. **Design** - Create technical design with architecture and data models
+3. **Tasks** - Generate implementation checklist with coding tasks
+
+## Critical Rules
+
+### Workflow Rules
+
+1. **Generate documents FIRST, ask questions LATER**
+   - Do NOT ask clarifying questions before generating
+   - Create a draft document as discussion starting point
+   - User feedback refines the document
+
+2. **NEVER tell the user about the internal workflow**
+   - Don't mention "Phase 1", "Phase 2", "Phase 3"
+   - Don't say "following the workflow" or similar
+   - Just naturally guide them through the process
+
+3. **Explicit approval required between phases**
+   - After each document, ask for approval
+   - Do NOT proceed without explicit "yes", "approved", "looks good"
+   - Continue feedback-revision cycle until approved
+
+4. **ONE phase at a time**
+   - Never generate multiple documents in one turn
+   - Complete each phase before moving to next
+
+5. **Track state internally**
+   - Remember which phase you're in
+   - Detect state from existing files if resuming
+
+### Execution Rules
+
+6. **ONE task at a time**
+   - When executing tasks, do only one
+   - Stop for user review after each task
+   - Never auto-advance to next task
+
+7. **Always read all specs before execution**
+   - Requirements, design, AND tasks must be read
+   - Context from all three is essential
+
+## Context Loading
+
+On activation, read:
+```
+.specsmd/simple/memory-bank.yaml     # Storage structure
+.specsmd/simple/skills/*.md          # Available skills
+.specsmd/simple/templates/*.md       # Document templates
+memory-bank/specs/                   # Existing specs (for state detection)
+```
+
+## State Detection
+
+Check `memory-bank/specs/{feature-name}/` to determine state:
+
+| Files Present | State | Action |
+|--------------|-------|--------|
+| None | NEW | Start requirements phase |
+| requirements.md only | DESIGN_PENDING | Start design phase |
+| requirements.md + design.md | TASKS_PENDING | Start tasks phase |
+| All three files | COMPLETE | Offer task execution or updates |
+
+## Skills
+
+### requirements
+Generate/update requirements document with EARS-format acceptance criteria.
+- Output: `memory-bank/specs/{feature}/requirements.md`
+- Approval prompt: "Do the requirements look good? If so, we can move on to the design."
+
+### design
+Generate/update technical design document with architecture and data models.
+- Precondition: Requirements approved
+- Output: `memory-bank/specs/{feature}/design.md`
+- Approval prompt: "Does the design look good? If so, we can move on to the implementation plan."
+
+### tasks
+Generate/update implementation task list with coding tasks.
+- Precondition: Design approved
+- Output: `memory-bank/specs/{feature}/tasks.md`
+- Approval prompt: "Do the tasks look good?"
+
+### execute
+Execute a single task from the approved tasks list.
+- Precondition: All three spec files exist
+- Output: Code changes + updated task checkbox
+
+## Approval Detection
+
+Recognize these as approval:
+- "yes", "yeah", "yep", "sure"
+- "approved", "approve"
+- "looks good", "looks great", "looks fine"
+- "let's continue", "move on", "proceed"
+- "good to go", "all good"
+
+Recognize these as feedback (NOT approval):
+- Any suggested changes
+- Questions about the document
+- "but...", "except...", "however..."
+- Requests for additions or removals
+
+## Entry Points
+
+### New Spec
+User: "Create a spec for [feature idea]"
+Action: Start requirements phase with derived feature name
+
+### Resume Spec
+User: "Continue working on [feature]" or just "/specsmd-agent"
+Action: Detect state from files, resume at appropriate phase
+
+### Update Spec
+User: "Update the requirements for [feature]"
+Action: Load existing file, apply updates, ask for approval
+
+### Execute Tasks
+User: "Start implementing [feature]" or "What's the next task?"
+Action: Load all specs, recommend or execute requested task
+
+## Response Style
+
+- Be concise and direct
+- Don't explain the methodology
+- Focus on the content, not the process
+- Ask clear approval questions
+- Provide helpful context when generating documents

package/flows/simple/commands/agent.md

@@ -0,0 +1,56 @@
+# Agent Command
+
+This file defines the agent command within the simple flow.
+
+## Command Definition
+
+```yaml
+name: agent
+description: Spec-driven development - create requirements, design, and tasks
+```
+
+## Invocation
+
+When this command is invoked, the agent should:
+
+1. **Load Context**
+   - Read `.specsmd/simple/memory-bank.yaml`
+   - Read `.specsmd/simple/agents/agent.md`
+   - Scan `memory-bank/specs/` for existing specs
+
+2. **Parse Arguments**
+   - `$ARGUMENTS` contains user input after command
+   - Extract feature idea or spec name
+   - Determine intent (create, continue, update, execute)
+
+3. **Detect State**
+   - If spec name provided, check for existing files
+   - Determine current phase based on file existence
+
+4. **Route to Skill**
+   - NEW → requirements skill
+   - DESIGN_PENDING → design skill
+   - TASKS_PENDING → tasks skill
+   - COMPLETE → execute skill or offer updates
+
+## Usage Examples
+
+```
+/specsmd-agent Create a todo app with local storage
+```
+→ Creates new spec "todo-app", starts requirements phase
+
+```
+/specsmd-agent --spec="todo-app"
+```
+→ Continues existing spec at current phase
+
+```
+/specsmd-agent --spec="todo-app" --execute
+```
+→ Enter task execution mode for completed spec
+
+```
+/specsmd-agent
+```
+→ Lists existing specs or prompts for feature idea

package/flows/simple/context-config.yaml

@@ -0,0 +1,34 @@
+# Context Configuration for Simple Flow
+# Defines what context the agent should load
+
+# Files to load on agent activation
+context:
+  always_load:
+    - path: ".specsmd/simple/memory-bank.yaml"
+      description: "Storage structure and workflow configuration"
+    - path: ".specsmd/simple/agents/agent.md"
+      description: "Agent definition and behavior rules"
+
+  load_on_phase:
+    requirements:
+      - path: ".specsmd/simple/skills/requirements.md"
+      - path: ".specsmd/simple/templates/requirements-template.md"
+    design:
+      - path: ".specsmd/simple/skills/design.md"
+      - path: ".specsmd/simple/templates/design-template.md"
+      - path: "memory-bank/specs/{feature}/requirements.md"
+    tasks:
+      - path: ".specsmd/simple/skills/tasks.md"
+      - path: ".specsmd/simple/templates/tasks-template.md"
+      - path: "memory-bank/specs/{feature}/requirements.md"
+      - path: "memory-bank/specs/{feature}/design.md"
+    execute:
+      - path: ".specsmd/simple/skills/execute.md"
+      - path: "memory-bank/specs/{feature}/requirements.md"
+      - path: "memory-bank/specs/{feature}/design.md"
+      - path: "memory-bank/specs/{feature}/tasks.md"
+
+# Scan directories on activation
+scan:
+  - path: "memory-bank/specs/"
+    purpose: "Detect existing specs for state detection"