specsmd 0.0.34 → 0.1.0

package/README.md

@@ -162,7 +162,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-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: `memory-bank/bolts/bolt-{unit}-*/bolt.md`
+   - 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** (bolt-artifact-parser-1 completes):
+
+```text
+1. Stories updated: 001, 002, 003, 004 → complete
+2. Check unit bolts:
+   - bolt-artifact-parser-1: complete ✓
+   - bolt-artifact-parser-2: 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:
+   - bolt-file-watcher-1: 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/inception/bolt-plan.md

@@ -212,7 +212,7 @@ Establish execution order based on dependencies:
    └── {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 `spec.md`).*
+   *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):
 

package/flows/aidlc/skills/master/analyze-context.md

@@ -70,6 +70,106 @@ Based on evidence found:
 - **All bolts completed** → Ready for Operations → Deploy unit
 - **Deployed to production** → Operations → Monitor and maintain
 
+### 6. Validate Status Integrity
+
+Check for status inconsistencies across the artifact hierarchy. Status must cascade correctly:
+
+```text
+Bolt complete → Stories complete → Unit complete (if all bolts done) → Intent complete (if all units done)
+```
+
+#### 6.1 Story Status Check
+
+For each completed bolt:
+
+- Read bolt's `stories` array
+- Check each story file's `status` field
+- **Inconsistency**: Bolt complete but story has `status: draft` or `status: in-progress`
+
+#### 6.2 Unit Status Check
+
+For each unit:
+
+- Find all bolts for unit: `memory-bank/bolts/bolt-{unit}-*/bolt.md`
+- Determine expected status:
+  - If ANY bolt `in-progress` → unit should be `in-progress`
+  - If ALL bolts `complete` → unit should be `complete`
+  - If ALL bolts `planned` and at least one story defined → unit should be `stories-defined`
+  - If NO bolts exist but stories exist → unit should be `stories-defined`
+- **Inconsistency**: Unit status doesn't match expected based on bolt states
+
+#### 6.3 Intent Status Check
+
+For each intent:
+
+- Read all unit-briefs: `{intent}/units/*/unit-brief.md`
+- Determine expected status:
+  - If ANY unit `in-progress` → intent should be `construction`
+  - If ALL units `complete` → intent should be `complete`
+  - If units defined but none started → intent should be `units-defined`
+- **Inconsistency**: Intent status doesn't match expected based on unit states
+
+#### 6.4 Report Inconsistencies
+
+If inconsistencies found, report them:
+
+```markdown
+## ⚠️ Status Inconsistencies Detected
+
+| Artifact | Current Status | Expected Status | Reason |
+|----------|----------------|-----------------|--------|
+| unit-brief: file-watcher | draft | complete | All bolts complete |
+| requirements: 011-vscode-extension | units-defined | construction | Has in-progress units |
+
+### Actions
+1 - **fix**: Update all statuses to expected values
+2 - **skip**: Continue without fixing
+3 - **review**: Show details for each inconsistency
+
+**Type 1 to fix inconsistencies, or 2 to skip.**
+```
+
+#### 6.5 Auto-Fix (On User Confirmation)
+
+If user confirms fix:
+
+- Update each artifact's frontmatter `status` field
+- Update `updated` timestamp to current date
+- Log changes to `memory-bank/maintenance-log.md`
+- Report changes made
+
+#### 6.6 Log to Maintenance Log
+
+Append entry to `memory-bank/maintenance-log.md` (create if doesn't exist):
+
+```markdown
+## {ISO-8601-timestamp} - Status Sync
+
+**Triggered by**: analyze-context integrity check
+
+| Artifact | Old Status | New Status | Reason |
+|----------|------------|------------|--------|
+| {path} | {old} | {new} | {reason} |
+
+---
+```
+
+**Example**:
+
+```markdown
+## 2025-12-26T15:30:00Z - Status Sync
+
+**Triggered by**: analyze-context integrity check
+
+| Artifact | Old Status | New Status | Reason |
+|----------|------------|------------|--------|
+| 011-vscode-extension/units/file-watcher/unit-brief.md | draft | complete | All bolts complete (1/1) |
+| 011-vscode-extension/units/extension-core/unit-brief.md | draft | complete | All bolts complete (1/1) |
+| 011-vscode-extension/requirements.md | units-defined | construction | Has in-progress units |
+
+---
+```
+
 ---
 
 ## Output
@@ -91,14 +191,21 @@ Provide a structured analysis:
 - Stories found: {count} for {unit}
 - Bolts found: {count} ({status breakdown})
 
+### Status Integrity
+- ✅ All statuses consistent (or)
+- ⚠️ {N} inconsistencies found (see details below)
+
 ### Current State Details
 {Specific details about what exists and what's missing}
 
+{If inconsistencies found, include the inconsistency table here}
+
 ### Actions
 
 1 - **proceed**: Execute suggested action
 2 - **explain**: Learn more about current phase
 3 - **different**: Work on something else
+{If inconsistencies: 4 - **fix**: Fix status inconsistencies}
 
 ### Suggested Next Step
 → **proceed** - {Specific command to run}

package/flows/aidlc/skills/master/explain-flow.md

@@ -41,11 +41,23 @@ AI-DLC is a reimagined development methodology where AI drives the workflow and
    - Output: Complete implementation plan
 
 2. **Construction** → Building & Testing
-   - Execute bolts through their stages
+   - Execute bolts through their stages (stages vary by bolt type)
    - AI generates designs, code, and tests
    - Human validates at each stage
    - Output: Tested, working code
 
+   **DDD Bolt** (for domain-heavy business logic):
+   - Stage 1: Domain Model → AI models entities, aggregates, events
+   - Stage 2: Technical Design → AI architects layers, APIs, data
+   - Stage 3: ADR Analysis → Capture architectural decisions (optional)
+   - Stage 4: Implement → AI generates code from designs
+   - Stage 5: Test → AI writes and runs tests
+
+   **Simple Bolt** (for straightforward tasks):
+   - Stage 1: Plan → Define what to build
+   - Stage 2: Implement → AI generates code
+   - Stage 3: Test → AI writes and runs tests
+
 3. **Operations** → Deploy & Monitor
    - Package deployment units
    - Deploy through environments (Dev → Staging → Prod)

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

@@ -34,12 +34,18 @@ status: planned
 stories:
   - story-1
   - story-2
-created: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 started: null
 completed: null
 current_stage: null
 stages_completed: []
 
+# Bolt Dependencies (for execution ordering)
+requires_bolts: []          # Bolts that must complete before this bolt can start
+enables_bolts: []           # Bolts that become unblocked when this bolt completes
+requires_units: []          # Units that must exist (usually empty)
+blocks: false               # Computed: true if any requires_bolts are incomplete
+
 # Complexity Assessment (aggregate of included stories)
 complexity:
   avg_complexity: 2        # 1=Low, 2=Medium, 3=High
@@ -142,6 +148,12 @@ stages_completed:
     completed: 2024-12-05T10:00:00Z
     artifact: ddd-01-domain-model.md
 
+requires_bolts: []
+enables_bolts:
+  - bolt-auth-service-2
+requires_units: []
+blocks: false
+
 complexity:
   avg_complexity: 2
   avg_uncertainty: 1

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

@@ -25,14 +25,14 @@
 **Stages MUST be executed in this exact order:**
 
 ```text
-Stage 1: Spec → Stage 2: Implement → Stage 3: Test
+Stage 1: Plan → Stage 2: Implement → Stage 3: Test
 ```
 
 **Stage Overview:**
 
-- ✅/[ ] **1. Spec** (Required) → `spec.md`
-- ✅/[ ] **2. Implement** (Required) → Source code
-- ✅/[ ] **3. Test** (Required) → Tests + `test-report.md`
+- ✅/[ ] **1. Plan** (Required) → `implementation-plan.md`
+- ✅/[ ] **2. Implement** (Required) → Source code + `implementation-walkthrough.md`
+- ✅/[ ] **3. Test** (Required) → Tests + `test-walkthrough.md`
 
 **Rules**:
 
@@ -84,7 +84,7 @@ This bolt type provides a lightweight construction process for work that doesn't
 
 ## Stages
 
-### Stage 1: Spec
+### Stage 1: Plan
 
 **Objective**: Define what to build with clear requirements
 
@@ -98,19 +98,19 @@ This bolt type provides a lightweight construction process for work that doesn't
 4 - **Define acceptance criteria**: How will we know it's done?
 5 - **Note technical approach**: High-level implementation notes
 
-**Artifact**: `spec.md`
-**Location**: `memory-bank/bolts/{bolt-id}/spec.md`
+**Artifact**: `implementation-plan.md`
+**Location**: `memory-bank/bolts/{bolt-id}/implementation-plan.md`
 
 **Template Structure**:
 
 ```markdown
 ---
-stage: spec
+stage: plan
 bolt: {bolt-id}
 created: {timestamp}
 ---
 
-## Spec: {unit-name}
+## Implementation Plan: {unit-name}
 
 ### Objective
 {What this bolt will accomplish}
@@ -137,13 +137,13 @@ created: {timestamp}
 - [ ] Dependencies identified
 - [ ] Acceptance criteria documented
 
-**⛔ HUMAN Checkpoint**: Present spec summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
+**⛔ HUMAN Checkpoint**: Present plan summary and **STOP**. Wait for user to confirm before proceeding to Stage 2.
 
 ---
 
 ### Stage 2: Implement
 
-**Objective**: Write the code
+**Objective**: Write the code and document what was done
 
 **Duration**: Hours (varies by complexity)
 
@@ -154,16 +154,84 @@ created: {timestamp}
 3 - **Handle edge cases**: Error handling, validation
 4 - **Add documentation**: Code comments, JSDoc/docstrings
 5 - **Run linting**: Ensure code style compliance
+6 - **Document implementation**: Create implementation walkthrough
 
-**Artifact**: Source code
-**Location**: As defined in project structure (e.g., `src/`, `app/`, `pages/`)
+**Artifacts**:
+
+- Source code - As defined in project structure (e.g., `src/`, `app/`, `pages/`)
+- `implementation-walkthrough.md` - `memory-bank/bolts/{bolt-id}/implementation-walkthrough.md`
+
+**Implementation Walkthrough Guidelines**:
+
+⚠️ **CRITICAL RULES**:
+
+- **NO CODE** in this document - only structure summaries and descriptions
+- **USE CHECKMARKS** for all file entries (completed work)
+- **BE CONSISTENT** - follow the template exactly
+
+**Template**:
+
+```markdown
+---
+stage: implement
+bolt: {bolt-id}
+created: {timestamp}
+---
+
+## Implementation Walkthrough: {unit-name}
+
+### Summary
+
+{2-3 sentence overview of what was built - NO CODE}
+
+### Structure Overview
+
+{High-level description of the architecture/organization - NO CODE}
+
+### Completed Work
+
+- [x] `{path/to/file}` - {what this file does, not how}
+- [x] `{path/to/file}` - {what this file does, not how}
+- [x] `{path/to/file}` - {what this file does, not how}
+
+### Key Decisions
+
+- **{Decision}**: {Why this approach was chosen}
+
+### Deviations from Plan
+
+{Any changes from implementation-plan.md and why, or "None"}
+
+### Dependencies Added
+
+- [x] `{package}` - {why needed}
+
+### Developer Notes
+
+{Gotchas, tips, or context for future work - keep brief}
+```
+
+**What to Include**:
+
+- ✅ File paths with brief purpose descriptions
+- ✅ Architectural decisions and rationale
+- ✅ Deviations from original plan
+- ✅ High-level structure explanations
+
+**What NOT to Include**:
+
+- ❌ Code snippets or examples
+- ❌ Implementation details (how it works internally)
+- ❌ Line-by-line explanations
+- ❌ API signatures or type definitions
 
 **Completion Criteria**:
 
-- [ ] All deliverables from spec implemented
+- [ ] All deliverables from plan implemented
 - [ ] Code follows project coding standards
 - [ ] Linting passes
 - [ ] Code is documented
+- [ ] Implementation walkthrough created
 
 **⛔ HUMAN Checkpoint**: Present implementation summary and **STOP**. Wait for user to confirm before proceeding to Stage 3.
 
@@ -180,11 +248,11 @@ created: {timestamp}
 1 - **Write unit tests**: Test individual functions/components
 2 - **Write integration tests**: Test API endpoints or component interactions
 3 - **Run test suite**: Execute all tests
-4 - **Verify acceptance criteria**: Check against spec
+4 - **Verify acceptance criteria**: Check against plan
 5 - **Document results**: Create test report
 
-**Artifact**: `test-report.md`
-**Location**: `memory-bank/bolts/{bolt-id}/test-report.md`
+**Artifact**: `test-walkthrough.md`
+**Location**: `memory-bank/bolts/{bolt-id}/test-walkthrough.md`
 
 **Template Structure**:
 
@@ -231,9 +299,9 @@ Bolt instance tracks progress:
 ---
 current_stage: implement
 stages_completed:
-  - name: spec
+  - name: plan
     completed: 2024-12-05T10:00:00Z
-    artifact: spec.md
+    artifact: implementation-plan.md
 status: in-progress
 ---
 ```
@@ -249,9 +317,10 @@ For Stage 2 (Implement) and Stage 3 (Test), load all artifacts from the bolt fol
 **Load all files in this folder**, which may include:
 
 - `bolt.md` - Bolt instance metadata
-- `spec.md` - Spec from Stage 1
+- `implementation-plan.md` - Plan from Stage 1
+- `implementation-walkthrough.md` - Developer notes from Stage 2 (if exists)
 
-This ensures implementation and test stages have context from the spec.
+This ensures later stages have full context from earlier work.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.34",
+  "version": "0.1.0",
   "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": {
@@ -10,8 +10,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:schema": "vitest run __tests__/unit/schema-validation/",
-    "lint:md": "markdownlint '../memory-bank/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml",
-    "lint:md:fix": "markdownlint '../memory-bank/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
+    "lint:md": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml",
+    "lint:md:fix": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
     "validate:all": "npm run test && npm run lint:md"
   },
   "keywords": [