mspec 0.0.5 → 0.0.8

package/README.md

@@ -16,16 +16,10 @@ It is designed to work seamlessly alongside your favorite AI coding agents: Clau
 
 ## Installation
 
-You can run `mspec` directly via `npx` (recommended) or install it globally.
+We recommend running `mspec` directly via `npx` so you always get the freshest, most up-to-date prompts for your AI agents when initializing a new project.
 
-### Running via npx (No install required)
 ```bash
-npx mspec <command>
-```
-
-### Global Installation
-```bash
-npm install -g mspec
+npx mspec@latest init
 ```
 
 ---
@@ -37,11 +31,12 @@ 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
+npx mspec@latest 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 custom commands into your project (e.g., `.gemini/commands/mspec.plan.toml` or `.cursor/rules/mspec.implement.mdc`) so your AI agent natively understands the framework and provides autocomplete commands like `/mspec.spec`.
+- **Note:** If you already have `.mspec` in your project, running this command will **update** your local AI instructions to the latest version without overwriting your specs or tasks.
 
 *(Note: After running `init`, you may need to restart your AI agent session so it can detect the new slash commands).*
 
@@ -53,9 +48,19 @@ Use the native slash command in your AI agent to start drafting a specification.
 /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.
+- **The Inquiry:** It will not guess. Instead, it will ask you multiple-choice questions to define the core logic, edge cases, and data models. 
+  
+  *Example Interaction:*
+  > **AI:** Q1: How should we handle session storage?
+  > Option A: JWT in HTTP-only cookies (Pros: Secure against XSS. Cons: Harder to invalidate).
+  > Option B: Redis-backed sessions (Pros: Easy to revoke. Cons: Requires setting up Redis).
+  > Option C: (Custom, please type your answer)
+  >
+  > **You:** Q1: A
+  
+- **Approval Checkpoint 1:** After you answer, the AI will ask: *"Are you ready for me to draft the specification based on these answers? (Please reply 'Approved' or 'LGTM')"*
+- **Drafting:** Once approved, it will generate a highly structured `.mspec/specs/001-auth.md` file featuring a Mermaid diagram and an Acceptance Criteria checklist.
+- **Approval Checkpoint 2:** It will output the file path for your review and wait for you to say **"Approved"** or **"LGTM"** again before automatically offering the next command.
 
 ### Step 3: Scaffold the Plan
 Once you are happy with the spec, use the planning command to break it down.
@@ -111,4 +116,4 @@ your-project/
 │       └── mspec.implement.toml
 ├── src/                           # Your actual code
 └── package.json
-```
+```

package/dist/commands/init.js

@@ -12,27 +12,44 @@ const templates_1 = require("../templates");
 const { prompt } = require('enquirer');
 async function initCommand() {
     const mspecDir = path_1.default.join(process.cwd(), '.mspec');
+    const configPath = path_1.default.join(mspecDir, 'mspec.json');
+    let existingAgent = '';
     if (fs_1.default.existsSync(mspecDir)) {
-        console.log(chalk_1.default.yellow('.mspec directory already exists. Initialization skipped.'));
-        return;
+        console.log(chalk_1.default.blue('Existing .mspec directory found. Updating integration files...'));
+        if (fs_1.default.existsSync(configPath)) {
+            try {
+                const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
+                if (config && config.agent) {
+                    existingAgent = config.agent;
+                }
+            }
+            catch (e) {
+                // ignore JSON parse errors
+            }
+        }
     }
-    let response;
-    try {
-        response = await prompt({
-            type: 'select',
-            name: 'agent',
-            message: 'Which AI agent are you using?',
-            choices: ['claude', 'gemini', 'cursor', 'opencode', 'zed', 'generic'],
-        });
+    let agent = existingAgent;
+    if (!agent) {
+        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;
+        }
+        agent = response.agent;
     }
-    catch (error) {
-        console.log(chalk_1.default.yellow('\nInitialization cancelled.'));
-        return;
+    // Create directories if they don't exist
+    if (!fs_1.default.existsSync(mspecDir)) {
+        fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'specs'), { recursive: true });
+        fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'tasks'), { recursive: true });
     }
-    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,
@@ -41,7 +58,7 @@ async function initCommand() {
             tasks: '.mspec/tasks'
         }
     };
-    fs_1.default.writeFileSync(path_1.default.join(mspecDir, 'mspec.json'), JSON.stringify(mspecConfig, null, 2));
+    fs_1.default.writeFileSync(configPath, JSON.stringify(mspecConfig, null, 2));
     // Write agent integration files
     const agentTemplates = (0, templates_1.getTemplates)(agent);
     if (agentTemplates.length > 0) {
@@ -49,11 +66,11 @@ async function initCommand() {
             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)}`));
+            console.log(chalk_1.default.green(`Updated 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!'));
+    console.log(chalk_1.default.green('mspec initialized/updated successfully!'));
 }

package/dist/commands/init.test.js

@@ -53,13 +53,26 @@ describe('initCommand', () => {
             }
         });
     });
-    it('should skip initialization if .mspec directory already exists', async () => {
+    it('should update integration files if .mspec directory already exists', async () => {
         const mspecDir = path_1.default.join(tmpDir, '.mspec');
         fs_1.default.mkdirSync(mspecDir);
+        fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'specs'));
+        fs_1.default.mkdirSync(path_1.default.join(mspecDir, 'tasks'));
+        fs_1.default.writeFileSync(path_1.default.join(mspecDir, 'mspec.json'), JSON.stringify({ agent: 'cursor' }));
         const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        mockPrompt.mockRejectedValueOnce(new Error('Should not prompt'));
         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.'));
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Existing .mspec directory found. Updating integration files...'));
+        expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.cursor/rules/mspec.spec.mdc'))).toBe(true);
+    });
+    it('should prompt if .mspec directory exists but mspec.json is missing or invalid', async () => {
+        const mspecDir = path_1.default.join(tmpDir, '.mspec');
+        fs_1.default.mkdirSync(mspecDir);
+        mockPrompt.mockResolvedValueOnce({ agent: 'gemini' });
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        await (0, init_1.initCommand)();
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Existing .mspec directory found. Updating integration files...'));
+        expect(fs_1.default.existsSync(path_1.default.join(tmpDir, '.gemini/commands/mspec.spec.toml'))).toBe(true);
     });
     it('should handle prompt cancellation gracefully', async () => {
         mockPrompt.mockRejectedValueOnce(new Error('User cancelled'));

package/dist/templates/index.js

@@ -13,16 +13,27 @@ PHASE 0: CONTEXT GATHERING
 
 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:
+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?
-4. Wait for the user to answer. Iterate if necessary until ambiguity is eliminated.
+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
-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:
+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)
@@ -34,12 +45,13 @@ PHASE 2: DRAFTING
    (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
-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]?"`
+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]?"`
     },
     'mspec.plan': {
         desc: 'Plan tasks for an existing spec',

package/package.json

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