mspec 0.0.1

package/README.md

@@ -0,0 +1,94 @@
+# mspec
+
+> **A minimalist Spec-Driven Development (SDD) toolkit for solo developers and AI agents.**
+
+`mspec` is a lightweight alternative to heavy SDD frameworks. It removes the "enterprise theater" (branch-per-feature, complex state files, and heavy daemon processes) and focuses strictly on **intent** (the Spec) and **execution** (the Tasks) using simple Markdown files.
+
+It is designed to work seamlessly alongside your favorite AI coding agents: Claude Code, Gemini CLI, Cursor, OpenCode, or Zed.
+
+## Philosophy
+- **Token Efficient:** Uses a single `SPEC.md` for context instead of massive chat histories.
+- **Visual-First:** Encourages Mermaid.js diagrams over long, confusing paragraphs.
+- **Data Dictionaries:** Uses simple Markdown tables for data modeling instead of strict, unreadable JSON schemas.
+- **Agent Handoff:** You design the spec; the AI breaks down the tasks; the AI implements the tasks sequentially.
+
+---
+
+## Installation
+
+You can run `mspec` directly via `npx` (recommended) or install it globally.
+
+### Running via npx (No install required)
+```bash
+npx mspec <command>
+```
+
+### Global Installation
+```bash
+npm install -g mspec
+```
+
+*(Note: If you are cloning this repository locally for development, run `npm install`, then `npm run build`, and finally `npm link` to make the `mspec` command available globally on your machine).*
+
+---
+
+## How to Use
+
+The workflow follows a simple three-step loop: **Initialize -> Plan -> Implement**.
+
+### Step 1: Initialize the Project
+Run this command in the root of your project:
+```bash
+npx mspec init
+```
+- It will prompt you for your preferred AI agent (Claude, Gemini, Cursor, etc.).
+- It will create the `.mspec/specs/` and `.mspec/tasks/` directories.
+- It will automatically inject a custom command/instruction file into your project (e.g., `.gemini/commands/mspec.toml` or `.cursor/rules/mspec.mdc`) so your AI agent understands the framework.
+
+### Step 2: The Inquiry (Creating a Spec)
+Talk to your AI agent and ask it to draft a specification using the `mspec` standard.
+
+**Example Prompt to your AI:**
+> "Let's create a spec for a new authentication feature. Save it to `.mspec/specs/001-auth.md`. Include a markdown description, a mermaid sequence diagram for login, and a markdown data dictionary for the user object."
+
+### Step 3: Scaffold the Plan
+Once you are happy with the `001-auth.md` spec, run:
+```bash
+npx mspec plan 001-auth
+```
+- This validates that the spec exists.
+- It generates a boilerplate `.mspec/tasks/001-auth.tasks.md` file containing strict instructions for the AI.
+- **Next Action:** Tell your AI agent: *"Please read the spec and fill out the tasks file for 001-auth."* The AI will break the spec down into granular checkboxes.
+
+### Step 4: Implement and Execute
+Once the checklist is generated, it's time to hand the wheel over to the AI.
+```bash
+npx mspec implement 001-auth
+```
+- This command analyzes the task list.
+- It outputs a highly structured prompt to your terminal. 
+- **Next Action:** Copy the outputted prompt and paste it to your AI agent. 
+  - *What the AI does:* It will read the `.tasks.md` file, pick the first unchecked `- [ ]` task, implement the code, run your tests, change the checkbox to `- [x]`, and then **stop** to wait for your review.
+
+#### Batch Execution
+If you trust the AI and want it to burn through the whole checklist without stopping for your approval between tasks, use the `--batch` flag:
+```bash
+npx mspec implement 001-auth --batch
+```
+
+---
+
+## Directory Structure
+A project using `mspec` will look like this:
+
+```text
+your-project/
+├── .mspec/
+│   ├── mspec.json                 # Auto-generated config
+│   ├── specs/
+│   │   └── 001-auth.md            # The "Intent" (Markdown/Mermaid)
+│   └── tasks/
+│       └── 001-auth.tasks.md      # The "Execution" (Checklists)
+├── src/                           # Your actual code
+└── package.json
+```

