@brucewaynedecoy/make-docs 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +93 -0
  3. package/dist/chunk-HP3HBG7F.js +626 -0
  4. package/dist/chunk-HP3HBG7F.js.map +1 -0
  5. package/dist/chunk-QRFH4J6H.js +1194 -0
  6. package/dist/chunk-QRFH4J6H.js.map +1 -0
  7. package/dist/chunk-WM3OXYTW.js +2630 -0
  8. package/dist/chunk-WM3OXYTW.js.map +1 -0
  9. package/dist/index.js +1720 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/skills-command-3ESCZ75U.js +547 -0
  12. package/dist/skills-command-3ESCZ75U.js.map +1 -0
  13. package/dist/uninstall-GQE4SJF2.js +150 -0
  14. package/dist/uninstall-GQE4SJF2.js.map +1 -0
  15. package/package.json +49 -0
  16. package/skill-registry.json +276 -0
  17. package/skill-registry.schema.json +64 -0
  18. package/template/.make-docs/scripts/check_path_hygiene.py +435 -0
  19. package/template/AGENTS.md +3 -0
  20. package/template/CLAUDE.md +3 -0
  21. package/template/docs/AGENTS.md +15 -0
  22. package/template/docs/CLAUDE.md +15 -0
  23. package/template/docs/assets/AGENTS.md +9 -0
  24. package/template/docs/assets/CLAUDE.md +9 -0
  25. package/template/docs/assets/archive/AGENTS.md +20 -0
  26. package/template/docs/assets/archive/CLAUDE.md +20 -0
  27. package/template/docs/assets/history/AGENTS.md +12 -0
  28. package/template/docs/assets/history/CLAUDE.md +12 -0
  29. package/template/docs/assets/prompts/AGENTS.md +8 -0
  30. package/template/docs/assets/prompts/CLAUDE.md +8 -0
  31. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +14 -0
  32. package/template/docs/assets/prompts/designs-to-plan.prompt.md +10 -0
  33. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +27 -0
  34. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +8 -0
  35. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +6 -0
  36. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +10 -0
  37. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +6 -0
  38. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +6 -0
  39. package/template/docs/assets/prompts/request-to-design.prompt.md +16 -0
  40. package/template/docs/assets/prompts/session-to-history-record.prompt.md +19 -0
  41. package/template/docs/assets/prompts/update-readme-green-field.prompt.md +6 -0
  42. package/template/docs/assets/prompts/work-to-commit-message.prompt.md +27 -0
  43. package/template/docs/assets/prompts/work-to-guides.prompt.md +18 -0
  44. package/template/docs/assets/references/AGENTS.md +9 -0
  45. package/template/docs/assets/references/CLAUDE.md +9 -0
  46. package/template/docs/assets/references/commit-message-convention.md +198 -0
  47. package/template/docs/assets/references/design-contract.md +62 -0
  48. package/template/docs/assets/references/design-workflow.md +60 -0
  49. package/template/docs/assets/references/execution-workflow.md +157 -0
  50. package/template/docs/assets/references/guide-contract.md +159 -0
  51. package/template/docs/assets/references/harness-capability-matrix.md +52 -0
  52. package/template/docs/assets/references/history-record-contract.md +137 -0
  53. package/template/docs/assets/references/output-contract.md +221 -0
  54. package/template/docs/assets/references/path-and-link-hygiene.md +49 -0
  55. package/template/docs/assets/references/planning-workflow.md +160 -0
  56. package/template/docs/assets/references/prd-change-management.md +129 -0
  57. package/template/docs/assets/references/wave-model.md +76 -0
  58. package/template/docs/assets/templates/AGENTS.md +8 -0
  59. package/template/docs/assets/templates/CLAUDE.md +8 -0
  60. package/template/docs/assets/templates/design.md +30 -0
  61. package/template/docs/assets/templates/guide-developer.md +54 -0
  62. package/template/docs/assets/templates/guide-user.md +58 -0
  63. package/template/docs/assets/templates/history-record.md +62 -0
  64. package/template/docs/assets/templates/plan-overview.md +32 -0
  65. package/template/docs/assets/templates/plan-prd-change.md +99 -0
  66. package/template/docs/assets/templates/plan-prd-decompose.md +70 -0
  67. package/template/docs/assets/templates/plan-prd.md +124 -0
  68. package/template/docs/assets/templates/prd-architecture.md +51 -0
  69. package/template/docs/assets/templates/prd-change-addition.md +45 -0
  70. package/template/docs/assets/templates/prd-change-revision.md +45 -0
  71. package/template/docs/assets/templates/prd-glossary.md +15 -0
  72. package/template/docs/assets/templates/prd-index.md +45 -0
  73. package/template/docs/assets/templates/prd-overview.md +43 -0
  74. package/template/docs/assets/templates/prd-reference.md +17 -0
  75. package/template/docs/assets/templates/prd-risk-register.md +55 -0
  76. package/template/docs/assets/templates/prd-subsystem.md +49 -0
  77. package/template/docs/assets/templates/work-index.md +21 -0
  78. package/template/docs/assets/templates/work-phase.md +34 -0
  79. package/template/docs/designs/AGENTS.md +21 -0
  80. package/template/docs/designs/CLAUDE.md +21 -0
  81. package/template/docs/guides/AGENTS.md +15 -0
  82. package/template/docs/guides/CLAUDE.md +15 -0
  83. package/template/docs/plans/AGENTS.md +20 -0
  84. package/template/docs/plans/CLAUDE.md +20 -0
  85. package/template/docs/prd/AGENTS.md +9 -0
  86. package/template/docs/prd/CLAUDE.md +9 -0
  87. package/template/docs/work/AGENTS.md +18 -0
  88. package/template/docs/work/CLAUDE.md +18 -0
