specsmd 0.0.0-dev.3 → 0.0.0-dev.31

package/flows/simple/quick-start.md

@@ -0,0 +1,219 @@
+# specsmd Simple Flow Quick Start Guide
+
+Get started with spec-driven development in minutes.
+
+---
+
+## Installation
+
+```bash
+npx specsmd@latest install
+```
+
+Select **Simple** when prompted for the SDLC flow.
+
+The installer will:
+
+1. Detect available agentic coding tools (Claude Code, Cursor, etc.)
+2. Install the spec agent and skills
+3. Set up slash commands for your tools
+
+---
+
+## Three-Phase Workflow
+
+Simple Flow has three sequential phases:
+
+| Phase | Output | Purpose |
+|-------|--------|---------|
+| **Requirements** | `requirements.md` | Define what to build with user stories and EARS criteria |
+| **Design** | `design.md` | Create technical design with architecture and data models |
+| **Tasks** | `tasks.md` | Generate implementation checklist with coding tasks |
+
+One agent (`/specsmd-agent`) guides you through all phases.
+
+---
+
+## Quick Start Flow
+
+### Step 1: Create a New Spec
+
+Open your AI coding tool and invoke the agent with your feature idea:
+
+```text
+/specsmd-agent Create a user authentication system with email login
+```
+
+The agent will:
+1. Derive a feature name (`user-auth`)
+2. Generate a requirements document
+3. Ask for your approval
+
+### Step 2: Review Requirements
+
+The agent generates:
+- **Introduction** - Feature summary
+- **Glossary** - Domain terms
+- **Requirements** - User stories with EARS acceptance criteria
+
+**Approval phrases:** "yes", "approved", "looks good", "let's continue"
+
+**Feedback:** Any other response triggers revision
+
+### Step 3: Review Design
+
+After requirements approval, the agent generates:
+- **Architecture** - System overview with Mermaid diagrams
+- **Components** - Interfaces and responsibilities
+- **Data Models** - Types with validation rules
+- **Error Handling** - Strategies for edge cases
+- **Testing Strategy** - Test categories and coverage
+
+### Step 4: Review Tasks
+
+After design approval, the agent generates:
+- **Numbered checkbox list** - Incremental coding steps
+- **Requirement references** - Traceability to requirements
+- **Checkpoint tasks** - Verification points
+
+### Step 5: Execute Tasks
+
+Once all three documents are approved:
+
+```text
+/specsmd-agent What's the next task?
+```
+
+Or specify a task:
+
+```text
+/specsmd-agent Execute task 2.1 from user-auth
+```
+
+The agent executes one task at a time, then waits for your review.
+
+---
+
+## Commands Reference
+
+### Single Agent: `/specsmd-agent`
+
+| Action | Example |
+|--------|---------|
+| Create new spec | `/specsmd-agent Create a todo app with local storage` |
+| Continue existing | `/specsmd-agent` (lists specs if multiple exist) |
+| Resume specific spec | `/specsmd-agent --spec="todo-app"` |
+| Execute tasks | `/specsmd-agent What's the next task?` |
+| Execute specific task | `/specsmd-agent Execute task 3.2` |
+
+---
+
+## File Structure
+
+After creating specs, your project will have:
+
+```text
+.specsmd/
+├── manifest.yaml                 # Installation manifest
+└── simple/                       # Simple flow resources
+    ├── agents/agent.md           # Agent definition
+    ├── skills/                   # Agent skills
+    │   ├── requirements.md       # Phase 1
+    │   ├── design.md             # Phase 2
+    │   ├── tasks.md              # Phase 3
+    │   └── execute.md            # Task execution
+    ├── templates/                # Document templates
+    ├── memory-bank.yaml          # Storage schema
+    └── quick-start.md            # This file
+
+memory-bank/
+└── specs/                        # Your feature specs
+    └── {feature-name}/
+        ├── requirements.md       # What to build
+        ├── design.md             # How to build it
+        └── tasks.md              # Step-by-step plan
+```
+
+---
+
+## EARS Format
+
+Requirements use EARS (Easy Approach to Requirements Syntax):
+
+| Pattern | Format |
+|---------|--------|
+| **Event-driven** | WHEN [trigger], THE [system] SHALL [response] |
+| **State-driven** | WHILE [condition], THE [system] SHALL [response] |
+| **Unwanted** | IF [condition], THEN THE [system] SHALL [response] |
+| **Optional** | WHERE [option], THE [system] SHALL [response] |
+
+Example:
+```
+WHEN user submits login form, THE Auth_System SHALL validate credentials
+IF password is invalid, THEN THE Auth_System SHALL display error message
+```
+
+---
+
+## Key Principles
+
+### Generate First, Ask Later
+The agent generates a draft immediately. Your feedback refines it.
+
+### Explicit Approval Required
+You must explicitly approve each phase before proceeding.
+
+### One Phase at a Time
+Complete each phase before moving to the next.
+
+### One Task at a Time
+During execution, only one task per interaction. Review before continuing.
+
+---
+
+## Tips for Success
+
+1. **Be specific** - "User auth with email/password and session management" beats "Login feature"
+2. **Use the glossary** - Define domain terms for consistent language
+3. **Check INCOSE rules** - Singular, Complete, Verifiable, Unambiguous, Consistent
+4. **Include edge cases** - Error scenarios in acceptance criteria
+5. **Review checkpoints** - Verify tests pass during execution
+
+---
+
+## Troubleshooting
+
+### Agent doesn't remember context
+The agent is stateless. It reads spec files at startup. Ensure documents are saved.
+
+### Multiple specs exist
+When you run `/specsmd-agent` without arguments, it lists existing specs and asks which to work on.
+
+### Want to start over
+Delete the spec folder: `rm -rf memory-bank/specs/{feature-name}`
+
+### Get help
+Ask the agent: `/specsmd-agent How do I add a new requirement?`
+
+---
+
+## When to Use Simple Flow vs AI-DLC
+
+| Simple Flow | AI-DLC Flow |
+|-------------|-------------|
+| Quick feature specs | Full development lifecycle |
+| Solo or small team | Multi-team coordination |
+| Prototypes & MVPs | Production systems |
+| Minimal overhead | Full traceability |
+| 1 agent, 3 phases | 4 agents, full methodology |
+
+---
+
+## What's Next?
+
+1. Run `/specsmd-agent` with your feature idea
+2. Review and approve requirements → design → tasks
+3. Execute tasks one at a time
+4. Ship your feature!
+
+Happy spec-driven development!

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,181 @@
+# 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 ("what's next?", "continue", etc.):
+- Use the Task Recommendation Algorithm below
+- Present the recommended task to user for confirmation
+
+### Task Recommendation Algorithm
+
+1. Parse all tasks from tasks.md
+2. Build task list with status (complete/incomplete)
+3. For each incomplete task in order:
+   - If task has sub-tasks, check if all previous sub-tasks are complete
+   - If task has no sub-tasks, check if all previous numbered tasks are complete
+   - Skip optional tasks (`*`) unless user specifically asks
+4. Return first incomplete task with all prerequisites met
+5. If no incomplete tasks remain, announce completion (see Output section)
+
+### 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 MINIMAL code needed to satisfy the task
+   - Follow design specifications
+   - Match coding standards if defined
+4. **Verify implementation**:
+   - Check code satisfies referenced requirements
+   - Run relevant tests if they exist for this component
+   - If tests fail, fix before proceeding
+5. **Mark task complete**:
+   - Update tasks.md: `- [ ]` → `- [x]`
+   - Only mark complete AFTER verification passes
+6. **Recommend next task**:
+   - Parse remaining incomplete tasks
+   - Identify next task with all prerequisites met
+   - If no tasks remain, announce completion
+7. **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]
+
+Verification:
+- Requirements [X.Y, X.Z]: ✓ Satisfied
+- Tests: ✓ Passing (or N/A if no tests for this component)
+
+Next recommended task: [X.Z] - [Task description]
+
+Ready for the next task? Or would you like to review the changes first?
+```
+
+When ALL tasks are complete:
+```
+All tasks complete!
+
+Summary:
+- [X] tasks executed
+- All requirements covered
+- Tests passing
+
+The feature implementation is complete. Consider:
+- Manual testing of the feature
+- Code review before merging
+```
+
+## 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
+- [ ] Verification passed (requirements + tests)
+- [ ] Task marked `[x]` in tasks.md
+- [ ] Next task recommended (or completion announced)
+- [ ] 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
+
+## Handling Repeated Failures
+
+If implementation fails twice on the same task:
+1. STOP attempting the same approach
+2. Explain what has been tried and why it failed
+3. Suggest alternatives:
+   - Different implementation approach
+   - Breaking task into smaller sub-tasks
+   - Returning to design for clarification
+4. Ask user for guidance before proceeding
+
+## 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.