specpilot 1.8.0 → 2.0.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.
@@ -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 specs files have been scaffolded with placeholders. Use your AI agent to draft them based on the project description you provided during \`specpilot init\`.
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
- ### Step 1: Copy the Onboarding Prompt
23
- 1. Open [\`development/prompts.md\`](development/prompts.md).
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
- ### Step 3: Review & Refine
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 specs files have been scaffolded with placeholders. Use your AI agent to populate them by analyzing your existing codebase.
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
- ### Step 2: Paste into Your AI Agent
69
- 1. In your IDE (VS Code, Cursor, etc.), open the AI chat.
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
- ### Step 3: Review & Iterate
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: Add requirements with proper template]
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 content = `# .specs/architecture/api.yaml
168
- # ------------------------------------------------------------
169
- # API & Interface Specification
170
- # Purpose: CLI / REST API / GraphQL interface spec
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
- # OPTION A: REST API (remove if not a web API project)
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
- 1. [BL-001] Plan initial feature set
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
- 1. [CS-001] Set up project foundation and tooling
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
- ## v0.1.0 — Foundation _(current)_
317
- **Goal:** Get a working skeleton in place.
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
- - [Primary goal for this project]
339
- - [Secondary goal]
248
+ [TODO]
340
249
 
341
250
  ## Goals & Success Criteria
342
- | Goal | Success Metric | Target |
343
- |------|----------------|--------|
344
- | [Primary goal] | [How we measure it] | [Target value] |
251
+ [TODO]
345
252
 
346
253
  ## Risks and Mitigations
347
- - [Risk 1]: [Mitigation]
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 generateDocsMd(specsDir, context) {
258
+ async generateContextMd(specsDir, context) {
360
259
  const content = `---
361
- fileID: DOC-001
362
- description: Development guidelines, spec conventions, and workflow checklist
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
- version: 1.0
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}} \u2014 Development Documentation
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
- *Last updated: {{currentDate}}*`;
271
+ ## Project Memory
272
+ [TODO]`;
432
273
  const rendered = this.templateEngine.renderFromString(content, context);
433
- (0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'docs.md'), rendered);
274
+ (0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'context.md'), rendered);
434
275
  }
435
- async generateContextMd(specsDir, context) {
276
+ async generatePromptsMd(specsDir, context) {
436
277
  const content = `---
437
- title: Development Context
438
- description: Project memory, decisions, and implementation notes
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
- # {{projectName}} Development Context
287
+ # Development Prompts Log
447
288
 
448
- ## Project Memory
449
- [TODO: Add project context and decisions]
289
+ ## Overview
290
+ This file (prompts.md) contains ALL AI interactions for {{projectName}}. Update .specs/prompts.md with every AI interaction.
450
291
 
451
- ## Cross-References
452
- - Docs: ./docs.md
453
- - Roadmap: ../planning/roadmap.md
454
- - Project config: ../project/project.yaml
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
- *Last updated: {{currentDate}}*`;
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, 'context.md'), rendered);
331
+ (0, fs_1.writeFileSync)((0, path_1.join)(specsDir, 'prompts.md'), rendered);
460
332
  }
461
- async generatePromptsMd(specsDir, context) {
462
- const isNew = context.mode !== 'existing';
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-{{author}}-001, PROMPT-{{author}}-001); Completed task IDs and Prompt log IDs use your personal handle as prefix to avoid collisions in multi-dev teams
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, and consistent formatting
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. The directory structure is IMMUTABLE.
474
-
475
- **File Structure Standards:**
476
-
477
- - \\\`project/project.yaml\\\`: name, version, description, tech_stack[], dependencies[], metadata
478
- - \\\`project/requirements.md\\\`: ## Functional/Non-Functional Requirements with REQ-XXX IDs, priority, status
479
- - \\\`architecture/architecture.md\\\`: ## Overview, Components, Data Flow, Tech Stack, Decisions (ADR format)
480
- - \\\`architecture/api.yaml\\\`: OpenAPI 3.0 spec or endpoints list with methods, paths, descriptions
481
- - \\\`planning/tasks.md\\\`: ## Backlog/In Progress/Completed with TASK-XXX, assignee, priority, dependencies
482
- - \\\`planning/roadmap.md\\\`: ## Milestones with versions, dates, features, status
483
- - \\\`quality/tests.md\\\`: ## Test Strategy, Test Cases (TEST-XXX), Coverage Goals, CI/CD integration
484
- - \\\`development/docs.md\\\`: ## Getting Started, Architecture, API, Deployment, Contributing
485
- - \\\`development/context.md\\\`: ## Project Context, Key Decisions, Known Issues, Future Considerations`;
486
- // ── New-project prompt ────────────────────────────────────────
487
- const projectContextBlock = pc
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
- : `**Project context:**
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
- const newProjectPrompt = `You are the specification co-pilot for a new project called "{{projectName}}".
499
- Tech stack: {{language}}{{#if framework}} / {{framework}}{{/if}}
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 markdown code block:
521
- \\\\\`\\\\\`\\\\\`markdown
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
- **Important:** These specifications are generated based on the AI's understanding of the project description. They are a draft — the developer should review, change, add, or remove anything as the project evolves. Add more detail into the spec files before starting AI-assisted coding.
404
+ **Final step: delete \`.specs/development/onboarding.md\` — it is a one-time bootstrap file.**
538
405
 
539
406
  Begin drafting now.`;
540
- // ── Existing-project prompt ──────────────────────────────────
541
- const existingProjectPrompt = `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:
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 projects = concise specs, large = comprehensive)
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 markdown code block:
557
- \\\\\`\\\\\`\\\\\`markdown
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
- - What was discovered about the project
571
- - What's documented vs. what's implemented
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
- // ── Assemble the full prompts.md ─────────────────────────────
577
- const primaryLabel = isNew ? 'New Project' : 'Existing Project';
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: Prompts Log
589
- description: AI interaction log and onboarding prompts for the project
590
- project: {{projectName}}
591
- language: {{language}}
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
- # Development Prompts Log
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
- ## Prompt History
656
-
657
- | Date | User | Prompt Summary | Context |
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: Add testing strategy and approach]
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
  }