@@ -0,0 +1,99 @@
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
@@ -0,0 +1,70 @@
1
+ # Codebase Decomposition 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 reverse-engineering the repository into a structured PRD set and rebuild backlog.
10
+
11
+ ## Objective
12
+
13
+ State what the decomposition should preserve, 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
+ ## Output Contract
22
+
23
+ - Plan directory: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/`
24
+ - entry point: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/00-overview.md`
25
+ - phase files: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/0N-<phase>.md`
26
+ - PRD core:
27
+ - `docs/prd/00-index.md`
28
+ - `docs/prd/01-product-overview.md`
29
+ - `docs/prd/02-architecture-overview.md`
30
+ - `docs/prd/03-open-questions-and-risk-register.md`
31
+ - `docs/prd/04-glossary.md`
32
+ - adaptive numbered subsystem/reference docs starting at `05-*`
33
+ - Rebuild work:
34
+ - `docs/work/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/`
35
+
36
+ ## Existing PRD Handling
37
+
38
+ - Active `docs/prd/` status: {{ACTIVE_PRD_STATUS}}
39
+ - Archive step required before execution: {{ARCHIVE_REQUIRED}}
40
+ - Planned archive target if approved: `{{ARCHIVE_TARGET}}`
41
+ - Active root entries to archive: {{ARCHIVE_ENTRIES}}
42
+
43
+ ## Coordinator Policy
44
+
45
+ - Highest intended delegation tier: {{DELEGATION_TIER}}
46
+ - Coordinator role: `coordination only`
47
+ - Coordinator write scope: `none` when delegation is available
48
+ - Coordinator responsibilities: preflight, approvals, routing, worker spawning, progress tracking, blocker handling, final status reporting
49
+
50
+ ## Proposed Catalog
51
+
52
+ List the fixed core docs plus adaptive docs and explain whether the tree should stay flat or use numbered subfolders.
53
+
54
+ ## Worker Ownership
55
+
56
+ List the delegated workers, their scopes, write scopes, dependencies, and deliverables.
57
+
58
+ - Assign every output-writing task to a worker when delegation is available.
59
+ - Include a dedicated shared-doc assembly worker for `docs/prd/00-index.md`, `docs/prd/03-open-questions-and-risk-register.md`, `docs/prd/04-glossary.md`, and the rebuild backlog.
60
+ - Include a dedicated validation/fix worker when the harness can support it.
61
+ - The coordinator should not appear as the owner of any document-writing task when delegation is available.
62
+
63
+ ## MCP Strategy
64
+
65
+ - Preferred servers available: {{MCP_STATUS}}
66
+ - Fallback plan if unavailable: {{FALLBACK_PLAN}}
67
+
68
+ ## Validation
69
+
70
+ Explain how the execution step will validate the generated outputs and which review pass happens at the end.
@@ -0,0 +1,124 @@
1
+ # PRD Generation 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 translating a new idea or design into a structured PRD set and implementation backlog.
10
+
11
+ ## Objective
12
+
13
+ State what the PRD set should capture, who the outputs are for, and what counts as completion. Identify whether the target is a greenfield project or an addition to an existing codebase.
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
+ ## Design Inputs
22
+
23
+ List every source of truth that feeds into PRD generation. Each entry should note its format, location, and confidence level (authoritative, draft, exploratory).
24
+
25
+ | Input | Format | Location | Confidence |
26
+ | ----- | ------ | -------- | ---------- |
27
+ | {{INPUT_NAME}} | {{FORMAT}} | {{LOCATION}} | {{CONFIDENCE}} |
28
+
29
+ Open questions or ambiguities in the inputs should be captured here and promoted into `03-open-questions-and-risk-register.md` during execution.
30
+
31
+ ## Existing Codebase Context
32
+
33
+ - Codebase status: {{CODEBASE_STATUS}} <!-- greenfield | existing-active | existing-legacy -->
34
+ - Integration constraints: {{INTEGRATION_CONSTRAINTS}} <!-- e.g., must use existing auth module, must preserve current API surface -->
35
+ - Discovery pass required: {{DISCOVERY_REQUIRED}} <!-- yes | no — whether workers need to audit existing code before writing PRDs -->
36
+ - Discovery scope if required: {{DISCOVERY_SCOPE}}
37
+
38
+ ## Output Contract
39
+
40
+ - Plan directory: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/`
41
+ - entry point: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/00-overview.md`
42
+ - phase files: `docs/plans/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/0N-<phase>.md`
43
+ - PRD core:
44
+ - `docs/prd/00-index.md`
45
+ - `docs/prd/01-product-overview.md`
46
+ - `docs/prd/02-architecture-overview.md`
47
+ - `docs/prd/03-open-questions-and-risk-register.md`
48
+ - `docs/prd/04-glossary.md`
49
+ - adaptive numbered feature/subsystem docs starting at `05-*`
50
+ - Implementation work:
51
+ - `docs/work/{{DATE}}-w{{W}}-r{{R}}-{{SLUG}}/`
52
+
53
+ ## Existing PRD Handling
54
+
55
+ - Active `docs/prd/` status: {{ACTIVE_PRD_STATUS}}
56
+ - Archive step required before execution: {{ARCHIVE_REQUIRED}}
57
+ - Planned archive target if approved: `{{ARCHIVE_TARGET}}`
58
+ - Active root entries to archive: {{ARCHIVE_ENTRIES}}
59
+
60
+ ## Coordinator Policy
61
+
62
+ - Highest intended delegation tier: {{DELEGATION_TIER}}
63
+ - Coordinator role: `coordination only`
64
+ - Coordinator write scope: `none` when delegation is available
65
+ - Coordinator responsibilities: preflight, approvals, routing, worker spawning, progress tracking, blocker handling, final status reporting
66
+
67
+ ## Scope & Phasing
68
+
69
+ Describe how the idea should be decomposed into implementable phases. Each phase should be self-contained enough to ship or validate independently.
70
+
71
+ - Phasing strategy: {{PHASING_STRATEGY}} <!-- single-phase | incremental | mvp-then-iterate -->
72
+ - Phase boundaries driven by: {{PHASE_DRIVERS}} <!-- user value | technical dependency | risk reduction | stakeholder milestones -->
73
+
74
+ If phases are known at plan time, list them:
75
+
76
+ | Phase | Summary | Key Deliverables | Dependencies |
77
+ | ----- | ------- | ---------------- | ------------ |
78
+ | {{PHASE_ID}} | {{SUMMARY}} | {{DELIVERABLES}} | {{DEPENDENCIES}} |
79
+
80
+ If phases are not yet known, note that a scoping worker should derive them from the design inputs before feature PRD writing begins.
81
+
82
+ ## Proposed Catalog
83
+
84
+ List the fixed core docs plus the adaptive feature/subsystem docs anticipated from the design inputs. Explain whether the tree should stay flat or use numbered subfolders.
85
+
86
+ Core docs are always produced. Adaptive docs should map to distinct features, subsystems, or integration surfaces identified in the design inputs. Each adaptive doc should be scoped narrowly enough that a single worker can own it.
87
+
88
+ ## Worker Ownership
89
+
90
+ List the delegated workers, their scopes, write scopes, dependencies, and deliverables.
91
+
92
+ - Assign every output-writing task to a worker when delegation is available.
93
+ - Include a scoping/discovery worker if the existing codebase requires audit before PRD writing.
94
+ - Include a dedicated shared-doc assembly worker for `docs/prd/00-index.md`, `docs/prd/03-open-questions-and-risk-register.md`, `docs/prd/04-glossary.md`, and the implementation backlog.
95
+ - Include a dedicated validation/fix worker when the harness can support it.
96
+ - The coordinator should not appear as the owner of any document-writing task when delegation is available.
97
+
98
+ | Worker | Scope | Write Scope | Dependencies | Deliverables |
99
+ | ------ | ----- | ----------- | ------------ | ------------ |
100
+ | {{WORKER_NAME}} | {{SCOPE}} | {{WRITE_SCOPE}} | {{DEPENDENCIES}} | {{DELIVERABLES}} |
101
+
102
+ ## MCP Strategy
103
+
104
+ - Preferred servers available: {{MCP_STATUS}}
105
+ - Fallback plan if unavailable: {{FALLBACK_PLAN}}
106
+
107
+ ## Acceptance Criteria Guidance
108
+
109
+ Describe how workers should derive acceptance criteria within each PRD. Criteria should be traceable back to design inputs and testable at implementation time.
110
+
111
+ - Criteria style: {{CRITERIA_STYLE}} <!-- given-when-then | checklist | user-story-driven -->
112
+ - Non-functional requirements to address in every feature PRD: {{NFR_CHECKLIST}} <!-- e.g., performance, accessibility, security, observability -->
113
+
114
+ ## Validation
115
+
116
+ Explain how the execution step will validate the generated outputs. Validation should confirm:
117
+
118
+ - Every design input is accounted for in at least one PRD.
119
+ - Every adaptive PRD traces back to a design input or a discovered integration need.
120
+ - The implementation backlog covers all PRDs with no orphaned or unreachable items.
121
+ - Open questions are captured and none block backlog generation without explicit acknowledgment.
122
+ - Cross-references between docs are consistent and resolvable.
123
+
124
+ Describe which review pass happens at the end and who approves the final output set.
@@ -0,0 +1,51 @@
1
+ # 02 Architecture Overview
2
+
3
+ ## Purpose
4
+
5
+ Explain how the system is shaped end to end.
6
+
7
+ ## Topology
8
+
9
+ Describe the main runtime surfaces, services, processes, or deployment shape.
10
+
11
+ Code anchors:
12
+
13
+ - `{{TOPOLOGY_PATHS}}`
14
+
15
+ ## Module Map
16
+
17
+ Describe the major modules, packages, apps, or directories and what each one owns.
18
+
19
+ Code anchors:
20
+
21
+ - `{{MODULE_MAP_PATHS}}`
22
+
23
+ ## Runtime Boundaries
24
+
25
+ Explain browser/server, service/service, or process/module boundaries and their responsibilities.
26
+
27
+ Code anchors:
28
+
29
+ - `{{BOUNDARY_PATHS}}`
30
+
31
+ ## Data Flow
32
+
33
+ Describe the important end-to-end flows that connect the system together.
34
+
35
+ Code anchors:
36
+
37
+ - `{{FLOW_PATHS}}`
38
+
39
+ ## Configuration Surfaces
40
+
41
+ Explain manifests, environment variables, config files, and operational switches that materially affect behavior.
42
+
43
+ Code anchors:
44
+
45
+ - `{{CONFIG_PATHS}}`
46
+
47
+ ## Source Anchors
48
+
49
+ - `{{ENTRYPOINTS}}`
50
+ - `{{MAIN_CONFIGS}}`
51
+ - `{{MAIN_RUNTIME_FILES}}`
@@ -0,0 +1,45 @@
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}}`
@@ -0,0 +1,45 @@
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}}`
@@ -0,0 +1,15 @@
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}}`
@@ -0,0 +1,45 @@
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.
@@ -0,0 +1,43 @@
1
+ # 01 Product Overview
2
+
3
+ ## Purpose
4
+
5
+ Explain what the product or repository does and why it exists.
6
+
7
+ ## Users
8
+
9
+ Describe the primary users, operators, or internal audiences.
10
+
11
+ Code anchors:
12
+
13
+ - `{{USER_SURFACE_PATHS}}`
14
+
15
+ ## Key Capabilities
16
+
17
+ Describe the main product capabilities in plain English.
18
+
19
+ Code anchors:
20
+
21
+ - `{{CAPABILITY_PATHS}}`
22
+
23
+ ## System Boundaries
24
+
25
+ Explain what is in scope for this repo and where it depends on external systems or sibling services.
26
+
27
+ Code anchors:
28
+
29
+ - `{{BOUNDARY_PATHS}}`
30
+
31
+ ## Current Limitations
32
+
33
+ Explain the most important known limits, omissions, or non-goals visible in the current implementation.
34
+
35
+ Code anchors:
36
+
37
+ - `{{LIMITATION_PATHS}}`
38
+
39
+ ## Source Anchors
40
+
41
+ - `README.md`
42
+ - `{{PRIMARY_MANIFESTS}}`
43
+ - `{{ENTRYPOINTS}}`
@@ -0,0 +1,17 @@
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}}`
@@ -0,0 +1,55 @@
1
+ # 03 Open Questions and Risk Register
2
+
3
+ ## Purpose
4
+
5
+ Capture drift, ambiguities, unresolved behavior, decisions, and rebuild risks that should remain visible instead of being buried inside subsystem docs.
6
+
7
+ Use this as the active PRD namespace's living register. When agents discover or resolve gaps, drift, open questions, risks, decisions, or closeout findings, update this document directly instead of creating a separate questions, decisions, risks, gaps, or architecture-decision file unless the user explicitly asks.
8
+
9
+ Each item under `## Confirmed Drift`, `## Open Questions`, and `## Rebuild Risks` should use one numbered `###` heading, a state table, and the body fields below. 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`. Assign the next available number inside the section and never renumber existing items, even when an item moves to `Closed`. Use `Open`, `Confirming`, `Deferred`, or `Closed` for `Status`. Add `Resolution` only when the item is closed.
10
+
11
+ Do not use `### Change Notes` inside this register. `### Change Notes` remains valid in baseline PRD docs for active-set evolution lineage, but the risk register tracks lineage through item IDs, `Decision`, `Follow-Up`, `Recommendation`, `To close`, and optional `Resolution`.
12
+
13
+ ```markdown
14
+ ### D-001 <Gap, Question, Drift, or Risk Title>
15
+
16
+ | Status | Decision | Follow-Up |
17
+ | --- | --- | --- |
18
+ | Open | None yet | <next action or owner/path> |
19
+
20
+ **Question** or **Issue**: <what needs to be answered, corrected, or tracked>
21
+
22
+ **Why it matters**: <impact on rebuild, maintenance, users, release, or future work>
23
+
24
+ **Recommendation**: <current recommendation or "None yet">
25
+
26
+ **To close**: <evidence, decision, or implementation needed to close the item>
27
+ ```
28
+
29
+ ## Confirmed Drift
30
+
31
+ List code-versus-doc or code-versus-behavior mismatches that are verified.
32
+
33
+ Code anchors:
34
+
35
+ - `{{DRIFT_PATHS}}`
36
+
37
+ ## Open Questions
38
+
39
+ List unanswered questions and unresolved decisions that matter for a faithful rebuild or future maintenance.
40
+
41
+ Code anchors:
42
+
43
+ - `{{QUESTION_PATHS}}`
44
+
45
+ ## Rebuild Risks
46
+
47
+ List the places where a clean-room rebuild is likely to go wrong without careful constraints.
48
+
49
+ Code anchors:
50
+
51
+ - `{{RISK_PATHS}}`
52
+
53
+ ## Source Anchors
54
+
55
+ - `{{PRIMARY_FILES}}`
@@ -0,0 +1,49 @@
1
+ # {{NUMBER}} {{TITLE}}
2
+
3
+ ## Purpose
4
+
5
+ Explain what this subsystem owns and why it exists.
6
+
7
+ ## Scope
8
+
9
+ Explain what is covered here and what is intentionally covered elsewhere.
10
+
11
+ Code anchors:
12
+
13
+ - `{{SCOPE_PATHS}}`
14
+
15
+ ## Component and Capability Map
16
+
17
+ Describe the subsystem's components, modules, or pages and the capabilities they implement.
18
+
19
+ Code anchors:
20
+
21
+ - `{{COMPONENT_PATHS}}`
22
+
23
+ ## Contracts and Data
24
+
25
+ Describe the important data models, API contracts, events, storage shapes, or configuration surfaces.
26
+
27
+ Code anchors:
28
+
29
+ - `{{CONTRACT_PATHS}}`
30
+
31
+ ## Integrations
32
+
33
+ Describe external dependencies, sibling modules, or cross-cutting connections.
34
+
35
+ Code anchors:
36
+
37
+ - `{{INTEGRATION_PATHS}}`
38
+
39
+ ## Rebuild Notes
40
+
41
+ Explain what a clean-room rebuild would need to preserve and where future implementers are likely to make mistakes.
42
+
43
+ Code anchors:
44
+
45
+ - `{{REBUILD_PATHS}}`
46
+
47
+ ## Source Anchors
48
+
49
+ - `{{PRIMARY_FILES}}`