specsmd 0.0.0-dev.3 → 0.0.0-dev.31

package/flows/simple/skills/tasks.md

@@ -0,0 +1,133 @@
+# Skill: Generate Tasks
+
+## Purpose
+
+Generate an implementation plan with coding tasks based on the approved design. This is Phase 3 of the spec-driven development workflow.
+
+## Preconditions
+
+- `requirements.md` exists and is approved
+- `design.md` exists and is approved
+
+## Trigger Conditions
+
+- Design phase completed and approved
+- User requests updates to existing tasks
+- User provides feedback on tasks document
+
+## Workflow
+
+### Initial Generation
+
+1. **Read both documents**:
+   - `memory-bank/specs/{feature}/requirements.md`
+   - `memory-bank/specs/{feature}/design.md`
+2. **Convert design into tasks**:
+   - Create incremental coding steps
+   - Each task builds on previous
+   - Reference specific requirements
+   - Include test tasks (mark optional with *)
+3. **Generate tasks.md** following the template:
+   - Numbered checkbox list
+   - Max 2 levels of hierarchy
+   - Requirement references for traceability
+4. **Write file** to `memory-bank/specs/{feature}/tasks.md`
+5. **Ask for approval**: "Do the tasks look good?"
+
+### Update Flow
+
+1. **Read all three** spec documents
+2. **Apply user feedback** - add, remove, or modify tasks
+3. **Write updated file**
+4. **Ask for approval again**
+
+## Critical Rules
+
+1. **CODING TASKS ONLY**
+   - Write, modify, or test code
+   - NO deployment, user testing, documentation, performance gathering
+
+2. **Requirement Traceability**
+   - Every task references requirement(s): `_Requirements: X.Y, X.Z_`
+   - Every requirement covered by at least one task
+
+3. **Incremental Progress**
+   - Tasks build on previous tasks
+   - No orphaned code that isn't integrated
+   - Include "Checkpoint" tasks every 2-3 implementation tasks
+
+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
+
+6. **Numbering Rules**
+   - Top-level tasks: `1.`, `2.`, `3.`
+   - Sub-tasks: `2.1`, `2.2`, `2.3`
+   - Maximum 2 levels (no `2.1.1`)
+   - Parent tasks with sub-tasks are GROUP HEADERS (not directly executed)
+     - Mark parent complete only when ALL sub-tasks are done
+   - Tasks without sub-tasks are directly executable
+   - Use sub-tasks when a feature has 3+ related implementation steps
+
+7. **Approval Gate**
+   - Workflow COMPLETE when tasks approved
+   - Inform user they can now execute tasks
+
+## Output
+
+- **File**: `memory-bank/specs/{feature-name}/tasks.md`
+- **Approval Prompt**: "Do the tasks look good?"
+
+## Task Types (Include)
+
+- Set up project structure
+- Create interfaces/types
+- Implement classes/modules
+- Write unit tests
+- Write integration tests
+- Wire components together
+- Checkpoint tasks (verify tests pass)
+
+## Task Types (Exclude)
+
+- User acceptance testing
+- Deployment to any environment
+- Performance metrics gathering
+- User training or documentation
+- Business process changes
+- Marketing activities
+- Running the app manually
+
+## Completion Message
+
+When tasks are approved:
+```
+The spec is complete. You now have:
+- requirements.md - What to build
+- design.md - How to build it
+- tasks.md - Step-by-step implementation plan
+
+You can start executing tasks by asking me to work on a specific task,
+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
+
+## Template Reference
+
+See `.specsmd/simple/templates/tasks-template.md` for full template structure.

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

@@ -0,0 +1,133 @@
+# Design Template
+
+Use this template when generating design.md for a feature spec.
+
+---
+
+```markdown
+# [Feature Name] Design Document
+
+## Overview
+
+[3-5 sentences describing the solution approach. Include:
+- What technology stack will be used?
+- What architectural style/pattern?
+- Key design decisions and rationale
+- How does this integrate with existing systems?]
+
+## Architecture
+
+[Include a diagram showing system components and their relationships]
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    A --> C[Component C]
+    B --> D[Data Store]
+    C --> D
+```
+
+**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"]
+
+## Components and Interfaces
+
+### [ComponentName] Class/Module
+
+[Brief description of component responsibility]
+
+**Key Methods:**
+- `methodName(param1: Type, param2: Type): ReturnType` - [Description]
+- `methodName2(): ReturnType` - [Description]
+
+### [InterfaceName] Interface
+
+```typescript
+interface InterfaceName {
+  field1: string;
+  field2: number;
+  field3: boolean;
+  method1(param: Type): ReturnType;
+}
+```
+
+### [Additional components...]
+
+## Data Models
+
+### [EntityName] Entity
+
+[Description of the entity and its role in the system]
+
+```typescript
+interface EntityName {
+  id: string;           // Unique identifier - [generation strategy]
+  field1: string;       // [Constraints: e.g., "non-empty, max 500 chars"]
+  field2: number;       // [Constraints: e.g., "positive integer"]
+  field3: boolean;      // [Default value and meaning]
+  createdAt: number;    // [Timestamp format]
+}
+```
+
+**Validation Rules:**
+- `id`: [Validation rule]
+- `field1`: [Validation rule]
+- `field2`: [Validation rule]
+
+### Storage Format
+
+[Describe how data is persisted - database schema, localStorage format, API payloads, etc.]
+
+## Error Handling
+
+### [Error Category 1]
+
+| Error Type | Condition | Recovery Strategy |
+|------------|-----------|-------------------|
+| [ErrorName] | [When it occurs] | [How to handle] |
+| [ErrorName2] | [When it occurs] | [How to handle] |
+
+### [Error Category 2]
+
+[Continue for each error category: Storage, Validation, Network, etc.]
+
+### Recovery Strategies
+
+- **Automatic Retry**: [When and how to retry]
+- **Fallback State**: [Default safe state]
+- **User Notification**: [What to tell the user]
+
+## Testing Strategy
+
+### 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]
+
+### Test Organization
+
+- Test file naming: `*.test.ts` or `*.spec.ts`
+- Location: [Co-located with source / separate test directory]
+- Framework: [Jest / Vitest / Mocha / etc.]
+
+```
+
+---
+
+## Guidelines
+
+1. **Reference requirements** - Design should address ALL requirements from Phase 1
+2. **Use Mermaid diagrams** - Visual architecture aids understanding
+3. **TypeScript-style interfaces** - Even for non-TS projects, the syntax is clear
+4. **Include validation rules** - Be explicit about data constraints
+5. **Error handling is mandatory** - Every design needs error recovery strategy
+6. **Testing is part of design** - Define testing approach upfront

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

