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

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