package/dist/commands/implement.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.implementCommand = implementCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+async function implementCommand(specName, options) {
+    if (typeof specName !== 'string' || specName.includes('..') || path_1.default.isAbsolute(specName)) {
+        console.error(chalk_1.default.red(`Error: Invalid spec name. Path traversal is not allowed.`));
+        process.exit(1);
+        return;
+    }
+    const mspecDir = path_1.default.join(process.cwd(), '.mspec');
+    const tasksPath = path_1.default.join(mspecDir, 'tasks', `${specName}.tasks.md`);
+    // 1. Check if the tasks file exists
+    if (!fs_1.default.existsSync(tasksPath)) {
+        console.error(chalk_1.default.red(`Error: Tasks file not found at ${tasksPath}`));
+        console.log(chalk_1.default.yellow(`Run 'mspec plan ${specName}' and have your AI fill it out first.`));
+        process.exit(1);
+        return;
+    }
+    // 2. Read the file and check for remaining tasks
+    const tasksContent = fs_1.default.readFileSync(tasksPath, 'utf-8');
+    if (!tasksContent.includes('- [ ]')) {
+        console.log(chalk_1.default.yellow(`Warning: No incomplete tasks found in ${specName}.tasks.md.`));
+        console.log(chalk_1.default.green(`It looks like this spec is already fully implemented!`));
+        return;
+    }
+    // 3. Generate the execution prompt
+    const isBatch = options.batch === true;
+    const executionPrompt = `> **mspec execution directive:**
+> Please read \`.mspec/tasks/${specName}.tasks.md\`. 
+> 1. Find the first incomplete task marked with \`- [ ]\`.
+> 2. Implement the requirements for that specific task.
+> 3. Verify your implementation (run tests/build).
+> 4. If successful, change the task to \`- [x]\` in the file.
+> 5. ${isBatch
+        ? 'Continue to the next task until all tasks in the current phase are complete.'
+        : 'Stop and wait for my approval before moving to the next task.'}`;
+    // 4. Output the prompt
+    console.log(chalk_1.default.magenta('\n=== Copy the text below and paste it to your AI agent ===\n'));
+    console.log(executionPrompt);
+    console.log(chalk_1.default.magenta('\n==========================================================\n'));
+}

package/dist/commands/implement.test.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const implement_1 = require("./implement");
+describe('implementCommand', () => {
+    let originalCwd;
+    let tmpDir;
+    let mockExit;
+    let mockConsoleError;
+    let mockConsoleLog;
+    beforeAll(() => {
+        originalCwd = process.cwd;
+    });
+    beforeEach(() => {
+        tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'mspec-test-implement-'));
+        process.cwd = () => tmpDir;
+        mockExit = jest.spyOn(process, 'exit').mockImplementation((() => { }));
+        mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => { });
+        mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        process.cwd = originalCwd;
+        fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        jest.restoreAllMocks();
+    });
+    it('should reject path traversal in spec name', async () => {
+        await (0, implement_1.implementCommand)('../outside-spec', {});
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Invalid spec name'));
+    });
+    it('should reject absolute paths in spec name', async () => {
+        await (0, implement_1.implementCommand)('/etc/passwd', {});
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Invalid spec name'));
+    });
+    it('should exit with error if tasks file does not exist', async () => {
+        await (0, implement_1.implementCommand)('missing-spec', {});
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Error: Tasks file not found'));
+    });
+    it('should warn if no incomplete tasks are found', async () => {
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks');
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, 'done-spec.tasks.md'), '- [x] task 1\n- [x] task 2');
+        await (0, implement_1.implementCommand)('done-spec', {});
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('Warning: No incomplete tasks found'));
+    });
+    it('should handle empty task files gracefully', async () => {
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks');
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, 'empty.tasks.md'), '');
+        await (0, implement_1.implementCommand)('empty', {});
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('Warning: No incomplete tasks found'));
+    });
+    it('should generate one-by-one execution prompt by default', async () => {
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks');
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, 'active-spec.tasks.md'), '- [x] task 1\n- [ ] task 2');
+        await (0, implement_1.implementCommand)('active-spec', {});
+        expect(mockExit).not.toHaveBeenCalled();
+        const promptOutput = mockConsoleLog.mock.calls[1][0];
+        expect(promptOutput).toContain('mspec execution directive:');
+        expect(promptOutput).toContain('active-spec.tasks.md');
+        expect(promptOutput).toContain('Stop and wait for my approval before moving to the next task');
+    });
+    it('should generate batch execution prompt when --batch is true', async () => {
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks');
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, 'batch-spec.tasks.md'), '- [ ] task 1\n- [ ] task 2');
+        await (0, implement_1.implementCommand)('batch-spec', { batch: true });
+        expect(mockExit).not.toHaveBeenCalled();
+        const promptOutput = mockConsoleLog.mock.calls[1][0];
+        expect(promptOutput).toContain('mspec execution directive:');
+        expect(promptOutput).toContain('Continue to the next task until all tasks');
+    });
+    it('should support nested spec names like feature/001-auth', async () => {
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks', 'feature');
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, '001-auth.tasks.md'), '- [ ] task 1');
+        await (0, implement_1.implementCommand)('feature/001-auth', {});
+        expect(mockExit).not.toHaveBeenCalled();
+        const promptOutput = mockConsoleLog.mock.calls[1][0];
+        expect(promptOutput).toContain('feature/001-auth.tasks.md');
+    });
+});