@@ -0,0 +1,85 @@
+# Requirements Template
+
+Use this template when generating requirements.md for a feature spec.
+
+---
+
+```markdown
+# Requirements Document
+
+## Introduction
+
+[2-3 sentences summarizing the feature and its purpose. What problem does it solve? Who benefits from this feature?]
+
+## Glossary
+
+- **[System_Name]**: [Definition of the main system/component being built]
+- **[Term_1]**: [Domain-specific term definition]
+- **[Term_2]**: [Domain-specific term definition]
+- **[Term_3]**: [Domain-specific term definition]
+
+[Include 3-10 domain-specific terms that will be used consistently in acceptance criteria]
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a [role], I want [feature/capability], so that [benefit/value]
+
+#### Acceptance Criteria
+
+1. WHEN [trigger event occurs], THE [System_Name] SHALL [expected response/action]
+2. WHILE [condition is true], THE [System_Name] SHALL [continuous behavior]
+3. IF [error/unwanted condition], THEN THE [System_Name] SHALL [recovery/handling action]
+4. WHERE [optional feature is enabled], THE [System_Name] SHALL [conditional behavior]
+
+### Requirement 2
+
+**User Story:** As a [role], I want [feature/capability], so that [benefit/value]
+
+#### Acceptance Criteria
+
+1. WHEN [trigger], THE [System_Name] SHALL [response]
+2. [Additional EARS-format criteria...]
+
+### Requirement 3
+
+[Continue pattern for 3-7 total requirements]
+
+```
+
+---
+
+## EARS Format Reference
+
+EARS (Easy Approach to Requirements Syntax) patterns:
+
+| Pattern | Format | Use When |
+|---------|--------|----------|
+| **Ubiquitous** | THE [system] SHALL [response] | Always true behavior |
+| **Event-driven** | WHEN [trigger], THE [system] SHALL [response] | Response to events |
+| **State-driven** | WHILE [condition], THE [system] SHALL [response] | Behavior during state |
+| **Unwanted** | IF [condition], THEN THE [system] SHALL [response] | Error handling |
+| **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
+2. **2-5 acceptance criteria per requirement** - Not too few, not too many
+3. **Active voice** - "System SHALL display" not "Message is displayed"
+4. **No vague terms** - Avoid "quickly", "adequate", "user-friendly"
+5. **Measurable criteria** - Include specific values where possible
+6. **One thought per criterion** - Break complex behaviors into multiple criteria

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

