nimai-core 0.4.9 → 0.5.1
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/data/nimai-spec-full.md +63 -0
- package/data/nimai-spec-lite.md +39 -0
- package/dist/index.d.ts +0 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +0 -2
- package/dist/index.js.map +1 -1
- package/dist/lint.d.ts.map +1 -1
- package/dist/lint.js +88 -311
- package/dist/lint.js.map +1 -1
- package/dist/prompts.d.ts +18 -8
- package/dist/prompts.d.ts.map +1 -1
- package/dist/prompts.js +142 -53
- package/dist/prompts.js.map +1 -1
- package/dist/template.d.ts +12 -1
- package/dist/template.d.ts.map +1 -1
- package/dist/template.js +32 -0
- package/dist/template.js.map +1 -1
- package/dist/types.d.ts +3 -7
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/data/FORGE-spec-template.md +0 -454
- package/dist/clarification.d.ts +0 -22
- package/dist/clarification.d.ts.map +0 -1
- package/dist/clarification.js +0 -106
- package/dist/clarification.js.map +0 -1
- package/dist/context.d.ts +0 -3
- package/dist/context.d.ts.map +0 -1
- package/dist/context.js +0 -186
- package/dist/context.js.map +0 -1
|
@@ -1,454 +0,0 @@
|
|
|
1
|
-
# FORGE Spec Template
|
|
2
|
-
> **You are here:** This is the Spec Template — the execution tool. Use it to turn a project direction into a complete agent-ready brief.
|
|
3
|
-
>
|
|
4
|
-
> **The other docs in this system:**
|
|
5
|
-
> - **Quick Reference** (`FORGE-quickref.md`) — start here if you don't have a project direction yet. If the request is a new idea or open-ended, go to the Quick Reference and run the Divergence → Convergence Loop or the Self-Spec Agent first. Come back here once you have a chosen direction.
|
|
6
|
-
> - **Canonical Framework** (`FORGE-canonical.md`) — go there if you encounter a concept in this template you don't fully understand. Each section maps to a section in the canonical doc.
|
|
7
|
-
>
|
|
8
|
-
> **When to be in this doc:** You have a specific project or direction. You are ready to define it completely before handing it to an agent. If you can't fill in a field, that is an unresolved decision — resolve it here, not mid-run.
|
|
9
|
-
>
|
|
10
|
-
> **Solo operator shortcut:** Instead of filling this manually, use the Self-Spec Agent prompt in the Quick Reference to generate a draft, then review and approve it here.
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
> Fill in every field before handing to an agent. A blank field is an unresolved decision — resolve it here, not mid-run.
|
|
15
|
-
> *Based on the FORGE*
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## 0. Pre-Flight Decisions
|
|
20
|
-
> These must be set first. Everything else is built on top of them.
|
|
21
|
-
|
|
22
|
-
**Risk Tier:** [ ] Low [ ] Medium [ ] High
|
|
23
|
-
*(If unsure, go one tier higher)*
|
|
24
|
-
|
|
25
|
-
**Primary Cognitive Mode for this project:**
|
|
26
|
-
[ ] Deterministic [ ] Exploratory [ ] Adversarial [ ] Synthesis [ ] Audit
|
|
27
|
-
[ ] Multi-phase — using Divergence → Convergence Loop (see Section 6)
|
|
28
|
-
*→ Unsure which mode? See Cognitive Mode table in Quick Reference or Canonical doc.*
|
|
29
|
-
|
|
30
|
-
**Resource Governance:**
|
|
31
|
-
- Model tier (Planner): `_______________`
|
|
32
|
-
- Model tier (Workers): `_______________`
|
|
33
|
-
- Max runtime per sub-task: `_______________`
|
|
34
|
-
- Total compute / cost budget: `_______________`
|
|
35
|
-
- Retry limit before escalation: `_______________`
|
|
36
|
-
- Cost threshold that triggers stop-and-report: `_______________`
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
## 1. Specification Layer — The Blueprint
|
|
41
|
-
|
|
42
|
-
### 1.1 Final Deliverable
|
|
43
|
-
*Describe precisely. Not "a good analysis" — describe the exact artifact, format, and measurable quality.*
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
Deliverable: _______________________________________________
|
|
47
|
-
|
|
48
|
-
Format: ___________________________________________________
|
|
49
|
-
|
|
50
|
-
Length / Size: _____________________________________________
|
|
51
|
-
|
|
52
|
-
Measurable quality bar: ____________________________________
|
|
53
|
-
|
|
54
|
-
Benchmark dataset (if quality bar requires measurement):
|
|
55
|
-
path: _______________ (e.g. tests/fixtures/receipts/ or N/A)
|
|
56
|
-
schema: _____________ (field names and types of each labeled example, or N/A)
|
|
57
|
-
threshold computation rule: ___ (e.g. "pass rate = correct / total labeled examples", or N/A)
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
### 1.2 Scope Boundaries
|
|
61
|
-
*Be explicit. Ambiguity here becomes scope creep mid-run.*
|
|
62
|
-
|
|
63
|
-
**In scope:**
|
|
64
|
-
- `_______________`
|
|
65
|
-
- `_______________`
|
|
66
|
-
- `_______________`
|
|
67
|
-
|
|
68
|
-
**Out of scope (Must-Not):**
|
|
69
|
-
- `_______________`
|
|
70
|
-
- `_______________`
|
|
71
|
-
- `_______________`
|
|
72
|
-
|
|
73
|
-
### 1.3 Task Decomposition
|
|
74
|
-
*Break the project into sub-tasks. Each must satisfy the 5 Primitives and complete in under 2 hours.*
|
|
75
|
-
*→ Need a reminder of the 5 Primitives? See Quick Reference or Canonical doc Section "5 Primitives."*
|
|
76
|
-
|
|
77
|
-
| # | Sub-task | Cognitive Mode | Risk Tier | Acceptance Criteria | Eval Method |
|
|
78
|
-
|---|---|---|---|---|---|
|
|
79
|
-
| 1 | | | | | |
|
|
80
|
-
| 2 | | | | | |
|
|
81
|
-
| 3 | | | | | |
|
|
82
|
-
| 4 | | | | | |
|
|
83
|
-
| 5 | | | | | |
|
|
84
|
-
|
|
85
|
-
*Add rows as needed. Every sub-task needs all five columns filled.*
|
|
86
|
-
|
|
87
|
-
*Note: Sub-task risk tiers may differ from the overall project tier. A research sub-task and a production deployment sub-task in the same project have different risk profiles — assign each independently. The project-level tier sets the floor for escalation; sub-task tiers govern validation routing.*
|
|
88
|
-
|
|
89
|
-
### 1.4 Acceptance Criteria — Master Definition of Done
|
|
90
|
-
*Binary. Measurable. No subjective criteria.*
|
|
91
|
-
|
|
92
|
-
The project is complete when ALL of the following are true:
|
|
93
|
-
- [ ] `_______________`
|
|
94
|
-
- [ ] `_______________`
|
|
95
|
-
- [ ] `_______________`
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## 1.5 Mechanism Decision
|
|
100
|
-
*One block per core architectural or algorithmic choice. If no core mechanism applies, write "N/A" and justify.*
|
|
101
|
-
*A builder must be able to start coding without choosing missing architecture. If any mechanism is undecided, resolve it here first.*
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
**Decision: [short name, e.g., "Primary parsing method"]**
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
Chosen approach: _______________________________________________
|
|
109
|
-
|
|
110
|
-
Rejected alternatives: _________________________________________
|
|
111
|
-
|
|
112
|
-
Why rejected: __________________________________________________
|
|
113
|
-
|
|
114
|
-
Impact on ACs: _________________________________________________
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
---
|
|
118
|
-
|
|
119
|
-
## 1.6 Architecture Lock
|
|
120
|
-
*Required for medium/high coding specs. Advisory for low/unknown/non-coding specs.*
|
|
121
|
-
*All fields must be resolved before builder handoff. Blank placeholders and "TBD" are unresolved.*
|
|
122
|
-
|
|
123
|
-
```
|
|
124
|
-
Persistence layer: _______________________________________________
|
|
125
|
-
|
|
126
|
-
File/object storage: _____________________________________________
|
|
127
|
-
|
|
128
|
-
External model/service + env var: ________________________________
|
|
129
|
-
|
|
130
|
-
API trigger flow: ________________________________________________
|
|
131
|
-
|
|
132
|
-
Entity status state machine: _____________________________________
|
|
133
|
-
|
|
134
|
-
Auth implementation: _____________________________________________
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
---
|
|
138
|
-
|
|
139
|
-
## 2. Intent Layer — The Compass
|
|
140
|
-
|
|
141
|
-
### 2.1 Agent Deployment Purpose
|
|
142
|
-
*Tell the agent what it is, what it is not, and who consumes its output. One clear paragraph.*
|
|
143
|
-
|
|
144
|
-
```
|
|
145
|
-
You are: ___________________________________________________
|
|
146
|
-
|
|
147
|
-
You are NOT responsible for: _______________________________
|
|
148
|
-
|
|
149
|
-
Your output is consumed by: ________________________________
|
|
150
|
-
(human decision-maker / another agent / automated pipeline)
|
|
151
|
-
|
|
152
|
-
Your output feeds into: ____________________________________
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
### 2.2 Trade-off Hierarchy
|
|
156
|
-
*Rank these in order of priority. The agent will use this when it hits a fork.*
|
|
157
|
-
|
|
158
|
-
Rank the following from 1 (highest) to n (lowest) for this task:
|
|
159
|
-
|
|
160
|
-
| Priority | Value |
|
|
161
|
-
|---|---|
|
|
162
|
-
| `___` | Accuracy / Correctness |
|
|
163
|
-
| `___` | Speed / Efficiency |
|
|
164
|
-
| `___` | Cost / Token economy |
|
|
165
|
-
| `___` | Safety / Risk avoidance |
|
|
166
|
-
| `___` | Novelty / Creativity |
|
|
167
|
-
| `___` | Completeness |
|
|
168
|
-
| `___` | Simplicity / Readability |
|
|
169
|
-
| `___` | *(add domain-specific value)* |
|
|
170
|
-
|
|
171
|
-
### 2.3 Constraint Architecture
|
|
172
|
-
|
|
173
|
-
**Must (non-negotiable requirements):**
|
|
174
|
-
- `_______________`
|
|
175
|
-
- `_______________`
|
|
176
|
-
|
|
177
|
-
**Must-Not (hard prohibitions):**
|
|
178
|
-
- `_______________`
|
|
179
|
-
- `_______________`
|
|
180
|
-
|
|
181
|
-
**Prefer (soft preferences when trade-offs arise):**
|
|
182
|
-
- `_______________`
|
|
183
|
-
- `_______________`
|
|
184
|
-
|
|
185
|
-
**Escalate (stop and surface to human when):**
|
|
186
|
-
- `_______________`
|
|
187
|
-
- `_______________`
|
|
188
|
-
|
|
189
|
-
### 2.4 Forbidden Approaches
|
|
190
|
-
*Specific methods, tools, frameworks, or reasoning patterns to avoid.*
|
|
191
|
-
|
|
192
|
-
- `_______________`
|
|
193
|
-
- `_______________`
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## 3. Context Layer — The Environment
|
|
198
|
-
|
|
199
|
-
### 3.1 Provided Context
|
|
200
|
-
*List all documents, artifacts, or data sources being provided. Mark each as AUTHORITATIVE or REFERENCE.*
|
|
201
|
-
|
|
202
|
-
| Source | Type | Authority Level | Notes |
|
|
203
|
-
|---|---|---|---|
|
|
204
|
-
| | | AUTHORITATIVE / REFERENCE | |
|
|
205
|
-
| | | AUTHORITATIVE / REFERENCE | |
|
|
206
|
-
| | | AUTHORITATIVE / REFERENCE | |
|
|
207
|
-
|
|
208
|
-
### 3.2 Known State
|
|
209
|
-
*What has already been tried? What failed? What is known?*
|
|
210
|
-
|
|
211
|
-
```
|
|
212
|
-
Prior attempts: ____________________________________________
|
|
213
|
-
|
|
214
|
-
Known failures / dead ends: ________________________________
|
|
215
|
-
|
|
216
|
-
Known constraints: _________________________________________
|
|
217
|
-
|
|
218
|
-
Current blockers: __________________________________________
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
### 3.3 Context Freshness
|
|
222
|
-
*Tell the agent when to trust the provided context vs. when to re-fetch or verify.*
|
|
223
|
-
|
|
224
|
-
[ ] All provided context is current — use as ground truth
|
|
225
|
-
[ ] The following sources may be stale and should be verified: `_______________`
|
|
226
|
-
[ ] The agent must re-fetch live data for: `_______________`
|
|
227
|
-
[ ] MCP connections available: `_______________`
|
|
228
|
-
|
|
229
|
-
### 3.4 Domain Conventions
|
|
230
|
-
*Terminology, style, standards, or norms the agent must match.*
|
|
231
|
-
|
|
232
|
-
```
|
|
233
|
-
Terminology to use: ________________________________________
|
|
234
|
-
|
|
235
|
-
Terminology to avoid: ______________________________________
|
|
236
|
-
|
|
237
|
-
Style / format standards: __________________________________
|
|
238
|
-
|
|
239
|
-
Domain-specific conventions: _______________________________
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
---
|
|
243
|
-
|
|
244
|
-
## 4. Prompt Layer — The Trigger
|
|
245
|
-
|
|
246
|
-
### 4.1 Opening System Instruction
|
|
247
|
-
*The master instruction that frames the entire run. Reference Sections 1–3 explicitly.*
|
|
248
|
-
|
|
249
|
-
```
|
|
250
|
-
You are [deployment purpose from 2.1].
|
|
251
|
-
|
|
252
|
-
Your task is to produce [deliverable from 1.1].
|
|
253
|
-
|
|
254
|
-
You are operating within the following constraints: [from 2.3].
|
|
255
|
-
|
|
256
|
-
Your trade-off priority order is: [from 2.2].
|
|
257
|
-
|
|
258
|
-
The context you have been provided is: [from 3.1].
|
|
259
|
-
|
|
260
|
-
You will complete this task by executing the following sub-tasks in order: [from 1.3].
|
|
261
|
-
|
|
262
|
-
For each sub-task, your completion criterion is: [from 1.4].
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
### 4.2 Per-Sub-Task Prompt Template
|
|
266
|
-
*Use this template for each sub-task trigger.*
|
|
267
|
-
|
|
268
|
-
```
|
|
269
|
-
Sub-task [#]: [name]
|
|
270
|
-
Cognitive mode: [mode]
|
|
271
|
-
Your input: [what you're working from]
|
|
272
|
-
Your output: [exact format and content required]
|
|
273
|
-
Acceptance criteria: [binary criteria from 1.3]
|
|
274
|
-
Evaluation: [how this will be checked]
|
|
275
|
-
Resource cap: [max runtime / tokens for this sub-task]
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
---
|
|
279
|
-
|
|
280
|
-
## 5. Governance & Validation
|
|
281
|
-
|
|
282
|
-
### 5.1 Escalation Contract
|
|
283
|
-
|
|
284
|
-
**Escalation triggers** *(from 2.3 — repeated here for executor clarity)*:
|
|
285
|
-
- `_______________`
|
|
286
|
-
- `_______________`
|
|
287
|
-
|
|
288
|
-
**Who reviews escalations:**
|
|
289
|
-
```
|
|
290
|
-
Name / Role: _______________________________________________
|
|
291
|
-
Contact: __________________________________________________
|
|
292
|
-
Response SLA: ______________________________________________
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
**If no response arrives within SLA, the agent should:**
|
|
296
|
-
[ ] Hold and wait
|
|
297
|
-
[ ] Attempt alternative path: `_______________`
|
|
298
|
-
[ ] Abort and report
|
|
299
|
-
|
|
300
|
-
### 5.2 Adversarial Reflection Trigger
|
|
301
|
-
*(Required for Medium and High risk tasks)*
|
|
302
|
-
|
|
303
|
-
[ ] Not required (Low risk)
|
|
304
|
-
[ ] Required after sub-task(s): `_______________`
|
|
305
|
-
[ ] Required before final delivery
|
|
306
|
-
|
|
307
|
-
The agent should critique: `_______________`
|
|
308
|
-
The revision threshold is: `_______________` *(what level of critique warrants a revision?)*
|
|
309
|
-
|
|
310
|
-
### 5.3 Uncertainty Reporting
|
|
311
|
-
*(Required for non-deterministic domains)*
|
|
312
|
-
|
|
313
|
-
[ ] Not required
|
|
314
|
-
[ ] Required — agent must report:
|
|
315
|
-
- Confidence estimate (0–100%) with justification
|
|
316
|
-
- Primary uncertainty drivers
|
|
317
|
-
- What data would most reduce uncertainty
|
|
318
|
-
- Alternative plausible interpretations
|
|
319
|
-
|
|
320
|
-
---
|
|
321
|
-
|
|
322
|
-
## 6. Brainstorming Mode (Divergence → Convergence)
|
|
323
|
-
*Complete this section only if primary mode is multi-phase brainstorming.*
|
|
324
|
-
|
|
325
|
-
**Phase 1 — DIVERGE (Exploratory Mode)**
|
|
326
|
-
```
|
|
327
|
-
Generate: _________________________________________________
|
|
328
|
-
Constraint: No filtering or judgment at this stage.
|
|
329
|
-
Output format: ____________________________________________
|
|
330
|
-
Volume target: ____________________________________________
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
**Phase 2 — CLUSTER (Synthesis Mode)**
|
|
334
|
-
```
|
|
335
|
-
Organize the output of Phase 1 by: ________________________
|
|
336
|
-
Identify: _________________________________________________
|
|
337
|
-
Output format: ____________________________________________
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
**Phase 3 — STRESS-TEST (Adversarial Mode)**
|
|
341
|
-
```
|
|
342
|
-
Attack the top [n] candidates from Phase 2.
|
|
343
|
-
Criteria to stress-test against: __________________________
|
|
344
|
-
Output format: ____________________________________________
|
|
345
|
-
What constitutes a fatal flaw: ____________________________
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
**Phase 4 — FORMALIZE (Deterministic Mode)**
|
|
349
|
-
```
|
|
350
|
-
Selected direction: ______________________________________
|
|
351
|
-
Formalize as: ____________________________________________
|
|
352
|
-
Acceptance criteria: _____________________________________
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
---
|
|
356
|
-
|
|
357
|
-
## 7. Domain-Specific Additions
|
|
358
|
-
|
|
359
|
-
### If Coding:
|
|
360
|
-
- Language / framework / version: `_______________`
|
|
361
|
-
- Performance targets: `_______________`
|
|
362
|
-
- API / interface contracts: `_______________`
|
|
363
|
-
- Security requirements: `_______________`
|
|
364
|
-
- Test coverage expectation: `_______________`
|
|
365
|
-
|
|
366
|
-
### If Science / Research:
|
|
367
|
-
- Null hypothesis: `_______________`
|
|
368
|
-
- Falsification criteria: `_______________`
|
|
369
|
-
- Authorized data sources: `_______________`
|
|
370
|
-
- Forbidden data sources: `_______________`
|
|
371
|
-
- Statistical significance threshold: `_______________`
|
|
372
|
-
- Correction method: `_______________`
|
|
373
|
-
- Reproducibility requirements: `_______________`
|
|
374
|
-
|
|
375
|
-
### If Writing / Content:
|
|
376
|
-
- Audience: `_______________`
|
|
377
|
-
- Purpose: `_______________`
|
|
378
|
-
- Structure: `_______________`
|
|
379
|
-
- Word count / length: `_______________`
|
|
380
|
-
- Style reference: `_______________`
|
|
381
|
-
- Mandatory inclusions: `_______________`
|
|
382
|
-
- Mandatory exclusions: `_______________`
|
|
383
|
-
|
|
384
|
-
### If Business / Strategy:
|
|
385
|
-
- Decision-maker: `_______________`
|
|
386
|
-
- Decision to be made: `_______________`
|
|
387
|
-
- Options to evaluate: `_______________`
|
|
388
|
-
- Recommendation format: `_______________`
|
|
389
|
-
- Regulatory Must-Nots: `_______________`
|
|
390
|
-
- Stakeholder sensitivities: `_______________`
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## 8. Spec Validation (Red-Team Checklist)
|
|
395
|
-
*Complete before handing to the agent. Every unchecked box is a known risk.*
|
|
396
|
-
|
|
397
|
-
**5 Primitives — does every sub-task have:**
|
|
398
|
-
- [ ] A self-contained problem statement (zero questions needed to start)
|
|
399
|
-
- [ ] A Constraint Architecture (Must / Must-Not / Prefer / Escalate)
|
|
400
|
-
- [ ] A runtime under 2 hours
|
|
401
|
-
- [ ] Binary acceptance criteria
|
|
402
|
-
- [ ] A built-in evaluation method
|
|
403
|
-
|
|
404
|
-
**Failure Mode Taxonomy — does this spec prevent:**
|
|
405
|
-
- [ ] Scope Creep — explicit Must-Not list and scope boundaries
|
|
406
|
-
- [ ] Hallucinated Completion — binary acceptance criteria defined
|
|
407
|
-
- [ ] Intent Drift — ranked trade-offs and deployment purpose explicit
|
|
408
|
-
- [ ] Context Collapse — context curated; noise removed
|
|
409
|
-
- [ ] Runaway Cost — resource caps set before decomposition
|
|
410
|
-
- [ ] Overconfident Output — uncertainty reporting required (if applicable)
|
|
411
|
-
|
|
412
|
-
**Final gate:**
|
|
413
|
-
- [ ] Risk tier and resource governance set *before* decomposition
|
|
414
|
-
- [ ] Every agent has a deployment purpose statement
|
|
415
|
-
- [ ] Escalation contract complete (who, when, SLA, no-response behavior)
|
|
416
|
-
- [ ] Planner execution plan will be saved as artifact
|
|
417
|
-
|
|
418
|
-
---
|
|
419
|
-
|
|
420
|
-
## 8.5 Edge Cases and Failure Modes
|
|
421
|
-
> Required for medium/high risk specs. Red-team the spec before builder handoff.
|
|
422
|
-
> For each scenario, document what the spec says the builder must do. A blank list is a hard stop.
|
|
423
|
-
|
|
424
|
-
**FORGE failure mode coverage:**
|
|
425
|
-
- Scope Creep — which Must-Not explicitly prevents it: `_______________`
|
|
426
|
-
- Hallucinated Completion — which AC is hardest to fake: `_______________`
|
|
427
|
-
- Intent Drift — which decision will the builder most likely get wrong: `_______________`
|
|
428
|
-
- Context Collapse — what context is load-bearing and must not be dropped: `_______________`
|
|
429
|
-
- Runaway Cost — what resource cap prevents unbounded execution: `_______________`
|
|
430
|
-
- Overconfident Output — what requires uncertainty reporting: `_______________`
|
|
431
|
-
|
|
432
|
-
**Domain-specific edge cases:**
|
|
433
|
-
- `_______________`
|
|
434
|
-
- `_______________`
|
|
435
|
-
|
|
436
|
-
---
|
|
437
|
-
|
|
438
|
-
## 9. Spec Convergence
|
|
439
|
-
> Fill before handing to a builder. A non-zero count or "no" is a hard stop.
|
|
440
|
-
> Every [NEEDS HUMAN INPUT] flag from spec drafting must be resolved before this section is filled.
|
|
441
|
-
|
|
442
|
-
```
|
|
443
|
-
open_questions: 0
|
|
444
|
-
ambiguities_remaining: 0
|
|
445
|
-
ready_for_build: yes
|
|
446
|
-
convergence_notes: _______________________________________________
|
|
447
|
-
```
|
|
448
|
-
|
|
449
|
-
---
|
|
450
|
-
|
|
451
|
-
*FORGE Spec Template v1.0 — companion to the FORGE system. A blank field is an unresolved decision.*
|
|
452
|
-
*System docs: Quick Reference · Canonical Framework · Spec Template (this doc)*
|
|
453
|
-
|
|
454
|
-
<!-- nimai-spec -->
|
package/dist/clarification.d.ts
DELETED
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Rule-based clarification heuristics for nimai_spec.
|
|
3
|
-
*
|
|
4
|
-
* These are pure functions — no IO, no LLM calls.
|
|
5
|
-
* Trigger `clarifications_needed` when any heuristic fires.
|
|
6
|
-
*/
|
|
7
|
-
export interface ClarificationResult {
|
|
8
|
-
needed: boolean;
|
|
9
|
-
reasons: string[];
|
|
10
|
-
questions: string[];
|
|
11
|
-
}
|
|
12
|
-
/**
|
|
13
|
-
* Evaluate whether a spec request needs clarification before drafting.
|
|
14
|
-
*
|
|
15
|
-
* Heuristics (any one firing triggers clarification):
|
|
16
|
-
* 1. Request is under 10 words
|
|
17
|
-
* 2. Zero repo files matched by context extractor
|
|
18
|
-
* 3. No domain nouns or action verbs detected
|
|
19
|
-
* 4. Conflicting stack hints (two competing tech choices in same category)
|
|
20
|
-
*/
|
|
21
|
-
export declare function detectClarifications(request: string, contextFileCount: number): ClarificationResult;
|
|
22
|
-
//# sourceMappingURL=clarification.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"clarification.d.ts","sourceRoot":"","sources":["../src/clarification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuEH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,GACvB,mBAAmB,CA+BrB"}
|
package/dist/clarification.js
DELETED
|
@@ -1,106 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/**
|
|
3
|
-
* Rule-based clarification heuristics for nimai_spec.
|
|
4
|
-
*
|
|
5
|
-
* These are pure functions — no IO, no LLM calls.
|
|
6
|
-
* Trigger `clarifications_needed` when any heuristic fires.
|
|
7
|
-
*/
|
|
8
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
9
|
-
exports.detectClarifications = detectClarifications;
|
|
10
|
-
// ─── Domain noun / action vocab ───────────────────────────────────────────────
|
|
11
|
-
/**
|
|
12
|
-
* Minimum set of technical domain nouns and action verbs that indicate the
|
|
13
|
-
* request describes a real engineering task. If the request contains none of
|
|
14
|
-
* these, it is likely too vague to spec reliably.
|
|
15
|
-
*/
|
|
16
|
-
const DOMAIN_TOKENS = new Set([
|
|
17
|
-
// Action verbs
|
|
18
|
-
'add', 'build', 'create', 'implement', 'fix', 'refactor', 'update', 'migrate',
|
|
19
|
-
'design', 'integrate', 'deploy', 'remove', 'generate', 'optimize', 'extend',
|
|
20
|
-
'replace', 'extract', 'expose', 'wire', 'scaffold', 'test', 'benchmark',
|
|
21
|
-
// Technical nouns
|
|
22
|
-
'api', 'service', 'component', 'model', 'module', 'database', 'endpoint',
|
|
23
|
-
'interface', 'schema', 'type', 'function', 'class', 'route', 'handler',
|
|
24
|
-
'middleware', 'auth', 'token', 'config', 'cli', 'ui', 'hook', 'store',
|
|
25
|
-
'query', 'mutation', 'event', 'queue', 'cache', 'index', 'migration',
|
|
26
|
-
'server', 'client', 'backend', 'frontend', 'test', 'spec', 'pipeline',
|
|
27
|
-
'workflow', 'adapter', 'plugin', 'sdk', 'contract', 'validator', 'parser',
|
|
28
|
-
]);
|
|
29
|
-
/**
|
|
30
|
-
* Returns true if the request contains at least one recognizable domain token.
|
|
31
|
-
*/
|
|
32
|
-
function hasDomainNoun(request) {
|
|
33
|
-
const words = request.toLowerCase().match(/\b[a-z]+\b/g) ?? [];
|
|
34
|
-
return words.some(w => DOMAIN_TOKENS.has(w));
|
|
35
|
-
}
|
|
36
|
-
// ─── Conflicting stack detection ──────────────────────────────────────────────
|
|
37
|
-
/** Groups of mutually-competing technology choices. Two items from the same group = conflict. */
|
|
38
|
-
const STACK_GROUPS = [
|
|
39
|
-
// Programming languages — any two in the same request signals ambiguous stack
|
|
40
|
-
[
|
|
41
|
-
'python', 'ruby', 'java', 'golang', 'rust', 'kotlin', 'swift', 'scala',
|
|
42
|
-
'php', 'elixir', 'csharp', 'typescript', 'javascript',
|
|
43
|
-
],
|
|
44
|
-
// JS UI frameworks
|
|
45
|
-
['react', 'vue', 'angular', 'svelte'],
|
|
46
|
-
// CSS frameworks
|
|
47
|
-
['tailwind', 'bootstrap'],
|
|
48
|
-
// Relational databases
|
|
49
|
-
['postgresql', 'postgres', 'mysql', 'sqlite'],
|
|
50
|
-
// NoSQL databases
|
|
51
|
-
['mongodb', 'dynamodb', 'firestore', 'cassandra'],
|
|
52
|
-
// JS test frameworks
|
|
53
|
-
['jest', 'vitest', 'jasmine'],
|
|
54
|
-
];
|
|
55
|
-
/**
|
|
56
|
-
* Returns true if the request mentions ≥2 items from the same competing stack group,
|
|
57
|
-
* indicating an ambiguous or conflicting technology choice.
|
|
58
|
-
*/
|
|
59
|
-
function hasConflictingStack(request) {
|
|
60
|
-
const lower = request.toLowerCase();
|
|
61
|
-
for (const group of STACK_GROUPS) {
|
|
62
|
-
const hits = group.filter(tech => {
|
|
63
|
-
// Match as whole word or compound (e.g. "typescript", "vue.js")
|
|
64
|
-
const pattern = new RegExp(`\\b${tech.replace(/[-.]/g, '[-.\\s]?')}\\b`, 'i');
|
|
65
|
-
return pattern.test(lower);
|
|
66
|
-
});
|
|
67
|
-
if (hits.length >= 2)
|
|
68
|
-
return true;
|
|
69
|
-
}
|
|
70
|
-
return false;
|
|
71
|
-
}
|
|
72
|
-
/**
|
|
73
|
-
* Evaluate whether a spec request needs clarification before drafting.
|
|
74
|
-
*
|
|
75
|
-
* Heuristics (any one firing triggers clarification):
|
|
76
|
-
* 1. Request is under 10 words
|
|
77
|
-
* 2. Zero repo files matched by context extractor
|
|
78
|
-
* 3. No domain nouns or action verbs detected
|
|
79
|
-
* 4. Conflicting stack hints (two competing tech choices in same category)
|
|
80
|
-
*/
|
|
81
|
-
function detectClarifications(request, contextFileCount) {
|
|
82
|
-
const reasons = [];
|
|
83
|
-
const wordCount = request.trim().split(/\s+/).length;
|
|
84
|
-
if (wordCount < 10) {
|
|
85
|
-
reasons.push(`request is too short (${wordCount} words — add more context)`);
|
|
86
|
-
}
|
|
87
|
-
if (contextFileCount === 0) {
|
|
88
|
-
reasons.push('no relevant repo files matched — is the repo path correct, or is this a new project?');
|
|
89
|
-
}
|
|
90
|
-
if (!hasDomainNoun(request)) {
|
|
91
|
-
reasons.push('no recognizable domain nouns or action verbs found — describe what should be built or changed');
|
|
92
|
-
}
|
|
93
|
-
if (hasConflictingStack(request)) {
|
|
94
|
-
reasons.push('conflicting technology stack hints detected — clarify which stack applies or separate into distinct tasks');
|
|
95
|
-
}
|
|
96
|
-
const needed = reasons.length > 0;
|
|
97
|
-
const questions = needed
|
|
98
|
-
? [
|
|
99
|
-
'What is the primary goal or outcome you want to achieve?',
|
|
100
|
-
'Which specific files, components, or systems should be modified?',
|
|
101
|
-
'Are there constraints, dependencies, or requirements we should be aware of?',
|
|
102
|
-
]
|
|
103
|
-
: [];
|
|
104
|
-
return { needed, reasons, questions };
|
|
105
|
-
}
|
|
106
|
-
//# sourceMappingURL=clarification.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"clarification.js","sourceRoot":"","sources":["../src/clarification.ts"],"names":[],"mappings":"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"}
|
package/dist/context.d.ts
DELETED
package/dist/context.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA4DtC,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAiB/E"}
|