package/dist/commands/init.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const templates_1 = require("../templates");
+// Use require for enquirer to avoid commonjs/esm interop issues with its types
+const { prompt } = require('enquirer');
+async function initCommand() {
+    const mspecDir = path_1.default.join(process.cwd(), '.mspec');
+    if (fs_1.default.existsSync(mspecDir)) {
+        console.log(chalk_1.default.yellow('.mspec directory already exists. Initialization skipped.'));
+        return;
+    }
+    let response;
+    try {
+        response = await prompt({
+            type: 'select',
+            name: 'agent',
+            message: 'Which AI agent are you using?',
+            choices: ['claude', 'gemini', 'cursor', 'opencode', 'zed', 'generic'],
+        });
+    }
+    catch (error) {
+        console.log(chalk_1.default.yellow('\nInitialization cancelled.'));
+        return;
+    }
+    const agent = response.agent;
+    // Create directories
+    fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'specs'), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'tasks'), { recursive: true });
+    // Write mspec.json config
+    const mspecConfig = {
+        agent,
+        paths: {
+            specs: '.mspec/specs',
+            tasks: '.mspec/tasks'
+        }
+    };
+    fs_1.default.writeFileSync(path_1.default.join(mspecDir, 'mspec.json'), JSON.stringify(mspecConfig, null, 2));
+    // Write agent integration file
+    const template = (0, templates_1.getTemplate)(agent);
+    if (template) {
+        const targetDir = path_1.default.join(process.cwd(), template.dir);
+        fs_1.default.mkdirSync(targetDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(targetDir, template.file), template.content);
+        console.log(chalk_1.default.green(`Created integration file for ${agent} at ${path_1.default.join(template.dir, template.file)}`));
+    }
+    else {
+        console.log(chalk_1.default.yellow(`No specific integration template found for ${agent}. Setup completed with generic settings.`));
+    }
+    console.log(chalk_1.default.green('mspec initialized successfully!'));
+}

package/dist/commands/init.test.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const init_1 = require("./init");
+const mockPrompt = jest.fn();
+jest.mock('enquirer', () => ({
+    prompt: (...args) => mockPrompt(...args)
+}));
+describe('initCommand', () => {
+    let originalCwd;
+    let tmpDir;
+    beforeAll(() => {
+        originalCwd = process.cwd;
+    });
+    beforeEach(() => {
+        tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'mspec-test-init-'));
+        process.cwd = () => tmpDir;
+        mockPrompt.mockReset();
+    });
+    afterEach(() => {
+        process.cwd = originalCwd;
+        fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        jest.restoreAllMocks();
+    });
+    const providers = [
+        { agent: 'claude', expectedFile: '.claude/commands/mspec.md' },
+        { agent: 'gemini', expectedFile: '.gemini/commands/mspec.toml' },
+        { agent: 'cursor', expectedFile: '.cursor/rules/mspec.mdc' },
+        { agent: 'opencode', expectedFile: '.opencode/commands/mspec.md' },
+        { agent: 'zed', expectedFile: '.mspec/INSTRUCTIONS.md' },
+        { agent: 'generic', expectedFile: '.mspec/INSTRUCTIONS.md' }
+    ];
+    providers.forEach(({ agent, expectedFile }) => {
+        it(`should initialize the .mspec environment for ${agent}`, async () => {
+            mockPrompt.mockResolvedValueOnce({ agent });
+            const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+            await (0, init_1.initCommand)();
+            expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.mspec'))).toBe(true);
+            expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.mspec/specs'))).toBe(true);
+            expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.mspec/tasks'))).toBe(true);
+            const configPath = path_1.default.join(tmpDir, '.mspec/mspec.json');
+            expect(fs_1.default.existsSync(configPath)).toBe(true);
+            const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
+            expect(config.agent).toBe(agent);
+            const integrationPath = path_1.default.join(tmpDir, expectedFile);
+            expect(fs_1.default.existsSync(integrationPath)).toBe(true);
+        });
+    });
+    it('should skip initialization if .mspec directory already exists', async () => {
+        const mspecDir = path_1.default.join(tmpDir, '.mspec');
+        fs_1.default.mkdirSync(mspecDir);
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        await (0, init_1.initCommand)();
+        expect(fs_1.default.existsSync(path_1.default.join(mspecDir, 'specs'))).toBe(false);
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Initialization skipped.'));
+    });
+    it('should handle prompt cancellation gracefully', async () => {
+        mockPrompt.mockRejectedValueOnce(new Error('User cancelled'));
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        await (0, init_1.initCommand)();
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Initialization cancelled.'));
+        expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.mspec'))).toBe(false);
+    });
+    it('should handle missing template gracefully', async () => {
+        mockPrompt.mockResolvedValueOnce({ agent: 'unknown-agent' });
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        await (0, init_1.initCommand)();
+        const configPath = path_1.default.join(tmpDir, '.mspec/mspec.json');
+        expect(fs_1.default.existsSync(configPath)).toBe(true);
+        const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
+        expect(config.agent).toBe('unknown-agent');
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('No specific integration template found'));
+    });
+});

