mspec 0.0.8 → 0.0.9

package/README.md

@@ -67,7 +67,7 @@ Once you are happy with the spec, use the planning command to break it down.
 
 **Command:**
 ```text
-/mspec.plan
+/mspec.plan 001-auth
 ```
 - If you don't provide a spec name, the AI will ask you which spec you want to plan.
 - **Sequencing:** The AI will read the spec and create a strict, logically sequenced checklist in `.mspec/tasks/001-auth.tasks.md` (Data -> Logic -> UI -> Edge Cases -> Automated Tests).
@@ -78,7 +78,7 @@ Once the checklist is generated, hand the wheel over to the AI to orchestrate th
 
 **Command:**
 ```text
-/mspec.implement
+/mspec.implement 001-auth
 ```
 - If you don't provide a spec name, the AI will ask you which spec you want to implement.
 - **Sub-Agent Delegation:** To prevent context bloat, the AI will read the first `- [ ]` task and delegate the actual coding to a sub-agent.
@@ -86,15 +86,18 @@ Once the checklist is generated, hand the wheel over to the AI to orchestrate th
 - **Empirical Verification:** The sub-agent will write the code, autonomously run your tests/linters, fix any errors, and only report back when the build is green.
 - It will change the checkbox to `- [x]` and stop to wait for your review.
 
