specsmd 0.0.0-dev.22 → 0.0.0-dev.23

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"

package/flows/simple/memory-bank.yaml

@@ -0,0 +1,66 @@
+# Memory Bank Configuration for Simple Flow
+# Spec-driven development inspired by Amazon Kiro
+# Defines the directory structure for spec artifacts
+
+# Structure created at project initialization
+structure:
+  - path: specs/
+    description: "Feature specifications (requirements, design, tasks)"
+
+# Dynamic structure (created per feature)
+# - specs/{feature-name}/requirements.md   → Phase 1: Requirements
+# - specs/{feature-name}/design.md         → Phase 2: Design
+# - specs/{feature-name}/tasks.md          → Phase 3: Tasks
+
+# Naming Conventions
+naming:
+  features:
+    format: "{feature-name}"
+    example: "todo-app"
+    note: "kebab-case derived from feature idea"
+    rules:
+      - "Lowercase only"
+      - "Spaces become hyphens"
+      - "Remove special characters except hyphens"
+      - "No consecutive hyphens"
+      - "2-4 words maximum"
+
+# Schema Definition (Source of Truth for Agent)
+schema:
+  specs: "memory-bank/specs/{feature-name}/"
+  requirements: "memory-bank/specs/{feature-name}/requirements.md"
+  design: "memory-bank/specs/{feature-name}/design.md"
+  tasks: "memory-bank/specs/{feature-name}/tasks.md"
+
+# Workflow Configuration
+workflow:
+  phases:
+    - name: requirements
+      file: requirements.md
+      next: design
+      approval_prompt: "Do the requirements look good? If so, we can move on to the design."
+    - name: design
+      file: design.md
+      next: tasks
+      approval_prompt: "Does the design look good? If so, we can move on to the implementation plan."
+    - name: tasks
+      file: tasks.md
+      next: null
+      approval_prompt: "Do the tasks look good?"
+
+  # State detection rules
+  state_detection:
+    NEW: "No spec directory exists"
+    REQUIREMENTS_PENDING: "Directory exists but no requirements.md"
+    DESIGN_PENDING: "requirements.md exists but no design.md"
+    TASKS_PENDING: "design.md exists but no tasks.md"
+    COMPLETE: "All three files exist"
+    EXECUTE: "All files exist and user requests task execution"
+
+# Agent Ownership
+ownership:
+  spec-agent:
+    - specs
+    - requirements
+    - design
+    - tasks

package/flows/simple/skills/design.md

@@ -0,0 +1,94 @@
+# Skill: Generate Design
+
+## Purpose
+
+Generate a technical design document based on approved requirements. This is Phase 2 of the spec-driven development workflow.
+
+## Preconditions
+
+- `requirements.md` exists for this feature
+- User has explicitly approved the requirements
+
+## Trigger Conditions
+
+- Requirements phase completed and approved
+- User requests updates to existing design
+- User provides feedback on design document
+
+## Workflow
+
+### Initial Generation
+
+1. **Read requirements** from `memory-bank/specs/{feature}/requirements.md`
+2. **Research codebase** if needed:
+   - Identify existing patterns and conventions
+   - Check tech stack from `memory-bank/standards/` if available
+   - Look for similar implementations to reference
+3. **Generate design.md** following the template:
+   - Overview (solution approach, tech decisions)
+   - Architecture (Mermaid diagram)
+   - Components and Interfaces
+   - Data Models (with validation rules)
+   - Error Handling (recovery strategies)
+   - Testing Strategy
+4. **Write file** to `memory-bank/specs/{feature}/design.md`
+5. **Ask for approval**: "Does the design look good? If so, we can move on to the implementation plan."
+
+### Update Flow
+
+1. **Read existing** `design.md` and `requirements.md`
+2. **Apply user feedback** - modify specific sections
+3. **Write updated file**
+4. **Ask for approval again**
+
+## Critical Rules
+
+1. **Design MUST address ALL requirements**
+   - Every requirement from Phase 1 should be covered
+   - Trace design decisions back to requirements
+
+2. **Include Architecture Diagram**
+   - Use Mermaid syntax for diagrams
+   - Show component relationships and data flow
+
+3. **Define Clear Interfaces**
+   - Use TypeScript-like syntax for interface definitions
+   - Include method signatures with types
+
+4. **Error Handling is Mandatory**
+   - Define error types and conditions
+   - Specify recovery strategies
+
+5. **Approval Gate**
+   - Do NOT proceed to Tasks phase without explicit approval
+   - If gaps found, may return to Requirements phase
+
+## Output
+
+- **File**: `memory-bank/specs/{feature-name}/design.md`
+- **Approval Prompt**: "Does the design look good? If so, we can move on to the implementation plan."
+
+## Design Sections Checklist
+
+- [ ] Overview (3-5 sentences)
+- [ ] Architecture diagram (Mermaid)
+- [ ] Architectural principles (2-4 bullet points)
+- [ ] Components and interfaces (all major classes/modules)
+- [ ] Data models (with TypeScript interfaces)
+- [ ] Validation rules (per field)
+- [ ] Error handling (by category)
+- [ ] Recovery strategies
+- [ ] Testing strategy (unit + integration)
+
+## Phase Transitions
+
+**Backward**: If user identifies missing requirements:
+- "Let's go back to requirements to add [X]"
+- Return to requirements skill, update, get approval, then return here
+
+**Forward**: On explicit approval:
+- Proceed to tasks skill to generate implementation plan
+
+## Template Reference
+
+See `.specsmd/simple/templates/design-template.md` for full template structure.