package/dist/commands/plan.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planCommand = planCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+async function planCommand(specName) {
+    if (typeof specName !== 'string' || specName.includes('..') || path_1.default.isAbsolute(specName)) {
+        console.error(chalk_1.default.red(`Error: Invalid spec name. Path traversal is not allowed.`));
+        process.exit(1);
+        return;
+    }
+    const mspecDir = path_1.default.join(process.cwd(), '.mspec');
+    const specPath = path_1.default.join(mspecDir, 'specs', `${specName}.md`);
+    const tasksPath = path_1.default.join(mspecDir, 'tasks', `${specName}.tasks.md`);
+    // 1. Check if the spec file exists
+    if (!fs_1.default.existsSync(specPath)) {
+        console.error(chalk_1.default.red(`Error: Spec file not found at ${specPath}`));
+        console.log(chalk_1.default.yellow(`Make sure you have created the spec first using your AI agent or manually.`));
+        process.exit(1);
+        return;
+    }
+    // 2. Check if the tasks file already exists
+    if (fs_1.default.existsSync(tasksPath)) {
+        console.log(chalk_1.default.yellow(`Warning: Tasks file already exists at ${tasksPath}`));
+        console.log(chalk_1.default.gray(`Skipping generation to prevent overwriting your existing plan.`));
+        return;
+    }
+    // 3. Generate the boilerplate markdown
+    const boilerplate = `# 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
+- [ ] ...
+`;
+    // Ensure tasks directory exists in case it was somehow deleted or it's a nested spec (e.g. 'auth/login')
+    fs_1.default.mkdirSync(path_1.default.dirname(tasksPath), { recursive: true });
+    // 4. Write the file
+    fs_1.default.writeFileSync(tasksPath, boilerplate, 'utf-8');
+    console.log(chalk_1.default.green(`Success: Scaffolded tasks file at ${tasksPath}`));
+    console.log(chalk_1.default.blue(`Next Step: Ask your AI agent to "fill out the tasks for ${specName}"`));
+}

