specsmd 0.0.0-dev.25 → 0.0.0-dev.27

package/flows/simple/agents/agent.md

@@ -150,10 +150,50 @@ Recognize these as feedback (NOT approval):
 
 ## Entry Points
 
+### No Arguments - Multi-Spec Handling
+User: `/specsmd-agent` (with no arguments)
+Action:
+1. Scan `memory-bank/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
@@ -250,15 +290,45 @@ Action: Load all specs, recommend or execute requested task
 
 ```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/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/execute.md

@@ -36,9 +36,20 @@ Execute implementation tasks from an approved tasks.md file. This is the post-sp
 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
+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
 
@@ -50,12 +61,21 @@ If user asks for recommendation:
    - Interfaces to implement
    - Data models involved
 3. **Implement the task**:
-   - Write/modify code as needed
+   - Write MINIMAL code needed to satisfy the task
    - Follow design specifications
    - Match coding standards if defined
-4. **Mark task complete**:
+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]`
-5. **STOP and wait for user review**
+   - 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
 
@@ -91,11 +111,29 @@ Changes made:
 - [File 1]: [What was done]
 - [File 2]: [What was done]
 
-The task satisfies requirements: [X.Y, X.Z]
+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:
@@ -108,7 +146,9 @@ Before executing:
 
 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
 
@@ -122,6 +162,17 @@ If task cannot be completed:
    - 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):

package/flows/simple/skills/tasks.md

@@ -54,13 +54,20 @@ Generate an implementation plan with coding tasks based on the approved design.
 3. **Incremental Progress**
    - Tasks build on previous tasks
    - No orphaned code that isn't integrated
-   - Include "Checkpoint" tasks to verify tests pass
+   - Include "Checkpoint" tasks every 2-3 implementation tasks
 
-4. **Task Format**
+4. **Checkpoint Tasks (REQUIRED)**
+   - Add checkpoint after every 2-3 implementation tasks
+   - Checkpoint MUST run the test suite
+   - If tests fail during checkpoint, fix before proceeding
+   - Checkpoints are BLOCKING (not optional) - do NOT mark with `*`
+   - Format: `- [ ] X. Checkpoint - Verify all tests pass`
+
+5. **Task Format**
    - `- [ ]` for pending, `- [x]` for done
    - `- [ ]*` for optional tasks
 
-5. **Numbering Rules**
+6. **Numbering Rules**
    - Top-level tasks: `1.`, `2.`, `3.`
    - Sub-tasks: `2.1`, `2.2`, `2.3`
    - Maximum 2 levels (no `2.1.1`)
@@ -69,7 +76,7 @@ Generate an implementation plan with coding tasks based on the approved design.
    - Tasks without sub-tasks are directly executable
    - Use sub-tasks when a feature has 3+ related implementation steps
 
-6. **Approval Gate**
+7. **Approval Gate**
    - Workflow COMPLETE when tasks approved
    - Inform user they can now execute tasks
 

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

@@ -63,6 +63,18 @@ EARS (Easy Approach to Requirements Syntax) patterns:
 | **Optional** | WHERE [option], THE [system] SHALL [response] | Feature flags |
 | **Complex** | [WHERE] [WHILE] [WHEN/IF] THE [system] SHALL [response] | Combined conditions |
 
+## INCOSE Quality Rules
+
+Before finalizing requirements, verify each criterion passes these checks:
+
+| Rule | Check | Bad Example | Good Example |
+|------|-------|-------------|--------------|
+| **Singular** | One capability per criterion (no "and") | "System SHALL log and notify" | "System SHALL log" + "System SHALL notify" |
+| **Complete** | All conditions stated | "System SHALL respond quickly" | "System SHALL respond within 200ms" |
+| **Verifiable** | Can be tested/measured | "System SHALL be user-friendly" | "System SHALL complete checkout in ≤3 clicks" |
+| **Unambiguous** | Only one interpretation | "System SHALL handle large files" | "System SHALL handle files up to 100MB" |
+| **Consistent** | No conflicts with other requirements | Req 1: "Always online" + Req 2: "Offline mode" | Reconcile or clarify conditions |
+
 ## Guidelines
 
 1. **Use glossary terms consistently** - Every system/component mentioned should be defined in glossary

package/lib/constants.js

@@ -17,12 +17,10 @@ const FLOWS = {
         description: 'AI-Driven Development Life Cycle - Best for greenfield projects with AI-native development',
         path: 'aidlc'
     },
-    agile: {
-        name: 'Agile',
-        description: 'Sprint-based Agile development - Best for iterative development with changing requirements',
-        path: 'agile',
-        disabled: true, // Not implemented yet
-        message: '(Coming soon)'
+    simple: {
+        name: 'Simple',
+        description: 'Spec-driven development - Best for quick feature specs without full methodology overhead',
+        path: 'simple'
     }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.0-dev.25",
+  "version": "0.0.0-dev.27",
   "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": {