package/flows/simple/skills/execute.md

@@ -0,0 +1,130 @@
+# Skill: Execute Tasks
+
+## Purpose
+
+Execute implementation tasks from an approved tasks.md file. This is the post-spec execution phase.
+
+## Preconditions
+
+- All three spec files exist:
+  - `memory-bank/specs/{feature}/requirements.md`
+  - `memory-bank/specs/{feature}/design.md`
+  - `memory-bank/specs/{feature}/tasks.md`
+- Tasks have been approved by user
+
+## Trigger Conditions
+
+- User requests to execute a specific task
+- User asks "what's next" or to continue implementation
+- User references the spec and asks to implement
+
+## Workflow
+
+### Before ANY Task Execution
+
+1. **ALWAYS read ALL three spec files**:
+   - requirements.md - Understand what to build
+   - design.md - Understand how to build it
+   - tasks.md - Understand current progress
+2. **Parse tasks.md** to identify:
+   - Completed tasks `- [x]`
+   - Pending tasks `- [ ]`
+   - Next logical task to execute
+
+### Task Selection
+
+If user specifies a task:
+- Execute that specific task
+
+If user asks for recommendation:
+- Find first unchecked task that has all prerequisites completed
+- Recommend it to user for confirmation
+
+### Task Execution
+
+1. **Read task details**:
+   - Task description and sub-bullets
+   - Requirement references
+2. **Review relevant design sections**:
+   - Components mentioned
+   - Interfaces to implement
+   - Data models involved
+3. **Implement the task**:
+   - Write/modify code as needed
+   - Follow design specifications
+   - Match coding standards if defined
+4. **Mark task complete**:
+   - Update tasks.md: `- [ ]` → `- [x]`
+5. **STOP and wait for user review**
+
+## Critical Rules
+
+1. **ONE TASK AT A TIME**
+   - Execute only the single requested task
+   - Never automatically proceed to next task
+   - Always stop for user review
+
+2. **READ ALL SPECS FIRST**
+   - Never execute without reading requirements + design + tasks
+   - Context from all three files is essential
+
+3. **VERIFY AGAINST REQUIREMENTS**
+   - Implementation must satisfy referenced requirements
+   - Check acceptance criteria are met
+
+4. **UPDATE TASK STATUS**
+   - Mark task `[x]` only when truly complete
+   - If blocked, leave unchecked and explain
+
+5. **WAIT FOR USER**
+   - After completing task, pause
+   - User decides when to continue
+   - Do NOT auto-advance
+
+## Output
+
+After task completion:
+```
+Task [X.Y] complete: [Task description]
+
+Changes made:
+- [File 1]: [What was done]
+- [File 2]: [What was done]
+
+The task satisfies requirements: [X.Y, X.Z]
+
+Ready for the next task? Or would you like to review the changes first?
+```
+
+## Task Execution Checklist
+
+Before executing:
+- [ ] Read requirements.md
+- [ ] Read design.md
+- [ ] Read tasks.md
+- [ ] Identify specific task to execute
+- [ ] Review requirement references
+- [ ] Review relevant design sections
+
+After executing:
+- [ ] Code changes complete
+- [ ] Task marked `[x]` in tasks.md
+- [ ] Summary provided to user
+- [ ] STOPPED - waiting for user
+
+## Handling Blocked Tasks
+
+If task cannot be completed:
+1. Do NOT mark as complete
+2. Explain the blocker
+3. Suggest resolution:
+   - Missing dependency → Execute prerequisite first
+   - Design gap → Return to design phase
+   - Requirement unclear → Return to requirements phase
+
+## Sub-task Handling
+
+For tasks with sub-tasks (e.g., 2.1, 2.2, 2.3):
+- Execute sub-tasks in order
+- Each sub-task is ONE execution
+- Parent task (e.g., 2.) marked complete only when all sub-tasks done