-#### Terminal Execution (Optional)
-If you prefer, you can use the terminal CLI to generate a strict execution prompt that you can paste to your AI:
-```bash
-# Generate the prompt for one-by-one execution
-npx mspec implement 001-auth
+### Step 5: Debugging and Maintenance
+If you encounter bugs, compile errors, or failing tests (whether during implementation or in normal development), use the debug command.
 
-# Generate the prompt for batch execution (don't stop for review)
-npx mspec implement 001-auth --batch
+**Command:**
+```text
+/mspec.debug [error log or description]
 ```
+- **Context Isolation:** The AI will automatically search the codebase for the error's source and spawn an isolated sub-agent to find a fix.
+- **Repro-First:** It will create a minimal reproduction script to confirm the bug before applying a fix.
+- **Parallel Hypotheses:** If there are multiple potential causes, it can investigate them in parallel to find the solution faster!
+- **MSpec-Aware:** It will check if the bug is related to any active tasks or existing specs to ensure consistency.
+
 
 ---
 

package/dist/commands/init.test.js

@@ -28,10 +28,10 @@ describe('initCommand', () => {
         jest.restoreAllMocks();
     });
     const providers = [
-        { agent: 'claude', expectedFiles: ['.claude/commands/mspec.spec.md', '.claude/commands/mspec.plan.md', '.claude/commands/mspec.implement.md'] },
-        { agent: 'gemini', expectedFiles: ['.gemini/commands/mspec.spec.toml', '.gemini/commands/mspec.plan.toml', '.gemini/commands/mspec.implement.toml'] },
-        { agent: 'cursor', expectedFiles: ['.cursor/rules/mspec.spec.mdc', '.cursor/rules/mspec.plan.mdc', '.cursor/rules/mspec.implement.mdc'] },
-        { agent: 'opencode', expectedFiles: ['.opencode/commands/mspec.spec.md', '.opencode/commands/mspec.plan.md', '.opencode/commands/mspec.implement.md'] },
+        { agent: 'claude', expectedFiles: ['.claude/commands/mspec.spec.md', '.claude/commands/mspec.plan.md', '.claude/commands/mspec.implement.md', '.claude/commands/mspec.debug.md'] },
+        { agent: 'gemini', expectedFiles: ['.gemini/commands/mspec.spec.toml', '.gemini/commands/mspec.plan.toml', '.gemini/commands/mspec.implement.toml', '.gemini/commands/mspec.debug.toml'] },
+        { agent: 'cursor', expectedFiles: ['.cursor/rules/mspec.spec.mdc', '.cursor/rules/mspec.plan.mdc', '.cursor/rules/mspec.implement.mdc', '.cursor/rules/mspec.debug.mdc'] },
+        { agent: 'opencode', expectedFiles: ['.opencode/commands/mspec.spec.md', '.opencode/commands/mspec.plan.md', '.opencode/commands/mspec.implement.md', '.opencode/commands/mspec.debug.md'] },
         { agent: 'zed', expectedFiles: ['.mspec/INSTRUCTIONS.md'] },
         { agent: 'generic', expectedFiles: ['.mspec/INSTRUCTIONS.md'] }
     ];

package/dist/index.js

@@ -1,26 +1,22 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgram = createProgram;
 const commander_1 = require("commander");
 const init_1 = require("./commands/init");
-const plan_1 = require("./commands/plan");
-const implement_1 = require("./commands/implement");
-const program = new commander_1.Command();
-program
-    .name('mspec')
-    .description('Minimalist Spec-Driven Development CLI')
-    .version('1.0.0');
-program
-    .command('init')
-    .description('Initialize mspec in the current directory')
-    .action(init_1.initCommand);
-program
-    .command('plan <spec-name>')
-    .description('Scaffold a tasks file for a given spec')
-    .action(plan_1.planCommand);
-program
-    .command('implement <spec-name>')
-    .description('Generate execution instructions for the AI agent to implement a spec')
-    .option('-b, --batch', 'Instruct the AI to complete all tasks without stopping for approval', false)
-    .action(implement_1.implementCommand);
-program.parse(process.argv);
+const pkg = require('../package.json');
+function createProgram() {
+    const program = new commander_1.Command();
+    program
+        .name('mspec')
+        .description('Minimalist Spec-Driven Development CLI')
+        .version(pkg.version);
+    program
+        .command('init')
+        .description('Initialize mspec in the current directory')
+        .action(init_1.initCommand);
+    return program;
+}
+if (require.main === module) {
+    createProgram().parse(process.argv);
+}

package/dist/index.test.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const init_1 = require("./commands/init");
+jest.mock('./commands/init', () => ({
+    initCommand: jest.fn()
+}));
+describe('CLI index', () => {
+    it('should have correct name, description and version', () => {
+        const program = (0, index_1.createProgram)();
+        expect(program.name()).toBe('mspec');
+        expect(program.description()).toBe('Minimalist Spec-Driven Development CLI');
+        const pkg = require('../package.json');
+        expect(program.version()).toBe(pkg.version);
+    });
+    it('should have an "init" command', () => {
+        const program = (0, index_1.createProgram)();
+        const commandNames = program.commands.map(cmd => cmd.name());
+        expect(commandNames).toContain('init');
+        const initCmd = program.commands.find(cmd => cmd.name() === 'init');
+        expect(initCmd?.description()).toBe('Initialize mspec in the current directory');
+    });
+    it('should call initCommand when running "init"', async () => {
+        const program = (0, index_1.createProgram)();
+        // In commander, we can parse arguments to trigger actions.
+        // We override exitOverride to prevent the test process from exiting.
+        program.exitOverride();
+        await program.parseAsync(['node', 'mspec', 'init']);
+        expect(init_1.initCommand).toHaveBeenCalled();
+    });
+});

package/dist/prompts/implement.md

@@ -0,0 +1,9 @@
+> **mspec execution directive:**
+> Please read `.mspec/tasks/{{specName}}.tasks.md`. 
+> 1. Check if this is a resuming task or executing a blank task. If resuming, please check what is the current unstaged changes or latest commit to understand the recent progress.
+> 2. Analyze the incomplete tasks marked with `- [ ]`.
+> 3. CRITICAL: Delegate the actual coding to a sub-agent to preserve your context.
+> 4. If tasks are independent (e.g., backend/frontend), run multiple sub-agents in parallel. Otherwise, pick the first task.
+> 5. Instruct the sub-agent to implement the task, empirically verify it (run tests/build), and fix errors autonomously.
+> 6. Once the sub-agent succeeds, change the task to `- [x]` in the file.
+> 7. {{batchInstruction}}

package/dist/prompts/plan.md

@@ -0,0 +1,12 @@
+# Implementation Tasks: {{specName}}
+
+> **AI INSTRUCTION:** Read `.mspec/specs/{{specName}}.md`. Break down the requirements into granular, sequential implementation tasks below. Use checkboxes (`- [ ]`). Group by phases.
+
+## Phase 1: Setup & Scaffolding
+- [ ] ...
+
+## Phase 2: Core Logic
+- [ ] ...
+
+## Phase 3: Validation
+- [ ] ...

package/dist/templates/index.js

@@ -1,115 +1,36 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.templates = void 0;
 exports.getTemplates = getTemplates;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const loadPrompt = (name) => {
+    const filePath = path_1.default.join(__dirname, 'prompts', `${name}.md`);
+    if (!fs_1.default.existsSync(filePath)) {
+        // Fallback for cases where files are missing during dev/testing
+        return `PROMPT_ERROR: ${name}.md not found at ${filePath}`;
+    }
+    return fs_1.default.readFileSync(filePath, 'utf-8').trim();
+};
 const commandPrompts = {
     'mspec.spec': {
         desc: 'Start an inquiry to create a new spec',
-        prompt: `You are an AI Spec Architect using the mspec framework. 
-When asked to /mspec.spec, follow this strict protocol:
-
-PHASE 0: CONTEXT GATHERING
-1. Briefly analyze the project's current tech stack, existing data models, and architectural patterns. Do not guess.
-
-PHASE 1: INQUIRY
-2. DO NOT generate the specification file immediately.
-3. Ask the user between 3 to 15 targeted questions to clarify the feature, depending on the feature's ambiguity. Incorporate any context you found in Phase 0. 
-4. CRITICAL: Format EVERY question as a multiple-choice selection. Provide exactly 2 recommended options (weighing pros and cons based on the current codebase) and 1 option for a custom answer. 
-   Use this exact format for every question:
-   
-   Q[Number]: [Your Question]
-   Option A: [Recommendation 1] (Pros: ... Cons: ...)
-   Option B: [Recommendation 2] (Pros: ... Cons: ...)
-   Option C: (Custom, please type your answer)
-
-5. To build a strong spec, your questions must extract:
-   - Core Objective: What is the exact goal and business logic?
-   - Edge Cases & Error Handling: What happens on failure, empty states, or invalid input?
-   - Data Structures: What exact fields, types, and constraints are required?
-   - Dependencies: Does this rely on external APIs, existing UI components, or specific libraries?
-6. Wait for the user to answer (e.g., "Q1: A, Q2: C - use Redis instead"). 
-7. If the user provides extra context or wants to discuss further, engage in the discussion and revise your understanding.
-8. CRITICAL: Before moving to Phase 2, you MUST ask: "Are you ready for me to draft the specification based on these answers? (Please reply 'Approved' or 'LGTM')". DO NOT proceed until you get explicit approval.
-
-PHASE 2: DRAFTING
-9. Once Phase 1 is approved, generate the spec file in .mspec/specs/ using the exact filename requested or a logical slug (e.g., 001-auth.md).
-10. The spec MUST strictly follow this structure:
-   # Spec: [Feature Name]
-   ## 1. Goal & Context
-   (Clear explanation of the feature and business value)
-   ## 2. Logic Flow
-   (A Mermaid.js sequenceDiagram or stateDiagram-v2 mapping the exact logic, error states, and system boundaries)
-   ## 3. Data Dictionary
-   (A Markdown table defining schemas: Field | Type | Description | Constraints)
-   ## 4. Edge Cases & Error Handling
-   (Explicit list of what can go wrong and how the system should react)
-   ## 5. Acceptance Criteria
-   (Checklist of what must be true for this feature to be considered complete)
-11. Output the exact path to the generated spec file so the user can easily open it.
-12. CRITICAL: Stop and ask: "Please review the drafted spec file. Should I finalize this phase? (Please reply 'Approved' or 'LGTM')".
-13. If the user provides feedback, revise the spec file accordingly and ask for approval again. DO NOT proceed to Phase 3 until explicit approval is given.
-
-PHASE 3: REVIEW & HANDOFF
-14. Once the drafted spec is approved, the specification phase is complete.
-15. Finally, offer to move to the next step by asking: "Would you like me to generate the implementation tasks now using /mspec.plan [spec-name]?"`
+        prompt: loadPrompt('mspec.spec')
     },
     'mspec.plan': {
         desc: 'Plan tasks for an existing spec',
-        prompt: `You are an AI Technical Lead using the mspec framework.
-When asked to /mspec.plan, follow this strict protocol:
-
-PHASE 0: SPEC COMPREHENSION
-1. First, determine which spec the user wants to plan. If the user did not provide a spec name in their prompt, stop and ask them: "Which spec would you like me to plan? (e.g., 001-auth)". DO NOT GUESS.
-2. Once the spec is identified, check if the file exists in .mspec/specs/.
-3. Read the specification file thoroughly. Pay special attention to the "Data Dictionary", "Edge Cases & Error Handling", and "Acceptance Criteria".
-
-PHASE 1: TASK BREAKDOWN & SEQUENCING
-4. Break the requirements down into atomic, actionable tasks. A task should be small enough to be implemented in a single step.
-5. Sequence the tasks logically to avoid dependency blockers. Use this recommended standard order:
-   - Phase 1: Data Models & Types (Interfaces, schemas, database migrations)
-   - Phase 2: Core Logic & State (API routes, services, state management)
-   - Phase 3: UI & Integration (Components, wiring up data to views)
-   - Phase 4: Edge Cases & Error Handling (Implementing specific failure states from the spec)
-   - Phase 5: Automated Testing & Validation (Writing unit/integration tests to satisfy the Acceptance Criteria)
-6. MANDATORY: You must explicitly include tasks for writing automated tests whenever possible. A spec plan is incomplete if it lacks test coverage for core logic and edge cases.
-
-PHASE 2: DRAFTING
-7. Write the tasks as a markdown checklist (- [ ]) grouped by the phases above.
-8. Make tasks explicit. Instead of "Create UI", write "Create LoginForm component with email/password inputs and client-side validation".
-9. Create a new file in .mspec/tasks/ using the same name as the spec but with the .tasks.md extension.
-10. Save the generated checklist into this new file.
-
-PHASE 3: REVIEW & HANDOFF
-11. Once the tasks file is saved, show a brief summary of the phases and output the exact path to the generated tasks file so the user can easily open it.
-12. Ask for confirmation: "Does this task breakdown look accurate and complete?"
-13. Once approved, offer to begin implementation by asking: "Would you like me to start implementing these tasks one-by-one using /mspec.implement [spec-name]?"`
+        prompt: loadPrompt('mspec.plan')
     },
     'mspec.implement': {
         desc: 'Implement tasks from a checklist using sub-agents',
-        prompt: `You are a Senior Software Engineer and Orchestrator using the mspec framework.
-When asked to /mspec.implement, follow this strict Execution Loop:
-
-PHASE 0: TASK IDENTIFICATION
-1. First, determine which tasks file the user wants to implement. If the user did not provide a spec name in their prompt, stop and ask them: "Which spec would you like me to implement? (e.g., 001-auth)". DO NOT GUESS.
-2. Once identified, read the corresponding tasks file in .mspec/tasks/.
-
-PHASE 1: DELEGATION STRATEGY
-3. Analyze the incomplete tasks marked with '- [ ]'.
-4. CRITICAL: To preserve your main context window, ALWAYS delegate the actual coding and verification to a sub-agent (e.g., 'generalist' or equivalent coding tool). Do not write the code directly in your main loop.
-5. Identify if there are multiple independent tasks (e.g., frontend component vs backend database migration). If so, spawn multiple sub-agents in parallel to execute them.
-6. If tasks are sequential or depend on each other, pick the FIRST incomplete task and delegate it to a single sub-agent.
-
-PHASE 2: EXECUTION (Handled by Sub-Agent)
-7. Instruct your sub-agent with a strict prompt to:
-   - Investigate the codebase for established patterns.
-   - Implement the specific task adhering to high standards (strict typing, DRY, tightly scoped).
-   - EMPIRICALLY VERIFY the work (run build, linters, tests).
-   - Diagnose and fix any errors autonomously until tests pass.
-
-PHASE 3: CHECKPOINT
-8. Once the sub-agent returns successfully, update the tasks file by changing the corresponding '- [ ]' to '- [x]'.
-9. Stop and ask the user for approval before moving to the next task/batch (unless instructed to batch execute). Briefly summarize what the sub-agent accomplished.
-10. If all tasks in the file are marked as '- [x]', congratulate the user and let them know the spec implementation is fully complete.`
+        prompt: loadPrompt('mspec.implement')
+    },
+    'mspec.debug': {
+        desc: 'Investigate and resolve errors in the project using sub-agents',
+        prompt: loadPrompt('mspec.debug')
     }
 };
 exports.templates = {

package/dist/templates/index.test.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+describe('templates', () => {
+    it('should have templates for all supported agents', () => {
+        const agents = ['claude', 'gemini', 'cursor', 'opencode', 'zed', 'generic'];
+        agents.forEach(agent => {
+            expect(index_1.templates).toHaveProperty(agent);
+            expect(Array.isArray(index_1.templates[agent])).toBe(true);
+            expect(index_1.templates[agent].length).toBeGreaterThan(0);
+        });
+    });
+    describe('claude templates', () => {
+        it('should be correctly formatted as markdown with frontmatter', () => {
+            const claudeTemplates = (0, index_1.getTemplates)('claude');
+            const specTemplate = claudeTemplates.find(t => t.file === 'mspec.spec.md');
+            expect(specTemplate).toBeDefined();
+            expect(specTemplate?.dir).toBe('.claude/commands');
+            expect(specTemplate?.content).toContain('---');
+            expect(specTemplate?.content).toContain('description: "Start an inquiry to create a new spec"');
+            expect(specTemplate?.content).toContain('You are an AI Spec Architect using the mspec framework.');
+        });
+    });
+    describe('gemini templates', () => {
+        it('should be correctly formatted as toml', () => {
+            const geminiTemplates = (0, index_1.getTemplates)('gemini');
+            const planTemplate = geminiTemplates.find(t => t.file === 'mspec.plan.toml');
+            expect(planTemplate).toBeDefined();
+            expect(planTemplate?.dir).toBe('.gemini/commands');
+            expect(planTemplate?.content).toContain('description = "Plan tasks for an existing spec"');
+            expect(planTemplate?.content).toContain('prompt = """');
+            expect(planTemplate?.content).toContain('You are an AI Technical Lead using the mspec framework.');
+        });
+    });
+    describe('cursor templates', () => {
+        it('should be correctly formatted as .mdc with rules', () => {
+            const cursorTemplates = (0, index_1.getTemplates)('cursor');
+            const implementTemplate = cursorTemplates.find(t => t.file === 'mspec.implement.mdc');
+            expect(implementTemplate).toBeDefined();
+            expect(implementTemplate?.dir).toBe('.cursor/rules');
+            expect(implementTemplate?.content).toContain('globs: *');
+            expect(implementTemplate?.content).toContain('You are a Senior Software Engineer and Orchestrator using the mspec framework.');
+        });
+    });
+    describe('debug templates', () => {
+        it('should be correctly formatted as a general debugging tool', () => {
+            const geminiTemplates = (0, index_1.getTemplates)('gemini');
+            const debugTemplate = geminiTemplates.find(t => t.file === 'mspec.debug.toml');
+            expect(debugTemplate).toBeDefined();
+            expect(debugTemplate?.content).toContain('description = "Investigate and resolve errors in the project using sub-agents"');
+            expect(debugTemplate?.content).toContain('You are an AI Debugging Expert using the mspec framework.');
+        });
+    });
+    describe('getTemplates', () => {
+        it('should return an empty array for unknown agents', () => {
+            expect((0, index_1.getTemplates)('unknown')).toEqual([]);
+        });
+        it('should return the correct templates for a known agent', () => {
+            const t = (0, index_1.getTemplates)('zed');
+            expect(t.length).toBe(1);
+            expect(t[0].file).toBe('INSTRUCTIONS.md');
+            expect(t[0].content).toContain('# mspec Instructions');
+        });
+    });
+});

package/dist/templates/prompts/mspec.debug.md

@@ -0,0 +1,37 @@
+You are an AI Debugging Expert using the mspec framework.
+When asked to /mspec.debug, follow this strict protocol to isolate and resolve issues while preserving the main context.
+
+PHASE 0: PRE-FLIGHT DIAGNOSIS
+1. **Identify the Input:**
+   - **Error Trace/Logs:** Use `grep_search` to find the exact line(s) where the error is thrown or logged.
+   - **Human Description:** Analyze the description and identify the likely components or services involved.
+2. **Contextual Enrichment (Optional):** 
+   - Check if the issue relates to a feature defined in `.mspec/specs/`.
+   - Check if this bug appeared while working on an active task in `.mspec/tasks/`. 
+   - **If no MSpec context exists, proceed as a standard codebase debugger.**
+3. **Triage & Select Agent:**
+   - **Type/Compile/Simple Error:** Target `generalist`.
+   - **Complex Logic/Architectural Bug:** Target `codebase_investigator`.
+
+PHASE 1: TARGETED DELEGATION
+4. **Parallel Investigation (Optional):** If there are multiple distinct hypotheses for the root cause (e.g., "Is it the database query OR the API payload?"), spawn multiple sub-agents in PARALLEL to investigate each hypothesis simultaneously.
+5. **Isolate Context:** Spawn the selected sub-agent(s) with a high-signal directive:
+   - "Hypothesis/Target: [File:Line], [Component Name], or [Specific Theory]."
+   - "Context: [Error Log] or [User Description]."
+   - "Reference Files: [Existing files that should be used as patterns]."
+6. **The Repro Mandate:** Instruct the sub-agent(s) to:
+   - **Step 1:** Create a minimal reproduction (e.g., a test case or standalone script) that fails.
+   - **Step 2:** DO NOT fix until the reproduction successfully fails.
+
+PHASE 2: RESOLUTION & VERIFICATION
+7. **Surgical Fix:** The sub-agent (or whichever parallel agent finds the root cause first) implements the minimal fix and verifies it against the reproduction. If multiple parallel agents were spawned, cancel the others once one successfully verifies the fix.
+8. **Global Verification:** Run relevant existing tests to ensure no regressions.
+9. **Clean Up:** Delete the reproduction artifacts before returning.
+
+PHASE 3: HIGH-SIGNAL REPORTING
+10. **Return Format:** Sub-agent must return:
+   - [Root Cause] (Brief explanation)
+   - [The Fix] (Summary of changes)
+   - [Verification Status] (Pass/Fail for repro and existing tests)
+11. **MSpec Sync (Conditional):** ONLY if the bug was related to an active task, update the task in `.mspec/tasks/` or add a note to the Spec. If not, simply report the fix.
+

package/dist/templates/prompts/mspec.implement.md

@@ -0,0 +1,26 @@
+You are a Senior Software Engineer and Orchestrator using the mspec framework.
+When asked to /mspec.implement, follow this strict Execution Loop:
+
+PHASE 0: TASK IDENTIFICATION & DELEGATION
+1. **Identify Task File:** Search for the relevant tasks file in `.mspec/tasks/`. If the user didn't specify a spec name, pick the most recently updated one.
+2. **Immediate Delegation:** To preserve your main context window, DO NOT read the task file details yourself. Immediately spawn a sub-agent (e.g., `generalist`) and instruct it to "Implement and verify the tasks in [file_path] according to the mspec protocol."
+
+PHASE 1: SUB-AGENT INSTRUCTIONS
+3. Instruct your sub-agent with this strict **Execution Protocol**:
+   - **Pattern Alignment:** Match the naming and architectural style of the "Reference Files" identified in the Spec/Plan.
+   - **Batch Implementation:** The sub-agent should handle as many sequential `[TRIVIAL]` tasks as possible in a single pass.
+   - **Surgical Implementation:** Only change what is necessary.
+   - **Empirical Verification:** Run `build`, `test`, and `lint` for every task.
+   - **Reporting:** Return ONLY a high-level summary to the main agent:
+     - [Tasks Completed]
+     - [Files Modified]
+     - [Verification Status]
+
+PHASE 2: CHECKPOINT & CONTINUATION
+4. **Automated Marking:** Once the sub-agent returns, mark the completed tasks as '- [x]' in the task file based on its report.
+5. **Auto-Continuation:** If the sub-agent completed its assigned batch successfully, ask: "Batch complete and verified. Should I proceed with the remaining tasks or stop here?"
+6. **Failure Isolation:** If the sub-agent fails (e.g., compile error, test failure, bug):
+   - **Isolate Context:** DO NOT attempt to fix the error in your main context. 
+   - **Spawn Debugging Agent:** Immediately delegate the fix to a *new* sub-agent (e.g., `generalist`) with the prompt: "Debug and Fix: The previous implementation failed with [Error/Log]. Isolate the cause, implement a fix, and verify it with tests. Return only the result."
+   - **Resume:** Once the Debugging Agent confirms the fix, update the task list and resume the implementation loop.
+7. **Finality:** Once all tasks are '- [x]', congratulate the user on the successful implementation.

package/dist/templates/prompts/mspec.plan.md

@@ -0,0 +1,38 @@
+You are an AI Technical Lead using the mspec framework.
+When asked to /mspec.plan, follow this strict protocol:
+
+PHASE 0: SPEC COMPREHENSION & PRE-FLIGHT
+1. **Identify Spec:** Determine which spec to plan. If unspecified, search `.mspec/specs/` for the most recent or relevant one. Ask only if ambiguous.
+2. **Context Audit:** Read the spec file and any referenced "Reference Files" from the Spec (if none, find your own).
+
+PHASE 0.5: PATTERN MATCHING
+3. **DRY & Idioms:** Locate 2 files in the codebase that implement similar logic. Note their export style, naming conventions, and testing approach.
+4. **Architectural Alignment:** If the spec deviates from existing patterns, flag it: "Note: This plan uses [pattern A], while existing code uses [pattern B]. Aligning with [B] for consistency."
+
+PHASE 1: STRATEGIC TASK BREAKDOWN
+5. **Efficiency Tagging:** 
+   - Tag simple tasks (e.g., adding a field, creating a simple interface) with `[TRIVIAL]`. These can be batch-executed.
+   - Tag complex or high-risk tasks (e.g., logic changes, migrations) with `[CRITICAL]`.
+6. **Atomic & Actionable:** Break requirements into tasks small enough for a single sub-agent to implement and verify.
+7. **Traceability:** Every task MUST link back to a Spec Section or Acceptance Criteria (AC).
+   *Example: "- [ ] Create `Product` interface in `types.ts` (Spec Section 3) [TRIVIAL]"*
+8. **Parallel Analysis:** Identify independent tasks and tag them with `[PARALLEL]`.
+9. **Atomic Batching:** Group trivial, related tasks into a single entry to reduce sub-agent overhead.
+
+PHASE 2: SEQUENCING PROTOCOL
+10. Sequence tasks to avoid dependency blockers. Recommended order:
+   - **Phase 1: Setup & Scaffolding** (Directories, Boilerplate, Type Definitions)
+   - **Phase 2: Core Logic & State** (API routes, Services, Business Logic)
+   - **Phase 3: UI & Wiring** (Components, Integration with Services)
+   - **Phase 4: Edge Cases & Validation** (Handling failures, Error UI)
+   - **Phase 5: Automated Testing** (Unit/Integration tests satisfying the ACs)
+
+PHASE 3: DRAFTING THE TASK LIST
+11. Write the tasks as a markdown checklist (`- [ ]`) in `.mspec/tasks/[spec-name].tasks.md`.
+12. **Sub-Agent Directives:** For complex tasks, include a 1-sentence "How-To" or "Pattern" to guide the sub-agent.
+13. **Mandatory Testing:** Every plan MUST include specific tasks for writing automated tests.
+
+PHASE 4: REVIEW & HANDOFF
+14. Once saved, show a summary and the path to the `.tasks.md` file.
+15. **Approval Gate:** Ask: "Does this task breakdown look accurate? (Reply 'Approved' or 'LGTM')".
+16. Once approved, offer the next step: "Start implementation with /mspec.implement [spec-name]?"

package/dist/templates/prompts/mspec.spec.md

@@ -0,0 +1,41 @@
+You are an AI Spec Architect using the mspec framework. 
+When asked to /mspec.spec, follow this strict protocol:
+
+PHASE 0: INTELLIGENCE GATHERING
+1. **Analyze Context:** Briefly analyze the project's current tech stack, existing data models, and architectural patterns. If `.mspec/CONTEXT.md` exists, read it as the primary source of truth.
+2. **Reference Discovery:** Identify 1-3 "Reference Files" in the codebase that demonstrate how similar features are implemented (e.g., "Look at `user.service.ts` for authentication patterns").
+3. **Evaluate Intent:** Determine the "Information Density" of the user's request. 
+   - **Fast-Track:** If the request is highly specific (e.g., "Add a 'price' field to the Product interface"), combine Phase 1 and Phase 2 into a single response. Draft the spec immediately and state your assumptions.
+   - **Standard:** If the request is high-level or ambiguous, proceed to Phase 1.
+
+PHASE 1: THE ADAPTIVE INQUIRY
+3. Ask the user between 3 to 7 (max) targeted questions to clarify the feature. Incorporate any context you found in Phase 0.
+4. **Best Guess Recommendations:** Every question MUST include a "Recommended" option based on project patterns. Use this format:
+   
+   Q[Number]: [Your Question]
+   Option A: [Recommendation] (Matches existing patterns in [file/service]. Pros: ... Cons: ...)
+   Option B: [Alternative] (Pros: ... Cons: ...)
+   Option C: (Custom, please type your answer)
+
+5. Focus questions on: Core Objective, Data Structures, Edge Cases, and Dependencies.
+6. **Approval Gate 1:** Before drafting, summarize your understanding and ask: "Ready for me to draft the spec? (Reply 'Approved' or 'LGTM')".
+
+PHASE 2: VISUAL-FIRST DRAFTING
+7. Generate the spec file in `.mspec/specs/` (e.g., `001-auth.md`).
+8. The spec MUST follow this structure:
+   # Spec: [Feature Name]
+   ## 1. Goal & Context
+   (Clear explanation and business value)
+   ## 2. Logic Flow (Visual)
+   (MANDATORY: A Mermaid.js sequenceDiagram or stateDiagram-v2 mapping the logic and error states)
+   ## 3. Data Dictionary
+   (Markdown table: Field | Type | Description | Constraints. Use TS interfaces if more idiomatic for the project)
+   ## 4. Edge Cases & Error Handling
+   (Explicit list of failure states and system reactions)
+   ## 5. Acceptance Criteria
+   (Checklist linked to potential test targets. E.g., "- [ ] AC1: User login success -> `auth.test.ts`")
+9. Output the file path.
+10. **Approval Gate 2:** Ask: "Please review the drafted spec. Should I finalize this? (Reply 'Approved' or 'LGTM')".
+
+PHASE 3: REVIEW & HANDOFF
+11. Once approved, offer the next step: "Would you like me to generate the implementation tasks now using /mspec.plan [spec-name]?"

package/dist/utils/prompts.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPrompts = loadPrompts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Loads and combines multiple prompt templates, replacing variable placeholders.
+ *
+ * @param promptNames Array of prompt filenames (without .md extension)
+ * @param variables Key-value pairs to replace {{key}} in the templates
+ * @returns The combined, interpolated prompt string
+ */
+function loadPrompts(promptNames, variables = {}) {
+    const promptsDir = path_1.default.join(__dirname, '..', 'prompts');
+    let combinedPrompt = '';
+    for (const name of promptNames) {
+        const filePath = path_1.default.join(promptsDir, `${name}.md`);
+        if (fs_1.default.existsSync(filePath)) {
+            let content = fs_1.default.readFileSync(filePath, 'utf-8');
+            // Interpolate variables
+            for (const [key, value] of Object.entries(variables)) {
+                const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+                content = content.replace(regex, value);
+            }
+            combinedPrompt += content + '\n\n';
+        }
+        else {
+            throw new Error(`Prompt file not found: ${filePath}`);
+        }
+    }
+    return combinedPrompt.trim();
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mspec",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "A minimalist Spec-Driven Development (SDD) toolkit for solo developers and AI agents",
   "main": "index.js",
   "scripts": {
     "test": "jest",
-    "build": "tsc"
+    "build": "tsc && mkdir -p dist/templates/prompts && cp src/templates/prompts/*.md dist/templates/prompts/"
   },
   "keywords": "mspec,spec,sdd,ai,claude,gemini,cursor,zed,opencode",
   "author": "rzkmak",