specsmd 0.0.0-dev.21 → 0.0.0-dev.22

package/flows/aidlc/commands/construction-agent.md

@@ -29,7 +29,7 @@ You are now the **Construction Agent** for specsmd AI-DLC.
 1. **Read Schema**: `.specsmd/aidlc/memory-bank.yaml`
 2. **Verify Unit**: Check unit exists and has completed inception
 3. **Load Bolts**: Find bolts for this unit
-4. **Determine State**: Check which bolts are planned/in-progress/completed
+4. **Determine State**: Check which bolts are planned/in-progress/complete
 5. **Present Menu or Continue**: Show status or continue active bolt
 
 ---

package/flows/aidlc/memory-bank.yaml

@@ -81,13 +81,14 @@ schema:
   story-index: "memory-bank/story-index.md"
   inception-log: "memory-bank/intents/{intent-name}/inception-log.md"
   construction-log: "memory-bank/intents/{intent-name}/units/{unit-name}/construction-log.md"
+  decision-index: "memory-bank/standards/decision-index.md"
 
   # Agent Ownership
   # Note: Both Inception and Construction can plan/create bolts
   # Inception: initial planning, Construction: replanning during execution
   ownership:
     inception: [intents, units, stories, story-index, bolts]  # Plans bolts initially
-    construction: [units, bolts]                               # Executes and can replan bolts
+    construction: [units, bolts, decision-index]               # Executes, can replan bolts, maintains decision index
     operations: [operations]
 
 # Global Story Index Options

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

@@ -52,7 +52,7 @@ For each bolt, determine progress:
 
 - **planned**: 0% - Not started
 - **in-progress**: `stages_completed / total_stages`
-- **completed**: 100%
+- **complete**: 100%
 - **blocked**: Show blocker reason
 
 ### 5. Display Results

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

@@ -81,7 +81,7 @@ Check for issues:
 - **Unit**: `{unit-name}`
 - **Intent**: `{intent-name}`
 - **Type**: {bolt-type}
-- **Status**: {planned|in-progress|completed|blocked}
+- **Status**: {planned|in-progress|complete|blocked}
 
 ### Progress
 [██████████░░░░░░░░░░] 50% (2/4 stages)

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

@@ -53,7 +53,7 @@ For recent/active intents:
 Check `schema.bolts` directory:
 
 - Are there bolt instance files?
-- What is their status? (planned, in-progress, completed)
+- What is their status? (planned, in-progress, complete)
 - What stage are in-progress bolts at?
 
 ### 5. Determine Phase

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

@@ -67,7 +67,7 @@ Before creating a bolt, verify ALL required fields are present:
 | `unit` | **YES** | Parent unit ID |
 | `intent` | **YES** | Parent intent ID |
 | `type` | **YES** | Bolt type (`ddd-construction-bolt` or `simple-construction-bolt`) |
-| `status` | **YES** | Current status (`planned`, `in-progress`, `completed`, `blocked`) |
+| `status` | **YES** | Current status (`planned`, `in-progress`, `complete`, `blocked`) |
 | `stories` | **YES** | Array of story IDs included in this bolt |
 | `created` | **YES** | Creation timestamp |
 | `requires_bolts` | **YES** | Array of bolt IDs this depends on (can be empty `[]`) |
@@ -134,7 +134,7 @@ Before creating a bolt, verify ALL required fields are present:
 
 - **planned**: Bolt created, not started
 - **in-progress**: Currently being executed
-- **completed**: All stages done
+- **complete**: All stages done
 - **blocked**: Cannot proceed due to dependency
 
 ---

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

@@ -272,6 +272,7 @@ Suggest an ADR when you identify:
 3 - **Identify ADR-worthy decisions**: Create decision list
 4 - **Present opportunities to user**: Get user selection
 5 - **Create ADR documents**: Generate selected ADRs
+6 - **Update decision index**: Add entries to `memory-bank/standards/decision-index.md`
 
 **Artifact**: `adr-{number}-{slug}.md` (zero or more)
 **Template**: `.specsmd/aidlc/templates/construction/bolt-types/ddd-construction-bolt/adr-template.md`
@@ -282,7 +283,8 @@ Suggest an ADR when you identify:
 1. Review stories, domain model, and technical design
 2. Compare against loaded project standards
 3. If decision-worthy patterns detected, present opportunities to user
-4. Handle user response and proceed to checkpoint
+4. Handle user response (create selected ADRs or skip)
+5. Update decision index (if ADRs created) and proceed to checkpoint
 
 **Step 3 Output Format**:
 
