mspec 0.0.5 → 0.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -12
- package/dist/templates/index.js +21 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -16,16 +16,10 @@ It is designed to work seamlessly alongside your favorite AI coding agents: Clau
|
|
|
16
16
|
|
|
17
17
|
## Installation
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
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.
|
|
20
20
|
|
|
21
|
-
### Running via npx (No install required)
|
|
22
21
|
```bash
|
|
23
|
-
npx mspec
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
### Global Installation
|
|
27
|
-
```bash
|
|
28
|
-
npm install -g mspec
|
|
22
|
+
npx mspec init
|
|
29
23
|
```
|
|
30
24
|
|
|
31
25
|
---
|
|
@@ -53,9 +47,19 @@ Use the native slash command in your AI agent to start drafting a specification.
|
|
|
53
47
|
/mspec.spec Let's create a spec for a new authentication feature.
|
|
54
48
|
```
|
|
55
49
|
- **Context Gathering:** The AI will automatically look at your existing codebase to understand your current architecture before answering.
|
|
56
|
-
- **The Inquiry:** It will
|
|
57
|
-
|
|
58
|
-
|
|
50
|
+
- **The Inquiry:** It will not guess. Instead, it will ask you multiple-choice questions to define the core logic, edge cases, and data models.
|
|
51
|
+
|
|
52
|
+
*Example Interaction:*
|
|
53
|
+
> **AI:** Q1: How should we handle session storage?
|
|
54
|
+
> Option A: JWT in HTTP-only cookies (Pros: Secure against XSS. Cons: Harder to invalidate).
|
|
55
|
+
> Option B: Redis-backed sessions (Pros: Easy to revoke. Cons: Requires setting up Redis).
|
|
56
|
+
> Option C: (Custom, please type your answer)
|
|
57
|
+
>
|
|
58
|
+
> **You:** Q1: A
|
|
59
|
+
|
|
60
|
+
- **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')"*
|
|
61
|
+
- **Drafting:** Once approved, it will generate a highly structured `.mspec/specs/001-auth.md` file featuring a Mermaid diagram and an Acceptance Criteria checklist.
|
|
62
|
+
- **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.
|
|
59
63
|
|
|
60
64
|
### Step 3: Scaffold the Plan
|
|
61
65
|
Once you are happy with the spec, use the planning command to break it down.
|
|
@@ -111,4 +115,4 @@ your-project/
|
|
|
111
115
|
│ └── mspec.implement.toml
|
|
112
116
|
├── src/ # Your actual code
|
|
113
117
|
└── package.json
|
|
114
|
-
```
|
|
118
|
+
```
|
package/dist/templates/index.js
CHANGED
|
@@ -13,16 +13,27 @@ PHASE 0: CONTEXT GATHERING
|
|
|
13
13
|
|
|
14
14
|
PHASE 1: INQUIRY
|
|
15
15
|
2. DO NOT generate the specification file immediately.
|
|
16
|
-
3. Ask the user 3
|
|
16
|
+
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.
|
|
17
|
+
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.
|
|
18
|
+
Use this exact format for every question:
|
|
19
|
+
|
|
20
|
+
Q[Number]: [Your Question]
|
|
21
|
+
Option A: [Recommendation 1] (Pros: ... Cons: ...)
|
|
22
|
+
Option B: [Recommendation 2] (Pros: ... Cons: ...)
|
|
23
|
+
Option C: (Custom, please type your answer)
|
|
24
|
+
|
|
25
|
+
5. To build a strong spec, your questions must extract:
|
|
17
26
|
- Core Objective: What is the exact goal and business logic?
|
|
18
27
|
- Edge Cases & Error Handling: What happens on failure, empty states, or invalid input?
|
|
19
28
|
- Data Structures: What exact fields, types, and constraints are required?
|
|
20
29
|
- Dependencies: Does this rely on external APIs, existing UI components, or specific libraries?
|
|
21
|
-
|
|
30
|
+
6. Wait for the user to answer (e.g., "Q1: A, Q2: C - use Redis instead").
|
|
31
|
+
7. If the user provides extra context or wants to discuss further, engage in the discussion and revise your understanding.
|
|
32
|
+
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.
|
|
22
33
|
|
|
23
34
|
PHASE 2: DRAFTING
|
|
24
|
-
|
|
25
|
-
|
|
35
|
+
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).
|
|
36
|
+
10. The spec MUST strictly follow this structure:
|
|
26
37
|
# Spec: [Feature Name]
|
|
27
38
|
## 1. Goal & Context
|
|
28
39
|
(Clear explanation of the feature and business value)
|
|
@@ -34,12 +45,13 @@ PHASE 2: DRAFTING
|
|
|
34
45
|
(Explicit list of what can go wrong and how the system should react)
|
|
35
46
|
## 5. Acceptance Criteria
|
|
36
47
|
(Checklist of what must be true for this feature to be considered complete)
|
|
48
|
+
11. Output the exact path to the generated spec file so the user can easily open it.
|
|
49
|
+
12. CRITICAL: Stop and ask: "Please review the drafted spec file. Should I finalize this phase? (Please reply 'Approved' or 'LGTM')".
|
|
50
|
+
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.
|
|
37
51
|
|
|
38
|
-
PHASE 3: REVIEW
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
9. Once approved, output the exact path to the generated spec file so the user can easily open it.
|
|
42
|
-
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]?"`
|
|
52
|
+
PHASE 3: REVIEW & HANDOFF
|
|
53
|
+
14. Once the drafted spec is approved, the specification phase is complete.
|
|
54
|
+
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]?"`
|
|
43
55
|
},
|
|
44
56
|
'mspec.plan': {
|
|
45
57
|
desc: 'Plan tasks for an existing spec',
|