specsmd 0.0.34 → 0.1.1

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
@@ -162,7 +182,7 @@ The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Spri
 | Type | Best For | Stages |
 |------|----------|--------|
 | **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
-| **Simple Construction** | UI, integrations, utilities | Spec → Implement → Test |
+| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
 
 ### Memory Bank
 File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.

package/flows/aidlc/agents/inception-agent.md

@@ -17,8 +17,10 @@ You are the **Inception Agent** for AI-DLC (AI-Driven Development Life Cycle).
 When user invokes `/specsmd-inception-agent`:
 
 1. Read `.specsmd/aidlc/memory-bank.yaml` for artifact schema
-2. Execute `menu` (navigator) skill to show state and options
-3. Route to selected skill based on user input
+2. Read `.specsmd/aidlc/context-config.yaml` for project context (under `agents.inception`)
+3. Load context files as defined (e.g., `project.yaml` for project type awareness)
+4. Execute `menu` (navigator) skill to show state and options
+5. Route to selected skill based on user input
 
 ---
 

package/flows/aidlc/context-config.yaml

@@ -37,5 +37,31 @@ agents:
 
         Or continue without standards (code may be inconsistent).
 
-# Note: Other agents (Master, Inception, Operations) do not require
-# standards to be loaded. They will be added here when needed.
+  inception:
+    description: "Inception Agent needs project type awareness for unit decomposition"
+    required_context:
+      - path: project.yaml
+        purpose: "Project type for unit decomposition and bolt type defaults"
+        critical: false
+
+    optional_context:
+      - path: standards/tech-stack.md
+        purpose: "Technology context for realistic decomposition"
+
+    on_missing_critical:
+      action: continue
+      message: |
+        ℹ️ Project not initialized yet.
+
+        The project.yaml file will be created during project-init.
+        Inception can proceed without it (will use defaults).
+
+  operations:
+    description: "Operations Agent requires deployment context"
+    required_context: []
+    optional_context:
+      - path: standards/system-architecture.md
+        purpose: "Architecture for deployment decisions"
+
+      - path: operations/deployment-config.md
+        purpose: "Existing deployment configuration"

package/flows/aidlc/memory-bank.yaml

@@ -50,20 +50,20 @@ naming:
     note: "3-digit prefix indicates order, kebab-case name"
 
   units:
-    format: "{unit-name}"
-    example: "auth-service"
-    note: "Kebab-case, descriptive name"
+    format: "{UUU}-{unit-name}"
+    example: "001-auth-service"
+    note: "3-digit prefix within intent, kebab-case name"
 
   stories:
     format: "{SSS}-{title-slug}.md"
     example: "001-user-signup.md"
     note: "3-digit story number + kebab-case story title"
-    full_path_example: "memory-bank/intents/001-user-authentication/units/auth-service/stories/001-user-signup.md"
+    full_path_example: "memory-bank/intents/001-user-authentication/units/001-auth-service/stories/001-user-signup.md"
 
   bolts:
-    format: "bolt-{unit-name}-{N}/"
-    example: "bolt-auth-service-1/"
-    note: "Directory per bolt, contains bolt.md and stage artifacts"
+    format: "{BBB}-{unit-name}/"
+    example: "001-auth-service/"
+    note: "Global 3-digit sequence, unit name for context"
     contents:
       - "bolt.md"                      # Bolt instance metadata
       - "ddd-01-domain-model.md"       # Stage 1 artifact (DDD bolt)

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

