@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,19 +0,0 @@
1
- ___
2
- name: Session to History Record
3
- description: Instructs the agent to summarize the current session into a new dated history record under `docs/assets/history/`.
4
- ___
5
-
6
- Please summarize this session into a new history record.
7
-
8
- Before writing anything, read `docs/assets/references/history-record-contract.md`, `docs/assets/templates/history-record.md`, and the router at `docs/assets/history/AGENTS.md` (or `CLAUDE.md`). Do not restate their rules — follow them.
9
-
10
- Use today's date for `YYYY-MM-DD` and never backdate. If the active plan or work context gives a known position, record it in one `coordinate` frontmatter field such as `W9 R0 P1` or `W9 R0 P1 S2 T4`; omit unknown coordinate levels.
11
-
12
- Create a new file under `docs/assets/history/` (default slug `summary`). If W/R/P is known, name it `YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`. If only W/R is known, name it `YYYY-MM-DD-w{W}-r{R}-<slug>.md`. If no coordinate is known, name it `YYYY-MM-DD-<slug>.md`. Fill only known frontmatter fields; do not invent unknown `client`, `model`, or `provider` values. Follow the required headings exactly: `## Changes`, then `## Documentation` containing `### Project`, `### Developer`, and `### User` tables. State `None this session.` for any empty sub-section.
13
-
14
- Keep the summary concise — breadcrumbs for a future auditor, not a verbose narrative. Use relative Markdown links to any touched files, plans, designs, or backlog phases.
15
-
16
- Optional hints (leave blank to accept defaults):
17
-
18
- - Focus: {{FOCUS}}
19
- - Slug: {{SLUG}}
@@ -1,18 +0,0 @@
1
- ___
2
- name: Work to Guides
3
- description: Instructs the agent to create or update developer and user guides from completed work backlog phases.
4
- ___
5
-
6
- Please review the completed work below and create or update the appropriate developer and/or user guides.
7
-
8
- Before writing anything, read `docs/assets/references/guide-contract.md`, the matching guide template in `docs/assets/templates/`, and the router in `docs/guides/`. Treat those files as the authority for audience intent, frontmatter, slug rules, guide coverage decisions, and future coverage handling.
9
-
10
- Start by inspecting existing guides under `docs/guides/developer/` and `docs/guides/user/`. Decide whether each completed capability should result in `developer`, `user`, `both`, `update-existing`, `link-only`, or `none`.
11
-
12
- Write guides as current-state documentation, not as phase summaries. Developer guides should help contributors and maintainers navigate the project, codebase, contracts, validation, extension points, and safe-change workflows so they can reach a useful first PR or maintenance action quickly. User guides should help users understand and use what the project ships, with novice-friendly orientation and clear paths into advanced capabilities.
13
-
14
- If current confirmed behavior is useful now, document it now. If downstream capabilities are needed to complete or enrich the guide later, add a `## Future Coverage` section with `Blocked by`, `Update when`, and `Guide change` items. Do not create design docs, architecture decisions, or PRD risk-register items solely to remember future guide work.
15
-
16
- Here is the completed work context:
17
-
18
- {{WORK_CONTEXT}}
@@ -1,9 +0,0 @@
1
- # References Router
2
-
3
- This directory is the authoritative source for workflow rules and output contracts.
4
-
5
- - Read only the specific reference file needed for the task.
6
- - Use these files to resolve structure, lifecycle, and workflow questions instead of restating those rules in routers.
7
- - Use `path-and-link-hygiene.md` for repo-relative path rules, relative Markdown links, sanitized placeholders, and full-path exceptions.
8
- - Do not treat this directory as an output target.
9
- - Do not modify reference files unless the user explicitly asks.
@@ -1,9 +0,0 @@
1
- # References Router
2
-
3
- This directory is the authoritative source for workflow rules and output contracts.
4
-
5
- - Read only the specific reference file needed for the task.
6
- - Use these files to resolve structure, lifecycle, and workflow questions instead of restating those rules in routers.
7
- - Use `path-and-link-hygiene.md` for repo-relative path rules, relative Markdown links, sanitized placeholders, and full-path exceptions.
8
- - Do not treat this directory as an output target.
9
- - Do not modify reference files unless the user explicitly asks.
@@ -1,157 +0,0 @@
1
- # Execution Workflow
2
-
3
- See `docs/assets/references/wave-model.md` for W/R semantics; archive rules are authoritative in `docs/assets/archive/AGENTS.md`.
4
-
5
- ## Purpose
6
-
7
- Use this workflow to generate or evolve the active PRD namespace and the related backlog in a consistent way. Execution mode is allowed only after the user explicitly authorizes execution, either after plan approval or as direct execution from the start.
8
-
9
- ## Preconditions
10
-
11
- Execution mode requires one of:
12
-
13
- - an approved plan plus an explicit instruction to execute it
14
- - a direct user instruction that explicitly authorizes immediate execution
15
-
16
- If neither exists, switch back to planning mode.
17
-
18
- ## Execution Modes
19
-
20
- Classify the task before writing:
21
-
22
- 1. `full-set generation` — create or replace the active PRD namespace from a plan, design, or decomposition workflow
23
- 2. `active-set evolution` — append change docs and update impacted baseline docs without replacing the namespace
24
-
25
- Use `active-set evolution` when the user wants to add capability, enhance an existing capability, revise a requirement, or deprecate or remove a requirement that already exists in the active PRD namespace.
26
-
27
- ## Preflight
28
-
29
- 1. Determine the highest usable delegation tier for the current session: parallel agents, then subagents, then single-agent fallback.
30
- 2. Re-check existing docs so you avoid duplicating or clobbering useful material.
31
- 3. Inspect `docs/prd/` and determine whether active root entries already exist outside the archive.
32
- 4. Classify the task as `full-set generation` or `active-set evolution`.
33
- 5. If the task is active-set evolution, identify the impacted baseline docs before spawning authoring work.
34
-
35
- ## Delegation Ladder
36
-
37
- - PRD work is delegation-first by default because this workflow is highly context-intensive.
38
- - Use this priority order:
39
- 1. parallel agents
40
- 2. subagents
41
- 3. single-agent fallback
42
- - If the harness likely supports delegation, decide the workstream split and spawn workers before broad repo analysis or document drafting by the coordinator.
43
- - If delegation is available, the coordinator write scope is `none`.
44
- - The coordinating agent must not draft PRD docs, create backlog files, fill shared docs, run assembly sweeps, or perform fix-up edits when those tasks can be delegated.
45
- - Any task that creates or edits output files must be assigned to a worker whenever delegation is available.
46
- - Single-agent execution is the fallback only when the harness or session policy does not permit delegation.
47
-
48
- ## Coordinator Role
49
-
50
- If delegation is available, the coordinator is limited to:
51
-
52
- - capability and preflight checks
53
- - approval handling
54
- - workstream definition and task routing
55
- - worker spawning and monitoring
56
- - blocker resolution and reassignment
57
- - final user-facing status reporting
58
-
59
- If delegation is available, the coordinator must not:
60
-
61
- - author PRD docs
62
- - author backlog docs
63
- - own shared-doc assembly
64
- - merge glossary or risk-register content itself
65
- - run validator-driven document fixes itself
66
- - perform broad deep-dive reads that belong to a worker's authoring scope
67
-
68
- ## Full-Set Replacement Gate
69
-
70
- Apply this gate only in `full-set generation` mode:
71
-
72
- - Treat `docs/prd/` as a single active PRD namespace.
73
- - If root entries already exist in `docs/prd/`, summarize them and ask for approval before moving them.
74
- - On approval, archive every root entry into `docs/assets/archive/prds/YYYY-MM-DD/` or `docs/assets/archive/prds/YYYY-MM-DD-XX/`.
75
- - Include stray or hidden root entries in the archive summary and move set when they are part of the active namespace.
76
- - If archival is declined, stop before writing anything into `docs/prd/`.
77
- - Treat archived PRD sets as historical records, not active output targets.
78
-
79
- ## Active-Set Evolution Gate
80
-
81
- Apply this gate only in `active-set evolution` mode:
82
-
83
- - Do not archive the active PRD namespace.
84
- - Determine the next available `NN-` number before drafting change docs.
85
- - Choose the relevant change template based on `docs/assets/references/prd-change-management.md`.
86
- - Preserve prior baseline text unless the user explicitly asked for a cleanup rewrite.
87
- - Update impacted baseline docs with `### Change Notes` backlinks where applicable.
88
- - Update `docs/prd/00-index.md` so the new change docs and affected baseline docs show accurate status and lineage metadata.
89
-
90
- ## Writing Order
91
-
92
- ### Full-set generation
93
-
94
- 1. Determine the delegation tier and spawn workstreams if supported.
95
- 2. Resolve the active-PRD archive gate if one is required.
96
- 3. Determine the final PRD catalog shape.
97
- 4. Route domain and subsystem docs to delegated workers.
98
- 5. Route shared-doc assembly for `00-index.md`, `03-open-questions-and-risk-register.md`, `04-glossary.md`, and the backlog to a dedicated worker.
99
- 6. Route contract validation and fix-up work to a dedicated validation worker.
100
- 7. Keep the coordinator focused on status, blockers, and final reporting.
101
-
102
- ### Active-set evolution
103
-
104
- 1. Determine the delegation tier and spawn workstreams if supported.
105
- 2. Confirm change classification, impacted baseline docs, and next available doc numbers.
106
- 3. Route change-doc authoring to one or more workers.
107
- 4. Route baseline annotation updates and index updates to a dedicated assembly worker when possible.
108
- 5. Route delta backlog generation to a dedicated worker.
109
- 6. Route backlink, status, and traceability validation to a dedicated validation worker.
110
- 7. Keep the coordinator focused on status, blockers, and final reporting.
111
-
112
- ## Parallelization Rules
113
-
114
- If the harness supports delegated workers, do not postpone delegation until the coordinator has already consumed most of its context budget.
115
-
116
- - Prefer multiple concurrent workers when the harness supports parallel agents.
117
- - If the harness does not support concurrent workers but does support delegated workers, use subagents before falling back to single-agent execution.
118
- - Split work by subsystem or document family.
119
- - Keep write scopes disjoint.
120
- - Reserve final assembly, cross-linking, and validation for delegated workers, not the coordinator.
121
- - Tell each spawned agent to build its own MCP indexes in its own session before deep analysis.
122
-
123
- For active-set evolution, prefer these separate write scopes when possible:
124
-
125
- - new change docs
126
- - existing baseline annotations
127
- - PRD index and shared-doc status updates
128
- - delta backlog generation
129
- - validation and fix-up
130
-
131
- ## Existing Documentation Rule
132
-
133
- - Supplement and cite useful existing docs.
134
- - Do not silently overwrite docs that serve another audience or purpose.
135
- - If existing docs drift from the code, record the drift in `03-open-questions-and-risk-register.md`.
136
- - If the task is full-set generation and an older active PRD set already exists under `docs/prd/`, archive it to `docs/assets/archive/prds/YYYY-MM-DD/` before writing the replacement active PRD set.
137
- - If the task is active-set evolution, preserve baseline text and add non-destructive annotations unless the user explicitly asks for a cleanup rewrite.
138
-
139
- ## Backlog Rules
140
-
141
- - Work is always a directory in v2. Full-set generation writes `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` containing `00-index.md` plus `0N-<phase>.md` phase files.
142
- - Active-set evolution writes `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` as a delta backlog directory containing `00-index.md` plus `0N-<phase>.md` phase files.
143
- - Plans use the same form: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` containing `00-overview.md` plus `0N-<phase>.md` phase files.
144
- - Keep backlog phases dependency-ordered across the `0N-<phase>.md` files.
145
- - In every stage, write `### Tasks` as markdown task list items using phase-local task IDs (`- [ ] t1: ...`, `- [x] t1: ...`) and write `### Acceptance criteria` as plain unordered bullets only.
146
- - Increment task IDs across the entire phase file without resetting in later stages. Do not renumber existing task IDs when inserting or completing work.
147
- - Include phase-level PRD traceability via `Source PRD Docs`.
148
- - Delta backlogs should cite both the new change docs and the impacted baseline docs that still constrain implementation.
149
-
150
- ## Final Validation
151
-
152
- Before closing the task:
153
-
154
- 1. Resolve broken links, missing core docs, missing required headings, or misplaced backlog files.
155
- 2. Confirm the PRD index reflects the final catalog, status, and lineage.
156
- 3. Confirm the backlog links to the relevant PRD docs.
157
- 4. For active-set evolution, confirm every required backlink, supersession or deprecation marker, and delta backlog traceability link is present.
@@ -1,221 +0,0 @@
1
- # Output Contract
2
-
3
- See `docs/assets/references/wave-model.md` for W/R/P semantics and resolution.
4
-
5
- ## Purpose
6
-
7
- Use this contract to keep plan, PRD, and work document outputs consistent across repositories and harnesses. Treat the codebase as authoritative, write in plain English, and keep the PRD set descriptive while keeping implementation work prescriptive.
8
-
9
- ## Markdown Source Formatting
10
-
11
- - Do not hard-wrap prose paragraphs for visual width; use editor soft-wrap instead. Paragraphs should be one logical source line unless semantic Markdown structure requires otherwise.
12
- - Insert line breaks only for semantic Markdown structure: paragraph boundaries, headings, list items, tables, blockquotes, code fences, frontmatter, comments, or intentional line-based formats.
13
- - Separate every Markdown block from the next block with one blank line, including headings, paragraphs, lists, fenced code blocks, blockquotes, comments, and tables.
14
- - Prefer one logical line per list item unless nested structure is semantically required. When list continuation or nesting is required, indentation is semantic and must be preserved exactly.
15
-
16
- ## Required Paths
17
-
18
- | Artifact | Required path |
19
- | --- | --- |
20
- | Design | `docs/designs/YYYY-MM-DD-<slug>.md` |
21
- | Plan directory | `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
22
- | Work directory | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
23
- | PRD index | `docs/prd/00-index.md` |
24
- | Product overview | `docs/prd/01-product-overview.md` |
25
- | Architecture overview | `docs/prd/02-architecture-overview.md` |
26
- | Risk and gap register | `docs/prd/03-open-questions-and-risk-register.md` |
27
- | Glossary | `docs/prd/04-glossary.md` |
28
- | Archived PRD set | `docs/assets/archive/prds/YYYY-MM-DD/` or `docs/assets/archive/prds/YYYY-MM-DD-XX/` |
29
- | History record | `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md` when W/R/P is known; fall back to `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md` when only W/R is known or `docs/assets/history/YYYY-MM-DD-<slug>.md` when no coordinate is known. |
30
-
31
- Plan directories contain `00-overview.md` plus one or more `0N-<phase>.md` files. Work directories contain `00-index.md` plus one or more `0N-<phase>.md` files. See `docs/assets/references/wave-model.md` for the full naming pattern and `## Work Phase Structure Rules` below for work content requirements.
32
-
33
- For change-oriented plans and delta backlogs, carry the distinguishing context in the `<slug>` (for example `...-auth-recovery-change` or `...-notifications-delta`) rather than in the directory structure. Every plan and every work backlog uses the same W/R directory shape.
34
-
35
- ## PRD Lifecycle Rules
36
-
37
- - `docs/prd/` contains one active PRD namespace at a time.
38
- - Every root entry in `docs/prd/` is part of the active namespace.
39
- - Active namespaces can be created in two ways:
40
- - `full-set generation` — generate or replace the active namespace as a set
41
- - `active-set evolution` — append change docs and update impacted baseline docs without replacing the namespace
42
- - `docs/prd/03-open-questions-and-risk-register.md` is the living register for discovered gaps, confirmed drift, open questions, decisions, and rebuild risks in the active namespace.
43
- - Older namespaces belong under `docs/assets/archive/prds/`, not alongside the active namespace.
44
- - Archived PRD sets are historical records and are not part of active PRD validation.
45
-
46
- ## Archive Rules
47
-
48
- Apply these rules only when writing a fresh active PRD namespace through `full-set generation`.
49
-
50
- - Before writing a fresh PRD set, inspect `docs/prd/` for active root entries.
51
- - If no such entries exist, proceed normally.
52
- - If active root entries exist, summarize them and ask for explicit approval before moving them.
53
- - On approval, move those entries into `docs/assets/archive/prds/YYYY-MM-DD/`.
54
- - If that dated directory already exists, use `docs/assets/archive/prds/YYYY-MM-DD-XX/`, where `XX` is a zero-padded increment starting at `01`.
55
- - Do not place loose files directly under `docs/assets/archive/prds/`; it should contain dated directories only.
56
- - Never archive designs, plans, work, or PRDs unless the user explicitly asks.
57
-
58
- Archive layout and hard rules are authoritative in `docs/assets/archive/AGENTS.md`.
59
-
60
- ## Active-Set Evolution Rules
61
-
62
- Apply these rules when the user wants to add, enhance, revise, deprecate, or remove requirements inside the current active namespace.
63
-
64
- - Do not archive the active namespace.
65
- - Append new change docs using the next available `NN-` number.
66
- - Never renumber or reorder existing active PRD docs.
67
- - Preserve prior baseline text unless the user explicitly asks for a cleanup rewrite.
68
- - Update impacted baseline docs with `### Change Notes` blocks as defined in `docs/assets/references/prd-change-management.md`.
69
- - Update `docs/prd/03-open-questions-and-risk-register.md` directly for newly discovered or resolved gaps, drift, questions, decisions, and risks. Do not create a new `NN-` change doc solely to track register state.
70
- - Update `docs/prd/00-index.md` so the effective lineage remains readable.
71
-
72
- ## PRD Tree Rules
73
-
74
- ### Fixed core
75
-
76
- Always generate the fixed core first or reserve its numbers:
77
-
78
- - `00-index.md`
79
- - `01-product-overview.md`
80
- - `02-architecture-overview.md`
81
- - `03-open-questions-and-risk-register.md`
82
- - `04-glossary.md`
83
-
84
- ### Adaptive middle
85
-
86
- Use `05` through `99` for:
87
-
88
- - baseline subsystem docs
89
- - baseline reference docs
90
- - additive change docs
91
- - enhancement docs
92
- - revision docs
93
- - removal docs
94
-
95
- Prefer a flat PRD tree by default:
96
-
97
- ```text
98
- docs/prd/
99
- ├── 00-index.md
100
- ├── 01-product-overview.md
101
- ├── 02-architecture-overview.md
102
- ├── 03-open-questions-and-risk-register.md
103
- ├── 04-glossary.md
104
- ├── 05-payments.md
105
- ├── 06-notifications-reference.md
106
- ├── 07-enhance-notifications.md
107
- └── 08-revise-billing-retries.md
108
- ```
109
-
110
- Switch to a numbered subfolder only when one baseline subsystem is too large for one doc:
111
-
112
- ```text
113
- docs/prd/
114
- ├── 00-index.md
115
- ├── 01-product-overview.md
116
- ├── 02-architecture-overview.md
117
- ├── 03-open-questions-and-risk-register.md
118
- ├── 04-glossary.md
119
- ├── 05-backend/
120
- │ ├── 01-server-core.md
121
- │ ├── 02-handlers.md
122
- │ └── 03-stores.md
123
- ├── 06-frontend/
124
- │ ├── 01-app-framework.md
125
- │ └── 02-pages.md
126
- ├── 07-enhance-auth-recovery.md
127
- └── 08-remove-legacy-session-flow.md
128
- ```
129
-
130
- Do not place unnumbered Markdown files directly under `docs/prd/`. Do not place active PRD docs under `docs/assets/archive/prds/`.
131
-
132
- ## Section Contracts
133
-
134
- Use the matching template in `docs/assets/templates/` and preserve these required headings.
135
-
136
- | Doc type | Required headings |
137
- | --- | --- |
138
- | `prd-index.md` | `## Purpose`, `## Reading Order`, `## Document Map`, `## Source Anchors`, `## Audience Paths` |
139
- | `prd-overview.md` | `## Purpose`, `## Users`, `## Key Capabilities`, `## System Boundaries`, `## Current Limitations`, `## Source Anchors` |
140
- | `prd-architecture.md` | `## Purpose`, `## Topology`, `## Module Map`, `## Runtime Boundaries`, `## Data Flow`, `## Configuration Surfaces`, `## Source Anchors` |
141
- | `prd-risk-register.md` | `## Purpose`, `## Confirmed Drift`, `## Open Questions`, `## Rebuild Risks`, `## Source Anchors` |
142
- | `prd-glossary.md` | `## Purpose`, `## Terms`, `## Source Anchors` |
143
- | `prd-subsystem.md` | `## Purpose`, `## Scope`, `## Component and Capability Map`, `## Contracts and Data`, `## Integrations`, `## Rebuild Notes`, `## Source Anchors` |
144
- | `prd-reference.md` | `## Purpose`, `## Reference`, `## Source Anchors` |
145
- | `prd-change-addition.md` | `## Purpose`, `## Change Type`, `## Capability Addition or Enhancement`, `## Affected Baseline Docs`, `## Contracts and Data`, `## Integration Impact`, `## Required Baseline Annotations`, `## Source Anchors` |
146
- | `prd-change-revision.md` | `## Purpose`, `## Change Type`, `## Baseline Being Revised or Removed`, `## Rationale`, `## Effective Requirement`, `## Impacted Docs and Dependencies`, `## Required Baseline Annotations`, `## Source Anchors` |
147
- | `work-index.md` | `## Purpose`, `## Phase Map`, `## Usage Notes` |
148
- | `work-phase.md` | `## Purpose`, `## Overview`, `## Source PRD Docs`, repeatable `## Stage {{STAGE_NUMBER}} - {{STAGE_NAME}}` headings with `### Tasks`, `### Acceptance criteria`, and `### Dependencies` |
149
-
150
- Risk-register items under `## Confirmed Drift`, `## Open Questions`, and `## Rebuild Risks` use numbered `###` item headings with a `Status` / `Decision` / `Follow-Up` table. Use `D-001`, `D-002`, etc. for confirmed drift; `Q-001`, `Q-002`, etc. for open questions; and `R-001`, `R-002`, etc. for rebuild risks. Assign the next available number within the section and never renumber existing items, even when they move to `Closed`. Do not use `### Change Notes` inside the risk register; that heading remains for baseline PRD lineage only. Valid item statuses are `Open`, `Confirming`, `Deferred`, and `Closed`. Each item should include `Question` or `Issue`, `Why it matters`, `Recommendation`, and `To close`; include `Resolution` only for closed items.
151
-
152
- ## Work Phase Structure Rules
153
-
154
- Every work backlog is a directory, not a single file.
155
-
156
- - The work directory is `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`.
157
- - It contains an index file `00-index.md` with:
158
- - `## Purpose`
159
- - `## Phase Map`
160
- - `## Usage Notes`
161
- - It contains one or more phase files named `0N-<phase>.md`. Each phase file contains:
162
- - `## Purpose`
163
- - `## Overview`
164
- - `## Source PRD Docs`
165
- - one or more `## Stage {{STAGE_NUMBER}} - {{STAGE_NAME}}` sections
166
- - Each stage in a phase file contains:
167
- - `### Tasks`
168
- - `### Acceptance criteria`
169
- - `### Dependencies`
170
- - `### Tasks` items are markdown task list items with phase-local task IDs: `- [ ] t1: {{TASK}}` for open tasks and `- [x] t1: {{TASK}}` for completed tasks.
171
- - Task IDs start at `t1` in each phase file and increment across all stages in that file. Do not reset numbering in later stages and do not renumber existing task IDs when inserting or completing work.
172
- - `### Acceptance criteria` items are always plain unordered bullets (`- {{ACCEPTANCE}}`). Do not use checkbox syntax or `t{T}` labels in acceptance criteria.
173
-
174
- ## Code Anchor Rules
175
-
176
- ### General rule
177
-
178
- Every substantive PRD section should cite concrete repo paths in inline code. Prefer relative repo paths with optional line anchors. Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, relative Markdown links, sanitized placeholders, and full-path exceptions.
179
-
180
- Accepted examples:
181
-
182
- - `package.json`
183
- - `src/main.ts`
184
- - `src/server/router.ts:42`
185
- - `cmd/sensoroni.go:49`
186
- - `server/modules/modules.go`
187
-
188
- ### Practical rule
189
-
190
- Keep code anchors inside the section they support. Do not rely only on a final source list to justify claims made earlier in the document.
191
-
192
- ### Source anchors section
193
-
194
- Use `## Source Anchors` to aggregate the most important files that shaped the document. This section supplements, but does not replace, section-level anchors.
195
-
196
- ## Existing Documentation Rule
197
-
198
- - Supplement existing docs and cite them where useful.
199
- - Do not silently rewrite or replace existing documentation that already serves a different audience.
200
- - If docs and code disagree, treat the code as authoritative and record the disagreement in `03-open-questions-and-risk-register.md`.
201
- - Do not create separate questions, decisions, risks, gaps, or architecture-decision files when the active PRD risk register exists unless the user explicitly asks for a new convention.
202
- - If an older active PRD namespace exists in `docs/prd/` and the task is full-set generation, archive it as a set before writing the new active namespace.
203
- - If the task is active-set evolution, preserve baseline text and use non-destructive annotations unless the user explicitly asks for a cleanup rewrite.
204
-
205
- ## Work Backlog Rule
206
-
207
- - Keep work out of `docs/prd/`.
208
- - Every work backlog is a directory under `docs/work/` following the W/R naming pattern; link phase files back to the relevant PRD docs.
209
- - Organize phases and stages by dependency order, not by implementation convenience.
210
- - Include markdown task-list items and plain-bullet acceptance criteria in every stage.
211
- - Use phase-local task IDs (`t1`, `t2`, etc.) on task items so a task can be referenced externally as `w{W} r{R} p{P} t{T}`.
212
- - For active-set evolution work, use a dated delta work directory with a distinguishing slug (for example `...-<subject>-delta`) instead of rewriting a prior backlog.
213
- - Every phase file must include `## Source PRD Docs`.
214
-
215
- ## Link Rules
216
-
217
- - Use relative Markdown links between generated docs.
218
- - Apply `docs/assets/references/path-and-link-hygiene.md` when deciding whether an absolute path or sanitized placeholder is warranted.
219
- - Make sure every internal link resolves.
220
- - Use the PRD index and the work `00-index.md` as navigation entry points.
221
- - Archived PRD docs do not need to satisfy the active PRD link contract.
@@ -1,49 +0,0 @@
1
- # Path and Link Hygiene
2
-
3
- ## Purpose
4
-
5
- Use this reference when writing, reviewing, or repairing project documentation that mentions repository files, generated documentation links, local runtime paths, or diagnostic paths.
6
-
7
- Documentation should be portable across checkouts, machines, and users. Do not write local checkout paths into project documentation when a project-relative path communicates the same information.
8
-
9
- ## Project Path Rules
10
-
11
- - Use project-relative paths for files inside the repository.
12
- - Prefer paths such as `README.md`, `./README.md`, `docs/prd/00-index.md`, or `src/main.rs`.
13
- - Use relative Markdown links between project documents.
14
- - Do not include real checkout paths such as `/Users/<name>/projects/repo/README.md`, `/home/<name>/projects/repo/README.md`, `C:\Users\<name>\projects\repo\README.md`, or `/mnt/c/Users/<name>/projects/repo/README.md`.
15
- - Do not include machine-local temporary paths such as `/private/var/folders/<id>/...` or `/var/folders/<id>/...` unless they are necessary diagnostic evidence and are sanitized.
16
-
17
- ## Allowed Absolute Path Forms
18
-
19
- Absolute paths are allowed only when the path is not a repository file path or when the absolute location is the subject of the documentation. Examples include platform storage locations, external tool conventions, or diagnostic evidence that cannot be made relative.
20
-
21
- When an absolute path is warranted, prefer sanitized placeholders:
22
-
23
- - `<repo-root>/docs/prd/00-index.md`
24
- - `<user-home>/.config/pile/config.toml`
25
- - `$HOME/.local/share/pile`
26
- - `~/.pile/profiles/default.toml`
27
- - `%APPDATA%\pile\config.toml`
28
- - `<temp-dir>/runtime/trace.log`
29
-
30
- If a real absolute path must remain for a specific audit reason, add an inline allow comment on the same line or the previous line:
31
-
32
- ```markdown
33
- <!-- make-docs-path-hygiene: allow retained diagnostic evidence from user-provided log -->
34
- ```
35
-
36
- Use the allow comment sparingly. The reason must explain why a project-relative path or sanitized placeholder would lose necessary evidence.
37
-
38
- ## Repair Policy
39
-
40
- - Convert paths under the current repository root to project-relative paths.
41
- - In Markdown link destinations, use plain relative destinations such as `docs/prd/00-index.md`.
42
- - In inline code or prose path literals, use `./docs/prd/00-index.md` when the leading `./` helps signal repository-relative intent.
43
- - Convert user-home examples to placeholders such as `<user-home>`, `$HOME`, or `~` when the exact username is not meaningful.
44
- - Convert temporary path examples to `<temp-dir>/...` when the exact machine-local path is not meaningful.
45
- - Preserve absolute paths only when they describe external behavior or required evidence, and document the exception with the allow comment.
46
-
47
- ## Validation
48
-
49
- Use `.make-docs/scripts/check_path_hygiene.py` to audit Make Docs-managed documentation. The script reports real checkout paths, user-home paths, local temporary paths, and absolute local Markdown links. Run it before finalizing broad documentation updates or when repairing path hygiene drift.
@@ -1,160 +0,0 @@
1
- # Planning Workflow
2
-
3
- See `docs/assets/references/wave-model.md` for W/R semantics and resolution rules.
4
-
5
- ## Purpose
6
-
7
- Use this workflow to produce a reviewable plan before generating or evolving PRD documentation. Planning mode exists to lock the output structure, workstream boundaries, and validation approach before the repo is mutated.
8
-
9
- This workflow supports three planning modes:
10
-
11
- 1. baseline PRD generation from a new idea or design
12
- 2. decomposition of an existing codebase into a fresh PRD set
13
- 3. active-set evolution through additive change, enhancement, revision, or removal
14
-
15
- ## Preflight
16
-
17
- Inspect:
18
-
19
- - the repo root and current documentation tree
20
- - any referenced design docs and whether they include `## Intended Follow-On`
21
- - any `Coordinate Handoff` or source-lineage notes in referenced designs
22
- - any existing plans, PRD docs, and work backlogs
23
- - any history records for prior phases that the request revises, reworks, corrects, standardizes, or finishes
24
- - whether `docs/prd/` already contains active content (archives live under `docs/assets/archive/prds/YYYY-MM-DD/`)
25
- - whether the user request is best classified as baseline generation, decomposition, or active-set evolution
26
-
27
- If a referenced design doc includes `## Intended Follow-On`, treat that route as authoritative unless the user explicitly overrides it.
28
-
29
- Resolve the W/R coordinate using `docs/assets/references/wave-model.md` before writing. Explicit user guidance and source lineage from designs, prior plans, prior work backlogs, and history records take precedence over the highest existing wave. If source lineage points to an earlier wave but later unrelated waves exist, keep the lineage wave and increment its revision.
30
-
31
- If the request is ambiguous, infer the likely mode from the repo, prompt, and explicit design handoff. Ask the user only when the ambiguity materially changes the output shape.
32
-
33
- ## Planning Goals
34
-
35
- Produce a plan that makes the execution step decision-complete. The plan should settle:
36
-
37
- - the execution mode
38
- - the doc tree shape
39
- - the fixed core docs plus adaptive docs or change docs
40
- - whether execution requires an archive gate or an active-set evolution path
41
- - the delegation tier and workstream split
42
- - the coordinator role and write scope
43
- - the backlog placement under `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/`
44
- - the validation pass and any follow-up review
45
-
46
- For active-set evolution, the plan should also settle:
47
-
48
- - the change taxonomy (`addition`, `enhancement`, `revision`, `removal`)
49
- - the impacted baseline docs
50
- - the new numbered change docs that will be created
51
- - the `### Change Notes` backlinks required in existing PRD docs
52
- - whether a scoped delta backlog is sufficient or the user explicitly wants a regenerated full backlog
53
-
54
- ## User Preference Questions
55
-
56
- Ask the user only when the answer affects the output shape or execution style. Typical planning questions include:
57
-
58
- - whether a large subsystem should split into a numbered folder
59
- - whether reference-style docs should stay separate from subsystem docs
60
- - whether a change should stay a scoped delta or force a wider PRD rewrite
61
- - whether the user explicitly wants a cleanup rewrite of baseline PRD text instead of the default non-destructive annotations
62
- - whether the backlog directory should be scoped to a delta or regenerated as a full backlog
63
- - whether the user explicitly wants to forbid delegation and force single-agent execution despite the default
64
-
65
- Do not ask questions that can be answered by repo inspection. Do not ask the user which planning route to use when the referenced design docs already declare `## Intended Follow-On`, unless the user is explicitly reconsidering that route.
66
-
67
- ## Plan Structure
68
-
69
- Plans are always directories. The chosen template describes the shape of the `00-overview.md` entry point inside the plan directory, plus the referenced `0N-<phase>.md` files.
70
-
71
- Start from the relevant template in `docs/assets/templates/`:
72
-
73
- - `plan-prd.md` for baseline PRD generation from a new idea or design
74
- - `plan-prd-decompose.md` for reverse-engineering an existing codebase into a fresh PRD set
75
- - `plan-prd-change.md` for additive changes, enhancements, revisions, or removals within the active PRD namespace
76
-
77
- Every plan should cover:
78
-
79
- - coordinate decision, including whether the plan is a new wave or a revision and the evidence used
80
- - repo summary
81
- - output contract
82
- - execution mode and PRD lifecycle handling
83
- - coordinator policy and delegation tier
84
- - planned document catalog
85
- - worker ownership, write scopes, and dependencies
86
- - MCP strategy and fallback strategy
87
- - validation and review steps
88
-
89
- Change plans should additionally cover:
90
-
91
- - the change classification
92
- - impacted baseline docs
93
- - new change docs to be created
94
- - required baseline annotations
95
- - delta backlog scope
96
-
97
- ## File Writing Rule
98
-
99
- Planning mode should present the plan in chat first.
100
-
101
- Plans are always directories. Write only after approval, using the matching path:
102
-
103
- - baseline or decomposition plan: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` (with `00-overview.md` as the entry point and `0N-<phase>.md` files for each phase)
104
- - change plan: same directory pattern — `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` — using a slug that signals the change intent (for example, `...-notifications-enhancement`). Do not hard-code a `-change-plan` suffix.
105
-
106
- ## Approval Prompt Rule
107
-
108
- After presenting the plan, separate the two user decisions:
109
-
110
- - whether to save the plan file
111
- - whether to start execution now
112
-
113
- Do not imply that approving the plan automatically authorizes execution. If the user approves the plan without explicitly choosing execution, default to saving the plan only and stop.
114
-
115
- ## Workstream Rules
116
-
117
- - Design workstreams to be delegation-ready first, not single-agent first.
118
- - For context-heavy repos, prefer using the same delegation ladder during planning if the harness supports it: parallel agents, then subagents, then single-agent fallback.
119
- - If delegation is available, the coordinator write scope is `none`.
120
- - Assign every output-writing task to a worker, including shared docs such as `docs/prd/00-index.md`, `docs/prd/03-open-questions-and-risk-register.md`, `docs/prd/04-glossary.md`, and the backlog.
121
- - Reserve a dedicated assembly worker for shared docs and a dedicated validation or fix worker for contract cleanup when the harness can support them.
122
- - Describe workstreams, dependencies, and merge order.
123
- - Do not hard-code Agent A, Agent B, or panel-specific assignments in the saved plan.
124
- - Keep scopes disjoint so an execution harness can parallelize safely.
125
- - The coordinator should never appear as the owner of document-writing tasks when delegation is available.
126
-
127
- For active-set evolution:
128
-
129
- - keep change-doc authoring, baseline annotations, index updates, and delta backlog generation as separate write scopes whenever practical
130
- - route cross-doc status updates and backlink validation to assembly or validation workers rather than the coordinator
131
-
132
- ## Flat Vs Nested Decision
133
-
134
- Use a flat PRD tree when:
135
-
136
- - the repo is small or medium
137
- - the subsystem count is manageable
138
- - one file per subsystem remains readable
139
- - change docs can be appended cleanly without creating navigation debt
140
-
141
- Use a numbered subfolder when:
142
-
143
- - a subsystem would become too large for one doc
144
- - the repo has strong backend or frontend or service or domain boundaries
145
- - a deep subsystem needs multiple docs but still needs one top-level number
146
-
147
- ## Handoff To Execution
148
-
149
- Before leaving planning mode, make the execution prerequisites explicit:
150
-
151
- - approved plan exists
152
- - the user has not necessarily approved execution yet
153
- - MCP availability has been confirmed or fallback is accepted
154
- - target output paths are fixed
155
- - execution should use the delegation ladder by default: parallel agents, then subagents, then single-agent fallback
156
- - if delegation is available, the coordinator write scope is `none`
157
- - if the task is full-set replacement and `docs/prd/` already has active content, archival approval is required before execution can write the new PRD set
158
- - if the task is active-set evolution, the plan names the new change docs, impacted baseline docs, annotation targets, and delta backlog scope
159
- - workstreams are disjoint
160
- - validation is mandatory