package/flows/simple/skills/requirements.md

@@ -0,0 +1,94 @@
+# Skill: Generate Requirements
+
+## Purpose
+
+Generate a requirements document for a feature using EARS (Easy Approach to Requirements Syntax) format. This is Phase 1 of the spec-driven development workflow.
+
+## Trigger Conditions
+
+- User provides a new feature idea
+- User requests updates to existing requirements
+- User provides feedback on requirements document
+
+## Workflow
+
+### Initial Generation (New Spec)
+
+1. **Parse feature idea** from user input
+2. **Derive feature name** in kebab-case (e.g., "user-authentication")
+3. **Create directory** at `memory-bank/specs/{feature-name}/`
+4. **Generate requirements.md** following the template:
+   - Introduction (2-3 sentences)
+   - Glossary (3-10 domain terms)
+   - Requirements (3-7 user stories with EARS acceptance criteria)
+5. **Write file** to `memory-bank/specs/{feature-name}/requirements.md`
+6. **Ask for approval**: "Do the requirements look good? If so, we can move on to the design."
+
+### Update Flow (Existing Spec)
+
+1. **Read existing** `requirements.md`
+2. **Apply user feedback** - modify specific sections as requested
+3. **Write updated file**
+4. **Ask for approval again**
+
+## Critical Rules
+
+1. **Generate FIRST, ask questions LATER**
+   - Do NOT ask clarifying questions before generating
+   - Create a draft document as starting point for discussion
+   - User feedback refines the document iteratively
+
+2. **EARS Format is Mandatory**
+   - Every acceptance criterion MUST use an EARS pattern
+   - Patterns: WHEN/THE SHALL, WHILE/THE SHALL, IF/THEN THE SHALL, WHERE/THE SHALL
+
+3. **Approval Gate**
+   - Do NOT proceed to Design phase without explicit approval
+   - Approval keywords: "yes", "approved", "looks good", "let's continue", "move on"
+   - Any feedback = revise and ask again
+
+4. **Glossary Consistency**
+   - Define system names and domain terms in glossary
+   - Use glossary terms consistently in acceptance criteria
+
+## Output
+
+- **File**: `memory-bank/specs/{feature-name}/requirements.md`
+- **Approval Prompt**: "Do the requirements look good? If so, we can move on to the design."
+
+## Example Generation
+
+For input: "Create a todo app with local storage"
+
+```markdown
+# Requirements Document
+
+## Introduction
+
+A simple todo application that allows users to manage their daily tasks through a clean interface. The system enables users to add, view, complete, and remove tasks while maintaining data persistence across sessions using browser local storage.
+
+## Glossary
+
+- **Todo_System**: The complete todo application including user interface and data management
+- **Task**: A single todo item with a description and completion status
+- **Task_List**: The collection of all tasks managed by the system
+- **Local_Storage**: Browser-based persistent storage mechanism
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a user, I want to add new tasks to my todo list, so that I can capture things I need to accomplish.
+
+#### Acceptance Criteria
+
+1. WHEN a user types a task description and presses Enter, THE Todo_System SHALL create a new task and add it to the Task_List
+2. WHEN a user attempts to add an empty task, THE Todo_System SHALL prevent the addition and maintain the current state
+3. WHEN a new task is added, THE Todo_System SHALL persist the task to Local_Storage immediately
+
+[... continue with more requirements ...]
+```
+
+## Template Reference
+
+See `.specsmd/simple/templates/requirements-template.md` for full template structure.

package/flows/simple/skills/tasks.md