@@ -61,7 +61,21 @@ Read bolt file from path defined by `schema.bolts`:
 └────────────────────────────────────────────────────────────┘
 ```
 
-### 3. Load Agent Context
+### 3. Load Unit Context (CRITICAL)
+
+**After extracting the unit from the bolt file, load its brief for context.**
+
+Load `{intent}/units/{unit}/unit-brief.md` which contains:
+
+- **Purpose and scope**: What the unit is responsible for
+- **Key entities**: Domain concepts to work with
+- **Technical constraints**: Specific limitations
+- **Dependencies**: Other units this depends on
+- **Unit type and bolt type**: Frontend vs backend, DDD vs simple
+
+This context is essential for understanding what you're building.
+
+### 4. Load Agent Context
 
 Load context as defined in `.specsmd/aidlc/context-config.yaml` for the `construction` agent:
 
@@ -81,16 +95,38 @@ agents:
 
 **Note**: This is agent-level context. Bolt-type-specific context loading may be added later.
 
-### 4. Determine Current Stage
+### 5. Determine Current Stage
 
 Based on bolt state:
 
-- **planned** → Start with first stage, set status to `in-progress`
+- **planned** → Start with first stage, update bolt file immediately (see Step 6)
 - **in-progress** → Continue from `current_stage`
 - **completed** → Inform user bolt is done
 - **blocked** → Show blocker, ask how to resolve
 
-### 5. Execute Stage
+### 6. Update Bolt File on Start (CRITICAL - DO FIRST)
+
+**⚠️ BEFORE any stage work begins, update the bolt file IMMEDIATELY.**
+
+When transitioning from `planned` to `in-progress`:
+
+```yaml
+---
+status: in-progress          # was: planned
+started: {ISO-8601-timestamp} # was: null
+current_stage: {first-stage}  # was: null (e.g., "domain-model")
+---
+```
+
+**This is NON-NEGOTIABLE.** The bolt file must reflect that work has begun before any stage activities start. This ensures:
+
+1. Progress is tracked even if execution is interrupted
+2. Other tools/agents see accurate status
+3. Resumption works correctly
+
+**Also update construction log** (see "Update Construction Log" section below).
+
+### 7. Execute Stage
 
 For the current stage, follow the bolt type definition:
 
@@ -122,7 +158,7 @@ For the current stage, follow the bolt type definition:
    - Use templates if specified by bolt type
    - Place in correct paths per schema
 
-### 6. Handle Checkpoints (As Defined by Bolt Type)
+### 8. Handle Checkpoints (As Defined by Bolt Type)
 
 The bolt type definition specifies:
 
@@ -146,9 +182,9 @@ Ready to proceed?
 
 If the bolt type specifies automatic validation criteria, follow those rules.
 
-### 7. Update Bolt File
+### 9. Update Bolt File on Stage Completion
 
-After stage completion:
+After each stage completion:
 
 - Add stage to `stages_completed` with timestamp
 - Update `current_stage` to next stage
@@ -171,7 +207,96 @@ stages_completed:
 completed: {timestamp}
 ```
 
-### 8. Continue or Complete
+#### Update Story Status (On Bolt Completion)
+
+When marking a bolt as `status: complete`, update all stories in the bolt's `stories` array:
+
+1. **Read bolt's stories**: Get story IDs from bolt frontmatter `stories: [001-story-name, 002-story-name, ...]`
+2. **Locate story files**: `{intent}/units/{unit}/stories/{story-id}.md`
+3. **Update each story frontmatter**:
+
+   ```yaml
+   # Change from
+   status: draft
+   implemented: false
+
+   # To
+   status: complete
+   implemented: true
+   ```
+
+**Example**:
+
+```text
+Bolt stories: [001-create-role, 002-manage-permissions, 003-view-roles]
+
+Updated:
+✅ stories/001-create-role.md → status: complete, implemented: true
+✅ stories/002-manage-permissions.md → status: complete, implemented: true
+✅ stories/003-view-roles.md → status: complete, implemented: true
+```
+
+This ensures the memory-bank reflects actual implementation status and the VS Code extension shows correct completion indicators.
+
+#### Update Unit & Intent Status (Status Cascade)
+
+Status changes cascade upward: Bolt → Story → Unit → Intent.
+
+**On Bolt Start** (when changing from `planned` to `in-progress`):
+
+1. **Update Unit Status**:
+   - Read unit-brief: `{intent}/units/{unit}/unit-brief.md`
+   - If unit status is `stories-defined` or `stories-updated` → change to `in-progress`
+
+2. **Update Intent Status**:
+   - Read requirements: `{intent}/requirements.md`
+   - If intent status is `units-defined` → change to `construction`
+
+**On Bolt Completion** (after updating stories):
+
+1. **Check Unit Completion**:
+   - 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**:
+   - Read unit-briefs for all units in intent: `{intent}/units/*/unit-brief.md`
+   - If ALL units have `status: complete` → update requirements to `status: complete`
+
+**Status Transitions**:
+
+```text
+Intent:  draft → requirements-defined → units-defined → construction → complete
+Unit:    draft → stories-defined → in-progress → complete
+Story:   draft → in-progress → complete
+```
+
+**Example** (001-artifact-parser completes):
+
+```text
+1. Stories updated: 001, 002, 003, 004 → complete
+2. Check unit bolts:
+   - 001-artifact-parser: complete ✓
+   - 005-artifact-parser: planned ✗
+   → Unit stays in-progress (not all bolts complete)
+3. Intent stays construction (unit not complete)
+```
+
+**Example** (last bolt for file-watcher completes):
+
+```text
+1. Stories updated: 001, 002 → complete
+2. Check unit bolts:
+   - 003-file-watcher: complete ✓
+   → Only bolt for unit, all complete!
+   → Update unit-brief: status: complete
+3. Check intent units:
+   - artifact-parser: in-progress ✗
+   - file-watcher: complete ✓
+   - sidebar-provider: in-progress ✗
+   → Intent stays construction (not all units complete)
+```
+
+### 10. Continue or Complete
 
 Based on condition:
 

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}