specsmd 0.0.0-dev.78 → 0.0.0-dev.79

package/README.md

@@ -4,9 +4,9 @@
   <img src="images/specs_md_pixel_logo.png" alt="specs.md logo" width="400" />
 </p>
 
-**AI-native software development with multi-agent orchestration.**
+**AI-native development framework with pluggable flows for every use case.**
 
-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.
+Choose the flow that matches your project needs: **Simple** for quick specs, **FIRE** for adaptive execution, or **AI-DLC** for full methodology with DDD.
 
 [![npm version](https://img.shields.io/npm/v/specsmd)](https://www.npmjs.com/package/specsmd)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -20,14 +20,29 @@ 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.
+Track your progress with our sidebar extension for VS Code and compatible IDEs.
+
+**AI-DLC Flow:**
+
+<p align="center">
+  <img src="vs-code-extension/resources/extension-preview.png" alt="AI-DLC Flow Extension Preview" width="800" />
+</p>
+
+**FIRE Flow:**
 
 <p align="center">
-  <img src="vs-code-extension/resources/extension-preview.png" alt="VS Code Extension Preview" width="800" />
+  <img src="images/fire1.png" alt="FIRE Flow - Intents View" width="400" />
+  <img src="images/fire3.png" alt="FIRE Flow - Runs View" width="400" />
 </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.
 
+**Features:**
+- Flow switcher for AI-DLC and FIRE views
+- Active run/bolt tracking with progress indicators
+- Intent and work item visualization
+- Click-to-open spec files
+
 **Install from:**
 - [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd) — VS Code, GitHub Codespaces
 - [Open VSX Registry](https://open-vsx.org/extension/fabriqaai/specsmd) — Cursor, Windsurf, Amazon Kiro, Google Antigravity, VSCodium, Gitpod, Google IDX
@@ -35,6 +50,18 @@ Track your AI-DLC progress with our sidebar extension for VS Code and compatible
 
 ---
 
+## Three Flows, Every Use Case
+
+| Flow | Optimized For | Agents | Checkpoints |
+|------|---------------|--------|-------------|
+| **[Simple](#simple-flow)** | Spec generation, prototypes | 1 | 3 (phase gates) |
+| **[FIRE](#fire-flow)** | Adaptive execution, brownfield, monorepos | 3 | Adaptive (0-2) |
+| **[AI-DLC](#ai-dlc-flow)** | Full traceability, DDD, regulated environments | 4 | Comprehensive |
+
+> **Not sure which flow?** If you want quick specs without execution tracking, use **Simple**. If you want adaptive execution that right-sizes rigor, use **FIRE**. If you need comprehensive documentation and DDD, use **AI-DLC**.
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -45,275 +72,177 @@ Track your AI-DLC progress with our sidebar extension for VS Code and compatible
 ### Installation
 
 > [!NOTE]
-> Do not use npm if you want to always get the latest version. Use the npx command below.
+> Always use npx to get the latest version. Do not install globally with npm.
 
 ```bash
 npx specsmd@latest install
 ```
 
-The installer detects your AI coding tools (Claude Code, Cursor, GitHub Copilot) and sets up:
-- Agent definitions and skills
-- Memory bank structure for context persistence
-- Slash commands for easy agent invocation
+During installation, select your flow:
 
-### Verify Installation
-
-```bash
-# Check the manifest
-cat .specsmd/manifest.yaml
-
-# List installed agents
-ls .specsmd/aidlc/agents/
 ```
-
-### Initialize Your Project
-Open your AI Assisted Tool (Claude Code, Cursor, GitHub Copilot) and run the following commands:
-
-```bash
-# Start the Master Agent
-/specsmd-master-agent
-
-# Then type:
-project-init
+? Select a development flow:
+  Simple - Spec generation only (requirements, design, tasks)
+❯ FIRE - Adaptive execution, brownfield & monorepo ready
+  AI-DLC - Full methodology with DDD (comprehensive checkpoints)
 ```
 
-This guides you through establishing:
-- **Tech Stack** - Languages, frameworks, databases, infrastructure
-- **Coding Standards** - Formatting, linting, naming, testing strategy
-- **System Architecture** - Architecture style, API design, state management
-- **UX Guide** - Design system, styling, accessibility (optional)
-- **API Conventions** - API style, versioning, response formats (optional)
+The installer detects your AI coding tools and sets up agent definitions, slash commands, and project structure for your selected flow.
 
-### Create Your First Intent
+### Install VS Code Extension (Optional)
 
-```bash
-/specsmd-inception-agent intent-create
-```
-
-An **Intent** is your high-level goal:
-- "User authentication system"
-- "Product catalog with search"
-- "Payment processing integration"
-
-The agent will:
-1. Ask clarifying questions to minimize ambiguity
-2. Elaborate into user stories and NFRs
-3. Define system context
-4. Decompose into loosely-coupled units
+Track your progress visually with our sidebar extension:
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd) — VS Code, GitHub Codespaces
+- [Open VSX Registry](https://open-vsx.org/extension/fabriqaai/specsmd) — Cursor, Windsurf, Amazon Kiro, Google Antigravity
 
-### Plan and Execute Bolts
+### Verify Installation
 
 ```bash
-# Plan bolts for your stories
-/specsmd-inception-agent bolt-plan
+# Check the manifest
+cat .specsmd/manifest.yaml
 
-# Execute a bolt
-/specsmd-construction-agent bolt-start
+# List installed agents (adjust path for your flow)
+ls .specsmd/fire/agents/     # FIRE flow
+ls .specsmd/simple/agents/   # Simple flow
+ls .specsmd/aidlc/agents/    # AI-DLC flow
 ```
 
-Each bolt goes through validated stages:
-1. **Domain Model** - Model business logic using DDD principles
-2. **Technical Design** - Apply patterns and make architecture decisions
-3. **ADR Analysis** - Document significant decisions (optional)
-4. **Implement** - Generate production code
-5. **Test** - Verify correctness with automated tests
-
-**Human validation happens at each stage gate.**
-
 ---
 
-## What is AI-DLC?
-
-AI-DLC is a reimagined software development methodology where **AI drives the conversation** and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in **Bolts** - rapid iterations measured in hours or days.
+## Simple Flow
 
-> "Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."
-
-### AI-DLC vs Traditional Methods
-
-| Aspect | Agile/Scrum | AI-DLC |
-|--------|-------------|--------|
-| Iteration duration | Weeks (Sprints) | Hours/days (Bolts) |
-| Who drives | Human-driven, AI assists | AI-driven, human-validated |
-| Design techniques | Out of scope | Integrated (DDD, TDD, BDD) |
-| Task decomposition | Manual | AI-powered |
-| Phases | Repeating sprints | Rapid three-phase cycles (Inception → Construction → Operations) |
-| Rituals | Daily standups, retrospectives | Mob Elaboration, Mob Construction |
-
----
+**Spec generation only.** Generate requirements, design, and task documents without execution tracking.
 
-## How It Works
-
-specsmd provides four specialized agents that guide you through the entire development lifecycle:
+```
+/specsmd-agent
+```
 
-```mermaid
-flowchart TB
-    MA[Master Agent<br/>Orchestrates & Navigates] --> IA[Inception Agent]
-    MA --> CA[Construction Agent]
-    MA --> OA[Operations Agent]
+**Three Phases:**
+1. **Requirements** → `requirements.md` - User stories, EARS criteria
+2. **Design** → `design.md` - Technical design, architecture diagrams
+3. **Tasks** → `tasks.md` - Implementation checklist
 
-    IA --> CA --> OA
+**Best for:** Prototypes, MVPs, spec handoff, projects that don't need AI-assisted execution.
 
-    style MA fill:#8B5CF6,stroke:#7C3AED,color:#fff
-    style IA fill:#818CF8,stroke:#6366F1,color:#fff
-    style CA fill:#34D399,stroke:#10B981,color:#fff
-    style OA fill:#FBBF24,stroke:#F59E0B,color:#fff
+**Output structure:**
+```
+specs/
+└── {feature-name}/
+    ├── requirements.md
+    ├── design.md
+    └── tasks.md
 ```
 
-### The Three Phases
-
-| Phase | Agent | Purpose | Key Outputs |
-|-------|-------|---------|-------------|
-| **Inception** | Inception Agent | Capture intents, elaborate requirements, decompose into units | User stories, NFRs, Unit definitions, Bolt plans |
-| **Construction** | Construction Agent | Execute bolts through domain design → logical design → code → test | Domain models, Technical designs, Code, Tests |
-| **Operations** | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |
+[Simple Flow Documentation →](https://specs.md/simple-flow/overview)
 
 ---
 
-## Key Concepts
+## FIRE Flow
 
-### Intent
-A high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.
+**Fast Intent-Run Engineering.** Adaptive execution with brownfield and monorepo support. Ships in hours with 0-2 checkpoints based on task complexity.
 
-### Unit
-A cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently. Analogous to a Subdomain (DDD) or Epic (Scrum).
+```
+/fire-orchestrator   # Entry point, routing
+/fire-planner        # Intent capture, work item decomposition
+/fire-builder        # Run execution, walkthrough generation
+```
 
-### Bolt
-The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are **hours to days**. Each bolt encapsulates a well-defined scope of work.
+**Key Features:**
+- **Adaptive checkpoints** - Autopilot (0), Confirm (1), or Validate (2) based on complexity
+- **First-class brownfield** - Auto-detects existing patterns and conventions
+- **Monorepo support** - Hierarchical standards with module-specific overrides
+- **Walkthrough generation** - Documents every change automatically
 
-| Type | Best For | Stages |
-|------|----------|--------|
-| **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
-| **Simple Construction** | UI, integrations, utilities | Plan → Implement → Test |
+**Best for:** Teams who hate friction, brownfield projects, monorepos.
 
-### Memory Bank
-File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.
+**Output structure:**
+```
+.specs-fire/
+├── state.yaml           # Central state tracking
+├── standards/           # Project standards
+├── intents/             # Intent documentation
+├── runs/                # Run logs
+└── walkthroughs/        # Generated documentation
+```
 
-### Standards
-Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.
+[FIRE Flow Documentation →](https://specs.md/fire-flow/overview)
 
 ---
 
-<details>
-<summary><h2>Project Structure</h2></summary>
+## AI-DLC Flow
 
-After installation:
+**Full methodology.** Implements the [AI-Driven Development Lifecycle](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) with Domain-Driven Design and comprehensive traceability.
 
 ```
-.specsmd/
-├── manifest.yaml              # Installation manifest
-└── aidlc/                     # AI-DLC flow
-    ├── agents/                # Agent definitions
-    ├── skills/                # Agent capabilities
-    ├── templates/             # Artifact templates
-    │   └── standards/         # Standards facilitation guides
-    └── memory-bank.yaml       # Memory bank schema
-
-memory-bank/                   # Created after project-init
-├── intents/                   # Your captured intents
-│   └── {intent-name}/
-│       ├── requirements.md
-│       ├── system-context.md
-│       └── units/
-├── bolts/                     # Bolt execution records
-├── standards/                 # Project standards
-│   ├── tech-stack.md
-│   ├── coding-standards.md
-│   └── ...
-└── operations/                # Deployment context
+/specsmd-master-agent       # Orchestrates & navigates
+/specsmd-inception-agent    # Requirements, stories, bolt planning
+/specsmd-construction-agent # Execute bolts through DDD stages
+/specsmd-operations-agent   # Deploy, verify, monitor
 ```
 
-</details>
+**Three Sequential Phases:**
+1. **Inception** - Capture intents, elaborate requirements, decompose into units
+2. **Construction** - Execute bolts: Model → Design → ADR → Implement → Test
+3. **Operations** - Deploy, verify, and monitor
 
-<details>
-<summary><h2>Agent Commands</h2></summary>
+**Best for:** Complex domains, multi-team coordination, regulated environments.
 
-### Master Agent
-```bash
-/specsmd-master-agent
+**Output structure:**
 ```
-| Command | Purpose |
-|---------|---------|
-| `project-init` | Initialize project with standards |
-| `analyze-context` | View current project state |
-| `route-request` | Get directed to the right agent |
-| `explain-flow` | Learn about AI-DLC methodology |
-| `answer-question` | Get help with any specsmd question |
-
-### Inception Agent
-```bash
-/specsmd-inception-agent
-```
-| Command | Purpose |
-|---------|---------|
-| `intent-create` | Create a new intent |
-| `intent-list` | List all intents |
-| `requirements` | Elaborate intent requirements |
-| `context` | Define system context |
-| `units` | Decompose into units |
-| `story-create` | Create stories for a unit |
-| `bolt-plan` | Plan bolts for stories |
-| `review` | Review inception artifacts |
-
-### Construction Agent
-```bash
-/specsmd-construction-agent
-```
-| Command | Purpose |
-|---------|---------|
-| `bolt-start` | Start/continue executing a bolt |
-| `bolt-status` | Check bolt progress |
-| `bolt-list` | List all bolts |
-| `bolt-replan` | Replan bolts if needed |
-
-### Operations Agent
-```bash
-/specsmd-operations-agent
+memory-bank/
+├── standards/           # Project standards
+├── intents/             # Intent documentation
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       └── units/
+├── bolts/               # Bolt execution records
+└── operations/          # Deployment context
 ```
-| Command | Purpose |
-|---------|---------|
-| `build` | Build the project |
-| `deploy` | Deploy to environment |
-| `verify` | Verify deployment |
-| `monitor` | Set up monitoring |
 
-</details>
+[AI-DLC Flow Documentation →](https://specs.md/aidlc/overview)
 
 ---
 
-## Why specsmd?
+## Why specs.md?
 
-### AI-Native, Not AI-Retrofitted
-Built from the ground up for AI-driven development. AI-DLC is a reimagination based on first principles, not a retrofit of existing methods.
+### Three Flows for Every Use Case
+From quick specs (Simple) to adaptive execution (FIRE) to full methodology (AI-DLC). Choose the flow that matches your project needs.
 
-### Human Oversight as Loss Function
-Validation at each stage catches errors early before they cascade downstream. Each validation transforms artifacts into rich context for subsequent stages.
+### Adaptive Checkpoints (FIRE)
+Right-sizes the rigor. Simple bug fixes burn through fast. Critical changes get design review. You configure your autonomy preference.
 
-### Design Techniques Built-In
-DDD, TDD, and BDD are integral to the methodology - not optional add-ons. This addresses the "whitespace" in Agile that has led to quality issues.
+### First-Class Brownfield & Monorepo (FIRE)
+Auto-detects existing patterns and respects your conventions. Hierarchical standards with module-specific overrides.
+
+### Full DDD Methodology (AI-DLC)
+Domain-Driven Design is integral to Construction, not an optional add-on. Every decision documented with full traceability.
 
 ### Tool Agnostic
-Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
+Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere—no vendor lock-in.
 
 ### Context Engineering
-Specs and Memory Bank provide structured context for AI agents. Agents reload context each session - no more lost knowledge.
+Structured artifacts provide persistent context for AI agents. Agents reload context each session—no more lost knowledge.
 
 ---
 
 ## Supported Tools
 
-| Tool | Status | Installation |
-|------|--------|--------------|
-| **Claude Code** | Full support | Slash commands in `.claude/commands/` |
-| **Cursor** | Full support | Rules in `.cursor/rules/` (`.mdc` format) |
-| **GitHub Copilot** | Full support | Agents in `.github/agents/` (`.agent.md` format) |
-| **Google Antigravity** | Full support | Agents in `.agent/agents/` |
-| **Windsurf** | Full support | Workflows in `.windsurf/workflows/` |
-| **Amazon Kiro** | Full support | Steering in `.kiro/steering/` |
-| **Gemini CLI** | Full support | Commands in `.gemini/commands/` (`.toml` format) |
-| **Cline** | Full support | Rules in `.clinerules/` |
-| **Roo Code** | Full support | Commands in `.roo/commands/` |
-| **OpenAI Codex** | Full support | Config in `.codex/` |
-| **OpenCode** | Full support | Agents in `.opencode/agent/` |
+specs.md is **IDE and AI-agnostic**—your specs and agents are portable markdown files that work anywhere.
+
+| Tool | Integration |
+|------|-------------|
+| **Claude Code** | Slash commands in `.claude/commands/` |
+| **Cursor** | Rules in `.cursor/rules/` (`.mdc` format) |
+| **GitHub Copilot** | Agents in `.github/agents/` (`.agent.md` format) |
+| **Google Antigravity** | Agents in `.agent/agents/` |
+| **Windsurf** | Rules in `.windsurf/rules/` |
+| **Amazon Kiro** | Steering in `.kiro/steering/` |
+| **Gemini CLI** | Commands in `.gemini/commands/` (`.toml` format) |
+| **Cline** | Rules in `.clinerules/` |
+| **Roo Code** | Commands in `.roo/commands/` |
+| **OpenAI Codex** | Config in `.codex/` |
+| **OpenCode** | Agents in `.opencode/agent/` |
 
 ---
 
@@ -324,7 +253,10 @@ Specs and Memory Bank provide structured context for AI agents. Agents reload co
 
 Ensure specs.md is installed correctly:
 ```bash
-ls .specsmd/aidlc/agents/
+# Check for your flow
+ls .specsmd/fire/agents/     # FIRE
+ls .specsmd/simple/agents/   # Simple
+ls .specsmd/aidlc/agents/    # AI-DLC
 ```
 
 If the directory is empty or missing, reinstall:
@@ -334,33 +266,26 @@ npx specsmd@latest install
 </details>
 
 <details>
-<summary><strong>Memory Bank artifacts missing</strong></summary>
+<summary><strong>Project artifacts missing</strong></summary>
 
-Check if the memory-bank directory exists:
+Check if the artifacts directory exists for your flow:
 ```bash
-ls memory-bank/
+ls .specs-fire/    # FIRE flow
+ls specs/          # Simple flow
+ls memory-bank/    # AI-DLC flow
 ```
 
-If missing, run project initialization:
-```
-/specsmd-master-agent
-> project-init
-```
+If missing, initialize your project using the appropriate agent.
 </details>
 
 <details>
 <summary><strong>Standards not being followed in generated code</strong></summary>
 
-Ensure standards are defined in `memory-bank/standards/`:
-- `tech-stack.md`
-- `coding-standards.md`
-- `architecture.md`
+Ensure standards are defined in your flow's standards directory:
+- FIRE: `.specs-fire/standards/`
+- AI-DLC: `memory-bank/standards/`
 
-If missing or incomplete, use the Master Agent to define them:
-```
-/specsmd-master-agent
-> project-init
-```
+Run project initialization if missing.
 </details>
 
 ---
@@ -368,17 +293,27 @@ If missing or incomplete, use the Master Agent to define them:
 <details>
 <summary><h2>FAQ</h2></summary>
 
+**Q: Which flow should I choose?**
+- **Simple**: Spec generation only, no execution tracking
+- **FIRE**: Adaptive execution, brownfield/monorepo support
+- **AI-DLC**: Full methodology with DDD and comprehensive traceability
+
+**Q: Can I switch flows after installation?**
+Flows are independent—they're not an upgrade path. Each is designed for different use cases. You can reinstall to change flows, but artifacts are structured differently.
+
 **Q: Agents don't seem to remember previous context?**
-Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
+Each agent invocation starts fresh. Agents read context from artifacts at startup. Ensure artifacts are saved after each step.
 
 **Q: How do I reset project state?**
-Clear the `memory-bank/` directory to reset all artifacts. To remove specsmd entirely, delete the `.specsmd/` directory and tool-specific command files.
+Delete the artifacts directory for your flow:
+- FIRE: `.specs-fire/`
+- Simple: `specs/`
+- AI-DLC: `memory-bank/`
 
-**Q: Can I use specsmd with existing Agile workflows?**
-AI-DLC is designed as a reimagination, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.
+To remove specsmd entirely, also delete `.specsmd/` and tool-specific command files.
 
 **Q: What project types is this suited for?**
-specsmd is designed for building complex systems that demand architectural complexity, trade-off management, and scalability. Simpler systems may be better suited for low-code/no-code approaches.
+specs.md supports everything from quick prototypes (Simple) to complex enterprise systems (AI-DLC). Choose the flow that matches your project needs.
 
 </details>
 
@@ -387,10 +322,11 @@ specsmd is designed for building complex systems that demand architectural compl
 ## Resources
 
 - [Documentation](https://specs.md)
+- [Choose Your Flow Guide](https://specs.md/architecture/choose-flow)
 - [AI-DLC Specification (AWS)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)
 - [npm Package](https://www.npmjs.com/package/specsmd)
-- [GitHub Issues](https://github.com/fabriqaai/specsmd/issues)
-
+- [GitHub Issues](https://github.com/fabriqaai/specs.md/issues)
+- [Discord Community](http://discord.specs.md/)
 
 ---
 
@@ -401,5 +337,5 @@ MIT License - see [LICENSE](LICENSE) for details.
 ---
 
 <p align="center">
-  Built with AWS' AI-DLC methodology by the <a href="https://specs.md">specs.md</a> team.
+  Built by the <a href="https://specs.md">specs.md</a> team.
 </p>

package/flows/aidlc/scripts/{artifact-validator.js → artifact-validator.cjs}

@@ -10,9 +10,9 @@
  * - Timestamp format (ISO 8601 without milliseconds)
  *
  * Usage:
- *   node .specsmd/aidlc/scripts/artifact-validator.js
- *   node .specsmd/aidlc/scripts/artifact-validator.js --json
- *   node .specsmd/aidlc/scripts/artifact-validator.js --fix
+ *   node .specsmd/aidlc/scripts/artifact-validator.cjs
+ *   node .specsmd/aidlc/scripts/artifact-validator.cjs --json
+ *   node .specsmd/aidlc/scripts/artifact-validator.cjs --fix
  *
  * Cross-platform: Works on Linux, macOS, Windows via Node.js
  */

package/flows/aidlc/scripts/{bolt-complete.js → bolt-complete.cjs}

@@ -115,11 +115,11 @@
  *
  *   From agent skill (bolt-start.md Step 10):
  *
- *     node .specsmd/aidlc/scripts/bolt-complete.js 016-analytics-tracker
+ *     node .specsmd/aidlc/scripts/bolt-complete.cjs 016-analytics-tracker
  *
  *   With optional stage name:
  *
- *     node .specsmd/aidlc/scripts/bolt-complete.js 016-analytics-tracker --last-stage test
+ *     node .specsmd/aidlc/scripts/bolt-complete.cjs 016-analytics-tracker --last-stage test
  *
  * ═══════════════════════════════════════════════════════════════════════════════
  */
@@ -594,7 +594,7 @@ const lastStage = process.argv['--last-stage'] || null;
 
 if (!boltId) {
     console.error(`${colors.red}Error:${colors.reset} Bolt ID required`);
-    console.error(`${colors.dim}Usage: node bolt-complete.js <bolt-id> [--last-stage <stage-name>]${colors.reset}`);
+    console.error(`${colors.dim}Usage: node bolt-complete.cjs <bolt-id> [--last-stage <stage-name>]${colors.reset}`);
     process.exit(1);
 }
 

package/flows/aidlc/scripts/{status-integrity.js → status-integrity.cjs}

@@ -7,8 +7,8 @@
  * Status must cascade correctly: Bolt complete → Stories complete → Unit complete → Intent complete
  *
  * Usage:
- *   node .specsmd/aidlc/scripts/status-integrity.js
- *   node .specsmd/aidlc/scripts/status-integrity.js --fix
+ *   node .specsmd/aidlc/scripts/status-integrity.cjs
+ *   node .specsmd/aidlc/scripts/status-integrity.cjs --fix
  *
  * Cross-platform: Works on Linux, macOS, Windows via Node.js
  */
@@ -577,15 +577,15 @@ const shouldFix = args.includes('--fix') || args.includes('-f');
 
 if (args.includes('--help') || args.includes('-h')) {
     console.log(`
-Usage: node status-integrity.js [options]
+Usage: node status-integrity.cjs [options]
 
 Options:
   --fix, -f    Automatically fix status inconsistencies
   --help, -h   Show this help message
 
 Examples:
-  node .specsmd/aidlc/scripts/status-integrity.js
-  node .specsmd/aidlc/scripts/status-integrity.js --fix
+  node .specsmd/aidlc/scripts/status-integrity.cjs
+  node .specsmd/aidlc/scripts/status-integrity.cjs --fix
 `);
     process.exit(0);
 }

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

@@ -194,7 +194,7 @@ If the bolt type specifies automatic validation criteria, follow those rules.
 ┌─────────────────────────────────────────────────────────────┐
 │  FINAL STAGE DETECTED                                       │
 │  → Re-read Step 10 NOW                                     │
-│  → You MUST run: node .specsmd/aidlc/scripts/bolt-complete.js │
+│  → You MUST run: node .specsmd/aidlc/scripts/bolt-complete.cjs │
 │  → Do NOT manually edit story files                        │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -235,7 +235,7 @@ stages_completed:
 ⛔ HARD GATE - SCRIPT EXECUTION REQUIRED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 You CANNOT report bolt completion without:
-1. Running the bolt-complete.js script
+1. Running the bolt-complete.cjs script
 2. Showing the script output to the user
 
 If you skip this, the memory-bank becomes inconsistent.
@@ -245,7 +245,7 @@ Do NOT manually edit story files - the script handles everything.
 **Run this command:**
 
 ```bash
-node .specsmd/aidlc/scripts/bolt-complete.js {bolt-id}
+node .specsmd/aidlc/scripts/bolt-complete.cjs {bolt-id}
 ```
 
 **What this command does (deterministically):**