@@ -0,0 +1,118 @@
+# Skill: Generate Tasks
+
+## Purpose
+
+Generate an implementation plan with coding tasks based on the approved design. This is Phase 3 of the spec-driven development workflow.
+
+## Preconditions
+
+- `requirements.md` exists and is approved
+- `design.md` exists and is approved
+
+## Trigger Conditions
+
+- Design phase completed and approved
+- User requests updates to existing tasks
+- User provides feedback on tasks document
+
+## Workflow
+
+### Initial Generation
+
+1. **Read both documents**:
+   - `memory-bank/specs/{feature}/requirements.md`
+   - `memory-bank/specs/{feature}/design.md`
+2. **Convert design into tasks**:
+   - Create incremental coding steps
+   - Each task builds on previous
+   - Reference specific requirements
+   - Include test tasks (mark optional with *)
+3. **Generate tasks.md** following the template:
+   - Numbered checkbox list
+   - Max 2 levels of hierarchy
+   - Requirement references for traceability
+4. **Write file** to `memory-bank/specs/{feature}/tasks.md`
+5. **Ask for approval**: "Do the tasks look good?"
+
+### Update Flow
+
+1. **Read all three** spec documents
+2. **Apply user feedback** - add, remove, or modify tasks
+3. **Write updated file**
+4. **Ask for approval again**
+
+## Critical Rules
+
+1. **CODING TASKS ONLY**
+   - Write, modify, or test code
+   - NO deployment, user testing, documentation, performance gathering
+
+2. **Requirement Traceability**
+   - Every task references requirement(s): `_Requirements: X.Y, X.Z_`
+   - Every requirement covered by at least one task
+
+3. **Incremental Progress**
+   - Tasks build on previous tasks
+   - No orphaned code that isn't integrated
+   - Include "Checkpoint" tasks to verify tests pass
+
+4. **Task Format**
+   - `- [ ]` for pending, `- [x]` for done
+   - `- [ ]*` for optional tasks
+   - Numbering: `1.`, `2.`, with sub-tasks `2.1`, `2.2`
+
+5. **Approval Gate**
+   - Workflow COMPLETE when tasks approved
+   - Inform user they can now execute tasks
+
+## Output
+
+- **File**: `memory-bank/specs/{feature-name}/tasks.md`
+- **Approval Prompt**: "Do the tasks look good?"
+
+## Task Types (Include)
+
+- Set up project structure
+- Create interfaces/types
+- Implement classes/modules
+- Write unit tests
+- Write integration tests
+- Wire components together
+- Checkpoint tasks (verify tests pass)
+
+## Task Types (Exclude)
+
+- User acceptance testing
+- Deployment to any environment
+- Performance metrics gathering
+- User training or documentation
+- Business process changes
+- Marketing activities
+- Running the app manually
+
+## Completion Message
+
+When tasks are approved:
+```
+The spec is complete. You now have:
+- requirements.md - What to build
+- design.md - How to build it
+- tasks.md - Step-by-step implementation plan
+
+You can start executing tasks by asking me to work on a specific task,
+or I can recommend the next task to work on.
+```
+
+## Phase Transitions
+
+**Backward**: If user identifies gaps:
+- Design changes → Return to design skill
+- Requirement changes → Return to requirements skill
+
+**Forward**: On approval:
+- Workflow complete
+- User can now request task execution
+
+## Template Reference
+
+See `.specsmd/simple/templates/tasks-template.md` for full template structure.

package/flows/simple/templates/design-template.md