@@ -0,0 +1,99 @@
+# Tasks Template
+
+Use this template when generating tasks.md for a feature spec.
+
+---
+
+```markdown
+# Implementation Plan
+
+- [ ] 1. Set up project structure and core interfaces
+  - Create directory structure for [components]
+  - Define core interfaces and types
+  - Set up testing framework if not present
+  - _Requirements: [X.Y]_
+
+- [ ] 2. Implement [Component Group Name]
+- [ ] 2.1 Create [specific component/module]
+  - [Implementation detail 1]
+  - [Implementation detail 2]
+  - _Requirements: [X.Y, X.Z]_
+
+- [ ]* 2.2 Write unit tests for [component]
+  - Create test file
+  - Test [specific behavior]
+  - _Requirements: [X.Y]_
+
+- [ ] 2.3 Implement [next component]
+  - [Details]
+  - _Requirements: [X.Y]_
+
+- [ ] 3. Implement [Next Component Group]
+- [ ] 3.1 Create [component]
+  - [Details]
+  - _Requirements: [X.Y]_
+
+- [ ] 3.2 Wire components together
+  - Connect [A] to [B]
+  - [Integration details]
+  - _Requirements: [X.Y, X.Z]_
+
+- [ ] 4. Checkpoint - Verify all tests pass
+  - Run test suite
+  - Address any failures before continuing
+
+- [ ] 5. [Continue with remaining components...]
+
+- [ ] N. Final Checkpoint - Ensure all tests pass
+  - Run complete test suite
+  - Verify all requirements are covered
+  - Review implementation against design
+```
+
+---
+
+## 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`)
+- Parent tasks with sub-tasks are GROUP HEADERS (not directly executed)
+  - Mark parent complete only when ALL sub-tasks are done
+- Tasks without sub-tasks are directly executable
+- 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
+
+## Guidelines
+
+1. **Coding tasks ONLY** - No deployment, user testing, documentation
+2. **Incremental progress** - Each task builds on previous
+3. **Test-driven where appropriate** - Mark test tasks with `*` if optional
+4. **Include checkpoints** - Periodic verification that tests pass
+5. **Reference requirements** - Every task traces to requirement(s)
+6. **Actionable by AI** - Tasks should be specific enough for code generation
+
+## Excluded Task Types (Do NOT include)
+
+- User acceptance testing
+- Deployment to environments
+- Performance metrics gathering
+- User training
+- Documentation creation (unless code comments)
+- Business process changes
+- Marketing activities

package/lib/analytics/tracker.js

@@ -57,7 +57,11 @@ class AnalyticsTracker {
             this.mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
                 protocol: 'https',
                 host: 'api-eu.mixpanel.com',  // EU endpoint for GDPR compliance
-                geolocate: true               // Enable IP-based geolocation
+                // Note: geolocate: true enables IP-based geolocation for analytics.
+                // This data is used solely for aggregate usage insights (e.g., country-level
+                // adoption patterns). No personal identifiers are collected. Users can
+                // opt out via the --no-telemetry flag or SPECSMD_NO_TELEMETRY env var.
+                geolocate: true
             });
 
             // Generate IDs
