specsmd 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,9 @@
 # specs.md
 
+<p align="center">
+  <img src="images/specs_md_pixel_logo.png" alt="specs.md logo" width="400" />
+</p>
+
 **AI-native software development with multi-agent orchestration.**
 
 specsmd implements the [AI-Driven Development Lifecycle (AI-DLC)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) methodology as a set of markdown-based agents that work with your favorite AI coding tools.
@@ -14,6 +18,22 @@ specsmd implements the [AI-Driven Development Lifecycle (AI-DLC)](https://aws.am
 
 ---
 
+## VS Code Extension
+
+Track your AI-DLC progress with our sidebar extension for VS Code and compatible IDEs.
+
+<p align="center">
+  <img src="vs-code-extension/resources/extension-preview.png" alt="VS Code Extension Preview" width="800" />
+</p>
+
+> **Note:** Works with any VS Code-based IDE including [Cursor](https://cursor.sh), [Google Antigravity](https://antigravity.google), [Windsurf](https://codeium.com/windsurf), and others.
+
+**Install from:**
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd)
+- [GitHub Releases (VSIX)](https://github.com/fabriqaai/specs.md/releases)
+
+---
+
 ## Quick Start
 
 ### Prerequisites

package/flows/aidlc/skills/construction/bolt-list.md

@@ -73,20 +73,20 @@ Sort bolts by:
 
 ### Active Bolts
 
-- ⏳ **bolt-auth-2** (auth-service, {bolt-type}) - Stage: {current-stage}, 2/4 (50%) ← working
+- ⏳ **002-auth-service** (auth-service, {bolt-type}) - Stage: {current-stage}, 2/4 (50%) ← working
 
 ### Planned Bolts
 
-- [ ] **bolt-auth-3** (auth-service) - Stories: 005-*, 006-* - Ready ✅
-- [ ] **bolt-payments-1** (payment-api) - Stories: 001-*, 002-*, 003-* - Ready ✅
+- [ ] **003-auth-service** (auth-service) - Stories: 005-*, 006-* - Ready ✅
+- [ ] **004-payment-api** (payment-api) - Stories: 001-*, 002-*, 003-* - Ready ✅
 
 ### Blocked Bolts
 
-- 🚫 **bolt-api-1** - Waiting for auth (since 2024-12-04)
+- 🚫 **005-api-gateway** - Waiting for auth (since 2024-12-04)
 
 ### Completed Bolts
 
-- ✅ **bolt-auth-1** (auth-service) - Completed 2024-12-05 (4 hours)
+- ✅ **001-auth-service** (auth-service) - Completed 2024-12-05 (4 hours)
 
 ### Summary
 - **Total**: {n} bolts
@@ -97,8 +97,8 @@ Sort bolts by:
 
 ### Actions
 
-1 - **Continue active bolt**: Resume `bolt-auth-2`
-2 - **Start planned bolt**: Begin `bolt-auth-3`
+1 - **Continue active bolt**: Resume `002-auth-service`
+2 - **Start planned bolt**: Begin `003-auth-service`
 3 - **View bolt status**: Check detailed status
 4 - **Plan new bolts**: Create additional bolts
 
@@ -112,14 +112,14 @@ Sort bolts by:
 ```markdown
 ## Bolts for Unit: {unit-name}
 
-- ✅ **bolt-{unit}-1** ({bolt-type}) - Completed 100% - Stories: 001-*, 002-*
-- ⏳ **bolt-{unit}-2** ({bolt-type}) - In progress 50% - Stories: 003-*, 004-* ← current
-- [ ] **bolt-{unit}-3** ({bolt-type}) - Planned 0% - Stories: 005-*
+- ✅ **001-{unit-name}** ({bolt-type}) - Completed 100% - Stories: 001-*, 002-*
+- ⏳ **002-{unit-name}** ({bolt-type}) - In progress 50% - Stories: 003-*, 004-* ← current
+- [ ] **003-{unit-name}** ({bolt-type}) - Planned 0% - Stories: 005-*
 
 ### Quick Actions
 
-1 - **Continue bolt-{unit}-2**: Resume current work
-2 - **View bolt-{unit}-1 status**: Review completed bolt
+1 - **Continue 002-{unit-name}**: Resume current work
+2 - **View 001-{unit-name} status**: Review completed bolt
 
 **Type a number to continue.**
 ```
@@ -133,8 +133,8 @@ Sort bolts by:
 ```text
 ### Available Bolts
 
-1 - bolt-{unit}-1 (planned) - Stories: 001-*, 002-*
-2 - bolt-{unit}-2 (planned) - Stories: 003-*, 004-*
+1 - 001-{unit-name} (planned) - Stories: 001-*, 002-*
+2 - 002-{unit-name} (planned) - Stories: 003-*, 004-*
 
 Which bolt would you like to work on?
 ```

package/flows/aidlc/skills/construction/bolt-replan.md

@@ -33,9 +33,9 @@ Replan bolts during Construction phase - add new bolts, split existing ones, or
 ```markdown
 ## Current Bolt Status: {unit-name}
 
-- ✅ **bolt-auth-service-1** ({bolt-type}): 001-user-signup, 002-user-login - completed - No dependencies
-- ⏳ **bolt-auth-service-2** ({bolt-type}): 003-password-reset, 004-email-verify - in-progress - requires bolt-1
-- [ ] **bolt-auth-service-3** ({bolt-type}): 005-mfa-setup - planned - requires bolt-2
+- ✅ **001-auth-service** ({bolt-type}): 001-user-signup, 002-user-login - completed - No dependencies
+- ⏳ **002-auth-service** ({bolt-type}): 003-password-reset, 004-email-verify - in-progress - requires 001-auth-service
+- [ ] **003-auth-service** ({bolt-type}): 005-mfa-setup - planned - requires 002-auth-service
 
 ### Summary
 
@@ -86,8 +86,10 @@ Select an option (1-4):
    ```
 
 2. **Determine next bolt ID**:
-   - Read existing bolts, find highest sequence number
-   - Next bolt: `bolt-{unit}-{N+1}`
+   - List all directories in `memory-bank/bolts/`
+   - Extract the 3-digit prefix from each (e.g., `015` from `015-auth-service`)
+   - Find the highest number
+   - Next bolt: `{next-BBB}-{unit-name}` (e.g., if highest is `015`, next is `016-auth-service`)
 
 3. **Create new bolt(s)**:
    - Use template: `.specsmd/aidlc/templates/construction/bolt-template.md`
@@ -103,12 +105,12 @@ Select an option (1-4):
 
    Created 1 new bolt:
 
-   - [ ] **bolt-auth-service-4** ({bolt-type}): 006-session-mgmt, 007-api-keys - requires bolt-3
+   - [ ] **004-auth-service** ({bolt-type}): 006-session-mgmt, 007-api-keys - requires 003-auth-service
 
    Updated dependency graph:
-   bolt-1 → bolt-2 → bolt-3 → bolt-4 (NEW)
+   001-auth-service → 002-auth-service → 003-auth-service → 004-auth-service (NEW)
 
-   File created: `memory-bank/bolts/bolt-auth-service-4.md`
+   File created: `memory-bank/bolts/004-auth-service/bolt.md`
    ```
 
 ---
@@ -136,8 +138,8 @@ Select an option (1-4):
 
    Splittable bolts (planned or in-progress):
 
-   - ⏳ **bolt-auth-service-2** ({bolt-type}): 003-password-reset, 004-email-verify, 005-mfa-setup - in-progress - ⚠️ Confirm to split
-   - [ ] **bolt-auth-service-3** ({bolt-type}): 006-session-mgmt, 007-api-keys, 008-rate-limit - planned - ✅ Can split
+   - ⏳ **002-auth-service** ({bolt-type}): 003-password-reset, 004-email-verify, 005-mfa-setup - in-progress - ⚠️ Confirm to split
+   - [ ] **003-auth-service** ({bolt-type}): 006-session-mgmt, 007-api-keys, 008-rate-limit - planned - ✅ Can split
 
    Enter bolt ID to split:
    ```
@@ -145,21 +147,21 @@ Select an option (1-4):
 2. **Propose split**:
 
    ```markdown
-   ## Split Proposal: bolt-auth-service-3
+   ## Split Proposal: 003-auth-service
 
    Current: 3 stories (006-session-mgmt, 007-api-keys, 008-rate-limit)
 
    Proposed split:
 
-   - **bolt-auth-service-3a**: 006-session-mgmt - Core feature
-   - **bolt-auth-service-3b**: 007-api-keys, 008-rate-limit - Related edge cases
+   - **003-auth-service**: 006-session-mgmt - Core feature
+   - **004-auth-service**: 007-api-keys, 008-rate-limit - Related edge cases
 
    Accept this split? (yes/no/customize)
    ```
 
 3. **Execute split**:
    - Archive or update original bolt file
-   - Create new bolt files with `3a`, `3b` suffixes (or next sequence)
+   - Create new bolt files with next sequence number
    - Update dependencies on dependent bolts
    - Update `enables_bolts` on prerequisite bolts
 
@@ -168,17 +170,17 @@ Select an option (1-4):
    ```markdown
    ## Bolt Split Complete
 
-   Original: bolt-auth-service-3 (archived)
+   Original: 003-auth-service (updated)
 
    Created:
 
-   - [ ] **bolt-auth-service-3** ({bolt-type}): 006-session-mgmt - requires bolt-2
-   - [ ] **bolt-auth-service-4** ({bolt-type}): 007-api-keys, 008-rate-limit - requires bolt-3
+   - [ ] **003-auth-service** ({bolt-type}): 006-session-mgmt - requires 002-auth-service
+   - [ ] **004-auth-service** ({bolt-type}): 007-api-keys, 008-rate-limit - requires 003-auth-service
 
    Updated files:
-   - `memory-bank/bolts/bolt-auth-service-3.md` (updated)
-   - `memory-bank/bolts/bolt-auth-service-4.md` (created)
-   - `memory-bank/bolts/bolt-auth-service-2.md` (updated enables_bolts)
+   - `memory-bank/bolts/003-auth-service/bolt.md` (updated)
+   - `memory-bank/bolts/004-auth-service/bolt.md` (created)
+   - `memory-bank/bolts/002-auth-service/bolt.md` (updated enables_bolts)
    ```
 
 ---
@@ -204,21 +206,21 @@ Select an option (1-4):
    ```markdown
    ## Current Execution Order
 
-   bolt-1 (completed) → bolt-2 (in-progress) → bolt-3 (planned) → bolt-4 (planned)
+   001-auth-service (completed) → 002-auth-service (in-progress) → 003-auth-service (planned) → 004-auth-service (planned)
 
-   - 1 - **bolt-auth-service-1**: completed - ❌ Cannot move
-   - 2 - **bolt-auth-service-2**: in-progress - ⚠️ Will pause if moved
-   - 3 - **bolt-auth-service-3**: planned - ✅ Can move
-   - 4 - **bolt-auth-service-4**: planned - ✅ Can move
+   - 1 - **001-auth-service**: completed - ❌ Cannot move
+   - 2 - **002-auth-service**: in-progress - ⚠️ Will pause if moved
+   - 3 - **003-auth-service**: planned - ✅ Can move
+   - 4 - **004-auth-service**: planned - ✅ Can move
    ```
 
 2. **Get new order**:
 
    ```markdown
    Enter new order for planned bolts (comma-separated IDs):
-   Example: bolt-auth-service-4, bolt-auth-service-3
+   Example: 004-auth-service, 003-auth-service
 
-   This will execute bolt-4 before bolt-3.
+   This will execute 004-auth-service before 003-auth-service.
    ```
 
 3. **Validate dependencies**:
@@ -236,11 +238,11 @@ Select an option (1-4):
 
    New execution order:
 
-   bolt-1 (completed) → bolt-2 (in-progress) → bolt-4 (planned) → bolt-3 (planned)
+   001-auth-service (completed) → 002-auth-service (in-progress) → 004-auth-service (planned) → 003-auth-service (planned)
 
    Updated files:
-   - `memory-bank/bolts/bolt-auth-service-3.md` (requires_bolts updated)
-   - `memory-bank/bolts/bolt-auth-service-4.md` (requires_bolts updated)
+   - `memory-bank/bolts/003-auth-service/bolt.md` (requires_bolts updated)
+   - `memory-bank/bolts/004-auth-service/bolt.md` (requires_bolts updated)
    ```
 
 ---
@@ -253,10 +255,10 @@ When modifying bolts, always update dependencies:
 
 ```yaml
 ---
-id: bolt-auth-service-3
+id: 003-auth-service
 type: ddd-construction-bolt
-requires_bolts: [bolt-auth-service-2]
-enables_bolts: [bolt-auth-service-4]
+requires_bolts: [002-auth-service]
+enables_bolts: [004-auth-service]
 requires_units: []
 complexity:
   avg_complexity: 2
@@ -314,12 +316,12 @@ Update Current Bolt Structure to reflect changes.
 
 ### Example
 
-After splitting bolt-2:
+After splitting 002-auth-service:
 
 ```markdown
 ## Replanning History
 
-- **2025-12-07**: split - bolt-2 → bolt-2, bolt-3 - Scope too large - ✅ Approved
+- **2025-12-07**: split - 002-auth-service → 002-auth-service, 003-auth-service - Scope too large - ✅ Approved
 ```
 
 ---

package/flows/aidlc/skills/construction/bolt-start.md

@@ -255,7 +255,7 @@ Status changes cascade upward: Bolt → Story → Unit → Intent.
 **On Bolt Completion** (after updating stories):
 
 1. **Check Unit Completion**:
-   - Find all bolts for this unit: `memory-bank/bolts/bolt-{unit}-*/bolt.md`
+   - Find all bolts for this unit: scan `memory-bank/bolts/*/bolt.md` and match `unit: {unit-name}` in frontmatter
    - If ALL bolts have `status: complete` → update unit-brief to `status: complete`
 
 2. **Check Intent Completion**:
@@ -270,13 +270,13 @@ Unit:    draft → stories-defined → in-progress → complete
 Story:   draft → in-progress → complete
 ```
 
-**Example** (bolt-artifact-parser-1 completes):
+**Example** (001-artifact-parser completes):
 
 ```text
 1. Stories updated: 001, 002, 003, 004 → complete
 2. Check unit bolts:
-   - bolt-artifact-parser-1: complete ✓
-   - bolt-artifact-parser-2: planned ✗
+   - 001-artifact-parser: complete ✓
+   - 005-artifact-parser: planned ✗
    → Unit stays in-progress (not all bolts complete)
 3. Intent stays construction (unit not complete)
 ```
@@ -286,7 +286,7 @@ Story:   draft → in-progress → complete
 ```text
 1. Stories updated: 001, 002 → complete
 2. Check unit bolts:
-   - bolt-file-watcher-1: complete ✓
+   - 003-file-watcher: complete ✓
    → Only bolt for unit, all complete!
    → Update unit-brief: status: complete
 3. Check intent units:

package/flows/aidlc/skills/construction/navigator.md

@@ -134,18 +134,18 @@ When user selects an option:
 
 ### Available Bolts
 
-- [ ] `bolt-auth-1` (auth-service, DDD) - planned
-- [ ] `bolt-auth-2` (auth-service, DDD) - planned
-- [ ] `bolt-api-1` (api-gateway, Simple) - planned
+- [ ] `001-auth-service` (auth-service, DDD) - planned
+- [ ] `002-auth-service` (auth-service, DDD) - planned
+- [ ] `003-api-gateway` (api-gateway, Simple) - planned
 
 ### Quick Actions
 
-1 - **Start bolt-auth-1**: Begin first bolt
+1 - **Start 001-auth-service**: Begin first bolt
 2 - **List all bolts**: View with details
 3 - **View bolt status**: Check specific bolt
 
 ### Suggested Next Step
-→ Start construction with `bolt-auth-1`
+→ Start construction with `001-auth-service`
 
 **Type a number or enter a bolt ID.**
 ```
@@ -161,8 +161,8 @@ When user selects an option:
 
 All {n} bolts have been completed:
 
-- ✅ `bolt-{unit}-1` - Completed 2024-12-05 (3h)
-- ✅ `bolt-{unit}-2` - Completed 2024-12-06 (4h)
+- ✅ `001-{unit-name}` - Completed 2024-12-05 (3h)
+- ✅ `005-{unit-name}` - Completed 2024-12-06 (4h)
 
 ### Summary
 - Stories delivered: {n}

package/flows/aidlc/skills/inception/bolt-plan.md

@@ -190,35 +190,51 @@ Establish execution order based on dependencies:
 1. **Read Path**: Check `schema.bolts` from `.specsmd/aidlc/memory-bank.yaml`
    *(Default: `memory-bank/bolts/{bolt-id}/`)*
 
-2. **Create Directory + File Per Bolt**:
+2. **Determine Bolt ID**:
+   - List all directories in `memory-bank/bolts/`
+   - Extract the 3-digit prefix from each (e.g., `015` from `015-auth-service`)
+   - Find the highest number
+   - Next bolt uses the next available number (e.g., if highest is `015`, next is `016`)
+
+   **⚠️ CRITICAL**: The `{BBB}` prefix is a **GLOBAL** sequence across ALL bolts in `memory-bank/bolts/`, NOT per-unit.
+
+3. **Create Directory + File Per Bolt**:
    For EACH bolt in the plan:
-   - Create directory: `memory-bank/bolts/bolt-{unit}-{N}/`
-   - Create file inside: `memory-bank/bolts/bolt-{unit}-{N}/bolt.md`
+   - Create directory: `memory-bank/bolts/{BBB}-{unit-name}/`
+   - Create file inside: `memory-bank/bolts/{BBB}-{unit-name}/bolt.md`
    - Use template: `.specsmd/aidlc/templates/construction/bolt-template.md`
 
-   **Example**: If planning 3 bolts for auth unit, CREATE THESE:
+   **Naming Convention** (from `memory-bank.yaml`):
+   - Format: `{BBB}-{unit-name}/` where BBB is a **GLOBAL** 3-digit sequence
+   - The number is global across ALL bolts in `memory-bank/bolts/` (not per-unit)
+   - Example sequence: `001-auth-service/`, `002-auth-service/`, `003-payment-service/`, `004-auth-service/`
+
+   **Example**: Planning bolts across multiple units (global numbering):
 
    ```text
-   memory-bank/bolts/bolt-auth-1/bolt.md  ← CREATE THIS DIRECTORY AND FILE
-   memory-bank/bolts/bolt-auth-2/bolt.md  ← CREATE THIS DIRECTORY AND FILE
-   memory-bank/bolts/bolt-auth-3/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+   memory-bank/bolts/
+   ├── 001-auth-service/bolt.md     ← First bolt ever created
+   ├── 002-auth-service/bolt.md     ← Second bolt (same unit, continues sequence)
+   ├── 003-payment-service/bolt.md  ← Third bolt (different unit)
+   ├── 004-auth-service/bolt.md     ← Fourth bolt (back to auth-service)
+   └── 005-api-gateway/bolt.md      ← Fifth bolt (another unit)
    ```
 
    **Stage artifacts will be added to same directory during construction:**
 
    ```text
-   memory-bank/bolts/bolt-auth-1/
+   memory-bank/bolts/001-auth-service/
    ├── bolt.md                      ← You create this now
    └── {stage-artifacts}            ← Created during construction (varies by bolt type)
    ```
 
    *Note: Artifact names depend on bolt type (e.g., DDD bolts create `ddd-01-domain-model.md`, simple bolts create `implementation-plan.md`).*
 
-3. **Bolt File Structure** (CRITICAL: Include all dependencies in frontmatter):
+4. **Bolt File Structure** (CRITICAL: Include all dependencies in frontmatter):
 
    ```markdown
    ---
-   id: bolt-{unit}-{sequence}
+   id: {BBB}-{unit-name}
    unit: {unit-name}
    intent: {intent-name}
    type: {bolt-type}  # From unit-brief.md or default (ddd-construction-bolt, simple-construction-bolt)
@@ -227,8 +243,8 @@ Establish execution order based on dependencies:
    created: {date}
 
    # Dependency Tracking (REQUIRED)
-   requires_bolts: [bolt-auth-1]           # Bolts that must complete first
-   enables_bolts: [bolt-auth-3, bolt-api-1] # Bolts that depend on this
+   requires_bolts: [001-auth-service]       # Bolts that must complete first
+   enables_bolts: [003-auth-service, 001-api-service] # Bolts that depend on this
    requires_units: [auth-service]           # Units that must be complete
    blocks: false                            # true if waiting on dependency
 
@@ -240,7 +256,7 @@ Establish execution order based on dependencies:
      testing_scope: 2         # 1=Unit, 2=Integration, 3=E2E
    ---
 
-   ## Bolt: {bolt-id}
+   ## Bolt: {BBB}-{unit-name}
 
    ### Objective
    {What this bolt will accomplish}
@@ -257,19 +273,19 @@ Establish execution order based on dependencies:
 
    #### Bolt Dependencies (within intent)
 
-   - **bolt-auth-1** (Required): Completed
-   - **bolt-auth-2** (Optional): In Progress
+   - **001-auth-service** (Required): Completed
+   - **002-auth-service** (Optional): In Progress
 
    #### Unit Dependencies (cross-unit)
 
    - **auth-service**: Needs auth tokens - Completed
 
    #### Enables (other bolts waiting on this)
-   - bolt-auth-3
-   - bolt-api-1
+   - 003-auth-service
+   - 001-api-service
    ```
 
-### 8. Validate Plan
+### 9. Validate Plan
 
 Check the plan against:
 
@@ -291,16 +307,20 @@ Check the plan against:
 **⚠️ YOU MUST CREATE THESE DIRECTORIES AND FILES:**
 
 ```text
-memory-bank/bolts/bolt-{unit}-1/bolt.md  ← CREATE THIS DIRECTORY AND FILE
-memory-bank/bolts/bolt-{unit}-2/bolt.md  ← CREATE THIS DIRECTORY AND FILE
-memory-bank/bolts/bolt-{unit}-3/bolt.md  ← CREATE THIS DIRECTORY AND FILE
+memory-bank/bolts/{BBB}-{unit-name}/bolt.md  ← CREATE THIS DIRECTORY AND FILE
 ```
 
+**Naming Convention** (from `memory-bank.yaml`):
+
+- Format: `{BBB}-{unit-name}/` where BBB is a global 3-digit sequence
+- Example: `001-auth-service/`, `002-auth-service/`, `016-analytics-tracker/`
+
 **⚠️ DO NOT CREATE:**
 
 - `bolt-plan.md` (summary doc)
 - `README.md` files
-- Flat files like `bolt-{unit}-1.md`
+- Flat files like `001-auth-service.md` (must be in directory)
+- Old format like `bolt-{unit}-1/` (incorrect)
 
 ### Summary (displayed to user)
 
@@ -309,17 +329,17 @@ memory-bank/bolts/bolt-{unit}-3/bolt.md  ← CREATE THIS DIRECTORY AND FILE
 
 ### Bolts Created
 
-- [ ] **bolt-{unit}-1** ({bolt-type}): 001-user-signup, 002-user-login
-- [ ] **bolt-{unit}-2** ({bolt-type}): 003-password-reset, 004-email-verify
-- [ ] **bolt-{unit}-3** ({bolt-type}): 005-mfa-setup
+- [ ] **001-auth-service** ({bolt-type}): 001-user-signup, 002-user-login
+- [ ] **002-auth-service** ({bolt-type}): 003-password-reset, 004-email-verify
+- [ ] **003-auth-service** ({bolt-type}): 005-mfa-setup
 
 ### Dependency Graph
-bolt-{unit}-1 ──► bolt-{unit}-2 ──► bolt-{unit}-3
+001-auth-service ──► 002-auth-service ──► 003-auth-service
 
 ### Directories Created
-✅ `memory-bank/bolts/bolt-{unit}-1/bolt.md`
-✅ `memory-bank/bolts/bolt-{unit}-2/bolt.md`
-✅ `memory-bank/bolts/bolt-{unit}-3/bolt.md`
+✅ `memory-bank/bolts/001-auth-service/bolt.md`
+✅ `memory-bank/bolts/002-auth-service/bolt.md`
+✅ `memory-bank/bolts/003-auth-service/bolt.md`
 
 ### Total
 - {n} bolts created

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

@@ -1,6 +1,6 @@
 ---
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 status: proposed | accepted | deprecated | superseded
 superseded_by: {adr-number if applicable}
 ---

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-01-domain-model-template.md

@@ -3,7 +3,7 @@ unit: {unit-name}
 bolt: {bolt-id}
 stage: model
 status: complete
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # Static Model - {Unit Name}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-02-technical-design-template.md

@@ -3,7 +3,7 @@ unit: {unit-name}
 bolt: {bolt-id}
 stage: design
 status: complete
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # Technical Design - {Unit Name}

package/flows/aidlc/templates/construction/bolt-types/ddd-construction-bolt/ddd-03-test-report-template.md

@@ -3,7 +3,7 @@ unit: {unit-name}
 bolt: {bolt-id}
 stage: test
 status: complete
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # Test Report - {Unit Name}

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

@@ -109,7 +109,7 @@ This bolt type implements Domain-Driven Design (DDD) methodology through five se
 ---
 stage: model
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Static Model: {unit-name}
@@ -189,7 +189,7 @@ created: {timestamp}
 ---
 stage: design
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Technical Design: {unit-name}
@@ -440,7 +440,7 @@ tests/
 ---
 stage: test
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Test Report: {unit-name}

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

@@ -107,7 +107,7 @@ This bolt type provides a lightweight construction process for work that doesn't
 ---
 stage: plan
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Implementation Plan: {unit-name}
@@ -175,7 +175,7 @@ created: {timestamp}
 ---
 stage: implement
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Implementation Walkthrough: {unit-name}
@@ -260,7 +260,7 @@ created: {timestamp}
 ---
 stage: test
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Test Report: {unit-name}

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

@@ -80,7 +80,7 @@ This bolt type is for research and proof-of-concept work when there are unknowns
 ---
 stage: explore
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 time_box: {hours}
 ---
 
@@ -142,7 +142,7 @@ time_box: {hours}
 ---
 stage: document
 bolt: {bolt-id}
-created: {timestamp}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 ## Spike Report: {topic}

package/flows/aidlc/templates/construction/construction-log-template.md

@@ -16,8 +16,8 @@ Use this template to track construction progress and replanning decisions for a
 ---
 unit: {unit-name}
 intent: {intent-name}
-created: {YYYY-MM-DD}
-last_updated: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+last_updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # Construction Log: {unit-name}

package/flows/aidlc/templates/inception/inception-log-template.md

@@ -15,8 +15,8 @@ Use this template to track inception progress and decisions for an intent.
 ```markdown
 ---
 intent: {intent-name}
-created: {YYYY-MM-DD}
-completed: {YYYY-MM-DD or null}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+completed: {YYYY-MM-DDTHH:MM:SSZ or null}
 status: {in-progress | complete}
 ---
 

package/flows/aidlc/templates/inception/requirements-template.md

@@ -11,8 +11,8 @@ Use this template when documenting requirements for an intent.
 intent: {intent-name}
 phase: inception
 status: draft|in-progress|complete
-created: {YYYY-MM-DD}
-updated: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 ```
 

package/flows/aidlc/templates/inception/stories-template.md

@@ -2,7 +2,7 @@
 intent: {intent-name}
 phase: inception
 status: stories-created
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # {Intent Name} - Stories

package/flows/aidlc/templates/inception/story-template.md

@@ -13,7 +13,7 @@ unit: {unit-name}
 intent: {intent-name}
 status: draft
 priority: must|should|could
-created: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 assigned_bolt: null
 implemented: false
 ---
@@ -96,7 +96,7 @@ unit: auth-service
 intent: user-authentication
 status: ready
 priority: must
-created: 2024-12-05
+created: 2024-12-05T10:00:00Z
 assigned_bolt: bolt-auth-service-1
 implemented: false
 ---

package/flows/aidlc/templates/inception/system-context-template.md

@@ -2,7 +2,7 @@
 intent: {intent-name}
 phase: inception
 status: context-defined
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # {Intent Name} - System Context

package/flows/aidlc/templates/inception/unit-brief-template.md

@@ -12,8 +12,8 @@ unit: {unit-name}
 intent: {intent-name}
 phase: inception
 status: draft|ready
-created: {YYYY-MM-DD}
-updated: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 ```
 

package/flows/aidlc/templates/inception/units-template.md

@@ -2,7 +2,7 @@
 intent: {intent-name}
 phase: inception
 status: units-decomposed
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # {Intent Name} - Unit Decomposition

package/lib/analytics/env-detector.js

@@ -0,0 +1,92 @@
+/**
+ * Environment Detection
+ *
+ * Detects shell environment and telemetry opt-out settings.
+ * Used to enrich analytics events and respect user privacy preferences.
+ */
+
+/**
+ * Detect the user's shell/terminal environment
+ *
+ * @returns {string} Shell name (zsh, bash, powershell, cmd, fish, etc.) or 'unknown'
+ */
+function detectShell() {
+    if (process.platform === 'win32') {
+        const comspec = (process.env.ComSpec || '').toLowerCase();
+        if (comspec.includes('powershell') || comspec.includes('pwsh')) {
+            return 'powershell';
+        }
+        if (comspec.includes('cmd')) {
+            return 'cmd';
+        }
+        return 'unknown';
+    }
+
+    // Unix-like systems (macOS, Linux)
+    const shell = process.env.SHELL || '';
+    const basename = shell.split('/').pop() || 'unknown';
+    return basename;
+}
+
+/**
+ * Check if telemetry is disabled via environment variables or CLI flag
+ *
+ * Respects:
+ * - SPECSMD_TELEMETRY_DISABLED=1
+ * - DO_NOT_TRACK=1
+ * - CI environments (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, JENKINS_URL)
+ * - --no-telemetry CLI flag
+ *
+ * @param {Object} options - Optional overrides
+ * @param {boolean} options.noTelemetryFlag - CLI flag state
+ * @returns {boolean} True if telemetry should be disabled
+ */
+function isTelemetryDisabled(options = {}) {
+    // Check CLI flag first (highest priority)
+    if (options.noTelemetryFlag === true) {
+        return true;
+    }
+
+    // Check process.argv for --no-telemetry flag
+    if (process.argv.includes('--no-telemetry')) {
+        return true;
+    }
+
+    // Check explicit opt-out environment variables
+    if (process.env.SPECSMD_TELEMETRY_DISABLED === '1') {
+        return true;
+    }
+
+    // Respect DO_NOT_TRACK standard (https://consoledonottrack.com/)
+    if (process.env.DO_NOT_TRACK === '1') {
+        return true;
+    }
+
+    // Auto-disable in CI environments
+    if (process.env.CI === 'true') {
+        return true;
+    }
+
+    if (process.env.GITHUB_ACTIONS === 'true') {
+        return true;
+    }
+
+    if (process.env.GITLAB_CI === 'true') {
+        return true;
+    }
+
+    if (process.env.CIRCLECI === 'true') {
+        return true;
+    }
+
+    if (process.env.JENKINS_URL !== undefined) {
+        return true;
+    }
+
+    return false;
+}
+
+module.exports = {
+    detectShell,
+    isTelemetryDisabled
+};

package/lib/analytics/index.js

@@ -0,0 +1,22 @@
+/**
+ * Analytics Module
+ *
+ * Exports the analytics tracker singleton for use throughout the installer.
+ *
+ * Usage:
+ *   const analytics = require('./analytics');
+ *
+ *   // Initialize at startup
+ *   analytics.init();
+ *
+ *   // Track events
+ *   analytics.trackInstallerStarted();
+ *   analytics.trackIdesConfirmed(['claude-code', 'cursor']);
+ *   analytics.trackFlowSelected('aidlc');
+ *   analytics.trackInstallationCompleted('claude-code', 'aidlc', 1500, 12);
+ *   analytics.trackInstallationFailed('cursor', 'file_permission', 'aidlc');
+ */
+
+const tracker = require('./tracker');
+
+module.exports = tracker;

package/lib/analytics/machine-id.js

@@ -0,0 +1,33 @@
+/**
+ * Machine ID Generation
+ *
+ * Generates a stable, anonymous machine identifier using a salted SHA-256 hash
+ * of the hostname. This ensures:
+ * - Same machine always produces same ID
+ * - Cannot reverse-lookup the hostname from the hash
+ * - No PII is stored or transmitted
+ */
+
+const crypto = require('crypto');
+const os = require('os');
+
+// Constant salt prevents rainbow table attacks
+// Do not change this value - it would break ID consistency
+const SALT = 'specsmd-analytics-v1';
+
+/**
+ * Generate a stable machine identifier
+ *
+ * @returns {string} SHA-256 hash of salted hostname (64 hex characters)
+ */
+function getMachineId() {
+    const hostname = os.hostname();
+    return crypto
+        .createHash('sha256')
+        .update(SALT + hostname)
+        .digest('hex');
+}
+
+module.exports = {
+    getMachineId
+};

package/lib/analytics/tracker.js

@@ -0,0 +1,227 @@
+/**
+ * Analytics Tracker
+ *
+ * Mixpanel-based analytics for the specsmd installer.
+ * Tracks anonymous usage patterns while respecting privacy.
+ *
+ * Features:
+ * - Fire-and-forget event delivery (non-blocking)
+ * - Silent failures (never breaks installation)
+ * - Privacy-first (no PII, respects opt-out)
+ */
+
+const crypto = require('crypto');
+const { getMachineId } = require('./machine-id');
+const { detectShell, isTelemetryDisabled } = require('./env-detector');
+
+// Mixpanel project token
+// This is safe to embed - analytics tokens are public by design
+const MIXPANEL_TOKEN = 'f405d1fa631f91137f9bb8e0a0277653';
+
+/**
+ * AnalyticsTracker - Singleton class for event tracking
+ */
+class AnalyticsTracker {
+    constructor() {
+        this.mixpanel = null;
+        this.enabled = false;
+        this.machineId = null;
+        this.sessionId = null;
+        this.baseProperties = null;
+        this.initialized = false;
+    }
+
+    /**
+     * Initialize the analytics tracker
+     *
+     * @param {Object} options - Initialization options
+     * @param {boolean} options.noTelemetry - CLI flag to disable telemetry
+     * @returns {boolean} True if analytics is enabled
+     */
+    init(options = {}) {
+        if (this.initialized) {
+            return this.enabled;
+        }
+
+        this.initialized = true;
+
+        // Check if telemetry is disabled
+        if (isTelemetryDisabled({ noTelemetryFlag: options.noTelemetry })) {
+            this.enabled = false;
+            return false;
+        }
+
+        try {
+            // Lazy-load Mixpanel to avoid blocking if not needed
+            const Mixpanel = require('mixpanel');
+            this.mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
+                protocol: 'https',
+                host: 'api-eu.mixpanel.com'  // EU endpoint for GDPR compliance
+            });
+
+            // Generate IDs
+            this.machineId = getMachineId();
+            this.sessionId = crypto.randomUUID();
+
+            // Build base properties included with every event
+            this.baseProperties = {
+                distinct_id: this.machineId,
+                session_id: this.sessionId,
+                $os: process.platform,
+                shell: detectShell(),
+                node_version: process.version,
+                specsmd_version: this._getVersion()
+            };
+
+            this.enabled = true;
+            return true;
+        } catch (error) {
+            // Silent failure - analytics should never break installation
+            this.enabled = false;
+            return false;
+        }
+    }
+
+    /**
+     * Get specsmd version from package.json
+     * @private
+     */
+    _getVersion() {
+        try {
+            const pkg = require('../../package.json');
+            return pkg.version || 'unknown';
+        } catch {
+            return 'unknown';
+        }
+    }
+
+    /**
+     * Track an event (fire-and-forget)
+     * @private
+     *
+     * @param {string} eventName - Name of the event
+     * @param {Object} properties - Additional event properties
+     * @param {boolean} waitForDelivery - Wait for event to be sent
+     * @returns {Promise<void>} Resolves when event is sent (if waitForDelivery is true)
+     */
+    track(eventName, properties = {}, waitForDelivery = false) {
+        if (!this.enabled || !this.mixpanel) {
+            return waitForDelivery ? Promise.resolve() : undefined;
+        }
+
+        const eventData = {
+            ...this.baseProperties,
+            ...properties
+        };
+
+        if (waitForDelivery) {
+            return new Promise((resolve) => {
+                try {
+                    this.mixpanel.track(eventName, eventData, (err) => {
+                        // Resolve regardless of error - silent failure
+                        resolve();
+                    });
+                } catch {
+                    resolve();
+                }
+            });
+        }
+
+        try {
+            this.mixpanel.track(eventName, eventData);
+        } catch {
+            // Silent failure
+        }
+    }
+
+    /**
+     * Track installer_started event
+     * Called when the installer begins
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackInstallerStarted() {
+        // Wait for delivery - critical funnel event
+        return this.track('installer_started', {}, true);
+    }
+
+    /**
+     * Track ides_confirmed event
+     * Called after user confirms IDE/tool selection
+     *
+     * @param {string[]} ides - Array of selected IDE keys (e.g., ['claude-code', 'cursor'])
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackIdesConfirmed(ides) {
+        // Wait for delivery - critical funnel event
+        return this.track('ides_confirmed', {
+            ide_count: ides.length,
+            ides: ides
+        }, true);
+    }
+
+    /**
+     * Track flow_selected event
+     * Called after user selects an SDLC flow
+     *
+     * @param {string} flow - Flow key (e.g., 'aidlc', 'agile')
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackFlowSelected(flow) {
+        // Wait for delivery - critical funnel event
+        return this.track('flow_selected', {
+            flow: flow
+        }, true);
+    }
+
+    /**
+     * Track installation_completed event
+     * Called after successful installation for an IDE
+     *
+     * @param {string} ide - IDE key (e.g., 'claude-code')
+     * @param {string} flow - Flow key (e.g., 'aidlc')
+     * @param {number} durationMs - Installation duration in milliseconds
+     * @param {number} filesCreated - Number of files created
+     */
+    trackInstallationCompleted(ide, flow, durationMs, filesCreated) {
+        this.track('installation_completed', {
+            ide: ide,
+            flow: flow,
+            duration_ms: durationMs,
+            files_created: filesCreated
+        });
+    }
+
+    /**
+     * Track installation_failed event
+     * Called after failed installation for an IDE
+     *
+     * @param {string} ide - IDE key (e.g., 'claude-code')
+     * @param {string} errorCategory - Error category (e.g., 'file_permission', 'network', 'unknown')
+     * @param {string} [flow] - Flow key (optional, may not be selected yet)
+     */
+    trackInstallationFailed(ide, errorCategory, flow) {
+        const properties = {
+            ide: ide,
+            error_category: errorCategory
+        };
+
+        if (flow) {
+            properties.flow = flow;
+        }
+
+        this.track('installation_failed', properties);
+    }
+
+    /**
+     * Check if analytics is enabled
+     * @returns {boolean}
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+}
+
+// Export singleton instance
+const tracker = new AnalyticsTracker();
+
+module.exports = tracker;

package/lib/installer.js

@@ -5,10 +5,56 @@ const yaml = require('js-yaml');
 const CLIUtils = require('./cli-utils');
 const InstallerFactory = require('./InstallerFactory');
 const { FLOWS } = require('./constants');
+const analytics = require('./analytics');
 
 // Use theme from CLIUtils for consistent styling
 const { theme } = CLIUtils;
 
+/**
+ * Categorize an error for analytics tracking
+ * @param {Error} error - The error to categorize
+ * @returns {string} Error category
+ */
+function categorizeError(error) {
+    const message = (error.message || '').toLowerCase();
+
+    if (message.includes('permission') || message.includes('eacces')) {
+        return 'file_permission';
+    }
+    if (message.includes('enoent') || message.includes('not found')) {
+        return 'file_not_found';
+    }
+    if (message.includes('network') || message.includes('enotfound') || message.includes('timeout')) {
+        return 'network';
+    }
+    if (message.includes('enospc') || message.includes('disk')) {
+        return 'disk_space';
+    }
+    return 'unknown';
+}
+
+/**
+ * Count files in a directory recursively
+ * @param {string} dir - Directory path
+ * @returns {Promise<number>} File count
+ */
+async function countFiles(dir) {
+    let count = 0;
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += await countFiles(path.join(dir, entry.name));
+            } else {
+                count++;
+            }
+        }
+    } catch {
+        // Ignore errors (directory might not exist)
+    }
+    return count;
+}
+
 async function detectTools() {
   const detected = [];
   const installers = InstallerFactory.getInstallers();
@@ -22,6 +68,12 @@ async function detectTools() {
 }
 
 async function install() {
+  // Initialize analytics (respects opt-out env vars)
+  analytics.init();
+  await analytics.trackInstallerStarted();
+
+  const installStartTime = Date.now();
+
   await CLIUtils.displayLogo();
   CLIUtils.displayHeader('Installation', '');
 
@@ -67,6 +119,9 @@ async function install() {
     process.exit(1);
   }
 
+  // Track IDE selection (await to ensure delivery before potential cancel)
+  await analytics.trackIdesConfirmed(selectedToolKeys);
+
   // Step 3: Select Flow
   console.log('');
   CLIUtils.displayStep(3, 4, 'Select SDLC flow');
@@ -88,12 +143,21 @@ async function install() {
     process.exit(1);
   }
 
+  // Track flow selection (await to ensure delivery before potential cancel)
+  await analytics.trackFlowSelected(selectedFlow);
+
   // Step 4: Install flow files
   console.log('');
   CLIUtils.displayStep(4, 4, `Installing ${FLOWS[selectedFlow].name} flow...`);
 
   try {
-    await installFlow(selectedFlow, selectedToolKeys);
+    const filesCreated = await installFlow(selectedFlow, selectedToolKeys);
+
+    // Track successful installation for each tool
+    const durationMs = Date.now() - installStartTime;
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationCompleted(toolKey, selectedFlow, durationMs, filesCreated);
+    }
 
     CLIUtils.displaySuccess(`${FLOWS[selectedFlow].name} flow installed successfully!`, 'Installation Complete');
 
@@ -108,6 +172,12 @@ async function install() {
     ];
     CLIUtils.displayNextSteps(nextSteps);
   } catch (error) {
+    // Track installation failure
+    const errorCategory = categorizeError(error);
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationFailed(toolKey, errorCategory, selectedFlow);
+    }
+
     CLIUtils.displayError(`Installation failed: ${error.message}`);
     console.log(theme.dim('\nRolling back changes...'));
     await rollback(selectedFlow, selectedToolKeys);
@@ -199,6 +269,10 @@ async function installFlow(flowKey, toolKeys) {
   );
 
   CLIUtils.displayStatus('', 'Created installation manifest', 'success');
+
+  // Count files created for analytics
+  const filesCreated = await countFiles(specsmdDir);
+  return filesCreated;
 }
 
 async function rollback(flowKey, toolKeys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {
@@ -45,6 +45,7 @@
     "fs-extra": "^11.1.1",
     "gradient-string": "^2.0.2",
     "js-yaml": "^4.1.0",
+    "mixpanel": "^0.18.0",
     "oh-my-logo": "^0.4.0",
     "prompts": "^2.4.2"
   },