specsmd 0.1.7 → 0.1.8

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

@@ -322,7 +322,7 @@ For each ADR created, add an entry to `memory-bank/standards/decision-index.md`:
 - **Read when**: {Generate guidance based on the ADR's domain - describe scenarios when agents should read this ADR}
 ```
 
-1. Update frontmatter: increment `total_decisions`, update `last_updated` timestamp
+Update frontmatter: increment `total_decisions`, update `last_updated` timestamp
 
 **"Read when" Guidance Examples**:
 

package/flows/simple/README.md

@@ -0,0 +1,190 @@
+# 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:
+
+```text
+/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:
+
+```text
+/specsmd-agent --spec="user-auth" --execute
+```
+
+Or ask: "What's the next task for user-auth?"
+
+## Output Structure
+
+```text
+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
+
+```text
+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 artifact 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,404 @@
+# 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
+
+1. **ONE task at a time**
+   - When executing tasks, do only one
+   - Stop for user review after each task
+   - Never auto-advance to next task
+
+2. **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:
+
+```text
+.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)
+```
+
+## Asking Questions
+
+When you need to ask the user a question (e.g., clarifying vague input), check for these tools:
+
+- `userInput` (Kiro)
+- `AskUserQuestionTool` (Claude Code)
+
+If either tool is available, use it to ask structured questions. If neither is available, ask directly in your response text.
+
+## 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:**
+
+```text
+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,60 @@
+# 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 `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
+
+```text
+/specsmd-agent Create a todo app with local storage
+```
+
+→ Creates new spec "todo-app", starts requirements phase
+
+```text
+/specsmd-agent --spec="todo-app"
+```
+
+→ Continues existing spec at current phase
+
+```text
+/specsmd-agent --spec="todo-app" --execute
+```
+
+→ Enter task execution mode for completed spec
+
+```text
+/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: "specs/{feature}/requirements.md"
+    tasks:
+      - path: ".specsmd/simple/skills/tasks.md"
+      - path: ".specsmd/simple/templates/tasks-template.md"
+      - path: "specs/{feature}/requirements.md"
+      - path: "specs/{feature}/design.md"
+    execute:
+      - path: ".specsmd/simple/skills/execute.md"
+      - path: "specs/{feature}/requirements.md"
+      - path: "specs/{feature}/design.md"
+      - path: "specs/{feature}/tasks.md"
+
+# Scan directories on activation
+scan:
+  - path: "specs/"
+    purpose: "Detect existing specs for state detection"