@@ -0,0 +1,133 @@
+# Design Template
+
+Use this template when generating design.md for a feature spec.
+
+---
+
+```markdown
+# [Feature Name] Design Document
+
+## Overview
+
+[3-5 sentences describing the solution approach. Include:
+- What technology stack will be used?
+- What architectural style/pattern?
+- Key design decisions and rationale
+- How does this integrate with existing systems?]
+
+## Architecture
+
+[Include a diagram showing system components and their relationships]
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    A --> C[Component C]
+    B --> D[Data Store]
+    C --> D
+```
+
+**Key Architectural Principles:**
+- [Principle 1: e.g., "Single responsibility per module"]
+- [Principle 2: e.g., "Event-driven for loose coupling"]
+- [Principle 3: e.g., "Immediate persistence on state change"]
+
+## Components and Interfaces
+
+### [ComponentName] Class/Module
+
+[Brief description of component responsibility]
+
+**Key Methods:**
+- `methodName(param1: Type, param2: Type): ReturnType` - [Description]
+- `methodName2(): ReturnType` - [Description]
+
+### [InterfaceName] Interface
+
+```typescript
+interface InterfaceName {
+  field1: string;
+  field2: number;
+  field3: boolean;
+  method1(param: Type): ReturnType;
+}
+```
+
+### [Additional components...]
+
+## Data Models
+
+### [EntityName] Entity
+
+[Description of the entity and its role in the system]
+
+```typescript
+interface EntityName {
+  id: string;           // Unique identifier - [generation strategy]
+  field1: string;       // [Constraints: e.g., "non-empty, max 500 chars"]
+  field2: number;       // [Constraints: e.g., "positive integer"]
+  field3: boolean;      // [Default value and meaning]
+  createdAt: number;    // [Timestamp format]
+}
+```
+
+**Validation Rules:**
+- `id`: [Validation rule]
+- `field1`: [Validation rule]
+- `field2`: [Validation rule]
+
+### Storage Format
+
+[Describe how data is persisted - database schema, localStorage format, API payloads, etc.]
+
+## Error Handling
+
+### [Error Category 1]
+
+| Error Type | Condition | Recovery Strategy |
+|------------|-----------|-------------------|
+| [ErrorName] | [When it occurs] | [How to handle] |
+| [ErrorName2] | [When it occurs] | [How to handle] |
+
+### [Error Category 2]
+
+[Continue for each error category: Storage, Validation, Network, etc.]
+
+### Recovery Strategies
+
+- **Automatic Retry**: [When and how to retry]
+- **Fallback State**: [Default safe state]
+- **User Notification**: [What to tell the user]
+
+## Testing Strategy
+
+### Unit Tests
+
+[What to test at unit level]
+- [Component 1]: [What to verify]
+- [Component 2]: [What to verify]
+
+### Integration Tests
+
+[What to test at integration level]
+- [Flow 1]: [End-to-end scenario]
+- [Flow 2]: [End-to-end scenario]
+
+### Test Organization
+
+- Test file naming: `*.test.ts` or `*.spec.ts`
+- Location: [Co-located with source / separate test directory]
+- Framework: [Jest / Vitest / Mocha / etc.]
+
+```
+
+---
+
+## Guidelines
+
+1. **Reference requirements** - Design should address ALL requirements from Phase 1
+2. **Use Mermaid diagrams** - Visual architecture aids understanding
+3. **TypeScript-style interfaces** - Even for non-TS projects, the syntax is clear
+4. **Include validation rules** - Be explicit about data constraints
+5. **Error handling is mandatory** - Every design needs error recovery strategy
+6. **Testing is part of design** - Define testing approach upfront

package/flows/simple/templates/requirements-template.md

@@ -0,0 +1,73 @@
+# Requirements Template
+
+Use this template when generating requirements.md for a feature spec.
+
+---
+
+```markdown
+# Requirements Document
+
+## Introduction
+
+[2-3 sentences summarizing the feature and its purpose. What problem does it solve? Who benefits from this feature?]
+
+## Glossary
+
+- **[System_Name]**: [Definition of the main system/component being built]
+- **[Term_1]**: [Domain-specific term definition]
+- **[Term_2]**: [Domain-specific term definition]
+- **[Term_3]**: [Domain-specific term definition]
+
+[Include 3-10 domain-specific terms that will be used consistently in acceptance criteria]
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a [role], I want [feature/capability], so that [benefit/value]
+
+#### Acceptance Criteria
+
+1. WHEN [trigger event occurs], THE [System_Name] SHALL [expected response/action]
+2. WHILE [condition is true], THE [System_Name] SHALL [continuous behavior]
+3. IF [error/unwanted condition], THEN THE [System_Name] SHALL [recovery/handling action]
+4. WHERE [optional feature is enabled], THE [System_Name] SHALL [conditional behavior]
+
+### Requirement 2
+
+**User Story:** As a [role], I want [feature/capability], so that [benefit/value]
+
+#### Acceptance Criteria
+
+1. WHEN [trigger], THE [System_Name] SHALL [response]
+2. [Additional EARS-format criteria...]
+
+### Requirement 3
+
+[Continue pattern for 3-7 total requirements]
+
+```
+
+---
+
+## EARS Format Reference
+
+EARS (Easy Approach to Requirements Syntax) patterns:
+
+| Pattern | Format | Use When |
+|---------|--------|----------|
+| **Ubiquitous** | THE [system] SHALL [response] | Always true behavior |
+| **Event-driven** | WHEN [trigger], THE [system] SHALL [response] | Response to events |
+| **State-driven** | WHILE [condition], THE [system] SHALL [response] | Behavior during state |
+| **Unwanted** | IF [condition], THEN THE [system] SHALL [response] | Error handling |
+| **Optional** | WHERE [option], THE [system] SHALL [response] | Feature flags |
+| **Complex** | [WHERE] [WHILE] [WHEN/IF] THE [system] SHALL [response] | Combined conditions |
+
+## Guidelines
+
+1. **Use glossary terms consistently** - Every system/component mentioned should be defined in glossary
+2. **2-5 acceptance criteria per requirement** - Not too few, not too many
+3. **Active voice** - "System SHALL display" not "Message is displayed"
+4. **No vague terms** - Avoid "quickly", "adequate", "user-friendly"
+5. **Measurable criteria** - Include specific values where possible
+6. **One thought per criterion** - Break complex behaviors into multiple criteria

package/flows/simple/templates/tasks-template.md

@@ -0,0 +1,95 @@
+# Tasks Template
+
+Use this template when generating tasks.md for a feature spec.
+
+---
+
+```markdown
+# Implementation Plan
+
+- [ ] 1. Set up project structure and core interfaces
+  - Create directory structure for [components]
+  - Define core interfaces and types
+  - Set up testing framework if not present
+  - _Requirements: [X.Y]_
+
+- [ ] 2. Implement [Component Group Name]
+- [ ] 2.1 Create [specific component/module]
+  - [Implementation detail 1]
+  - [Implementation detail 2]
+  - _Requirements: [X.Y, X.Z]_
+
+- [ ]* 2.2 Write unit tests for [component]
+  - Create test file
+  - Test [specific behavior]
+  - _Requirements: [X.Y]_
+
+- [ ] 2.3 Implement [next component]
+  - [Details]
+  - _Requirements: [X.Y]_
+
+- [ ] 3. Implement [Next Component Group]
+- [ ] 3.1 Create [component]
+  - [Details]
+  - _Requirements: [X.Y]_
+
+- [ ] 3.2 Wire components together
+  - Connect [A] to [B]
+  - [Integration details]
+  - _Requirements: [X.Y, X.Z]_
+
+- [ ] 4. Checkpoint - Verify all tests pass
+  - Run test suite
+  - Address any failures before continuing
+
+- [ ] 5. [Continue with remaining components...]
+
+- [ ] N. Final Checkpoint - Ensure all tests pass
+  - Run complete test suite
+  - Verify all requirements are covered
+  - Review implementation against design
+```
+
+---
+
+## Task Format Rules
+
+### Checkbox Format
+- `- [ ]` - Pending task
+- `- [x]` - Completed task
+- `- [ ]*` - Optional task (nice-to-have, not blocking)
+
+### Numbering
+- Top-level: `1.`, `2.`, `3.` etc.
+- Sub-tasks: `2.1`, `2.2`, `2.3` etc.
+- Maximum 2 levels of hierarchy
+
+### Requirement References
+- Always include: `_Requirements: X.Y, X.Z_`
+- Reference specific acceptance criteria numbers
+- Every requirement should be covered by at least one task
+
+### Task Content
+Each task should include:
+1. **Clear objective** - What to implement
+2. **Implementation details** - Sub-bullets with specifics
+3. **Requirement reference** - Traceability
+
+## Guidelines
+
+1. **Coding tasks ONLY** - No deployment, user testing, documentation
+2. **Incremental progress** - Each task builds on previous
+3. **Test-driven where appropriate** - Mark test tasks with `*` if optional
+4. **Include checkpoints** - Periodic verification that tests pass
+5. **Reference requirements** - Every task traces to requirement(s)
+6. **Actionable by AI** - Tasks should be specific enough for code generation
+
+## Excluded Task Types (Do NOT include)
+
+- User acceptance testing
+- Deployment to environments
+- Performance metrics gathering
+- User training
+- Documentation creation (unless code comments)
+- Business process changes
+- Marketing activities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.22",
+  "version": "0.0.0-dev.23",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {