specsmd 0.0.0-dev.34 → 0.0.0-dev.35

package/flows/simple/README.md

@@ -14,14 +14,16 @@ Each phase produces a markdown document that serves as both documentation and ex
 
 ## When to Use Simple Flow
 
-### Use Simple Flow when:
+### 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:
+### 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
@@ -34,13 +36,14 @@ Each phase produces a markdown document that serves as both documentation and ex
 
 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
@@ -50,6 +53,7 @@ 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
@@ -61,6 +65,7 @@ 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
@@ -70,7 +75,7 @@ After design approval, the agent generates:
 
 Once all three documents are approved:
 
-```
+```text
 /specsmd-agent --spec="user-auth" --execute
 ```
 
@@ -78,7 +83,7 @@ Or ask: "What's the next task for user-auth?"
 
 ## Output Structure
 
-```
+```text
 specs/
 └── {feature-name}/
     ├── requirements.md    # Phase 1: What to build
@@ -100,20 +105,24 @@ Requirements use EARS (Easy Approach to Requirements Syntax) patterns:
 ## 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
@@ -149,24 +158,28 @@ src/flows/simple/
 ## 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

package/flows/simple/agents/agent.md

@@ -5,6 +5,7 @@
 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
@@ -14,6 +15,7 @@ You follow a three-phase workflow:
 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
@@ -24,6 +26,7 @@ This agent should ONLY be activated when the user's input EXPLICITLY:
   - "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
@@ -35,6 +38,7 @@ This agent should ONLY be activated when the user's input EXPLICITLY:
   - "Continue with the user-auth spec"
 
 ### Spec Updates
+
 - Asks to modify existing spec documents
 - References specific specs for changes
 - Examples:
@@ -43,7 +47,9 @@ This agent should ONLY be activated when the user's input EXPLICITLY:
   - "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
@@ -80,12 +86,12 @@ Do NOT activate for:
 
 ### Execution Rules
 
-6. **ONE task at a time**
+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
 
-7. **Always read all specs before execution**
+2. **Always read all specs before execution**
    - Requirements, design, AND tasks must be read
    - Context from all three is essential
 
@@ -94,6 +100,7 @@ Do NOT activate for:
 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?" |
@@ -102,6 +109,7 @@ Before generating, assess if the input is actionable. If too vague, ask ONE clar
 | "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"
@@ -112,7 +120,8 @@ Before generating, assess if the input is actionable. If too vague, ask ONE clar
 ## 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
@@ -142,30 +151,39 @@ Check `specs/{feature-name}/` to determine state:
 ## 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"
@@ -173,6 +191,7 @@ Recognize these as approval:
 - "good to go", "all good"
 
 Recognize these as feedback (NOT approval):
+
 - Any suggested changes
 - Questions about the document
 - "but...", "except...", "however..."
@@ -181,8 +200,10 @@ Recognize these as feedback (NOT approval):
 ## 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?"
@@ -193,7 +214,8 @@ Action:
    - Ask user to choose or create new
 
 **Status display format:**
-```
+
+```text
 Existing specs:
 | Spec | Status |
 |------|--------|
@@ -205,10 +227,12 @@ 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
@@ -216,6 +240,7 @@ Action: Start requirements phase with derived feature name
 5. Be specific but concise
 
 **Examples:**
+
 | User Input | Derived Name |
 |------------|--------------|
 | "Add user authentication" | `user-auth` |
@@ -225,20 +250,24 @@ Action: Start requirements phase with derived feature name
 | "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
@@ -246,23 +275,27 @@ Action: Load all specs, recommend or execute requested task
 - 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]
@@ -270,12 +303,14 @@ Action: Load all specs, recommend or execute requested task
 ## 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
@@ -284,6 +319,7 @@ Action: Load all specs, recommend or execute requested task
 - 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
@@ -303,16 +339,19 @@ Action: Load all specs, recommend or execute requested 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

package/flows/simple/commands/agent.md

@@ -35,22 +35,26 @@ When this command is invoked, the agent should:
 
 ## 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/quick-start.md

@@ -45,6 +45,7 @@ Open your AI coding tool and invoke the agent with your feature idea:
 ```
 
 The agent will:
+
 1. Derive a feature name (`user-auth`)
 2. Generate a requirements document
 3. Ask for your approval
@@ -52,6 +53,7 @@ The agent will:
 ### Step 2: Review Requirements
 
 The agent generates:
+
 - **Introduction** - Feature summary
 - **Glossary** - Domain terms
 - **Requirements** - User stories with EARS acceptance criteria
@@ -63,6 +65,7 @@ The agent generates:
 ### 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
@@ -72,6 +75,7 @@ After requirements approval, the agent generates:
 ### 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
@@ -147,7 +151,8 @@ Requirements use EARS (Easy Approach to Requirements Syntax):
 | **Optional** | WHERE [option], THE [system] SHALL [response] |
 
 Example:
-```
+
+```text
 WHEN user submits login form, THE Auth_System SHALL validate credentials
 IF password is invalid, THEN THE Auth_System SHALL display error message
 ```
@@ -157,15 +162,19 @@ 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.
 
 ---
@@ -183,15 +192,19 @@ During execution, only one task per interaction. Review before continuing.
 ## 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 specs/{feature-name}`
 
 ### Get help
+
 Ask the agent: `/specsmd-agent How do I add a new requirement?`
 
 ---

package/flows/simple/skills/design.md

@@ -83,10 +83,12 @@ Generate a technical design document based on approved requirements. This is Pha
 ## 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

package/flows/simple/skills/execute.md

@@ -34,9 +34,11 @@ Execute implementation tasks from an approved tasks.md file. This is the post-sp
 ### 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
 
@@ -104,7 +106,8 @@ If user asks for recommendation ("what's next?", "continue", etc.):
 ## Output
 
 After task completion:
-```
+
+```text
 Task [X.Y] complete: [Task description]
 
 Changes made:
@@ -121,7 +124,8 @@ Ready for the next task? Or would you like to review the changes first?
 ```
 
 When ALL tasks are complete:
-```
+
+```text
 All tasks complete!
 
 Summary:
@@ -137,6 +141,7 @@ The feature implementation is complete. Consider:
 ## Task Execution Checklist
 
 Before executing:
+
 - [ ] Read requirements.md
 - [ ] Read design.md
 - [ ] Read tasks.md
@@ -145,6 +150,7 @@ Before executing:
 - [ ] Review relevant design sections
 
 After executing:
+
 - [ ] Code changes complete
 - [ ] Verification passed (requirements + tests)
 - [ ] Task marked `[x]` in tasks.md
@@ -155,6 +161,7 @@ After executing:
 ## Handling Blocked Tasks
 
 If task cannot be completed:
+
 1. Do NOT mark as complete
 2. Explain the blocker
 3. Suggest resolution:
@@ -165,6 +172,7 @@ If task cannot be completed:
 ## 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:
@@ -176,6 +184,7 @@ If implementation fails twice on the same task:
 ## 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/tasks.md

@@ -108,7 +108,8 @@ Generate an implementation plan with coding tasks based on the approved design.
 ## Completion Message
 
 When tasks are approved:
-```
+
+```text
 The spec is complete. You now have:
 - requirements.md - What to build
 - design.md - How to build it
@@ -121,10 +122,12 @@ or I can recommend the next task to work on.
 ## Phase Transitions
 
 **Backward**: If user identifies gaps:
+
 - Design changes → Return to design skill
 - Requirement changes → Return to requirements skill
 
 **Forward**: On approval:
+
 - Workflow complete
 - User can now request task execution
 

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

@@ -28,6 +28,7 @@ graph TD
 ```
 
 **Key Architectural Principles:**
+
 - [Principle 1: e.g., "Single responsibility per module"]
 - [Principle 2: e.g., "Event-driven for loose coupling"]
 - [Principle 3: e.g., "Immediate persistence on state change"]
@@ -39,6 +40,7 @@ graph TD
 [Brief description of component responsibility]
 
 **Key Methods:**
+
 - `methodName(param1: Type, param2: Type): ReturnType` - [Description]
 - `methodName2(): ReturnType` - [Description]
 
@@ -72,6 +74,7 @@ interface EntityName {
 ```
 
 **Validation Rules:**
+
 - `id`: [Validation rule]
 - `field1`: [Validation rule]
 - `field2`: [Validation rule]
@@ -104,12 +107,14 @@ interface EntityName {
 ### Unit Tests
 
 [What to test at unit level]
+
 - [Component 1]: [What to verify]
 - [Component 2]: [What to verify]
 
 ### Integration Tests
 
 [What to test at integration level]
+
 - [Flow 1]: [End-to-end scenario]
 - [Flow 2]: [End-to-end scenario]
 

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

@@ -55,11 +55,13 @@ Use this template when generating tasks.md for a feature spec.
 ## Task Format Rules
 
 ### Checkbox Format
+
 - `- [ ]` - Pending task
 - `- [x]` - Completed task
 - `- [ ]*` - Optional task (nice-to-have, not blocking)
 
 ### Numbering Rules
+
 - Top-level tasks: `1.`, `2.`, `3.`
 - Sub-tasks: `2.1`, `2.2`, `2.3`
 - Maximum 2 levels (no `2.1.1`)
@@ -69,12 +71,15 @@ Use this template when generating tasks.md for a feature spec.
 - Use sub-tasks when a feature has 3+ related implementation steps
 
 ### Requirement References
+
 - Always include: `_Requirements: X.Y, X.Z_`
 - Reference specific acceptance criteria numbers
 - Every requirement should be covered by at least one task
 
 ### Task Content
+
 Each task should include:
+
 1. **Clear objective** - What to implement
 2. **Implementation details** - Sub-bullets with specifics
 3. **Requirement reference** - Traceability

package/package.json

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