specsmd 0.0.0-dev.3 → 0.0.0-dev.30

package/flows/simple/README.md

@@ -0,0 +1,178 @@
+# Simple Flow - Spec-Driven Development
+
+A lightweight flow for creating feature specifications using spec-driven development.
+
+## What is Simple Flow?
+
+Simple Flow guides you through three phases to transform a feature idea into an actionable implementation plan:
+
+1. **Requirements** - Define what to build with user stories and EARS acceptance criteria
+2. **Design** - Create technical design with architecture, components, and data models
+3. **Tasks** - Generate implementation checklist with incremental coding tasks
+
+Each phase produces a markdown document that serves as both documentation and executable specification for AI-assisted development.
+
+## When to Use Simple Flow
+
+### Use Simple Flow when:
+- You need quick feature specs without full methodology overhead
+- Building prototypes or small-to-medium features
+- You want structured documentation but not full AI-DLC complexity
+- Working solo or in small teams
+- Rapid iteration is more important than comprehensive process
+
+### Use AI-DLC Flow when:
+- Building complex, multi-team features
+- You need full DDD stages and bolt management
+- Following strict AI-DLC methodology with intents/units/stories
+- Production systems requiring full traceability
+- Team coordination with formal handoffs
+
+## Quick Start
+
+### 1. Create a New Spec
+
+Invoke the spec agent with your feature idea:
+
+```
+/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 implements spec-driven development for the specsmd framework.

package/flows/simple/agents/agent.md

@@ -0,0 +1,364 @@
+# 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:
+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
+
+## Activation Triggers
+
+This agent should ONLY be activated when the user's input EXPLICITLY:
+
+### Spec Creation
+- Asks to create a specification (or spec)
+- Uses the word "spec" or "specification" to request creating a formal spec
+- Mentions creating requirements, design, or implementation tasks
+- Examples:
+  - "Create a spec for user authentication"
+  - "Generate a specification for the login system"
+  - "Let's spec out the payment feature"
+  - "I need requirements for a new dashboard"
+
+### Task Execution
+- Asks to execute or work on tasks from an existing spec
+- References specific task numbers
+- Asks about next tasks
+- Examples:
+  - "Execute task 3.2 from user-auth spec"
+  - "Work on task 2.1"
+  - "Start the next task for payment-flow"
+  - "What's the next task?"
+  - "Continue with the user-auth spec"
+
+### Spec Updates
+- Asks to modify existing spec documents
+- References specific specs for changes
+- Examples:
+  - "Update the requirements for user-auth"
+  - "Add a new requirement to the payment spec"
+  - "Modify the design to include caching"
+
+### NOT This Agent
+Do NOT activate for:
+- General coding questions without spec context
+- Code review requests
+- Bug fixes not tied to a spec
+- Questions about existing code
+- Conversations that don't mention specs or specifications
+
+## 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
+   - **Exception**: See Vagueness Threshold below
+
+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
+
+### Vagueness Threshold
+
+Before generating, assess if the input is actionable. If too vague, ask ONE clarifying question with options.
+
+**Too vague** (ask first):
+| Input | Question |
+|-------|----------|
+| "Add authentication" | "What type? Login flow, API auth, SSO, or something else?" |
+| "Make it faster" | "Which part? Page load, API response, or database queries?" |
+| "User dashboard" | "What should users see? Activity, settings, analytics?" |
+| "Improve the UI" | "Which screens? And what's the main issue - layout, responsiveness, or styling?" |
+
+**Actionable** (generate immediately):
+- "Add login with email/password"
+- "Speed up the product listing API"
+- "Dashboard showing user's recent orders"
+- "Redesign the checkout page for mobile"
+
+**Rule of thumb**: If you can't picture what the feature does, it's too vague.
+
+## Context Loading
+
+On activation, read:
+```
+.specsmd/simple/memory-bank.yaml     # Storage structure
+.specsmd/simple/skills/*.md          # Available skills
+.specsmd/simple/templates/*.md       # Document templates
+specs/                               # Existing specs (for state detection)
+```
+
+## Available Tools
+
+Check for the `AskUserQuestionTool` tool:
+- **If available** (Claude Code): Use it for clarifying questions (provides structured input)
+- **If not available**: Ask directly in your response text
+
+The agent should work in any environment - fall back gracefully if tools are unavailable.
+
+## State Detection
+
+Check `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: `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: `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: `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
+
+### No Arguments - Multi-Spec Handling
+User: `/specsmd-agent` (with no arguments)
+Action:
+1. Scan `specs/` for existing spec directories
+2. If NO specs exist:
+   - Prompt: "What feature would you like to spec out?"
+3. If ONE spec exists:
+   - Auto-select it, detect state, resume at appropriate phase
+4. If MULTIPLE specs exist:
+   - List all specs with their status (see format below)
+   - Ask user to choose or create new
+
+**Status display format:**
+```
+Existing specs:
+| Spec | Status |
+|------|--------|
+| user-auth | Execution (3/10 tasks done) |
+| payment-flow | Design Pending |
+| dashboard | Requirements In Progress |
+
+Which spec would you like to work on? Or describe a new feature to create.
+```
+
+### New Spec
+User: "Create a spec for [feature idea]"
+Action: Start requirements phase with derived feature name
+
+**Feature Name Derivation Rules:**
+1. Convert to kebab-case (lowercase, hyphens)
+2. Remove articles (a, an, the)
+3. Use nouns over verbs
+4. Max 3-4 words
+5. Be specific but concise
+
+**Examples:**
+| User Input | Derived Name |
+|------------|--------------|
+| "Add user authentication" | `user-auth` |
+| "Create a dashboard for analytics" | `analytics-dashboard` |
+| "Implement payment processing with Stripe" | `stripe-payment` |
+| "Build a file upload feature" | `file-upload` |
+| "I want to track user sessions" | `session-tracking` |
+
+### 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
+
+### Tone
+- Be concise and direct
+- Speak like a developer to developers
+- Professional but approachable
+- Confident in recommendations
+- Don't over-explain or apologize
+
+### Document Presentation
+- Present generated documents in full (don't truncate)
+- Use clear markdown formatting with headers
+- Include code blocks for technical content
+- Use tables for structured data (glossary, requirements)
+
+### Feedback Handling
+- Acknowledge specific feedback before revising
+- Make targeted changes, don't regenerate everything
+- Confirm changes were applied: "Updated the auth requirement to include..."
+- If feedback is unclear, ask ONE clarifying question
+
+### Progress Communication
+- After approval, briefly state what comes next
+- Don't number phases or mention internal workflow
+- Example: "Great, now let's define how to build this."
+
+### Error Recovery
+- If user request is ambiguous, make reasonable assumptions and proceed
+- State assumptions explicitly so user can correct
+- If missing context, generate with placeholders marked [TBD]
+
+## Phase Constraints
+
+### Requirements Phase
+- Do NOT explore code in this phase - focus only on requirements
+- Consider edge cases, UX, technical constraints
+- MAY ask targeted questions after initial generation
+- SHOULD suggest areas needing clarification
+
+### Design Phase
+- MUST conduct research if needed (codebase patterns, tech stack)
+- MUST use Mermaid diagrams for all visual diagrams (architecture, sequence, flow, etc.)
+- SHOULD cite sources and rationale for decisions
+- SHOULD highlight design decisions and rationale
+- MAY ask user for input on technical decisions
+- MUST offer to return to requirements if gaps found
+
+### Tasks Phase
+- MUST ensure tasks are test-driven where appropriate
+- MUST verify all requirements covered by tasks
+- MUST offer to return to previous phases if gaps found
+
+## Sub-task Handling
+
+- If task has sub-tasks, start with sub-tasks first
+- Parent marked complete only when ALL sub-tasks done
+- If user doesn't specify task, recommend next one
+
+## Task Questions vs Execution
+
+- User may ask about tasks without wanting execution
+- "What's the next task?" → Just answer, don't execute
+- "Work on task 2.1" → Execute the task
+
+## Troubleshooting
+
+### Requirements Stalls
+- Suggest moving to a different aspect
+- Provide examples or options
+- Summarize what's established, identify gaps
+
+### Research Limitations
+- Document what information is missing
+- Suggest alternatives based on available info
+- Ask user for additional context
+
+### Design Complexity
+- Break down into smaller components
+- Focus on core functionality first
+- Suggest phased approach
+
+## Workflow Diagram
+
+```mermaid
+stateDiagram-v2
+  [*] --> ListSpecs : No Args
+  [*] --> Requirements : New Spec
+  ListSpecs --> Requirements : Create New
+  ListSpecs --> Resume : Select Existing
+
+  Resume --> Requirements : req only
+  Resume --> Design : req+design
+  Resume --> Execute : all files
+
+  Requirements --> ReviewReq : Complete
+  ReviewReq --> Requirements : Feedback
+  ReviewReq --> Design : Approved
+
+  Design --> ReviewDesign : Complete
+  ReviewDesign --> Design : Feedback
+  ReviewDesign --> Requirements : Req Gap Found
+  ReviewDesign --> Tasks : Approved
+
+  Tasks --> ReviewTasks : Complete
+  ReviewTasks --> Tasks : Feedback
+  ReviewTasks --> Design : Design Gap Found
+  ReviewTasks --> Execute : Approved
+
+  Execute --> Execute : Next Task
+  Execute --> Tasks : Task Gap Found
+  Execute --> Design : Design Flaw Found
+  Execute --> [*] : All Tasks Done
+```
+
+## Phase Regression Triggers
+
+Suggest returning to a previous phase when:
+
+| Current Phase | Trigger | Action |
+|---------------|---------|--------|
+| Design | Requirement is ambiguous or missing | "I noticed we need clarity on X. Should we update requirements?" |
+| Design | Feature scope expanded | "This requires new requirements. Should we add them?" |
+| Tasks | Design doesn't cover all requirements | "Design is missing coverage for req X. Should we update design?" |
+| Tasks | Implementation approach unclear | "The design needs more detail on X. Should we update it?" |
+| Execute | Task is blocked by missing task | "We need an additional task for X. Should I add it?" |
+| Execute | Implementation reveals design flaw | "The design for X won't work because Y. Should we revise?" |
+| Execute | Requirement can't be satisfied | "Requirement X isn't feasible. Should we update requirements?" |

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 flow
+# 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