mspec 0.0.2 → 0.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 > **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.
+`mspec` is a lightweight alternative to heavy SDD frameworks like `spec-kit` or `get-shit-done`. 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.
 
@@ -10,7 +10,7 @@ It is designed to work seamlessly alongside your favorite AI coding agents: Clau
 - **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.
+- **Sub-Agent Orchestration:** It instructs your main AI agent to act as an orchestrator, delegating implementation to parallel sub-agents to preserve your context window.
 
 ---
 
@@ -28,13 +28,11 @@ npx mspec <command>
 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**.
+The workflow follows a simple three-step loop: **Initialize -> Plan -> Apply**.
 
 ### Step 1: Initialize the Project
 Run this command in the root of your project:
@@ -43,36 +41,52 @@ 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.
+- It will automatically inject custom commands into your project (e.g., `.gemini/commands/mspec.plan.toml` or `.cursor/rules/mspec.apply.mdc`) so your AI agent natively understands the framework and provides autocomplete commands like `/mspec.spec`.
+
+*(Note: After running `init`, you may need to restart your AI agent session so it can detect the new slash commands).*
 
 ### Step 2: The Inquiry (Creating a Spec)
-Talk to your AI agent and ask it to draft a specification using the `mspec` standard.
+Use the native slash command in your AI agent to start drafting a specification.
 
-**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."
+**Command:**
+```text
+/mspec.spec Let's create a spec for a new authentication feature.
+```
+- **Context Gathering:** The AI will automatically look at your existing codebase to understand your current architecture before answering.
+- **The Inquiry:** It will stop and ask you targeted questions about edge cases, data models, and logic.
+- **Drafting:** After you answer, it will generate a highly structured `.mspec/specs/001-auth.md` file featuring a Mermaid diagram and an Acceptance Criteria checklist.
+- It will output the file path for your review and wait for you to say **"Approved"** or **"LGTM"** before automatically offering the next command.
 
 ### Step 3: Scaffold the Plan
-Once you are happy with the `001-auth.md` spec, run:
-```bash
-npx mspec plan 001-auth
+Once you are happy with the spec, use the planning command to break it down.
+
+**Command:**
+```text
+/mspec.plan
 ```
-- 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.
+- 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).
+- It will show you the exact file path so you can review the generated tasks and ask for your approval before proceeding.
 
 ### 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
+Once the checklist is generated, hand the wheel over to the AI to orchestrate the implementation.
+
+**Command:**
+```text
+/mspec.apply
 ```
-- 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.
+- **Sub-Agent Delegation:** To prevent context bloat, the AI will read the first `- [ ]` task and delegate the actual coding to a sub-agent.
+- **Parallelization:** If tasks are independent (e.g., backend and frontend), it will spawn multiple sub-agents to execute them simultaneously!
+- **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.
 
-#### 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:
+#### 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
+
+# Generate the prompt for batch execution (don't stop for review)
 npx mspec implement 001-auth --batch
 ```
 
@@ -89,6 +103,11 @@ your-project/
 │   │   └── 001-auth.md            # The "Intent" (Markdown/Mermaid)
 │   └── tasks/
 │       └── 001-auth.tasks.md      # The "Execution" (Checklists)
