@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.
- package/LICENSE +201 -0
- package/README.md +93 -0
- package/dist/chunk-HP3HBG7F.js +626 -0
- package/dist/chunk-HP3HBG7F.js.map +1 -0
- package/dist/chunk-QRFH4J6H.js +1194 -0
- package/dist/chunk-QRFH4J6H.js.map +1 -0
- package/dist/chunk-WM3OXYTW.js +2630 -0
- package/dist/chunk-WM3OXYTW.js.map +1 -0
- package/dist/index.js +1720 -0
- package/dist/index.js.map +1 -0
- package/dist/skills-command-3ESCZ75U.js +547 -0
- package/dist/skills-command-3ESCZ75U.js.map +1 -0
- package/dist/uninstall-GQE4SJF2.js +150 -0
- package/dist/uninstall-GQE4SJF2.js.map +1 -0
- package/package.json +49 -0
- package/skill-registry.json +276 -0
- package/skill-registry.schema.json +64 -0
- package/template/.make-docs/scripts/check_path_hygiene.py +435 -0
- package/template/AGENTS.md +3 -0
- package/template/CLAUDE.md +3 -0
- package/template/docs/AGENTS.md +15 -0
- package/template/docs/CLAUDE.md +15 -0
- package/template/docs/assets/AGENTS.md +9 -0
- package/template/docs/assets/CLAUDE.md +9 -0
- package/template/docs/assets/archive/AGENTS.md +20 -0
- package/template/docs/assets/archive/CLAUDE.md +20 -0
- package/template/docs/assets/history/AGENTS.md +12 -0
- package/template/docs/assets/history/CLAUDE.md +12 -0
- package/template/docs/assets/prompts/AGENTS.md +8 -0
- package/template/docs/assets/prompts/CLAUDE.md +8 -0
- package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +14 -0
- package/template/docs/assets/prompts/designs-to-plan.prompt.md +10 -0
- package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +27 -0
- package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +8 -0
- package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +6 -0
- package/template/docs/assets/prompts/prd-change-to-work.prompt.md +10 -0
- package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +6 -0
- package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +6 -0
- package/template/docs/assets/prompts/request-to-design.prompt.md +16 -0
- package/template/docs/assets/prompts/session-to-history-record.prompt.md +19 -0
- package/template/docs/assets/prompts/update-readme-green-field.prompt.md +6 -0
- package/template/docs/assets/prompts/work-to-commit-message.prompt.md +27 -0
- package/template/docs/assets/prompts/work-to-guides.prompt.md +18 -0
- package/template/docs/assets/references/AGENTS.md +9 -0
- package/template/docs/assets/references/CLAUDE.md +9 -0
- package/template/docs/assets/references/commit-message-convention.md +198 -0
- package/template/docs/assets/references/design-contract.md +62 -0
- package/template/docs/assets/references/design-workflow.md +60 -0
- package/template/docs/assets/references/execution-workflow.md +157 -0
- package/template/docs/assets/references/guide-contract.md +159 -0
- package/template/docs/assets/references/harness-capability-matrix.md +52 -0
- package/template/docs/assets/references/history-record-contract.md +137 -0
- package/template/docs/assets/references/output-contract.md +221 -0
- package/template/docs/assets/references/path-and-link-hygiene.md +49 -0
- package/template/docs/assets/references/planning-workflow.md +160 -0
- package/template/docs/assets/references/prd-change-management.md +129 -0
- package/template/docs/assets/references/wave-model.md +76 -0
- package/template/docs/assets/templates/AGENTS.md +8 -0
- package/template/docs/assets/templates/CLAUDE.md +8 -0
- package/template/docs/assets/templates/design.md +30 -0
- package/template/docs/assets/templates/guide-developer.md +54 -0
- package/template/docs/assets/templates/guide-user.md +58 -0
- package/template/docs/assets/templates/history-record.md +62 -0
- package/template/docs/assets/templates/plan-overview.md +32 -0
- package/template/docs/assets/templates/plan-prd-change.md +99 -0
- package/template/docs/assets/templates/plan-prd-decompose.md +70 -0
- package/template/docs/assets/templates/plan-prd.md +124 -0
- package/template/docs/assets/templates/prd-architecture.md +51 -0
- package/template/docs/assets/templates/prd-change-addition.md +45 -0
- package/template/docs/assets/templates/prd-change-revision.md +45 -0
- package/template/docs/assets/templates/prd-glossary.md +15 -0
- package/template/docs/assets/templates/prd-index.md +45 -0
- package/template/docs/assets/templates/prd-overview.md +43 -0
- package/template/docs/assets/templates/prd-reference.md +17 -0
- package/template/docs/assets/templates/prd-risk-register.md +55 -0
- package/template/docs/assets/templates/prd-subsystem.md +49 -0
- package/template/docs/assets/templates/work-index.md +21 -0
- package/template/docs/assets/templates/work-phase.md +34 -0
- package/template/docs/designs/AGENTS.md +21 -0
- package/template/docs/designs/CLAUDE.md +21 -0
- package/template/docs/guides/AGENTS.md +15 -0
- package/template/docs/guides/CLAUDE.md +15 -0
- package/template/docs/plans/AGENTS.md +20 -0
- package/template/docs/plans/CLAUDE.md +20 -0
- package/template/docs/prd/AGENTS.md +9 -0
- package/template/docs/prd/CLAUDE.md +9 -0
- package/template/docs/work/AGENTS.md +18 -0
- 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}}`
|