@brucewaynedecoy/make-docs 1.0.0-rc.1 → 2.0.2

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.
Files changed (187) hide show
  1. package/LICENSE +21 -201
  2. package/README.md +36 -27
  3. package/dist/backup-73HQNKMC.js +20 -0
  4. package/dist/backup-73HQNKMC.js.map +1 -0
  5. package/dist/chunk-3BAJQXGH.js +1575 -0
  6. package/dist/chunk-3BAJQXGH.js.map +1 -0
  7. package/dist/chunk-64CTKJO7.js +4136 -0
  8. package/dist/chunk-64CTKJO7.js.map +1 -0
  9. package/dist/chunk-BENO4IH5.js +875 -0
  10. package/dist/chunk-BENO4IH5.js.map +1 -0
  11. package/dist/chunk-D4HDZEJT.js +37 -0
  12. package/dist/chunk-D4HDZEJT.js.map +1 -0
  13. package/dist/chunk-G5EF63GG.js +1291 -0
  14. package/dist/chunk-G5EF63GG.js.map +1 -0
  15. package/dist/chunk-GNP6HRVP.js +523 -0
  16. package/dist/chunk-GNP6HRVP.js.map +1 -0
  17. package/dist/chunk-HJYIQTMD.js +204 -0
  18. package/dist/chunk-HJYIQTMD.js.map +1 -0
  19. package/dist/chunk-LQ5NSWCJ.js +39 -0
  20. package/dist/chunk-LQ5NSWCJ.js.map +1 -0
  21. package/dist/chunk-LRVV7UDD.js +2340 -0
  22. package/dist/chunk-LRVV7UDD.js.map +1 -0
  23. package/dist/chunk-LVQSJF63.js +24674 -0
  24. package/dist/chunk-LVQSJF63.js.map +1 -0
  25. package/dist/chunk-MXBHCHSM.js +13995 -0
  26. package/dist/chunk-MXBHCHSM.js.map +1 -0
  27. package/dist/chunk-Z5K4FHYP.js +922 -0
  28. package/dist/chunk-Z5K4FHYP.js.map +1 -0
  29. package/dist/index.js +3798 -250
  30. package/dist/index.js.map +1 -1
  31. package/dist/self-YYXOLDKU.js +653 -0
  32. package/dist/self-YYXOLDKU.js.map +1 -0
  33. package/dist/server-O2ZELIMX.js +512 -0
  34. package/dist/server-O2ZELIMX.js.map +1 -0
  35. package/dist/setup-system-HZROFNMP.js +544 -0
  36. package/dist/setup-system-HZROFNMP.js.map +1 -0
  37. package/dist/{skills-command-3ESCZ75U.js → skills-command-MGGHY7HU.js} +190 -32
  38. package/dist/skills-command-MGGHY7HU.js.map +1 -0
  39. package/dist/uninstall-3UXXXNFO.js +223 -0
  40. package/dist/uninstall-3UXXXNFO.js.map +1 -0
  41. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js +11 -0
  42. package/dist/virtual_make-docs-first-party-skills-ZII74YOB.js.map +1 -0
  43. package/package.json +9 -6
  44. package/skill-registry.json +328 -125
  45. package/skill-registry.schema.json +221 -45
  46. package/template/.make-docs/AGENTS.md +18 -0
  47. package/template/.make-docs/CLAUDE.md +18 -0
  48. package/template/.make-docs/archive/AGENTS.md +11 -0
  49. package/template/.make-docs/archive/CLAUDE.md +11 -0
  50. package/template/.make-docs/system/AGENTS.md +12 -0
  51. package/template/.make-docs/system/CLAUDE.md +12 -0
  52. package/template/.make-docs/system/contracts/AGENTS.md +13 -0
  53. package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
  54. package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
  55. package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
  56. package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
  57. package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
  58. package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
  59. package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
  60. package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
  61. package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
  62. package/template/.make-docs/system/contracts/output-contract.md +277 -0
  63. package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
  64. package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
  65. package/template/.make-docs/system/prompts/AGENTS.md +12 -0
  66. package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
  67. package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
  68. package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
  69. package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
  70. package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
  71. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
  72. package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
  73. package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
  74. package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
  75. package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
  76. package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
  77. package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
  78. package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
  79. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
  80. package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
  81. package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
  82. package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
  83. package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
  84. package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
  85. package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
  86. package/template/.make-docs/system/references/AGENTS.md +14 -0
  87. package/template/.make-docs/system/references/CLAUDE.md +14 -0
  88. package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
  89. package/template/.make-docs/system/references/execution-workflow.md +189 -0
  90. package/template/.make-docs/system/references/human-experience.md +138 -0
  91. package/template/.make-docs/system/references/lifecycle.md +153 -0
  92. package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
  93. package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
  94. package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
  95. package/template/.make-docs/system/references/performance-evidence.md +114 -0
  96. package/template/.make-docs/system/references/planning-workflow.md +209 -0
  97. package/template/.make-docs/system/references/prd-change-management.md +165 -0
  98. package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
  99. package/template/.make-docs/system/templates/AGENTS.md +12 -0
  100. package/template/.make-docs/system/templates/CLAUDE.md +12 -0
  101. package/template/.make-docs/system/templates/design.md +79 -0
  102. package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
  103. package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
  104. package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
  105. package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
  106. package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
  107. package/template/.make-docs/system/templates/plan-overview.md +76 -0
  108. package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
  109. package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
  110. package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
  111. package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
  112. package/template/.make-docs/system/templates/prd-glossary.md +28 -0
  113. package/template/.make-docs/system/templates/prd-index.md +70 -0
  114. package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
  115. package/template/.make-docs/system/templates/prd-reference.md +30 -0
  116. package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
  117. package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
  118. package/template/.make-docs/system/templates/work-index.md +58 -0
  119. package/template/.make-docs/system/templates/work-phase.md +107 -0
  120. package/template/.make-docs/system-resources.catalog.json +91 -0
  121. package/template/.make-docs/system-resources.schema.json +204 -0
  122. package/template/AGENTS.md +8 -1
  123. package/template/CLAUDE.md +8 -1
  124. package/template/docs/AGENTS.codex-only.md +22 -0
  125. package/template/docs/AGENTS.md +21 -13
  126. package/template/docs/CLAUDE.claude-only.md +22 -0
  127. package/template/docs/CLAUDE.md +21 -13
  128. package/template/docs/assets/AGENTS.md +11 -7
  129. package/template/docs/assets/CLAUDE.md +11 -7
  130. package/template/docs/designs/AGENTS.md +8 -3
  131. package/template/docs/designs/CLAUDE.md +8 -3
  132. package/template/docs/plans/AGENTS.md +10 -3
  133. package/template/docs/plans/CLAUDE.md +10 -3
  134. package/template/docs/prd/AGENTS.md +14 -4
  135. package/template/docs/prd/CLAUDE.md +14 -4
  136. package/template/docs/work/AGENTS.md +10 -3
  137. package/template/docs/work/CLAUDE.md +10 -3
  138. package/dist/chunk-HP3HBG7F.js +0 -626
  139. package/dist/chunk-HP3HBG7F.js.map +0 -1
  140. package/dist/chunk-QRFH4J6H.js +0 -1194
  141. package/dist/chunk-QRFH4J6H.js.map +0 -1
  142. package/dist/chunk-WM3OXYTW.js +0 -2630
  143. package/dist/chunk-WM3OXYTW.js.map +0 -1
  144. package/dist/skills-command-3ESCZ75U.js.map +0 -1
  145. package/dist/uninstall-GQE4SJF2.js +0 -150
  146. package/dist/uninstall-GQE4SJF2.js.map +0 -1
  147. package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
  148. package/template/docs/assets/archive/AGENTS.md +0 -20
  149. package/template/docs/assets/archive/CLAUDE.md +0 -20
  150. package/template/docs/assets/history/AGENTS.md +0 -12
  151. package/template/docs/assets/history/CLAUDE.md +0 -12
  152. package/template/docs/assets/prompts/AGENTS.md +0 -8
  153. package/template/docs/assets/prompts/CLAUDE.md +0 -8
  154. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
  155. package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
  156. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
  157. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
  158. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
  159. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
  160. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
  161. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
  162. package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
  163. package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
  164. package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
  165. package/template/docs/assets/references/AGENTS.md +0 -9
  166. package/template/docs/assets/references/CLAUDE.md +0 -9
  167. package/template/docs/assets/references/execution-workflow.md +0 -157
  168. package/template/docs/assets/references/output-contract.md +0 -221
  169. package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
  170. package/template/docs/assets/references/planning-workflow.md +0 -160
  171. package/template/docs/assets/references/prd-change-management.md +0 -129
  172. package/template/docs/assets/templates/AGENTS.md +0 -8
  173. package/template/docs/assets/templates/CLAUDE.md +0 -8
  174. package/template/docs/assets/templates/design.md +0 -30
  175. package/template/docs/assets/templates/plan-overview.md +0 -32
  176. package/template/docs/assets/templates/plan-prd-change.md +0 -99
  177. package/template/docs/assets/templates/prd-change-addition.md +0 -45
  178. package/template/docs/assets/templates/prd-change-revision.md +0 -45
  179. package/template/docs/assets/templates/prd-glossary.md +0 -15
  180. package/template/docs/assets/templates/prd-index.md +0 -45
  181. package/template/docs/assets/templates/prd-reference.md +0 -17
  182. package/template/docs/assets/templates/work-index.md +0 -21
  183. package/template/docs/assets/templates/work-phase.md +0 -34
  184. package/template/docs/guides/AGENTS.md +0 -15
  185. package/template/docs/guides/CLAUDE.md +0 -15
  186. /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
  187. /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