+├── .gemini/                       # (Or .claude / .cursor depending on your agent)
+│   └── commands/
+│       ├── mspec.spec.toml
+│       ├── mspec.plan.toml
+│       └── mspec.apply.toml
 ├── src/                           # Your actual code
 └── package.json
 ```

package/dist/commands/implement.js

@@ -33,12 +33,13 @@ async function implementCommand(specName, options) {
     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.'
+> 1. Analyze the incomplete tasks marked with \`- [ ]\`.
+> 2. CRITICAL: Delegate the actual coding to a sub-agent to preserve your context.
+> 3. If tasks are independent (e.g., backend/frontend), run multiple sub-agents in parallel. Otherwise, pick the first task.
+> 4. Instruct the sub-agent to implement the task, empirically verify it (run tests/build), and fix errors autonomously.
+> 5. Once the sub-agent succeeds, change the task to \`- [x]\` in the file.
+> 6. ${isBatch
+        ? 'Continue delegating the next task(s) 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'));

package/dist/commands/implement.test.js

@@ -78,7 +78,7 @@ describe('implementCommand', () => {
         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');
+        expect(promptOutput).toContain('Continue delegating the next task(s) until all tasks');
     });
     it('should support nested spec names like feature/001-auth', async () => {
         const tasksDir = path_1.default.join(tmpDir, '.mspec', 'tasks', 'feature');

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.apply.md'] },
-        { agent: 'gemini', expectedFiles: ['.gemini/commands/mspec.spec.toml', '.gemini/commands/mspec.plan.toml', '.gemini/commands/mspec.apply.toml'] },
-        { agent: 'cursor', expectedFiles: ['.cursor/rules/mspec.spec.mdc', '.cursor/rules/mspec.plan.mdc', '.cursor/rules/mspec.apply.mdc'] },
-        { agent: 'opencode', expectedFiles: ['.opencode/commands/mspec.spec.md', '.opencode/commands/mspec.plan.md', '.opencode/commands/mspec.apply.md'] },
+        { 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: 'zed', expectedFiles: ['.mspec/INSTRUCTIONS.md'] },
         { agent: 'generic', expectedFiles: ['.mspec/INSTRUCTIONS.md'] }
     ];

package/dist/templates/index.js

@@ -2,55 +2,140 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.templates = void 0;
 exports.getTemplates = getTemplates;
-const commands = [
-    { name: 'mspec.spec', desc: 'Create a new spec' },
-    { name: 'mspec.plan', desc: 'Plan tasks for a spec' },
-    { name: 'mspec.apply', desc: 'Implement tasks for a spec' }
-];
+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 3-5 targeted questions to clarify the feature, incorporating any context you found in Phase 0. To build a strong spec, you 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?
+4. Wait for the user to answer. Iterate if necessary until ambiguity is eliminated.
+
+PHASE 2: DRAFTING
+5. Generate the spec file in .mspec/specs/ using the exact filename requested or a logical slug (e.g., 001-auth.md).
+6. 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)
+
+PHASE 3: REVIEW
+7. AFTER generating the spec file, ask the user for confirmation. DO NOT consider the task completed until the user explicitly replies with "Approved" or "LGTM". 
+8. If the user provides feedback, revise the spec and ask for confirmation again.
+9. Once approved, output the exact path to the generated spec file so the user can easily open it.
+10. Finally, offer to move to the next phase by asking: "Would you like me to generate the implementation tasks now using /mspec.plan [spec-name]?"`
+    },
+    '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]?"`
+    },
+    '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.`
+    }
+};
 exports.templates = {
-    claude: commands.map(cmd => ({
+    claude: Object.entries(commandPrompts).map(([name, data]) => ({
         dir: '.claude/commands',
-        file: `${cmd.name}.md`,
+        file: `${name}.md`,
         content: `---
-description: "${cmd.desc} using mspec"
+description: "${data.desc}"
 ---
-You are an AI assistant using the mspec framework.
-When asked to /${cmd.name}, follow the minimalist spec-driven development guidelines.
-Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+${data.prompt}
 `
     })),
-    gemini: commands.map(cmd => ({
+    gemini: Object.entries(commandPrompts).map(([name, data]) => ({
         dir: '.gemini/commands',
-        file: `${cmd.name}.toml`,
-        content: `description = "${cmd.desc} using mspec"
+        file: `${name}.toml`,
+        content: `description = "${data.desc}"
 prompt = """
-You are an AI assistant using the mspec framework.
-When asked to /${cmd.name}, follow the minimalist spec-driven development guidelines.
-Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+${data.prompt}
 """
 `
     })),
-    cursor: commands.map(cmd => ({
+    cursor: Object.entries(commandPrompts).map(([name, data]) => ({
         dir: '.cursor/rules',
-        file: `${cmd.name}.mdc`,
+        file: `${name}.mdc`,
         content: `---
-description: ${cmd.desc} using mspec
+description: ${data.desc}
 globs: *
 ---
-You are an AI assistant using the mspec framework.
-When asked to /${cmd.name}, follow the minimalist spec-driven development guidelines.
-Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+${data.prompt}
 `
     })),
-    opencode: commands.map(cmd => ({
+    opencode: Object.entries(commandPrompts).map(([name, data]) => ({
         dir: '.opencode/commands',
-        file: `${cmd.name}.md`,
+        file: `${name}.md`,
         content: `---
-description: "${cmd.desc} using mspec"
+description: "${data.desc}"
 ---
-You are an AI assistant using the mspec framework.
-When asked to /${cmd.name}, follow the minimalist spec-driven development guidelines.
-Specs are in .mspec/specs. Tasks are in .mspec/tasks.
+${data.prompt}
 `
     })),
     zed: [{
@@ -58,9 +143,7 @@ Specs are in .mspec/specs. Tasks are in .mspec/tasks.
             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.
+${Object.entries(commandPrompts).map(([name, data]) => `## ${name}\n${data.prompt}`).join('\n\n')}
 `
         }],
     generic: [{
@@ -68,9 +151,7 @@ Specs are in .mspec/specs. Tasks are in .mspec/tasks.
             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.
+${Object.entries(commandPrompts).map(([name, data]) => `## ${name}\n${data.prompt}`).join('\n\n')}
 `
         }]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mspec",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A minimalist Spec-Driven Development (SDD) toolkit for solo developers and AI agents",
   "main": "index.js",
   "scripts": {