specpilot 1.8.0 → 2.0.0
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 +29 -14
- package/dist/commands/add-specs.d.ts.map +1 -1
- package/dist/commands/add-specs.js +44 -1
- package/dist/commands/add-specs.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +45 -1
- package/dist/commands/init.js.map +1 -1
- package/dist/utils/ideConfigGenerator.d.ts +1 -0
- package/dist/utils/ideConfigGenerator.d.ts.map +1 -1
- package/dist/utils/ideConfigGenerator.js +32 -27
- package/dist/utils/ideConfigGenerator.js.map +1 -1
- package/dist/utils/specFileGenerator.d.ts +4 -2
- package/dist/utils/specFileGenerator.d.ts.map +1 -1
- package/dist/utils/specFileGenerator.js +144 -448
- package/dist/utils/specFileGenerator.js.map +1 -1
- package/dist/utils/specGenerator.d.ts +5 -1
- package/dist/utils/specGenerator.d.ts.map +1 -1
- package/dist/utils/specGenerator.js +16 -1
- package/dist/utils/specGenerator.js.map +1 -1
- package/dist/utils/templateEngine.d.ts +2 -0
- package/dist/utils/templateEngine.d.ts.map +1 -1
- package/dist/utils/templateEngine.js +1 -41
- package/dist/utils/templateEngine.js.map +1 -1
- package/package.json +1 -1
|
@@ -17,23 +17,14 @@ This folder contains structured documentation for your project.
|
|
|
17
17
|
|
|
18
18
|
## 🚀 Quick Start: Generate Your Specs with AI
|
|
19
19
|
|
|
20
|
-
Your
|
|
20
|
+
Your spec files have been scaffolded with placeholders. An onboarding prompt has been saved to [\`development/onboarding.md\`](development/onboarding.md).
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
2. Find the **"New Project Onboarding Prompt"** section.
|
|
25
|
-
3. Copy the entire fenced code block (\`\`\`...\`\`\`).
|
|
26
|
-
|
|
27
|
-
### Step 2: Paste into Your AI Agent
|
|
28
|
-
1. In your IDE (VS Code, Cursor, etc.), open the AI chat.
|
|
29
|
-
2. Paste the prompt and run it.
|
|
22
|
+
1. Open \`development/onboarding.md\` and copy the prompt inside it.
|
|
23
|
+
2. Paste it into your AI agent (VS Code, Cursor, etc.).
|
|
30
24
|
3. The AI will draft all spec files based on your project description.
|
|
25
|
+
4. Review each file, refine as needed, then **delete \`onboarding.md\`**.
|
|
31
26
|
|
|
32
|
-
|
|
33
|
-
- The generated specs are a **starting point** based on the AI's understanding.
|
|
34
|
-
- Review each file — change, add, or remove anything as your project evolves.
|
|
35
|
-
- Add details the AI couldn't know before you start coding.
|
|
36
|
-
- Run \`specpilot validate\` to ensure consistency.
|
|
27
|
+
Run \`specpilot validate\` to check consistency at any time.
|
|
37
28
|
|
|
38
29
|
## 📁 File Structure
|
|
39
30
|
- \`project/\`: Metadata and requirements
|
|
@@ -58,22 +49,14 @@ This folder contains structured documentation for your codebase.
|
|
|
58
49
|
|
|
59
50
|
## 🚀 Quick Start: Populate Your Specs
|
|
60
51
|
|
|
61
|
-
Your
|
|
62
|
-
|
|
63
|
-
### Step 1: Copy the Onboarding Prompt
|
|
64
|
-
1. Open [\`development/prompts.md\`](development/prompts.md).
|
|
65
|
-
2. Find the **"Existing Project Onboarding Prompt"** section.
|
|
66
|
-
3. Copy the entire fenced code block (\`\`\`...\`\`\`).
|
|
52
|
+
Your spec files have been scaffolded with placeholders. An onboarding prompt has been saved to [\`development/onboarding.md\`](development/onboarding.md).
|
|
67
53
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
2. Paste the prompt and run it.
|
|
54
|
+
1. Open \`development/onboarding.md\` and copy the prompt inside it.
|
|
55
|
+
2. Paste it into your AI agent (VS Code, Cursor, etc.).
|
|
71
56
|
3. The AI will analyze your codebase and populate all spec files.
|
|
57
|
+
4. Review each file, refine as needed, then **delete \`onboarding.md\`**.
|
|
72
58
|
|
|
73
|
-
|
|
74
|
-
- Check the generated content in each \`.specs\` file.
|
|
75
|
-
- Refine as needed (e.g., add missing details).
|
|
76
|
-
- Run \`specpilot validate\` to ensure consistency.
|
|
59
|
+
Run \`specpilot validate\` to check consistency at any time.
|
|
77
60
|
|
|
78
61
|
## 📁 File Structure
|
|
79
62
|
- \`project/\`: Metadata and requirements
|
|
@@ -102,14 +85,15 @@ For AI guidelines and prompt history, see [\`development/prompts.md\`](developme
|
|
|
102
85
|
await this.generateApiYaml((0, path_1.join)(specsDir, 'architecture'), context);
|
|
103
86
|
await this.generateTasksMd((0, path_1.join)(specsDir, 'planning'), context);
|
|
104
87
|
await this.generateRoadmapMd((0, path_1.join)(specsDir, 'planning'), context);
|
|
105
|
-
await this.generateDocsMd((0, path_1.join)(specsDir, 'development'), context);
|
|
106
88
|
await this.generateContextMd((0, path_1.join)(specsDir, 'development'), context);
|
|
107
89
|
await this.generatePromptsMd((0, path_1.join)(specsDir, 'development'), context);
|
|
90
|
+
const onboardingPrompt = await this.generateOnboardingMd((0, path_1.join)(specsDir, 'development'), context);
|
|
108
91
|
await this.generateTestsMd((0, path_1.join)(specsDir, 'quality'), context);
|
|
109
92
|
const securityDir = (0, path_1.join)(specsDir, 'security');
|
|
110
93
|
(0, fs_1.mkdirSync)(securityDir, { recursive: true });
|
|
111
94
|
await this.generateThreatModelMd(securityDir, context);
|
|
112
95
|
await this.generateSecurityDecisionsMd(securityDir, context);
|
|
96
|
+
return { onboardingPrompt };
|
|
113
97
|
}
|
|
114
98
|
async generateReadmeMd(specsDir, context) {
|
|
115
99
|
const template = context.mode === 'existing' ? this.EXISTING_PROJECT_README : this.NEW_PROJECT_README;
|
|
@@ -143,42 +127,26 @@ sourceOfTruth: project/project.yaml
|
|
|
143
127
|
{{description}}
|
|
144
128
|
|
|
145
129
|
## Functional Requirements
|
|
146
|
-
[TODO
|
|
130
|
+
[TODO]
|
|
147
131
|
|
|
148
132
|
## Assumptions
|
|
149
|
-
|
|
150
|
-
> Label each assumption with [ASSUMPTION] so it can be reviewed and revised.
|
|
151
|
-
|
|
152
|
-
- [ASSUMPTION] [e.g. Users have internet access at runtime]
|
|
153
|
-
- [ASSUMPTION] [e.g. Single-user deployment, no multi-tenancy required]
|
|
154
|
-
- [ASSUMPTION] [e.g. Input data is well-formed; no adversarial input expected]
|
|
155
|
-
|
|
156
|
-
## Cross-References
|
|
157
|
-
- Architecture: ../architecture/architecture.md
|
|
158
|
-
- API: ../architecture/api.yaml
|
|
159
|
-
- Project config: ../project/project.yaml
|
|
160
|
-
|
|
161
|
-
---
|
|
162
|
-
*Last updated: {{currentDate}}*`;
|
|
133
|
+
[TODO]`;
|
|
163
134
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
164
135
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'requirements.md'), rendered);
|
|
165
136
|
}
|
|
166
137
|
async generateApiYaml(specsDir, context) {
|
|
167
|
-
const
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
# Remove the section(s) that don't apply to your project.
|
|
138
|
+
const paradigm = context.apiParadigm ?? 'rest';
|
|
139
|
+
if (paradigm === 'none')
|
|
140
|
+
return;
|
|
141
|
+
const header = `# .specs/architecture/api.yaml
|
|
172
142
|
# meta: project={{projectName}} language={{language}} framework={{framework}} updated={{currentDate}}
|
|
173
|
-
# ------------------------------------------------------------
|
|
174
143
|
|
|
175
144
|
project: "{{projectName}}"
|
|
176
145
|
version: "1.0.0"
|
|
177
146
|
lastUpdated: "{{currentDate}}"
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
# ============================================================
|
|
147
|
+
`;
|
|
148
|
+
const sections = {
|
|
149
|
+
rest: `
|
|
182
150
|
openapi: "3.0.0"
|
|
183
151
|
info:
|
|
184
152
|
title: "{{projectName}} API"
|
|
@@ -196,10 +164,8 @@ paths:
|
|
|
196
164
|
responses:
|
|
197
165
|
"200":
|
|
198
166
|
description: "Success"
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
# OPTION B: CLI Interface (remove if not a CLI project)
|
|
202
|
-
# ============================================================
|
|
167
|
+
`,
|
|
168
|
+
cli: `
|
|
203
169
|
cli:
|
|
204
170
|
name: "{{projectName}}"
|
|
205
171
|
version: "1.0.0"
|
|
@@ -213,10 +179,8 @@ cli:
|
|
|
213
179
|
options:
|
|
214
180
|
- flag: "--example <value>"
|
|
215
181
|
description: "[TODO: option description]"
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
# OPTION C: GraphQL (remove if not a GraphQL project)
|
|
219
|
-
# ============================================================
|
|
182
|
+
`,
|
|
183
|
+
graphql: `
|
|
220
184
|
graphql:
|
|
221
185
|
endpoint: "/graphql"
|
|
222
186
|
queries:
|
|
@@ -225,7 +189,9 @@ graphql:
|
|
|
225
189
|
mutations:
|
|
226
190
|
- name: "[TODO: firstMutation]"
|
|
227
191
|
description: "[TODO: What does this mutation do?]"
|
|
228
|
-
|
|
192
|
+
`,
|
|
193
|
+
};
|
|
194
|
+
const content = header + sections[paradigm];
|
|
229
195
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
230
196
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'api.yaml'), rendered);
|
|
231
197
|
}
|
|
@@ -248,45 +214,17 @@ Task ID conventions
|
|
|
248
214
|
- CD-{devPrefix}-###: Completed items (e.g. CD-{{author}}-001)
|
|
249
215
|
- PROMPT-{devPrefix}-###: Prompt log entries (e.g. PROMPT-{{author}}-001)
|
|
250
216
|
|
|
251
|
-
Notes
|
|
252
|
-
|
|
253
|
-
- IDs are stable; do not change once assigned (even if reordered or moved between sections).
|
|
254
|
-
- Reference tasks by ID in commits, prompts, PRs, and discussions.
|
|
255
|
-
- When moving an item from Backlog to Current Sprint, retain its original BL ID or create a CS mirror that references the BL ID.
|
|
256
|
-
- Archive guidance: when Completed grows large, move older entries to \`tasks-archive.md\` and add a pointer here.
|
|
257
|
-
|
|
258
|
-
## Multi-Dev Notes
|
|
259
|
-
|
|
260
|
-
> **ID collisions are the #1 source of merge conflicts in shared spec files.**
|
|
261
|
-
> Follow these rules when more than one person commits to this repo:
|
|
262
|
-
>
|
|
263
|
-
> - Always \`git pull\` before appending to the Completed section.
|
|
264
|
-
> - Use your personal prefix in all Completed IDs: \`CD-{your-handle}-###\`
|
|
265
|
-
> so two devs never claim the same number independently.
|
|
266
|
-
> - Only run \`specpilot archive\` on the default branch (main/master) **after** merging,
|
|
267
|
-
> never on a feature branch — diverged trim points break the archive history.
|
|
268
|
-
|
|
269
217
|
## Backlog
|
|
270
218
|
|
|
271
|
-
|
|
272
|
-
2. [BL-002] Gather user feedback and feature requests
|
|
273
|
-
3. [BL-003] Write documentation and usage guide
|
|
219
|
+
[TODO]
|
|
274
220
|
|
|
275
221
|
## Current Sprint
|
|
276
222
|
|
|
277
|
-
|
|
278
|
-
2. [CS-002] Implement core features
|
|
279
|
-
3. [CS-003] Write unit tests
|
|
223
|
+
[TODO]
|
|
280
224
|
|
|
281
225
|
## Completed
|
|
282
226
|
|
|
283
|
-
1. [CD-001] Initialise .specs directory ({{currentDate}})
|
|
284
|
-
|
|
285
|
-
## Cross-References
|
|
286
|
-
|
|
287
|
-
- Roadmap (milestones): ./roadmap.md
|
|
288
|
-
- Requirements: ../project/requirements.md
|
|
289
|
-
- Project config: ../project/project.yaml`;
|
|
227
|
+
1. [CD-001] Initialise .specs directory ({{currentDate}})`;
|
|
290
228
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
291
229
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'tasks.md'), rendered);
|
|
292
230
|
}
|
|
@@ -301,141 +239,44 @@ lastUpdated: {{currentDate}}
|
|
|
301
239
|
sourceOfTruth: project/project.yaml
|
|
302
240
|
---
|
|
303
241
|
|
|
304
|
-
<!--
|
|
305
|
-
PURPOSE: Release-level milestone planner — the "when are we shipping what" file.
|
|
306
|
-
Scope: Quarter-level phases, version targets, feature groupings, goals, and risks.
|
|
307
|
-
Update cadence: Per release / per sprint planning session.
|
|
308
|
-
|
|
309
|
-
Boundary guide:
|
|
310
|
-
- roadmap.md → release milestones, timeline, objectives, and risks (this file)
|
|
311
|
-
- tasks.md → individual work items and sprint status
|
|
312
|
-
-->
|
|
313
|
-
|
|
314
242
|
# {{projectName}} — Development Roadmap
|
|
315
243
|
|
|
316
|
-
##
|
|
317
|
-
|
|
318
|
-
- [x] Project initialised
|
|
319
|
-
- [ ] Core data model implemented
|
|
320
|
-
- [ ] Basic CLI / API working
|
|
321
|
-
|
|
322
|
-
## v0.2.0 — Core Features
|
|
323
|
-
**Goal:** Deliver the primary user-facing functionality.
|
|
324
|
-
- [ ] Feature A
|
|
325
|
-
- [ ] Feature B
|
|
326
|
-
- [ ] Unit test coverage ≥ 80 %
|
|
327
|
-
|
|
328
|
-
## v1.0.0 — Production Ready
|
|
329
|
-
**Goal:** Stable, documented, deployable release.
|
|
330
|
-
- [ ] All P0/P1 requirements met
|
|
331
|
-
- [ ] Documentation complete
|
|
332
|
-
- [ ] CI/CD pipeline green
|
|
333
|
-
|
|
334
|
-
## Unscheduled / Icebox
|
|
335
|
-
- [ ] Nice-to-have feature ideas go here
|
|
244
|
+
## Milestones
|
|
245
|
+
[TODO]
|
|
336
246
|
|
|
337
247
|
## Objectives
|
|
338
|
-
|
|
339
|
-
- [Secondary goal]
|
|
248
|
+
[TODO]
|
|
340
249
|
|
|
341
250
|
## Goals & Success Criteria
|
|
342
|
-
|
|
343
|
-
|------|----------------|--------|
|
|
344
|
-
| [Primary goal] | [How we measure it] | [Target value] |
|
|
251
|
+
[TODO]
|
|
345
252
|
|
|
346
253
|
## Risks and Mitigations
|
|
347
|
-
|
|
348
|
-
- [Risk 2]: [Mitigation]
|
|
349
|
-
|
|
350
|
-
## Cross-References
|
|
351
|
-
- Sprint tasks: ./tasks.md
|
|
352
|
-
- Requirements: ../project/requirements.md
|
|
353
|
-
|
|
354
|
-
---
|
|
355
|
-
*Last updated: {{currentDate}}*`;
|
|
254
|
+
[TODO]`;
|
|
356
255
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
357
256
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'roadmap.md'), rendered);
|
|
358
257
|
}
|
|
359
|
-
async
|
|
258
|
+
async generateContextMd(specsDir, context) {
|
|
360
259
|
const content = `---
|
|
361
|
-
|
|
362
|
-
description:
|
|
260
|
+
title: Development Context
|
|
261
|
+
description: Project memory, decisions, and implementation notes
|
|
262
|
+
project: {{projectName}}
|
|
263
|
+
language: {{language}}
|
|
264
|
+
framework: {{framework}}
|
|
363
265
|
lastUpdated: {{currentDate}}
|
|
364
|
-
|
|
365
|
-
contributors: []
|
|
366
|
-
relatedFiles: [project/project.yaml, development/context.md, planning/roadmap.md, planning/tasks.md]
|
|
266
|
+
sourceOfTruth: project/project.yaml
|
|
367
267
|
---
|
|
368
268
|
|
|
369
|
-
# {{projectName}}
|
|
370
|
-
|
|
371
|
-
## Spec File Conventions
|
|
372
|
-
|
|
373
|
-
All \`.specs/\` files must include a YAML front-matter header with:
|
|
374
|
-
- \`fileID\`: Unique identifier (e.g., \`REQ-001\`, \`ARCH-001\`)
|
|
375
|
-
- \`lastUpdated\`: Date in YYYY-MM-DD format
|
|
376
|
-
- \`version\`: Semantic version (e.g., \`1.0\`)
|
|
377
|
-
- \`contributors\`: Array of contributor handles
|
|
378
|
-
- \`relatedFiles\`: Array of related spec file paths
|
|
379
|
-
|
|
380
|
-
Section IDs use the format \`[PREFIX-NNN.S]\` (e.g., \`[REQ-001.1]\`) and must be stable — do not change once assigned.
|
|
381
|
-
|
|
382
|
-
## Development Procedures
|
|
383
|
-
|
|
384
|
-
### Workflow
|
|
385
|
-
|
|
386
|
-
1. Update relevant \`.specs/\` files before committing
|
|
387
|
-
2. Write tests before implementation
|
|
388
|
-
3. Use small, focused commits with conventional commit messages (\`type(scope): description\`)
|
|
389
|
-
4. Log all AI interactions in \`development/prompts.md\`
|
|
390
|
-
|
|
391
|
-
### Spec Update Checklist (before each commit)
|
|
392
|
-
|
|
393
|
-
- [ ] \`tasks.md\` \u2014 task status updated
|
|
394
|
-
- [ ] \`context.md\` \u2014 decisions and lessons logged
|
|
395
|
-
- [ ] \`requirements.md\` \u2014 updated if features changed
|
|
396
|
-
- [ ] \`architecture.md\` \u2014 updated if structure changed
|
|
397
|
-
- [ ] \`api.yaml\` \u2014 updated if CLI interface changed
|
|
398
|
-
- [ ] \`tests.md\` \u2014 updated if test strategy changed
|
|
399
|
-
|
|
400
|
-
## CLI Commands Reference
|
|
401
|
-
|
|
402
|
-
\\\`\\\`\\\`bash
|
|
403
|
-
# Initialize a new project
|
|
404
|
-
specpilot init <project-name> [--lang <language>] [--framework <framework>] [--no-prompts]
|
|
405
|
-
|
|
406
|
-
# Add .specs/ to an existing project
|
|
407
|
-
specpilot add-specs
|
|
408
|
-
|
|
409
|
-
# List available templates
|
|
410
|
-
specpilot list
|
|
411
|
-
|
|
412
|
-
# Validate spec files
|
|
413
|
-
specpilot validate [--fix]
|
|
414
|
-
|
|
415
|
-
# Migrate to newer spec structure
|
|
416
|
-
specpilot migrate
|
|
417
|
-
|
|
418
|
-
# Update specs with current project context (shows diff + confirmation)
|
|
419
|
-
specpilot refine
|
|
420
|
-
\\\`\\\`\\\`
|
|
421
|
-
|
|
422
|
-
## Cross-References
|
|
423
|
-
- Context: ./context.md
|
|
424
|
-
- Roadmap: ../planning/roadmap.md
|
|
425
|
-
- Tasks: ../planning/tasks.md
|
|
426
|
-
- Project config: ../project/project.yaml
|
|
427
|
-
|
|
428
|
-
> For contributing guidelines, troubleshooting, and support, see README.md.
|
|
269
|
+
# {{projectName}} Development Context
|
|
429
270
|
|
|
430
|
-
|
|
431
|
-
|
|
271
|
+
## Project Memory
|
|
272
|
+
[TODO]`;
|
|
432
273
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
433
|
-
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, '
|
|
274
|
+
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'context.md'), rendered);
|
|
434
275
|
}
|
|
435
|
-
async
|
|
276
|
+
async generatePromptsMd(specsDir, context) {
|
|
436
277
|
const content = `---
|
|
437
|
-
title:
|
|
438
|
-
description:
|
|
278
|
+
title: Prompts Log
|
|
279
|
+
description: AI interaction log for {{projectName}}
|
|
439
280
|
project: {{projectName}}
|
|
440
281
|
language: {{language}}
|
|
441
282
|
framework: {{framework}}
|
|
@@ -443,60 +284,89 @@ lastUpdated: {{currentDate}}
|
|
|
443
284
|
sourceOfTruth: project/project.yaml
|
|
444
285
|
---
|
|
445
286
|
|
|
446
|
-
#
|
|
287
|
+
# Development Prompts Log
|
|
447
288
|
|
|
448
|
-
##
|
|
449
|
-
|
|
289
|
+
## Overview
|
|
290
|
+
This file (prompts.md) contains ALL AI interactions for {{projectName}}. Update .specs/prompts.md with every AI interaction.
|
|
450
291
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
292
|
+
**🚨 MANDATE**: Update with every AI interaction.
|
|
293
|
+
|
|
294
|
+
## Archive Policy
|
|
295
|
+
|
|
296
|
+
> **Line limit: 100 lines.** When this file exceeds 100 lines, run:
|
|
297
|
+
>
|
|
298
|
+
> \`\`\`bash
|
|
299
|
+
> specpilot archive
|
|
300
|
+
> \`\`\`
|
|
301
|
+
>
|
|
302
|
+
> This will move older entries from this file into \`development/prompts-archive.md\` automatically, keeping the most recent entries here. A \`--dry-run\` flag is available to preview changes before writing.
|
|
303
|
+
>
|
|
304
|
+
> No stub \`prompts-archive.md\` file is generated during \`specpilot init\` — it is created on first archive run.
|
|
305
|
+
|
|
306
|
+
## Re-Anchor Prompt
|
|
307
|
+
|
|
308
|
+
> Paste this into your AI agent when: the session has been running > 1 hour, you've made > 20 exchanges, or the AI seems to have forgotten project rules.
|
|
309
|
+
|
|
310
|
+
~~~
|
|
311
|
+
You are working on {{projectName}} ({{language}}{{#if framework}} / {{framework}}{{/if}}).
|
|
312
|
+
|
|
313
|
+
CRITICAL RULES — re-read these before continuing:
|
|
314
|
+
1. NEVER commit, push, or deploy unless I explicitly ask you to.
|
|
315
|
+
2. NEVER modify .specs/ folder structure or file names — only update file contents.
|
|
316
|
+
3. After EVERY code change, proactively update all affected .specs/ files without being asked.
|
|
317
|
+
4. Spec-First Development — update .specs/ before writing code.
|
|
318
|
+
5. Log this and all AI interactions in .specs/development/prompts.md.
|
|
319
|
+
|
|
320
|
+
For full project context, read .specs/project/project.yaml.
|
|
321
|
+
~~~
|
|
455
322
|
|
|
456
323
|
---
|
|
457
|
-
|
|
324
|
+
|
|
325
|
+
## Prompt History
|
|
326
|
+
|
|
327
|
+
| Date | User | Prompt Summary | Context |
|
|
328
|
+
|------|------|----------------|---------|
|
|
329
|
+
| YYYY-MM-DD | @username | Example prompt | Brief context or outcome |`;
|
|
458
330
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
459
|
-
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, '
|
|
331
|
+
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'prompts.md'), rendered);
|
|
460
332
|
}
|
|
461
|
-
async
|
|
462
|
-
const
|
|
333
|
+
async generateOnboardingMd(specsDir, context) {
|
|
334
|
+
const isGreenfield = context.projectType !== 'brownfield';
|
|
463
335
|
const pc = context.projectContext;
|
|
464
|
-
// ── Shared conventions block (used by both prompts) ──────────
|
|
465
336
|
const conventions = `**Conventions & Rules:**
|
|
466
|
-
1. **IDs**: Use semantic prefixes with zero-padded numbers (e.g., REQ-001, CD
|
|
337
|
+
1. **IDs**: Use semantic prefixes with zero-padded numbers (e.g., REQ-001, CD-${context.author || '{{author}}'}-001)
|
|
467
338
|
2. **Status values**: Must be one of: not-started, in-progress, completed, blocked, deprecated
|
|
468
339
|
3. **Priority values**: Must be: critical, high, medium, low
|
|
469
340
|
4. **Dates**: Use ISO 8601 format (YYYY-MM-DD)
|
|
470
341
|
5. **YAML**: Use proper indentation (2 spaces), include all required fields
|
|
471
|
-
6. **Markdown**: Use ATX headers (#), fenced code blocks,
|
|
342
|
+
6. **Markdown**: Use ATX headers (#), fenced code blocks, consistent formatting
|
|
472
343
|
7. **Traceability**: Link requirements to tasks, tasks to tests, architecture to implementation
|
|
473
|
-
8. **❌ CRITICAL**: Never modify the .specs folder structure or file names. Only update file CONTENTS.
|
|
474
|
-
|
|
475
|
-
**File Structure
|
|
476
|
-
|
|
477
|
-
-
|
|
478
|
-
-
|
|
479
|
-
-
|
|
480
|
-
-
|
|
481
|
-
-
|
|
482
|
-
-
|
|
483
|
-
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
? `**Project context (provided by the developer):**
|
|
344
|
+
8. **❌ CRITICAL**: Never modify the .specs folder structure or file names. Only update file CONTENTS.
|
|
345
|
+
|
|
346
|
+
**File Structure:**
|
|
347
|
+
- \`project/project.yaml\`: name, version, description, tech_stack[], dependencies[]
|
|
348
|
+
- \`project/requirements.md\`: ## Functional/Non-Functional Requirements, REQ-XXX IDs
|
|
349
|
+
- \`architecture/architecture.md\`: ## Overview, Components, Data Flow, Decisions (ADR)
|
|
350
|
+
- \`architecture/api.yaml\`: endpoints with methods, paths, descriptions
|
|
351
|
+
- \`planning/tasks.md\`: ## Backlog/In Progress/Completed with TASK-XXX IDs
|
|
352
|
+
- \`planning/roadmap.md\`: ## Milestones with versions, dates, features, status
|
|
353
|
+
- \`quality/tests.md\`: ## Test Strategy, Test Cases (TEST-XXX), Coverage Goals
|
|
354
|
+
- \`development/context.md\`: ## Project Context, Key Decisions, Known Issues`;
|
|
355
|
+
let prompt;
|
|
356
|
+
if (isGreenfield) {
|
|
357
|
+
const projectContextBlock = pc
|
|
358
|
+
? `**Project context (provided by the developer):**
|
|
489
359
|
- **What it does:** ${pc.whatItDoes}
|
|
490
360
|
- **Target users:** ${pc.targetUsers}
|
|
491
361
|
- **Expected scale:** ${pc.expectedScale}
|
|
492
362
|
- **Key constraints:** ${pc.constraints}`
|
|
493
|
-
|
|
363
|
+
: `**Project context:**
|
|
494
364
|
- **What it does:** [DESCRIBE YOUR PROJECT HERE]
|
|
495
365
|
- **Target users:** Not specified — use your judgment and mark as [ASSUMPTION]
|
|
496
366
|
- **Expected scale:** Not specified — use your judgment and mark as [ASSUMPTION]
|
|
497
367
|
- **Key constraints:** Not specified — use your judgment and mark as [ASSUMPTION]`;
|
|
498
|
-
|
|
499
|
-
Tech stack: {
|
|
368
|
+
prompt = `You are the specification co-pilot for a new project called "${context.projectName}".
|
|
369
|
+
Tech stack: ${context.language}${context.framework ? ` / ${context.framework}` : ''}
|
|
500
370
|
|
|
501
371
|
${projectContextBlock}
|
|
502
372
|
|
|
@@ -517,11 +387,11 @@ ${conventions}
|
|
|
517
387
|
4. Draft a test strategy appropriate for the project type
|
|
518
388
|
|
|
519
389
|
**Output Format:**
|
|
520
|
-
For each file, provide the complete content in a
|
|
521
|
-
|
|
390
|
+
For each file, provide the complete content in a fenced code block:
|
|
391
|
+
\`\`\`markdown
|
|
522
392
|
// filepath: .specs/project/project.yaml
|
|
523
393
|
[full file content]
|
|
524
|
-
|
|
394
|
+
\`\`\`
|
|
525
395
|
|
|
526
396
|
**Constraints:**
|
|
527
397
|
- These specs are a starting point — the developer will review and refine them
|
|
@@ -529,16 +399,14 @@ For each file, provide the complete content in a markdown code block:
|
|
|
529
399
|
- Keep descriptions clear, concise, and technical
|
|
530
400
|
- Ensure all IDs are unique within their domain
|
|
531
401
|
|
|
532
|
-
After populating all files, provide a summary of:
|
|
533
|
-
- What you understood about the project
|
|
534
|
-
- Assumptions you made and why
|
|
535
|
-
- Recommended next steps before the developer starts coding
|
|
402
|
+
After populating all files, provide a summary of: what you understood, assumptions you made, and recommended next steps.
|
|
536
403
|
|
|
537
|
-
**
|
|
404
|
+
**Final step: delete \`.specs/development/onboarding.md\` — it is a one-time bootstrap file.**
|
|
538
405
|
|
|
539
406
|
Begin drafting now.`;
|
|
540
|
-
|
|
541
|
-
|
|
407
|
+
}
|
|
408
|
+
else {
|
|
409
|
+
prompt = `You are onboarding as the specification co-pilot for this repository. We just initialized the .specs directory using SpecPilot SDD. Your task is to inspect the codebase and populate all .specs files following these strict conventions:
|
|
542
410
|
|
|
543
411
|
${conventions}
|
|
544
412
|
|
|
@@ -548,16 +416,16 @@ ${conventions}
|
|
|
548
416
|
- Reflects the actual implementation state
|
|
549
417
|
- Follows the conventions above exactly
|
|
550
418
|
- Maintains internal consistency (cross-references work)
|
|
551
|
-
- Scales appropriately to project size (small
|
|
419
|
+
- Scales appropriately to project size (small = concise, large = comprehensive)
|
|
552
420
|
3. Identify gaps: missing tests, undocumented APIs, unclear requirements, architectural debt
|
|
553
421
|
4. Propose actionable next steps in planning/tasks.md
|
|
554
422
|
|
|
555
423
|
**Output Format:**
|
|
556
|
-
For each file, provide the complete content in a
|
|
557
|
-
|
|
424
|
+
For each file, provide the complete content in a fenced code block:
|
|
425
|
+
\`\`\`markdown
|
|
558
426
|
// filepath: .specs/project/project.yaml
|
|
559
427
|
[full file content]
|
|
560
|
-
|
|
428
|
+
\`\`\`
|
|
561
429
|
|
|
562
430
|
**Constraints:**
|
|
563
431
|
- Maintain the exact file paths and names from the .specs structure
|
|
@@ -566,130 +434,28 @@ For each file, provide the complete content in a markdown code block:
|
|
|
566
434
|
- Keep descriptions clear, concise, and technical
|
|
567
435
|
- Ensure all IDs are unique within their domain
|
|
568
436
|
|
|
569
|
-
After populating all files, provide a summary of:
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
- Critical gaps or risks
|
|
573
|
-
- Recommended immediate actions
|
|
437
|
+
After populating all files, provide a summary of: what was discovered, what's documented vs. implemented, critical gaps, and recommended immediate actions.
|
|
438
|
+
|
|
439
|
+
**Final step: delete \`.specs/development/onboarding.md\` — it is a one-time bootstrap file.**
|
|
574
440
|
|
|
575
441
|
Begin your analysis now.`;
|
|
576
|
-
|
|
577
|
-
const
|
|
578
|
-
const secondaryLabel = isNew ? 'Existing Project' : 'New Project';
|
|
579
|
-
const primaryPrompt = isNew ? newProjectPrompt : existingProjectPrompt;
|
|
580
|
-
const secondaryPrompt = isNew ? existingProjectPrompt : newProjectPrompt;
|
|
581
|
-
const primaryNote = isNew
|
|
582
|
-
? 'Use this prompt to have your AI agent draft all specification files based on your project description.'
|
|
583
|
-
: 'Use this prompt to have your AI agent analyze your codebase and populate all specification files.';
|
|
584
|
-
const secondaryNote = isNew
|
|
585
|
-
? 'If you later need to re-generate specs from an existing codebase (e.g., after significant implementation), use this prompt instead.'
|
|
586
|
-
: 'If you start a fresh module or sub-project and want to plan specs before writing code, use this prompt instead.';
|
|
442
|
+
}
|
|
443
|
+
const label = isGreenfield ? 'Greenfield' : 'Brownfield';
|
|
587
444
|
const content = `---
|
|
588
|
-
title:
|
|
589
|
-
|
|
590
|
-
project: {
|
|
591
|
-
|
|
592
|
-
framework: {{framework}}
|
|
593
|
-
lastUpdated: {{currentDate}}
|
|
594
|
-
sourceOfTruth: project/project.yaml
|
|
445
|
+
title: Onboarding Prompt (${label})
|
|
446
|
+
description: One-time AI prompt to bootstrap .specs/ files — delete after use
|
|
447
|
+
project: ${context.projectName}
|
|
448
|
+
lastUpdated: ${new Date().toISOString().split('T')[0]}
|
|
595
449
|
---
|
|
596
450
|
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
## Overview
|
|
600
|
-
This file (prompts.md) contains ALL AI interactions for {{projectName}}. Update .specs/prompts.md with every AI interaction.
|
|
601
|
-
|
|
602
|
-
**🚨 MANDATE**: Update with every AI interaction.
|
|
603
|
-
|
|
604
|
-
## Archive Policy
|
|
605
|
-
|
|
606
|
-
> **Line limit: 100 lines.** When this file exceeds 100 lines, run:
|
|
607
|
-
>
|
|
608
|
-
> \`\`\`bash
|
|
609
|
-
> specpilot archive
|
|
610
|
-
> \`\`\`
|
|
611
|
-
>
|
|
612
|
-
> This will move older entries from this file into \`development/prompts-archive.md\` automatically, keeping the most recent entries here. A \`--dry-run\` flag is available to preview changes before writing.
|
|
613
|
-
>
|
|
614
|
-
> No stub \`prompts-archive.md\` file is generated during \`specpilot init\` — it is created on first archive run.
|
|
615
|
-
|
|
616
|
-
## ${primaryLabel} Onboarding Prompt
|
|
617
|
-
|
|
618
|
-
${primaryNote}
|
|
619
|
-
|
|
620
|
-
~~~
|
|
621
|
-
${primaryPrompt}
|
|
622
|
-
~~~
|
|
623
|
-
|
|
624
|
-
---
|
|
625
|
-
|
|
626
|
-
## ${secondaryLabel} Onboarding Prompt (Reference)
|
|
627
|
-
|
|
628
|
-
${secondaryNote}
|
|
629
|
-
|
|
630
|
-
~~~
|
|
631
|
-
${secondaryPrompt}
|
|
632
|
-
~~~
|
|
633
|
-
|
|
634
|
-
---
|
|
635
|
-
|
|
636
|
-
## Re-Anchor Prompt
|
|
637
|
-
|
|
638
|
-
> Paste this into your AI agent when: the session has been running > 1 hour, you've made > 20 exchanges, or the AI seems to have forgotten project rules.
|
|
639
|
-
|
|
640
|
-
~~~
|
|
641
|
-
You are working on {{projectName}} ({{language}}{{#if framework}} / {{framework}}{{/if}}).
|
|
642
|
-
|
|
643
|
-
CRITICAL RULES — re-read these before continuing:
|
|
644
|
-
1. NEVER commit, push, or deploy unless I explicitly ask you to.
|
|
645
|
-
2. NEVER modify .specs/ folder structure or file names — only update file contents.
|
|
646
|
-
3. After EVERY code change, proactively update all affected .specs/ files without being asked.
|
|
647
|
-
4. Spec-First Development — update .specs/ before writing code.
|
|
648
|
-
5. Log this and all AI interactions in .specs/development/prompts.md.
|
|
649
|
-
|
|
650
|
-
For full project context, read .specs/project/project.yaml.
|
|
651
|
-
~~~
|
|
451
|
+
> **One-time file — delete after use.**
|
|
452
|
+
> Copy the prompt below and paste it into your AI agent. Once all \`.specs/\` files are populated, your AI will delete this file as its final step. If it doesn't, delete it manually.
|
|
652
453
|
|
|
653
454
|
---
|
|
654
455
|
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|------|------|----------------|---------|
|
|
659
|
-
| YYYY-MM-DD | @username | Example prompt | Brief context or outcome |
|
|
660
|
-
|
|
661
|
-
## Common Commands
|
|
662
|
-
|
|
663
|
-
\\\`\\\`\\\`bash
|
|
664
|
-
# Generate specs for new project
|
|
665
|
-
specpilot init
|
|
666
|
-
|
|
667
|
-
# Add specs to existing project
|
|
668
|
-
specpilot add-specs
|
|
669
|
-
|
|
670
|
-
# Validate spec files
|
|
671
|
-
specpilot validate
|
|
672
|
-
\\\`\\\`\\\`
|
|
673
|
-
|
|
674
|
-
## AI Agent Guidelines
|
|
675
|
-
|
|
676
|
-
When working with AI agents on this codebase:
|
|
677
|
-
- Always reference relevant .specs files for context
|
|
678
|
-
- Update specifications before/after significant changes
|
|
679
|
-
- Use the conventions defined in the onboarding prompt
|
|
680
|
-
- Link code changes to tasks (TASK-XXX) and requirements (REQ-XXX)
|
|
681
|
-
- Keep development/context.md current with architectural decisions
|
|
682
|
-
- **🚨 MANDATE**: Never modify the .specs folder structure or file names - only update file contents
|
|
683
|
-
- **🚨 RELEASE MANDATE**: Never commit, push, create tags, publish releases, or publish to npm without explicit user consent and approval
|
|
684
|
-
|
|
685
|
-
## Cross-References
|
|
686
|
-
- Context: ./context.md
|
|
687
|
-
- Project config: ../project/project.yaml
|
|
688
|
-
|
|
689
|
-
---
|
|
690
|
-
*Last updated: {{currentDate}}*`;
|
|
691
|
-
const rendered = this.templateEngine.renderFromString(content, context);
|
|
692
|
-
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'prompts.md'), rendered);
|
|
456
|
+
${prompt}`;
|
|
457
|
+
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'onboarding.md'), content);
|
|
458
|
+
return prompt;
|
|
693
459
|
}
|
|
694
460
|
async generateTestsMd(specsDir, context) {
|
|
695
461
|
const content = `---
|
|
@@ -705,14 +471,7 @@ sourceOfTruth: project/project.yaml
|
|
|
705
471
|
# {{projectName}} Test Strategy
|
|
706
472
|
|
|
707
473
|
## Overview
|
|
708
|
-
[TODO
|
|
709
|
-
|
|
710
|
-
## Cross-References
|
|
711
|
-
- Requirements: ../project/requirements.md
|
|
712
|
-
- Project config: ../project/project.yaml
|
|
713
|
-
|
|
714
|
-
---
|
|
715
|
-
*Last updated: {{currentDate}}*`;
|
|
474
|
+
[TODO]`;
|
|
716
475
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
717
476
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'tests.md'), rendered);
|
|
718
477
|
}
|
|
@@ -729,48 +488,16 @@ relatedFiles: [security/security-decisions.md, architecture/architecture.md, pro
|
|
|
729
488
|
# Threat Model
|
|
730
489
|
|
|
731
490
|
## Overview [SEC-001.1]
|
|
732
|
-
|
|
733
|
-
> Describe the attack surface: what the system does, what it reads/writes, and what it does NOT do (e.g., no network calls at runtime).
|
|
734
|
-
|
|
735
|
-
[TODO: Summarise the system's threat surface — input sources, outputs, and offline/online constraints.]
|
|
491
|
+
[TODO]
|
|
736
492
|
|
|
737
493
|
## Threat Model [SEC-002]
|
|
738
|
-
|
|
739
|
-
### [Threat Name] [SEC-002.1]
|
|
740
|
-
|
|
741
|
-
| Field | Detail |
|
|
742
|
-
|---|---|
|
|
743
|
-
| **Description** | [TODO: Describe the threat] |
|
|
744
|
-
| **Impact** | [TODO: High / Medium / Low] |
|
|
745
|
-
| **Likelihood** | [TODO: High / Medium / Low / Very low] |
|
|
746
|
-
| **Entry point** | [TODO: Where does attacker-controlled data enter?] |
|
|
747
|
-
| **Mitigation** | [TODO: What control prevents or limits this threat?] |
|
|
748
|
-
| **Residual risk** | [TODO: What risk remains after mitigation?] |
|
|
749
|
-
|
|
750
|
-
### [Threat Name] [SEC-002.2]
|
|
751
|
-
|
|
752
|
-
| Field | Detail |
|
|
753
|
-
|---|---|
|
|
754
|
-
| **Description** | [TODO: Describe the threat] |
|
|
755
|
-
| **Impact** | [TODO: High / Medium / Low] |
|
|
756
|
-
| **Likelihood** | [TODO: High / Medium / Low / Very low] |
|
|
757
|
-
| **Entry point** | [TODO: Where does attacker-controlled data enter?] |
|
|
758
|
-
| **Mitigation** | [TODO: What control prevents or limits this threat?] |
|
|
759
|
-
| **Residual risk** | [TODO: What risk remains after mitigation?] |
|
|
494
|
+
[TODO]
|
|
760
495
|
|
|
761
496
|
## Attack Surface Summary [SEC-003]
|
|
762
|
-
|
|
763
|
-
| Entry Point | Data Type | Validated? | Used In |
|
|
764
|
-
|---|---|---|---|
|
|
765
|
-
| [TODO: entry point] | [TODO: type] | [TODO: ✅ / ⚠️ / ❌] | [TODO: component] |
|
|
497
|
+
[TODO]
|
|
766
498
|
|
|
767
499
|
## Out of Scope [SEC-004]
|
|
768
|
-
|
|
769
|
-
- [TODO: List threats explicitly out of scope, e.g. OS-level permissions, container isolation]
|
|
770
|
-
|
|
771
|
-
---
|
|
772
|
-
|
|
773
|
-
_Last updated: {{currentDate}}_`;
|
|
500
|
+
[TODO]`;
|
|
774
501
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
775
502
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'threat-model.md'), rendered);
|
|
776
503
|
}
|
|
@@ -786,39 +513,8 @@ relatedFiles: [security/threat-model.md, architecture/architecture.md]
|
|
|
786
513
|
|
|
787
514
|
# Security Decisions
|
|
788
515
|
|
|
789
|
-
> Record security-relevant architectural decisions here in ADR style.
|
|
790
|
-
> Each entry should capture: what was decided, why, and any trade-offs.
|
|
791
|
-
|
|
792
516
|
## Decisions [SEC-002.1]
|
|
793
|
-
|
|
794
|
-
### [Decision title] [ADR-001]
|
|
795
|
-
|
|
796
|
-
| Field | Detail |
|
|
797
|
-
|---|---|
|
|
798
|
-
| **Decision** | [TODO: What was decided?] |
|
|
799
|
-
| **Status** | [TODO: Accepted / Proposed / Deprecated] |
|
|
800
|
-
| **Context** | [TODO: What problem does this solve?] |
|
|
801
|
-
| **Rationale** | [TODO: Why was this approach chosen over alternatives?] |
|
|
802
|
-
| **Trade-offs** | [TODO: What are the downsides or limitations?] |
|
|
803
|
-
| **Related threat** | [TODO: Which threat in threat-model.md does this address?] |
|
|
804
|
-
|
|
805
|
-
### [Decision title] [ADR-002]
|
|
806
|
-
|
|
807
|
-
| Field | Detail |
|
|
808
|
-
|---|---|
|
|
809
|
-
| **Decision** | [TODO: What was decided?] |
|
|
810
|
-
| **Status** | [TODO: Accepted / Proposed / Deprecated] |
|
|
811
|
-
| **Context** | [TODO: What problem does this solve?] |
|
|
812
|
-
| **Rationale** | [TODO: Why was this approach chosen over alternatives?] |
|
|
813
|
-
| **Trade-offs** | [TODO: What are the downsides or limitations?] |
|
|
814
|
-
| **Related threat** | [TODO: Which threat in threat-model.md does this address?] |
|
|
815
|
-
|
|
816
|
-
## Cross-References
|
|
817
|
-
- Threat model: ./threat-model.md
|
|
818
|
-
- Architecture: ../architecture/architecture.md
|
|
819
|
-
|
|
820
|
-
---
|
|
821
|
-
*Last updated: {{currentDate}}*`;
|
|
517
|
+
[TODO]`;
|
|
822
518
|
const rendered = this.templateEngine.renderFromString(content, context);
|
|
823
519
|
(0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'security-decisions.md'), rendered);
|
|
824
520
|
}
|