specsmd 0.0.0-dev.25 → 0.0.0-dev.26

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/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/package.json

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