@@ -118,7 +122,7 @@ class AnalyticsTracker {
         if (waitForDelivery) {
             return new Promise((resolve) => {
                 try {
-                    this.mixpanel.track(eventName, eventData, (err) => {
+                    this.mixpanel.track(eventName, eventData, () => {
                         // Resolve regardless of error - silent failure
                         resolve();
                     });

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/lib/installer.js

@@ -229,6 +229,9 @@ async function installFlow(flowKey, toolKeys) {
   if (await fs.pathExists(path.join(flowPath, 'shared'))) {
     await fs.copy(path.join(flowPath, 'shared'), path.join(targetFlowDir, 'shared'));
   }
+  if (await fs.pathExists(path.join(flowPath, 'scripts'))) {
+    await fs.copy(path.join(flowPath, 'scripts'), path.join(targetFlowDir, 'scripts'));
+  }
 
   // Copy config files
   if (await fs.pathExists(path.join(flowPath, 'memory-bank.yaml'))) {
@@ -250,20 +253,6 @@ async function installFlow(flowKey, toolKeys) {
 
   CLIUtils.displayStatus('', 'Installed flow resources', 'success');
 
-  // Step 2.5: Install local scripts for deterministic operations
-  // These scripts are version-matched to the installed specsmd version
-  const scriptsDir = path.join(specsmdDir, 'scripts');
-  await fs.ensureDir(scriptsDir);
-
-  const sourceScriptsDir = path.join(__dirname, '..', 'scripts');
-  if (await fs.pathExists(sourceScriptsDir)) {
-    await fs.copy(sourceScriptsDir, scriptsDir);
-    CLIUtils.displayStatus('', 'Installed local scripts', 'success');
-  }
-
-  // Note: Scripts are invoked directly via relative path (e.g., node .specsmd/scripts/bolt-complete.js)
-  // No npm scripts added to package.json to avoid dependency on package.json for execution
-
   // NOTE: memory-bank/ is NOT created during installation
   // It will be created when user runs project-init
   // This allows us to detect if project is initialized by checking for memory-bank/standards/

package/lib/installers/KiroInstaller.js

@@ -1,5 +1,8 @@
 const ToolInstaller = require('./ToolInstaller');
 const path = require('path');
+const fs = require('fs-extra');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
 
 class KiroInstaller extends ToolInstaller {
     get key() {
@@ -17,6 +20,46 @@ class KiroInstaller extends ToolInstaller {
     get detectPath() {
         return '.kiro';
     }
+
+    /**
+     * Override to install commands and create specs symlink for simple flow
+     */
+    async installCommands(flowPath, config) {
+        // Install commands (default behavior)
+        const installedCommands = await super.installCommands(flowPath, config);
+
+        // For simple flow, create symlink to make specs visible in Kiro
+        if (flowPath.includes('simple')) {
+            await this.createSpecsSymlink();
+        }
+
+        return installedCommands;
+    }
+
+    /**
+     * Create symlink from .kiro/specs to specs/ for Kiro specifications compatibility
+     */
+    async createSpecsSymlink() {
+        const kiroSpecsPath = path.join('.kiro', 'specs');
+        const specsPath = 'specs';
+
+        // Only create if .kiro/specs doesn't exist
+        if (await fs.pathExists(kiroSpecsPath)) {
+            console.log(theme.dim(`  .kiro/specs already exists, skipping symlink`));
+            return;
+        }
+
+        // Ensure specs folder exists
+        await fs.ensureDir(specsPath);
+
+        try {
+            // Create relative symlink from .kiro/specs -> ../specs
+            await fs.ensureSymlink(path.join('..', specsPath), kiroSpecsPath);
+            CLIUtils.displayStatus('', 'Created .kiro/specs symlink for Kiro compatibility', 'success');
+        } catch (err) {
+            console.log(theme.warning(`  Failed to create specs symlink: ${err.message}`));
+        }
+    }
 }
 
 module.exports = KiroInstaller;

package/lib/installers/WindsurfInstaller.js

@@ -1,8 +1,5 @@
 const ToolInstaller = require('./ToolInstaller');
-const fs = require('fs-extra');
 const path = require('path');
-const CLIUtils = require('../cli-utils');
-const { theme } = CLIUtils;
 
 class WindsurfInstaller extends ToolInstaller {
     get key() {
@@ -20,57 +17,6 @@ class WindsurfInstaller extends ToolInstaller {
     get detectPath() {
         return '.windsurf';
     }
-
-    /**
-     * Override to add frontmatter for Windsurf workflows
-     */
-    async installCommands(flowPath, config) {
-        const targetCommandsDir = this.commandsDir;
-        console.log(theme.dim(`  Installing workflows to ${targetCommandsDir}/...`));
-        await fs.ensureDir(targetCommandsDir);
-
-        const commandsSourceDir = path.join(flowPath, 'commands');
-
-        if (!await fs.pathExists(commandsSourceDir)) {
-            console.log(theme.warning(`  No commands folder found at ${commandsSourceDir}`));
-            return [];
-        }
-
-        const commandFiles = await fs.readdir(commandsSourceDir);
-        const installedFiles = [];
-
-        for (const cmdFile of commandFiles) {
-            if (cmdFile.endsWith('.md')) {
-                const sourcePath = path.join(commandsSourceDir, cmdFile);
-                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
-
-                const targetFileName = `specsmd-${prefix}${cmdFile}`;
-                const targetPath = path.join(targetCommandsDir, targetFileName);
-
-                // Extract agent name from target filename (e.g., "specsmd-master-agent.md" -> "specsmd-master-agent")
-                const agentName = targetFileName.replace(/\.md$/, '');
-
-                // Read source content and add Windsurf frontmatter
-                let content = await fs.readFile(sourcePath, 'utf8');
-
-                // Add Windsurf-specific frontmatter if not present
-                if (!content.startsWith('---')) {
-                    const frontmatter = `---
-description: ${agentName}
----
-
-`;
-                    content = frontmatter + content;
-                }
-
-                await fs.writeFile(targetPath, content);
-                installedFiles.push(targetFileName);
-            }
-        }
-
-        CLIUtils.displayStatus('', `Installed ${installedFiles.length} workflows for ${this.name}`, 'success');
-        return installedFiles;
-    }
 }
 
 module.exports = WindsurfInstaller;

package/package.json

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