@@ -1,129 +0,0 @@
1
- # PRD Change Management
2
-
3
- Archive layout is authoritative in `docs/assets/archive/AGENTS.md`.
4
-
5
- ## Purpose
6
-
7
- Use this reference when `docs/prd/` already contains an active PRD namespace and the user wants to evolve it without replacing the whole set.
8
-
9
- This workflow covers:
10
-
11
- - net-new capability additions
12
- - enhancements to existing capabilities
13
- - revisions to established requirements
14
- - deprecations or removals of established requirements
15
- - direct updates to the living risk register for newly discovered or resolved gaps, drift, open questions, decisions, and risks
16
-
17
- ## Change Taxonomy
18
-
19
- | Change type | Meaning | Template | Typical annotation |
20
- | --- | --- | --- | --- |
21
- | `addition` | Introduces a net-new capability that was not previously required | `docs/assets/templates/prd-change-addition.md` | None required unless baseline docs need cross-links |
22
- | `enhancement` | Extends an existing capability with new behavior or scope | `docs/assets/templates/prd-change-addition.md` | `Enhanced by` |
23
- | `revision` | Changes an established requirement, contract, or constraint | `docs/assets/templates/prd-change-revision.md` | `Superseded by` |
24
- | `removal` | Deprecates or removes an established requirement or capability | `docs/assets/templates/prd-change-revision.md` | `Deprecated by` or `Removed by` |
25
-
26
- ## Active-Set Evolution Rules
27
-
28
- - Treat `docs/prd/` as one active PRD namespace.
29
- - Do not archive the active namespace when performing an additive change, enhancement, revision, or removal.
30
- - Append each new change doc using the next available `NN-` number in the active namespace.
31
- - Never renumber or reorder existing active PRD docs just because a change was introduced.
32
- - Recommended slug prefixes:
33
- - `add-`
34
- - `enhance-`
35
- - `revise-`
36
- - `remove-`
37
- - The newest linked change doc defines the effective requirement for the scope it changes.
38
- - Earlier baseline text remains visible unless the user explicitly asks for a cleanup rewrite.
39
- - Update `docs/prd/03-open-questions-and-risk-register.md` directly when the change discovers or resolves a gap, drift item, open question, decision, or risk; do not create a new `NN-` change doc solely to track register state.
40
- - Do not create separate questions, decisions, risks, gaps, or architecture-decision files while an active PRD risk register exists unless the user explicitly asks for a new convention.
41
-
42
- ## Risk Register Update Rules
43
-
44
- - Keep `docs/prd/03-open-questions-and-risk-register.md` as the canonical living register for gap state, open questions, resolved decisions, confirmed drift, and rebuild risks.
45
- - Preserve the fixed sections `## Confirmed Drift`, `## Open Questions`, `## Rebuild Risks`, and `## Source Anchors`.
46
- - Add or update one numbered `###` item per gap, question, drift, or risk.
47
- - Use `D-001`, `D-002`, etc. under `## Confirmed Drift`; `Q-001`, `Q-002`, etc. under `## Open Questions`; and `R-001`, `R-002`, etc. under `## Rebuild Risks`.
48
- - Assign the next available number within the section and never renumber existing items, even when they move to `Closed`.
49
- - Each item starts with a table containing `Status`, `Decision`, and `Follow-Up`.
50
- - Use only `Open`, `Confirming`, `Deferred`, or `Closed` for item status.
51
- - Include `Question` or `Issue`, `Why it matters`, `Recommendation`, and `To close` for every item.
52
- - Add `Resolution` only when the item is closed.
53
- - If the item is already documented, update that existing item instead of duplicating it.
54
- - Do not use `### Change Notes` inside `03-open-questions-and-risk-register.md`; that heading remains valid only in baseline PRD docs and sections that need active-set evolution lineage.
55
-
56
- ## Change Doc Selection Rules
57
-
58
- - Use one change doc per coherent change scope whenever possible.
59
- - Split change docs when different requirement areas have materially different rationale, impacted docs, or delivery sequencing.
60
- - Use an addition/enhancement doc even when the new capability is large enough to resemble a subsystem. Under this model, net-new active-set changes are still recorded as change docs.
61
- - Use a revision/removal doc whenever the change alters or retires an already-established requirement, even if new implementation work will also be needed.
62
-
63
- ## Baseline Annotation Rules
64
-
65
- - Add `### Change Notes` only in the existing PRD docs and sections that are actually affected.
66
- - Place the block directly under the impacted heading or immediately after the impacted requirement text.
67
- - Use only these note verbs:
68
- - `Enhanced by`
69
- - `Superseded by`
70
- - `Deprecated by`
71
- - `Removed by`
72
- - Each note must link to the numbered change doc that carries the effective change.
73
- - When multiple change notes apply, list them in chronological order with the newest note last.
74
- - Do not delete or silently rewrite the baseline requirement merely because a change note exists.
75
-
76
- Example:
77
-
78
- ```md
79
- ### Change Notes
80
-
81
- - Enhanced by [07-enhance-notifications.md](./07-enhance-notifications.md).
82
- - Superseded by [09-revise-notification-routing.md](./09-revise-notification-routing.md).
83
- ```
84
-
85
- ## Index And Status Rules
86
-
87
- - Update `docs/prd/00-index.md` whenever a change doc is added.
88
- - The document map should show at least:
89
- - document path
90
- - kind
91
- - status
92
- - related docs
93
- - focus
94
- - Recommended `Kind` values:
95
- - `core`
96
- - `baseline`
97
- - `reference`
98
- - `addition`
99
- - `enhancement`
100
- - `revision`
101
- - `removal`
102
- - Recommended `Status` values:
103
- - `active`
104
- - `superseded`
105
- - `deprecated`
106
- - `removed`
107
- - Use `Related Docs` to connect a change doc to the baseline docs it affects and to connect affected baseline docs back to the change doc.
108
-
109
- ## Work Backlog Coupling
110
-
111
- - Backlogs are always directories: `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` with `00-index.md` and `0N-<phase>.md` files.
112
- - Plans that drive those backlogs are also directories: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` with `00-overview.md` and `0N-<phase>.md` files.
113
- - Full-set generation still writes a backlog directory covering the whole active PRD set.
114
- - Active-set evolution writes a new dated delta backlog directory by default instead of rewriting a prior backlog.
115
- - Every delta backlog phase should cite:
116
- - the new change doc or docs
117
- - the impacted baseline docs that still matter to implementation
118
- - Regenerate the full implementation backlog only when the user explicitly asks for it.
119
-
120
- ## Validation Checklist
121
-
122
- Before closing an active-set evolution task, confirm:
123
-
124
- 1. Every new change doc uses the next available number and no existing PRD docs were renumbered.
125
- 2. Every impacted baseline doc contains the required `### Change Notes` backlinks when applicable.
126
- 3. `docs/prd/00-index.md` includes the new change docs and updated status or lineage metadata.
127
- 4. The effective requirement can be resolved by following links from the impacted baseline doc to the newest change doc.
128
- 5. Baseline text remains visible unless the user explicitly approved a cleanup rewrite.
129
- 6. Newly discovered or resolved gaps, drift, questions, decisions, and risks are reflected in `docs/prd/03-open-questions-and-risk-register.md`.
@@ -1,8 +0,0 @@
1
- # Templates Router
2
-
3
- This directory contains structural starting points for generated docs.
4
-
5
- - Copy the relevant template shape into the target output file; do not write outputs here.
6
- - Use `design.md` for design docs, `guide-developer.md` or `guide-user.md` for guides, and the matching `plan-*`, `prd-*`, or `work-*` template for the target artifact.
7
- - Resolve workflow and contract questions in `docs/assets/references/`, then continue in the target output directory router.
8
- - Do not modify template files unless the user explicitly asks.
@@ -1,8 +0,0 @@
1
- # Templates Router
2
-
3
- This directory contains structural starting points for generated docs.
4
-
5
- - Copy the relevant template shape into the target output file; do not write outputs here.
6
- - Use `design.md` for design docs, `guide-developer.md` or `guide-user.md` for guides, and the matching `plan-*`, `prd-*`, or `work-*` template for the target artifact.
7
- - Resolve workflow and contract questions in `docs/assets/references/`, then continue in the target output directory router.
8
- - Do not modify template files unless the user explicitly asks.
@@ -1,30 +0,0 @@
1
- # {{TITLE}}
2
-
3
- > Filename: `YYYY-MM-DD-<slug>.md`. See `docs/assets/references/design-contract.md` for naming and structural rules.
4
-
5
- ## Purpose
6
-
7
- Explain what decision this document captures and why it exists.
8
-
9
- ## Context
10
-
11
- Describe the problem, constraints, forces, and existing conditions that shape the decision.
12
-
13
- ## Decision
14
-
15
- Describe the chosen approach clearly enough that planning can proceed from it.
16
-
17
- ## Alternatives Considered
18
-
19
- List the meaningful alternatives and why they were not chosen.
20
-
21
- ## Consequences
22
-
23
- Describe outcomes, trade-offs, risks, and follow-on implications.
24
-
25
- ## Intended Follow-On
26
-
27
- - Route: `baseline-plan` or `change-plan`
28
- - Next Prompt: [{{PROMPT_LABEL}}](../prompts/{{PROMPT_FILE}})
29
- - Why: Explain why this design should flow into that planning path.
30
- - Coordinate Handoff: For `change-plan`, identify the related completed coordinate and recommended downstream W/R coordinate when known; otherwise state `unresolved; planner must resolve before writing.`
@@ -1,32 +0,0 @@
1
- # {{TITLE}}
2
-
3
- ## Purpose
4
-
5
- State what this plan covers and why it exists in one short paragraph. Link back to the originating design or change request if applicable.
6
-
7
- ## Objective
8
-
9
- List the concrete goals and the completion criteria for the plan. A reader should be able to tell when the plan is done.
10
-
11
- ## Coordinate Decision
12
-
13
- - Coordinate: `W{{W}} R{{R}}`
14
- - Classification: `new-wave` or `revision`
15
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
16
-
17
- ## Phase Map
18
-
19
- List the phase detail files in this plan directory with a one-line description of each. Every plan has at least one phase file even when the work is small.
20
-
21
- | File | Purpose |
22
- | ---- | ------- |
23
- | `01-{{UPPER_SNAKE}}.md` | {{PHASE_PURPOSE}} |
24
- | `02-{{UPPER_SNAKE}}.md` | {{PHASE_PURPOSE}} |
25
-
26
- ## Dependencies
27
-
28
- Call out external dependencies, upstream artifacts, or prerequisites that must be resolved before or during execution.
29
-
30
- ## Validation
31
-
32
- Describe how success of the overall plan is verified once all phases complete. Reference the review pass or acceptance gate that closes the plan.
@@ -1,99 +0,0 @@
1
- # PRD Change Plan
2
-
3
- > In v2, plans are directories. Use this template as the shape of the `00-overview.md` file in the plan directory; split additional detail into `0N-<phase>.md` files as needed.
4
-
5
- **Date:** {{DATE}}
6
-
7
- **Repository:** `{{REPO_ROOT}}`
8
-
9
- **Purpose:** Produce a reviewable plan for evolving the active PRD namespace through an additive change, enhancement, revision, or removal.
10
-
11
- ## Objective
12
-
13
- State what is changing, why the change is needed, who the outputs are for, and what counts as completion.
14
-
15
- ## Coordinate Decision
16
-
17
- - Coordinate: `W{{W}} R{{R}}`
18
- - Classification: `new-wave` or `revision`
19
- - Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
20
-
21
- ## Change Classification
22
-
23
- - Requested change type: {{CHANGE_TYPE}} <!-- addition | enhancement | revision | removal -->
24
- - Effective execution mode: `active-set evolution`
25
- - Cleanup rewrite requested: {{CLEANUP_REWRITE}} <!-- no | yes -->
26
- - Full backlog regeneration requested: {{FULL_BACKLOG_REGEN}} <!-- no | yes -->
27
-
28
- ## Change Inputs
29
-
30
- List every source of truth that feeds into the change plan. Each entry should note its format, location, and confidence level.
31
-
32
- | Input | Format | Location | Confidence |
33
- | ----- | ------ | -------- | ---------- |
34
- | {{INPUT_NAME}} | {{FORMAT}} | {{LOCATION}} | {{CONFIDENCE}} |
35
-
36
- Open questions or ambiguities should be captured here and promoted into `03-open-questions-and-risk-register.md` during execution when appropriate.
37
-
38
- ## Baseline Context
39
-
40
- - Active `docs/prd/` status: {{ACTIVE_PRD_STATUS}}
41
- - Impacted baseline docs: {{IMPACTED_DOCS}}
42
- - Discovery pass required: {{DISCOVERY_REQUIRED}} <!-- yes | no -->
43
- - Discovery scope if required: {{DISCOVERY_SCOPE}}
44
-
45
- ## Output Contract
46
-
47
- - Plan directory: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{CHANGE_SLUG}}/`
48
- - entry point: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{CHANGE_SLUG}}/00-overview.md`
49
- - phase files: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{CHANGE_SLUG}}/0N-<phase>.md`
50
- - New change docs:
51
- - `docs/prd/{{NEXT_NUMBER}}-{{CHANGE_SLUG}}.md`
52
- - add more if the change must split across multiple docs
53
- - Baseline docs to annotate: {{ANNOTATION_TARGETS}}
54
- - Delta backlog:
55
- - `docs/work/{{DATE}}-w{{W}}-r{{R}}-{{CHANGE_SLUG}}/`
56
-
57
- ## Change Doc Strategy
58
-
59
- List the change docs that will be added and the reason each one exists.
60
-
61
- | New doc | Kind | Why it exists | Affected baseline docs |
62
- | ------- | ---- | ------------- | ---------------------- |
63
- | `{{NEXT_NUMBER}}-{{CHANGE_SLUG}}.md` | {{KIND}} | {{RATIONALE}} | {{AFFECTED_DOCS}} |
64
-
65
- ## Baseline Annotation Plan
66
-
67
- List the existing docs and sections that need `### Change Notes` updates.
68
-
69
- | Baseline doc | Impacted sections | Note verb | Target change doc |
70
- | ------------ | ----------------- | --------- | ----------------- |
71
- | `{{DOC_PATH}}` | {{SECTIONS}} | {{NOTE_VERB}} | `{{CHANGE_DOC}}` |
72
-
73
- ## Worker Ownership
74
-
75
- List the delegated workers, their scopes, write scopes, dependencies, and deliverables.
76
-
77
- - Assign every output-writing task to a worker when delegation is available.
78
- - Keep change-doc authoring, baseline annotations, index updates, and delta backlog generation as separate write scopes whenever practical.
79
- - Include a dedicated validation or fix worker when the harness can support it.
80
- - The coordinator should not appear as the owner of any document-writing task when delegation is available.
81
-
82
- | Worker | Scope | Write Scope | Dependencies | Deliverables |
83
- | ------ | ----- | ----------- | ------------ | ------------ |
84
- | {{WORKER_NAME}} | {{SCOPE}} | {{WRITE_SCOPE}} | {{DEPENDENCIES}} | {{DELIVERABLES}} |
85
-
86
- ## MCP Strategy
87
-
88
- - Preferred servers available: {{MCP_STATUS}}
89
- - Fallback plan if unavailable: {{FALLBACK_PLAN}}
90
-
91
- ## Validation
92
-
93
- Explain how the execution step will validate the generated outputs. Validation should confirm:
94
-
95
- - every new change doc uses the right template and change type
96
- - every impacted baseline doc includes the required backlinks
97
- - `docs/prd/00-index.md` reflects the new status and lineage
98
- - the delta backlog traces back to the change docs and impacted baseline docs
99
- - no existing PRD docs were renumbered or silently rewritten
@@ -1,45 +0,0 @@
1
- # {{NUMBER}} {{TITLE}}
2
-
3
- ## Purpose
4
-
5
- Explain what new capability or enhancement this document introduces and why it is being added to the active PRD namespace.
6
-
7
- ## Change Type
8
-
9
- State whether this doc records an `addition` or an `enhancement`, and summarize the expected effect on the active requirement set.
10
-
11
- ## Capability Addition or Enhancement
12
-
13
- Describe the new behavior, scope, user-visible capability, and operational impact introduced by this change.
14
-
15
- Code anchors:
16
-
17
- - `{{CHANGE_PATHS}}`
18
-
19
- ## Affected Baseline Docs
20
-
21
- List the existing PRD docs this change extends, complements, or cross-cuts. If the capability is net-new, say so explicitly and still note any baseline docs that need awareness updates.
22
-
23
- ## Contracts and Data
24
-
25
- Describe the important data models, API contracts, events, storage shapes, or configuration surfaces introduced or expanded by this change.
26
-
27
- Code anchors:
28
-
29
- - `{{CONTRACT_PATHS}}`
30
-
31
- ## Integration Impact
32
-
33
- Describe external dependencies, sibling modules, or cross-cutting connections that must now account for this change.
34
-
35
- Code anchors:
36
-
37
- - `{{INTEGRATION_PATHS}}`
38
-
39
- ## Required Baseline Annotations
40
-
41
- List the baseline PRD docs and sections that must receive `### Change Notes` updates, including the verb that should be used.
42
-
43
- ## Source Anchors
44
-
45
- - `{{PRIMARY_FILES}}`
@@ -1,45 +0,0 @@
1
- # {{NUMBER}} {{TITLE}}
2
-
3
- ## Purpose
4
-
5
- Explain what established requirement is being revised, deprecated, or removed and why this change belongs in the active PRD namespace.
6
-
7
- ## Change Type
8
-
9
- State whether this doc records a `revision` or a `removal`, and summarize the expected effect on the active requirement set.
10
-
11
- ## Baseline Being Revised or Removed
12
-
13
- Identify the prior PRD docs, sections, and requirement areas that this change alters or retires.
14
-
15
- ## Rationale
16
-
17
- Explain why the prior requirement is no longer sufficient or should no longer remain active.
18
-
19
- Code anchors:
20
-
21
- - `{{RATIONALE_PATHS}}`
22
-
23
- ## Effective Requirement
24
-
25
- Describe the requirement that should now be treated as effective, or explain the required removal state if the capability is being retired.
26
-
27
- Code anchors:
28
-
29
- - `{{EFFECTIVE_REQUIREMENT_PATHS}}`
30
-
31
- ## Impacted Docs and Dependencies
32
-
33
- List the PRD docs, integrations, downstream work items, or adjacent requirement areas affected by this change.
34
-
35
- Code anchors:
36
-
37
- - `{{IMPACT_PATHS}}`
38
-
39
- ## Required Baseline Annotations
40
-
41
- List the baseline PRD docs and sections that must receive `### Change Notes` updates, including whether they should use `Superseded by`, `Deprecated by`, or `Removed by`.
42
-
43
- ## Source Anchors
44
-
45
- - `{{PRIMARY_FILES}}`
@@ -1,15 +0,0 @@
1
- # 04 Glossary
2
-
3
- ## Purpose
4
-
5
- Define the canonical vocabulary used across this PRD set so humans and coding assistants interpret the same terms the same way.
6
-
7
- ## Terms
8
-
9
- | Term | Definition | Notes |
10
- | --- | --- | --- |
11
- | `{{TERM}}` | Explain the term in plain English. | Link it back to the subsystem or workflow that uses it. |
12
-
13
- ## Source Anchors
14
-
15
- - `{{PRIMARY_FILES}}`
@@ -1,45 +0,0 @@
1
- # {{PRODUCT_NAME}} PRD Index
2
-
3
- ## Purpose
4
-
5
- Explain what this PRD set covers, who it is for, and why it exists.
6
-
7
- ## Reading Order
8
-
9
- 1. [01-product-overview.md](./01-product-overview.md)
10
- 2. [02-architecture-overview.md](./02-architecture-overview.md)
11
- 3. [03-open-questions-and-risk-register.md](./03-open-questions-and-risk-register.md)
12
- 4. [04-glossary.md](./04-glossary.md)
13
- 5. Add the adaptive baseline docs and change docs here in the order that best rebuilds understanding.
14
-
15
- ## Document Map
16
-
17
- | Document | Kind | Status | Related Docs | Focus |
18
- | --- | --- | --- | --- | --- |
19
- | `00-index.md` | `core` | `active` | `—` | Explain the PRD set and how to read it |
20
- | `01-product-overview.md` | `core` | `active` | `—` | Explain product purpose, users, capabilities, boundaries, and limitations |
21
- | `02-architecture-overview.md` | `core` | `active` | `—` | Explain topology, module map, runtime boundaries, data flow, and config surfaces |
22
- | `03-open-questions-and-risk-register.md` | `core` | `active` | `—` | Capture drift, gaps, and rebuild risks |
23
- | `04-glossary.md` | `core` | `active` | `—` | Define canonical terms |
24
- | `{{ADAPTIVE_DOCS}}` | `baseline` or change kind | `active`, `superseded`, `deprecated`, or `removed` | List linked baseline or change docs | Explain subsystem, reference, or change scope generated for this repo |
25
-
26
- ## Source Anchors
27
-
28
- - `README.md`
29
- - `package.json`
30
- - `{{PRIMARY_ENTRYPOINT}}`
31
- - `{{PRIMARY_DOCS}}`
32
-
33
- ## Audience Paths
34
-
35
- ### New developer
36
-
37
- List the best reading path for a developer joining the project.
38
-
39
- ### Product or technical lead
40
-
41
- List the best reading path for product, architecture, or planning review.
42
-
43
- ### AI coding assistant
44
-
45
- List the fastest path for an assistant that needs safe, code-first context before making changes.
@@ -1,17 +0,0 @@
1
- # {{NUMBER}} {{TITLE}}
2
-
3
- ## Purpose
4
-
5
- Explain what this reference doc captures and why it should stay separate from subsystem narrative docs.
6
-
7
- ## Reference
8
-
9
- Capture the schema, API, config, protocol, operational checklist, or other reference material in a table-heavy format.
10
-
11
- Code anchors:
12
-
13
- - `{{REFERENCE_PATHS}}`
14
-
15
- ## Source Anchors
16
-
17
- - `{{PRIMARY_FILES}}`
@@ -1,21 +0,0 @@
1
- # {{TITLE}}
2
-
3
- > In v2, work backlogs are directories. This template is the shape of the `00-index.md` entry-point file. Phase detail lives in sibling `0N-<phase>.md` files (see `work-phase.md`). See `docs/assets/references/wave-model.md` for W/R semantics.
4
-
5
- ## Purpose
6
-
7
- Describe what this work directory covers and how to navigate its phase files.
8
-
9
- ## Phase Map
10
-
11
- | File | Purpose |
12
- | --- | --- |
13
- | [01-{{PHASE_SLUG}}.md](./01-{{PHASE_SLUG}}.md) | {{PHASE_ONE_PURPOSE}} |
14
- | [02-{{PHASE_SLUG}}.md](./02-{{PHASE_SLUG}}.md) | {{PHASE_TWO_PURPOSE}} |
15
-
16
- ## Usage Notes
17
-
18
- - Read phases in order unless otherwise noted.
19
- - Keep phase files dependency-ordered.
20
- - Every phase file must include `## Source PRD Docs`.
21
- - Link every phase back to the relevant PRD docs.
@@ -1,34 +0,0 @@
1
- # Phase {{PHASE_NUMBER}}: {{PHASE_TITLE}}
2
-
3
- > Shape for `0N-<phase>.md` files inside a work directory. See `docs/assets/references/wave-model.md` for W/R semantics.
4
-
5
- ## Purpose
6
-
7
- Explain why this phase exists and what foundation it depends on.
8
-
9
- ## Overview
10
-
11
- Explain the work covered by this phase and the value it unlocks.
12
-
13
- ## Source PRD Docs
14
-
15
- - [{{DOC_TITLE}}](../../prd/{{DOC_PATH}})
16
- - [{{DOC_TITLE}}](../../prd/{{DOC_PATH}})
17
-
18
- ## Stage {{STAGE_NUMBER}} - {{STAGE_NAME}}
19
-
20
- ### Tasks
21
-
22
- - [ ] t1: {{TASK}}
23
- - [ ] t2: {{TASK}}
24
-
25
- ### Acceptance criteria
26
-
27
- - {{ACCEPTANCE}}
28
- - {{ACCEPTANCE}}
29
-
30
- ### Dependencies
31
-
32
- - {{DEPENDENCY}}
33
-
34
- <!-- Insert additional STAGES as needed -->
@@ -1,15 +0,0 @@
1
- # Guides for Devs and Users
2
-
3
- Use `docs/guides` only as a router. Do not create generated files directly in this directory.
4
-
5
- - Before writing any guide, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, and decide whether the right outcome is `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`.
6
- - **User guides** are stored in `docs/guides/user/`. They explain the shipped product from a user's perspective, from novice orientation through advanced workflows. Use `docs/assets/templates/guide-user.md` when creating one.
7
- - **Developer guides** are stored in `docs/guides/developer/`. They help contributors, maintainers, integrators, and operators navigate the codebase, docs, contracts, validation, extension points, and safe-change workflows. Use `docs/assets/templates/guide-developer.md` when creating one.
8
- - Prefer updating an existing guide when it already owns the topic. Use cross-links and `related` frontmatter instead of duplicating full guides across audiences.
9
- - After creating or updating guides, re-check overlapping guides and add reciprocal links, `related` frontmatter, or concise supplemental context when the new work improves their discoverability.
10
- - If current confirmed behavior is useful but downstream work will expand it, write the current coverage now and add `## Future Coverage` for the blocked guide update.
11
- - Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
12
- - History records are not guides. Route them through `docs/assets/history/` instead.
13
- - If the `docs/guides/user` or `docs/guides/developer` directories do not exist, create them ONLY when first writing a guide that belongs in the specific sub-folder.
14
-
15
- Documentation must be easy to understand, easy to use, and easy to follow, with links to supporting sections or documents where necessary and where possible.
@@ -1,15 +0,0 @@
1
- # Guides for Devs and Users
2
-
3
- Use `docs/guides` only as a router. Do not create generated files directly in this directory.
4
-
5
- - Before writing any guide, read `docs/assets/references/guide-contract.md`, inspect existing guides for overlap, and decide whether the right outcome is `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`.
6
- - **User guides** are stored in `docs/guides/user/`. They explain the shipped product from a user's perspective, from novice orientation through advanced workflows. Use `docs/assets/templates/guide-user.md` when creating one.
7
- - **Developer guides** are stored in `docs/guides/developer/`. They help contributors, maintainers, integrators, and operators navigate the codebase, docs, contracts, validation, extension points, and safe-change workflows. Use `docs/assets/templates/guide-developer.md` when creating one.
8
- - Prefer updating an existing guide when it already owns the topic. Use cross-links and `related` frontmatter instead of duplicating full guides across audiences.
9
- - After creating or updating guides, re-check overlapping guides and add reciprocal links, `related` frontmatter, or concise supplemental context when the new work improves their discoverability.
10
- - If current confirmed behavior is useful but downstream work will expand it, write the current coverage now and add `## Future Coverage` for the blocked guide update.
11
- - Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
12
- - History records are not guides. Route them through `docs/assets/history/` instead.
13
- - If the `docs/guides/user` or `docs/guides/developer` directories do not exist, create them ONLY when first writing a guide that belongs in the specific sub-folder.
14
-
15
- Documentation must be easy to understand, easy to use, and easy to follow, with links to supporting sections or documents where necessary and where possible.