package/dist/commands/plan.test.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const plan_1 = require("./plan");
+describe('planCommand', () => {
+    let originalCwd;
+    let tmpDir;
+    let mockExit;
+    let mockConsoleError;
+    let mockConsoleLog;
+    beforeAll(() => {
+        originalCwd = process.cwd;
+    });
+    beforeEach(() => {
+        tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'mspec-test-plan-'));
+        process.cwd = () => tmpDir;
+        mockExit = jest.spyOn(process, 'exit').mockImplementation((() => { }));
+        mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => { });
+        mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        process.cwd = originalCwd;
+        fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        jest.restoreAllMocks();
+    });
+    it('should reject path traversal in spec name', async () => {
+        await (0, plan_1.planCommand)('../outside-spec');
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Invalid spec name'));
+    });
+    it('should reject absolute paths in spec name', async () => {
+        await (0, plan_1.planCommand)('/etc/passwd');
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Invalid spec name'));
+    });
+    it('should exit with error if spec file does not exist', async () => {
+        await (0, plan_1.planCommand)('missing-spec');
+        expect(mockExit).toHaveBeenCalledWith(1);
+        expect(mockConsoleError).toHaveBeenCalledWith(expect.stringContaining('Error: Spec file not found'));
+    });
+    it('should skip generation if tasks file already exists', async () => {
+        const specsDir = path_1.default.join(tmpDir, '.mspec', 'specs');
+        const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks');
+        fs_1.default.mkdirSync(specsDir, { recursive: true });
+        fs_1.default.mkdirSync(tasksDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(specsDir, 'test-spec.md'), '# Spec');
+        fs_1.default.writeFileSync(path_1.default.join(tasksDir, 'test-spec.tasks.md'), '# Existing Tasks');
+        await (0, plan_1.planCommand)('test-spec');
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('Warning: Tasks file already exists'));
+        const content = fs_1.default.readFileSync(path_1.default.join(tasksDir, 'test-spec.tasks.md'), 'utf-8');
+        expect(content).toBe('# Existing Tasks');
+    });
+    it('should scaffold boilerplate if spec exists and tasks do not', async () => {
+        const specsDir = path_1.default.join(tmpDir, '.mspec', 'specs');
+        fs_1.default.mkdirSync(specsDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(specsDir, 'test-spec.md'), '# Spec');
+        await (0, plan_1.planCommand)('test-spec');
+        expect(mockExit).not.toHaveBeenCalled();
+        expect(mockConsoleLog).toHaveBeenCalledWith(expect.stringContaining('Success: Scaffolded tasks file'));
+        const tasksPath = path_1.default.join(tmpDir, '.mspec', 'tasks', 'test-spec.tasks.md');
+        expect(fs_1.default.existsSync(tasksPath)).toBe(true);
+    });
+    it('should support nested spec names like feature/001-auth', async () => {
+        const specsDir = path_1.default.join(tmpDir, '.mspec', 'specs', 'feature');
+        fs_1.default.mkdirSync(specsDir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(specsDir, '001-auth.md'), '# Spec');
+        await (0, plan_1.planCommand)('feature/001-auth');
+        expect(mockExit).not.toHaveBeenCalled();
+        const tasksPath = path_1.default.join(tmpDir, '.mspec', 'tasks', 'feature', '001-auth.tasks.md');
+        expect(fs_1.default.existsSync(tasksPath)).toBe(true);
+    });
+});

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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);

package/dist/templates/index.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templates = void 0;
+exports.getTemplate = getTemplate;
+exports.templates = {
+    claude: {
+        dir: '.claude/commands',
+        file: 'mspec.md',
+        content: `---
+description: "Commands for Spec-Driven Development using mspec"
+---
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+`
+    },
+    gemini: {
+        dir: '.gemini/commands',
+        file: 'mspec.toml',
+        content: `description = "Commands for Spec-Driven Development using mspec"
+prompt = """
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+"""
+`
+    },
+    cursor: {
+        dir: '.cursor/rules',
+        file: 'mspec.mdc',
+        content: `---
+description: Commands for Spec-Driven Development using mspec
+globs: *
+---
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+`
+    },
+    opencode: {
+        dir: '.opencode/commands',
+        file: 'mspec.md',
+        content: `---
+description: "Commands for Spec-Driven Development using mspec"
+---
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+`
+    },
+    zed: {
+        dir: '.mspec',
+        file: 'INSTRUCTIONS.md',
+        content: `# mspec Instructions
+
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+`
+    },
+    generic: {
+        dir: '.mspec',
+        file: 'INSTRUCTIONS.md',
+        content: `# mspec Instructions
+
+You are an AI assistant using the mspec framework.
+When asked to /mspec:spec, /mspec:plan, or /mspec:apply, follow the minimalist spec-driven development guidelines.
+Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+`
+    }
+};
+function getTemplate(agent) {
+    return exports.templates[agent];
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mspec",
+  "version": "0.0.1",
+  "description": "A minimalist Spec-Driven Development (SDD) toolkit for solo developers and AI agents",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "build": "tsc"
+  },
+  "keywords": "mspec,spec,sdd,ai,claude,gemini,cursor,zed,opencode",
+  "author": "rzkmak",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "@types/node": "^25.3.5",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.3",
+    "enquirer": "^2.4.1",
+    "ts-node": "^10.9.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "mspec": "./dist/index.js"
+  },
+  "repository": "https://github.com/rzkmak/mspec",
+  "files": [
+    "dist"
+  ]
+}