@@ -299,10 +301,35 @@ Would you like to create ADRs for any of these? (Enter numbers, "all", or "skip"
 
 **Step 4 Decision Handling**:
 
-- **User selects numbers or "all"** → Generate ADRs using template, then proceed to checkpoint
+- **User selects numbers or "all"** → Generate ADRs using template, then update decision index
 - **User selects "skip"** → Proceed to checkpoint with "No ADRs created"
 - **No ADR opportunities identified** → Auto-proceed to checkpoint with "No ADR-worthy decisions found"
 
+**Step 5 Decision Index Update**:
+
+For each ADR created, add an entry to `memory-bank/standards/decision-index.md`:
+
+1. If `decision-index.md` doesn't exist, create it from template: `.specsmd/aidlc/templates/standards/decision-index-template.md`
+2. Add entry for each ADR in the following format:
+
+```markdown
+### ADR-{n}: {title}
+- **Status**: {status from ADR frontmatter}
+- **Date**: {YYYY-MM-DD from ADR created timestamp}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context section}. {First sentence from Decision section}.
+- **Read when**: {Generate guidance based on the ADR's domain - describe scenarios when agents should read this ADR}
+```
+
+3. Update frontmatter: increment `total_decisions`, update `last_updated` timestamp
+
+**"Read when" Guidance Examples**:
+- "Working on authentication flows or session management"
+- "Implementing caching strategies or data persistence patterns"
+- "Designing API contracts or integration points"
+- "Handling error cases or implementing retry logic"
+
 **Example ADR**:
 
 ```markdown
@@ -330,6 +357,7 @@ Implement CQRS pattern with separate read models for task queries.
 - [ ] Project standards compared
 - [ ] User presented with ADR opportunities (if any)
 - [ ] Selected ADRs created (or explicitly skipped)
+- [ ] Decision index updated (if ADRs were created)
 
 **Important**: Do not force ADRs. Only suggest when there's genuine value. Simple bolts with straightforward decisions don't need ADRs.
 
@@ -495,6 +523,34 @@ status: in-progress
 
 ## Bolt Context Loading
 
+### Prior Decision Lookup (All Stages)
+
+**Before starting any stage**, scan the decision index for relevant prior ADRs:
+
+1. Read `memory-bank/standards/decision-index.md` (if it exists)
+2. Match the current bolt's domain/scope against "Read when" fields
+3. Load full ADRs for any matching entries
+4. Consider these decisions as constraints or guidance for the current work
+
+**Example**: If working on a bolt for "user-service" and the decision index contains:
+```
+### ADR-001: Use JWT for Authentication
+- **Read when**: Working on authentication flows or user services
+```
+→ Load and consider `ADR-001` before starting design work.
+
+**Present relevant ADRs to user** at bolt start:
+```
+## Relevant Prior Decisions
+
+Found {n} ADR(s) that may apply to this bolt:
+- ADR-001: Use JWT for Authentication → [View](bolts/001-auth-service/adr-001-jwt-auth.md)
+
+These decisions may constrain or guide your approach. Proceed? (y/n)
+```
+
+### Bolt Folder Artifacts (Stages 4-5)
+
 For stages that build on previous work (Stage 4: Implement, Stage 5: Test), load all artifacts from the bolt folder:
 
 **Location**: `memory-bank/bolts/{bolt-id}/`
@@ -515,14 +571,16 @@ This ensures the implementation and test stages have full context from earlier d
 1. **Load bolt instance** from path defined by `schema.bolts`
 2. **Read `bolt_type` field** (e.g., `ddd-construction-bolt`)
 3. **Load this definition** from `.specsmd/aidlc/templates/construction/bolt-types/`
-4. **Check `current_stage`** in bolt instance
-5. **Load bolt folder artifacts** if stage requires previous context (see Bolt Context Loading)
-6. **Execute stage** following activities defined here
-7. **Create artifacts** using templates
-8. **⛔ STOP and present completion summary** - DO NOT continue automatically
-9. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
-10. **Only after approval**: Update bolt state and advance to next stage
-
-**⛔ CRITICAL**: Steps 8-9 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
+4. **Scan decision index** for relevant prior ADRs (see Prior Decision Lookup)
+5. **Present relevant ADRs** to user if any found, get confirmation to proceed
+6. **Check `current_stage`** in bolt instance
+7. **Load bolt folder artifacts** if stage requires previous context (see Bolt Folder Artifacts)
+8. **Execute stage** following activities defined here
+9. **Create artifacts** using templates
+10. **⛔ STOP and present completion summary** - DO NOT continue automatically
+11. **Wait for user confirmation** - user must explicitly approve (e.g., "continue", "proceed", "next")
+12. **Only after approval**: Update bolt state and advance to next stage
+
+**⛔ CRITICAL**: Steps 10-11 are MANDATORY. Never skip the human checkpoint. Never auto-advance.
 
 The Construction Agent is **bolt-type agnostic** - it reads stages from this file and executes them.

package/flows/aidlc/templates/standards/decision-index-template.md

@@ -0,0 +1,32 @@
+---
+last_updated: {YYYY-MM-DDTHH:MM:SSZ}
+total_decisions: 0
+---
+
+# Decision Index
+
+This index tracks all Architecture Decision Records (ADRs) created during Construction bolts.
+Use this to find relevant prior decisions when working on related features.
+
+## How to Use
+
+**For Agents**: Scan the "Read when" fields below to identify decisions relevant to your current task. Before implementing new features, check if existing ADRs constrain or guide your approach. Load the full ADR for matching entries.
+
+**For Humans**: Browse decisions chronologically or search for keywords. Each entry links to the full ADR with complete context, alternatives considered, and consequences.
+
+---
+
+## Decisions
+
+<!-- Entries are appended below in reverse chronological order (newest first) -->
+<!-- Format for each entry:
+
+### ADR-{n}: {title}
+- **Status**: {proposed|accepted|deprecated|superseded}
+- **Date**: {YYYY-MM-DD}
+- **Bolt**: {bolt-id} ({unit-name})
+- **Path**: `bolts/{bolt-id}/adr-{n}-{slug}.md`
+- **Summary**: {First sentence from Context}. {First sentence from Decision}.
+- **Read when**: {Agent guidance - domain keywords and scenarios when this ADR is relevant}
+
+-->

package/package.json

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