@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,160 @@
|
|
|
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
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# PRD Change Management
|
|
2
|
+
|
|
3
|
+
Archive layout is authoritative in `docs/assets/archive/AGENTS.md`.
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
Use this reference when `docs/prd/` already contains an active PRD namespace and the user wants to evolve it without replacing the whole set.
|
|
8
|
+
|
|
9
|
+
This workflow covers:
|
|
10
|
+
|
|
11
|
+
- net-new capability additions
|
|
12
|
+
- enhancements to existing capabilities
|
|
13
|
+
- revisions to established requirements
|
|
14
|
+
- deprecations or removals of established requirements
|
|
15
|
+
- direct updates to the living risk register for newly discovered or resolved gaps, drift, open questions, decisions, and risks
|
|
16
|
+
|
|
17
|
+
## Change Taxonomy
|
|
18
|
+
|
|
19
|
+
| Change type | Meaning | Template | Typical annotation |
|
|
20
|
+
| --- | --- | --- | --- |
|
|
21
|
+
| `addition` | Introduces a net-new capability that was not previously required | `docs/assets/templates/prd-change-addition.md` | None required unless baseline docs need cross-links |
|
|
22
|
+
| `enhancement` | Extends an existing capability with new behavior or scope | `docs/assets/templates/prd-change-addition.md` | `Enhanced by` |
|
|
23
|
+
| `revision` | Changes an established requirement, contract, or constraint | `docs/assets/templates/prd-change-revision.md` | `Superseded by` |
|
|
24
|
+
| `removal` | Deprecates or removes an established requirement or capability | `docs/assets/templates/prd-change-revision.md` | `Deprecated by` or `Removed by` |
|
|
25
|
+
|
|
26
|
+
## Active-Set Evolution Rules
|
|
27
|
+
|
|
28
|
+
- Treat `docs/prd/` as one active PRD namespace.
|
|
29
|
+
- Do not archive the active namespace when performing an additive change, enhancement, revision, or removal.
|
|
30
|
+
- Append each new change doc using the next available `NN-` number in the active namespace.
|
|
31
|
+
- Never renumber or reorder existing active PRD docs just because a change was introduced.
|
|
32
|
+
- Recommended slug prefixes:
|
|
33
|
+
- `add-`
|
|
34
|
+
- `enhance-`
|
|
35
|
+
- `revise-`
|
|
36
|
+
- `remove-`
|
|
37
|
+
- The newest linked change doc defines the effective requirement for the scope it changes.
|
|
38
|
+
- Earlier baseline text remains visible unless the user explicitly asks for a cleanup rewrite.
|
|
39
|
+
- Update `docs/prd/03-open-questions-and-risk-register.md` directly when the change discovers or resolves a gap, drift item, open question, decision, or risk; do not create a new `NN-` change doc solely to track register state.
|
|
40
|
+
- Do not create separate questions, decisions, risks, gaps, or architecture-decision files while an active PRD risk register exists unless the user explicitly asks for a new convention.
|
|
41
|
+
|
|
42
|
+
## Risk Register Update Rules
|
|
43
|
+
|
|
44
|
+
- Keep `docs/prd/03-open-questions-and-risk-register.md` as the canonical living register for gap state, open questions, resolved decisions, confirmed drift, and rebuild risks.
|
|
45
|
+
- Preserve the fixed sections `## Confirmed Drift`, `## Open Questions`, `## Rebuild Risks`, and `## Source Anchors`.
|
|
46
|
+
- Add or update one numbered `###` item per gap, question, drift, or risk.
|
|
47
|
+
- Use `D-001`, `D-002`, etc. under `## Confirmed Drift`; `Q-001`, `Q-002`, etc. under `## Open Questions`; and `R-001`, `R-002`, etc. under `## Rebuild Risks`.
|
|
48
|
+
- Assign the next available number within the section and never renumber existing items, even when they move to `Closed`.
|
|
49
|
+
- Each item starts with a table containing `Status`, `Decision`, and `Follow-Up`.
|
|
50
|
+
- Use only `Open`, `Confirming`, `Deferred`, or `Closed` for item status.
|
|
51
|
+
- Include `Question` or `Issue`, `Why it matters`, `Recommendation`, and `To close` for every item.
|
|
52
|
+
- Add `Resolution` only when the item is closed.
|
|
53
|
+
- If the item is already documented, update that existing item instead of duplicating it.
|
|
54
|
+
- Do not use `### Change Notes` inside `03-open-questions-and-risk-register.md`; that heading remains valid only in baseline PRD docs and sections that need active-set evolution lineage.
|
|
55
|
+
|
|
56
|
+
## Change Doc Selection Rules
|
|
57
|
+
|
|
58
|
+
- Use one change doc per coherent change scope whenever possible.
|
|
59
|
+
- Split change docs when different requirement areas have materially different rationale, impacted docs, or delivery sequencing.
|
|
60
|
+
- Use an addition/enhancement doc even when the new capability is large enough to resemble a subsystem. Under this model, net-new active-set changes are still recorded as change docs.
|
|
61
|
+
- Use a revision/removal doc whenever the change alters or retires an already-established requirement, even if new implementation work will also be needed.
|
|
62
|
+
|
|
63
|
+
## Baseline Annotation Rules
|
|
64
|
+
|
|
65
|
+
- Add `### Change Notes` only in the existing PRD docs and sections that are actually affected.
|
|
66
|
+
- Place the block directly under the impacted heading or immediately after the impacted requirement text.
|
|
67
|
+
- Use only these note verbs:
|
|
68
|
+
- `Enhanced by`
|
|
69
|
+
- `Superseded by`
|
|
70
|
+
- `Deprecated by`
|
|
71
|
+
- `Removed by`
|
|
72
|
+
- Each note must link to the numbered change doc that carries the effective change.
|
|
73
|
+
- When multiple change notes apply, list them in chronological order with the newest note last.
|
|
74
|
+
- Do not delete or silently rewrite the baseline requirement merely because a change note exists.
|
|
75
|
+
|
|
76
|
+
Example:
|
|
77
|
+
|
|
78
|
+
```md
|
|
79
|
+
### Change Notes
|
|
80
|
+
|
|
81
|
+
- Enhanced by [07-enhance-notifications.md](./07-enhance-notifications.md).
|
|
82
|
+
- Superseded by [09-revise-notification-routing.md](./09-revise-notification-routing.md).
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Index And Status Rules
|
|
86
|
+
|
|
87
|
+
- Update `docs/prd/00-index.md` whenever a change doc is added.
|
|
88
|
+
- The document map should show at least:
|
|
89
|
+
- document path
|
|
90
|
+
- kind
|
|
91
|
+
- status
|
|
92
|
+
- related docs
|
|
93
|
+
- focus
|
|
94
|
+
- Recommended `Kind` values:
|
|
95
|
+
- `core`
|
|
96
|
+
- `baseline`
|
|
97
|
+
- `reference`
|
|
98
|
+
- `addition`
|
|
99
|
+
- `enhancement`
|
|
100
|
+
- `revision`
|
|
101
|
+
- `removal`
|
|
102
|
+
- Recommended `Status` values:
|
|
103
|
+
- `active`
|
|
104
|
+
- `superseded`
|
|
105
|
+
- `deprecated`
|
|
106
|
+
- `removed`
|
|
107
|
+
- Use `Related Docs` to connect a change doc to the baseline docs it affects and to connect affected baseline docs back to the change doc.
|
|
108
|
+
|
|
109
|
+
## Work Backlog Coupling
|
|
110
|
+
|
|
111
|
+
- Backlogs are always directories: `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` with `00-index.md` and `0N-<phase>.md` files.
|
|
112
|
+
- Plans that drive those backlogs are also directories: `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` with `00-overview.md` and `0N-<phase>.md` files.
|
|
113
|
+
- Full-set generation still writes a backlog directory covering the whole active PRD set.
|
|
114
|
+
- Active-set evolution writes a new dated delta backlog directory by default instead of rewriting a prior backlog.
|
|
115
|
+
- Every delta backlog phase should cite:
|
|
116
|
+
- the new change doc or docs
|
|
117
|
+
- the impacted baseline docs that still matter to implementation
|
|
118
|
+
- Regenerate the full implementation backlog only when the user explicitly asks for it.
|
|
119
|
+
|
|
120
|
+
## Validation Checklist
|
|
121
|
+
|
|
122
|
+
Before closing an active-set evolution task, confirm:
|
|
123
|
+
|
|
124
|
+
1. Every new change doc uses the next available number and no existing PRD docs were renumbered.
|
|
125
|
+
2. Every impacted baseline doc contains the required `### Change Notes` backlinks when applicable.
|
|
126
|
+
3. `docs/prd/00-index.md` includes the new change docs and updated status or lineage metadata.
|
|
127
|
+
4. The effective requirement can be resolved by following links from the impacted baseline doc to the newest change doc.
|
|
128
|
+
5. Baseline text remains visible unless the user explicitly approved a cleanup rewrite.
|
|
129
|
+
6. Newly discovered or resolved gaps, drift, questions, decisions, and risks are reflected in `docs/prd/03-open-questions-and-risk-register.md`.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Wave Model
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
This file is the single source of truth for the Wave/Revision/Phase (W/R/P) encoding used across `make-docs` v2.
|
|
6
|
+
|
|
7
|
+
Every other reference file, template, and router links here instead of restating these rules. The encoding was piloted in `docs/assets/references/history-record-contract.md` and is extended to designs, plans, and work in v2. PRDs are exempt; see `## PRD Exemption`.
|
|
8
|
+
|
|
9
|
+
## Terms
|
|
10
|
+
|
|
11
|
+
| Token | Name | Meaning |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| `w{W}` | Wave | One end-to-end iteration: design to plan to work. Wave 1 is the initial wave. A new wave begins when the user starts a new end-to-end initiative. |
|
|
14
|
+
| `r{R}` | Revision | Revision within a wave. `r0` is the initial revision. `r1+` are meaningful redos of that wave's artifacts (for example a redesigned design or a re-planned plan after feedback). |
|
|
15
|
+
| `p{P}` | Phase | Phase within a plan or work backlog. Appears in inner phase files, phase-scoped history filenames, and history record `coordinate` frontmatter. `p{P}` does not appear in the top-level names of designs, plans, or work directories. Stage/task detail stays in `coordinate` only. |
|
|
16
|
+
| `t{T}` | Task | Task within one work backlog phase file. Task IDs appear on `### Tasks` checkbox items as phase-local ordinals (`t1`, `t2`, etc.) and are referenced externally as `w{W} r{R} p{P} t{T}` by inferring W/R from the work directory and P from the phase file. |
|
|
17
|
+
|
|
18
|
+
## Naming Patterns
|
|
19
|
+
|
|
20
|
+
| Artifact | Required path |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Plan directory | `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
|
|
23
|
+
| Plan overview file | `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/00-overview.md` |
|
|
24
|
+
| Plan phase file | `docs/plans/YYYY-MM-DD-w{W}-r{R}-<slug>/0N-<phase>.md` |
|
|
25
|
+
| Work directory | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/` |
|
|
26
|
+
| Work index file | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/00-index.md` |
|
|
27
|
+
| Work phase file | `docs/work/YYYY-MM-DD-w{W}-r{R}-<slug>/0N-<phase>.md` |
|
|
28
|
+
| History record | `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md` when W/R/P is known; see `docs/assets/references/history-record-contract.md` for fallbacks. |
|
|
29
|
+
|
|
30
|
+
`YYYY-MM-DD` is the date the artifact is written. Never backdate.
|
|
31
|
+
|
|
32
|
+
`<slug>` is lowercase, hyphens only, no special characters.
|
|
33
|
+
|
|
34
|
+
## Resolution Rules
|
|
35
|
+
|
|
36
|
+
When writing a new plan directory or work directory, determine `W` and `R` in this order:
|
|
37
|
+
|
|
38
|
+
1. **Honor explicit guidance.** If the user has stated the wave or revision (for example "this is wave 2" or "redo the design as r1"), use those values.
|
|
39
|
+
2. **Resolve source lineage before scanning for the highest wave.** Inspect the user request, referenced designs, design lineage, intended follow-on coordinate handoff, prior plans, prior work backlogs, and history records for an existing W/R/P coordinate. If the new work revises, reworks, corrects, standardizes, or finishes something already delivered in a known wave, keep that `W` and use the next unused `R` for that wave. This lineage rule wins even when later unrelated waves already exist.
|
|
40
|
+
3. **Scan the target directory only after lineage is resolved** (`docs/plans/` or `docs/work/`) for existing entries matching `w{W}-r{R}`. Parse the highest `W` and the existing revisions for any lineage-selected wave.
|
|
41
|
+
4. **Decide W and R when no source lineage applies:**
|
|
42
|
+
- If the user is revising an existing artifact in the highest relevant wave, keep `W` and use the next unused `R`.
|
|
43
|
+
- If the user is starting a new end-to-end initiative, increment the highest existing `W` and reset `R` to `0`.
|
|
44
|
+
5. **If no prior entries exist**, default to `w1-r0`.
|
|
45
|
+
|
|
46
|
+
Do not assign a new wave solely because newer unrelated waves exist. The highest-wave scan is a fallback for genuinely new initiatives, not evidence that a revision to older work belongs to a newer wave.
|
|
47
|
+
|
|
48
|
+
For history records, store any known W/R/P/S/T position in the `coordinate` frontmatter field described by `docs/assets/references/history-record-contract.md`. Include W/R/P in the filename when all three are known. Include W/R when only those two are known. Keep stage and task detail only in `coordinate`.
|
|
49
|
+
|
|
50
|
+
For work backlog tasks, number task IDs ordinally across the entire phase file, not within each stage. Start the first task at `t1`, continue through later `### Tasks` sections without resetting, and do not renumber existing task IDs when inserting or completing work. Use unordered markdown task syntax (`- [ ] t1: ...` or `- [x] t1: ...`) so checkbox rendering stays reliable.
|
|
51
|
+
|
|
52
|
+
## PRD Exemption
|
|
53
|
+
|
|
54
|
+
PRDs are intentionally exempt from W/R/P. The PRD namespace evolves in place through active-set evolution and change docs rather than iterating in waves.
|
|
55
|
+
|
|
56
|
+
- PRD docs keep the fixed `NN-<slug>.md` convention described in `docs/assets/references/output-contract.md`.
|
|
57
|
+
- Change management for PRDs is governed by `docs/assets/references/prd-change-management.md`.
|
|
58
|
+
- Archived PRD sets are grouped by date, not by wave (see `## Archive Integration`).
|
|
59
|
+
|
|
60
|
+
## Design Exemption
|
|
61
|
+
|
|
62
|
+
Designs are exempt from W/R encoding. Design filenames use the simplified pattern `YYYY-MM-DD-<slug>.md`.
|
|
63
|
+
|
|
64
|
+
The date provides chronological ordering; the slug provides topical identity. No wave or revision identifier is required.
|
|
65
|
+
|
|
66
|
+
When a design is revised or superseded, write a new dated design and use `## Design Lineage` (defined in `docs/assets/references/design-contract.md`) to link back to prior designs. Do not use `r{R}` revision numbering on designs.
|
|
67
|
+
|
|
68
|
+
Designs are inputs to a wave cycle (design → plan → work), not products of one. Binding a design to a wave number implies a 1:1 relationship with a downstream plan/work cycle that often does not hold.
|
|
69
|
+
|
|
70
|
+
## Archive Integration
|
|
71
|
+
|
|
72
|
+
Archive rules for designs, plans, work, and PRDs live in `docs/assets/archive/AGENTS.md`. W/R/P naming is preserved when an artifact is archived; it is not rewritten.
|
|
73
|
+
|
|
74
|
+
## Forward Compatibility
|
|
75
|
+
|
|
76
|
+
The W/R/P encoding was piloted in legacy history filenames before broader adoption. Existing legacy files continue to conform without change.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Templates Router
|
|
2
|
+
|
|
3
|
+
This directory contains structural starting points for generated docs.
|
|
4
|
+
|
|
5
|
+
- Copy the relevant template shape into the target output file; do not write outputs here.
|
|
6
|
+
- Use `design.md` for design docs, `guide-developer.md` or `guide-user.md` for guides, and the matching `plan-*`, `prd-*`, or `work-*` template for the target artifact.
|
|
7
|
+
- Resolve workflow and contract questions in `docs/assets/references/`, then continue in the target output directory router.
|
|
8
|
+
- Do not modify template files unless the user explicitly asks.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Templates Router
|
|
2
|
+
|
|
3
|
+
This directory contains structural starting points for generated docs.
|
|
4
|
+
|
|
5
|
+
- Copy the relevant template shape into the target output file; do not write outputs here.
|
|
6
|
+
- Use `design.md` for design docs, `guide-developer.md` or `guide-user.md` for guides, and the matching `plan-*`, `prd-*`, or `work-*` template for the target artifact.
|
|
7
|
+
- Resolve workflow and contract questions in `docs/assets/references/`, then continue in the target output directory router.
|
|
8
|
+
- Do not modify template files unless the user explicitly asks.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# {{TITLE}}
|
|
2
|
+
|
|
3
|
+
> Filename: `YYYY-MM-DD-<slug>.md`. See `docs/assets/references/design-contract.md` for naming and structural rules.
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
Explain what decision this document captures and why it exists.
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
Describe the problem, constraints, forces, and existing conditions that shape the decision.
|
|
12
|
+
|
|
13
|
+
## Decision
|
|
14
|
+
|
|
15
|
+
Describe the chosen approach clearly enough that planning can proceed from it.
|
|
16
|
+
|
|
17
|
+
## Alternatives Considered
|
|
18
|
+
|
|
19
|
+
List the meaningful alternatives and why they were not chosen.
|
|
20
|
+
|
|
21
|
+
## Consequences
|
|
22
|
+
|
|
23
|
+
Describe outcomes, trade-offs, risks, and follow-on implications.
|
|
24
|
+
|
|
25
|
+
## Intended Follow-On
|
|
26
|
+
|
|
27
|
+
- Route: `baseline-plan` or `change-plan`
|
|
28
|
+
- Next Prompt: [{{PROMPT_LABEL}}](../prompts/{{PROMPT_FILE}})
|
|
29
|
+
- Why: Explain why this design should flow into that planning path.
|
|
30
|
+
- Coordinate Handoff: For `change-plan`, identify the related completed coordinate and recommended downstream W/R coordinate when known; otherwise state `unresolved; planner must resolve before writing.`
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "{{TITLE}}"
|
|
3
|
+
path: "{{PATH}}"
|
|
4
|
+
status: draft
|
|
5
|
+
# version: ""
|
|
6
|
+
# order: 100
|
|
7
|
+
# tags: []
|
|
8
|
+
# applies-to: []
|
|
9
|
+
# related: []
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# {{TITLE}}
|
|
13
|
+
|
|
14
|
+
> See `docs/assets/references/guide-contract.md` for frontmatter schema, slug rules, audience rules, coverage decisions, and future coverage handling.
|
|
15
|
+
|
|
16
|
+
## Overview
|
|
17
|
+
|
|
18
|
+
What this guide helps contributors, maintainers, integrators, or operators do.
|
|
19
|
+
|
|
20
|
+
## Project Orientation
|
|
21
|
+
|
|
22
|
+
Where the relevant code, docs, generated files, contracts, and source-of-truth artifacts live.
|
|
23
|
+
|
|
24
|
+
## Prerequisites
|
|
25
|
+
|
|
26
|
+
Tools, access, local setup, or project knowledge required before starting.
|
|
27
|
+
|
|
28
|
+
## Development Workflow
|
|
29
|
+
|
|
30
|
+
How to change, extend, maintain, validate, or troubleshoot this capability.
|
|
31
|
+
|
|
32
|
+
## Validation
|
|
33
|
+
|
|
34
|
+
Commands, checks, review points, or evidence that show the change is working.
|
|
35
|
+
|
|
36
|
+
## Troubleshooting
|
|
37
|
+
|
|
38
|
+
Common failures, likely causes, and recovery steps.
|
|
39
|
+
|
|
40
|
+
## Related Resources
|
|
41
|
+
|
|
42
|
+
Links to related guides, designs, PRDs, work backlogs, history records, or reference contracts.
|
|
43
|
+
|
|
44
|
+
<!--
|
|
45
|
+
## Future Coverage
|
|
46
|
+
|
|
47
|
+
Use this section only when confirmed downstream work should update this guide later.
|
|
48
|
+
|
|
49
|
+
- Blocked by: <phase, capability, decision, or artifact>
|
|
50
|
+
Update when: <concrete trigger>
|
|
51
|
+
Guide change: <what to add, revise, or remove>
|
|
52
|
+
-->
|
|
53
|
+
|
|
54
|
+
<!-- Headings above are suggestions. Add, remove, or rename sections to fit the guide's content while preserving the audience intent in the guide contract. -->
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "{{TITLE}}"
|
|
3
|
+
path: "{{PATH}}"
|
|
4
|
+
status: draft
|
|
5
|
+
# version: ""
|
|
6
|
+
# order: 100
|
|
7
|
+
# tags: []
|
|
8
|
+
# applies-to: []
|
|
9
|
+
# related: []
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# {{TITLE}}
|
|
13
|
+
|
|
14
|
+
> See `docs/assets/references/guide-contract.md` for frontmatter schema, slug rules, audience rules, coverage decisions, and future coverage handling.
|
|
15
|
+
|
|
16
|
+
## Overview
|
|
17
|
+
|
|
18
|
+
What this guide helps users accomplish and who should start here.
|
|
19
|
+
|
|
20
|
+
## Before You Begin
|
|
21
|
+
|
|
22
|
+
What the user needs before they can follow the guide.
|
|
23
|
+
|
|
24
|
+
## Getting Started
|
|
25
|
+
|
|
26
|
+
The shortest path to a first successful outcome.
|
|
27
|
+
|
|
28
|
+
## Core Workflow
|
|
29
|
+
|
|
30
|
+
Step-by-step instructions for the primary user task.
|
|
31
|
+
|
|
32
|
+
## Advanced Usage
|
|
33
|
+
|
|
34
|
+
Optional deeper capabilities, variations, or next steps for experienced users.
|
|
35
|
+
|
|
36
|
+
## Troubleshooting
|
|
37
|
+
|
|
38
|
+
Common issues, expected symptoms, and how to resolve them.
|
|
39
|
+
|
|
40
|
+
## FAQ
|
|
41
|
+
|
|
42
|
+
Frequently asked questions.
|
|
43
|
+
|
|
44
|
+
## Related Resources
|
|
45
|
+
|
|
46
|
+
Links to related guides or deeper reference material.
|
|
47
|
+
|
|
48
|
+
<!--
|
|
49
|
+
## Future Coverage
|
|
50
|
+
|
|
51
|
+
Use this section only when confirmed downstream work should update this guide later.
|
|
52
|
+
|
|
53
|
+
- Blocked by: <phase, capability, decision, or artifact>
|
|
54
|
+
Update when: <concrete trigger>
|
|
55
|
+
Guide change: <what to add, revise, or remove>
|
|
56
|
+
-->
|
|
57
|
+
|
|
58
|
+
<!-- Headings above are suggestions. Add, remove, or rename sections to fit the guide's content while preserving the audience intent in the guide contract. -->
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
date: "{{YYYY-MM-DD}}"
|
|
3
|
+
client: "{{CLIENT}}"
|
|
4
|
+
model: "{{MODEL}}"
|
|
5
|
+
coordinate: "{{COORDINATE}}"
|
|
6
|
+
# provider: "{{PROVIDER}}"
|
|
7
|
+
# repo: "{{REPO}}"
|
|
8
|
+
# branch: "{{BRANCH}}"
|
|
9
|
+
# status: "{{STATUS}}"
|
|
10
|
+
# summary: "{{ONE_LINE_SUMMARY}}"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
<!-- Remove unknown frontmatter keys instead of leaving placeholders or inventing values. -->
|
|
14
|
+
|
|
15
|
+
<!-- Filename: docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md when W/R/P is known. If only W/R is known, omit p{P}; if no coordinate is known, use YYYY-MM-DD-<slug>.md. Keep stage/task details only in coordinate frontmatter. -->
|
|
16
|
+
|
|
17
|
+
# {{TITLE}}
|
|
18
|
+
|
|
19
|
+
## Changes
|
|
20
|
+
|
|
21
|
+
Summarize what was touched this session. Use prose, a short file tree, a table, or optional sub-sections — whichever best fits the work.
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
{{REPO_ROOT}}/
|
|
25
|
+
└── {{PATH_TOUCHED}}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
| Area | Summary |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| {{AREA}} | {{ONE_LINE_SUMMARY}} |
|
|
31
|
+
|
|
32
|
+
## Documentation
|
|
33
|
+
|
|
34
|
+
### Project
|
|
35
|
+
|
|
36
|
+
Project-level docs: READMEs, agent instructions, designs, plans, work backlogs, references, or templates.
|
|
37
|
+
|
|
38
|
+
| Path | Description |
|
|
39
|
+
| --- | --- |
|
|
40
|
+
| {{DOCS_PATH}} | {{ONE_LINE_DESCRIPTION}} |
|
|
41
|
+
|
|
42
|
+
If none, state "None this session."
|
|
43
|
+
|
|
44
|
+
### Developer
|
|
45
|
+
|
|
46
|
+
Docs intended for engineers, maintainers, or internal contributors.
|
|
47
|
+
|
|
48
|
+
| Path | Description |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| {{DOCS_PATH}} | {{ONE_LINE_DESCRIPTION}} |
|
|
51
|
+
|
|
52
|
+
If none, state "None this session."
|
|
53
|
+
|
|
54
|
+
### User
|
|
55
|
+
|
|
56
|
+
Docs intended for end users, operators, or external readers.
|
|
57
|
+
|
|
58
|
+
| Path | Description |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| {{DOCS_PATH}} | {{ONE_LINE_DESCRIPTION}} |
|
|
61
|
+
|
|
62
|
+
If none, state "None this session."
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# {{TITLE}}
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
State what this plan covers and why it exists in one short paragraph. Link back to the originating design or change request if applicable.
|
|
6
|
+
|
|
7
|
+
## Objective
|
|
8
|
+
|
|
9
|
+
List the concrete goals and the completion criteria for the plan. A reader should be able to tell when the plan is done.
|
|
10
|
+
|
|
11
|
+
## Coordinate Decision
|
|
12
|
+
|
|
13
|
+
- Coordinate: `W{{W}} R{{R}}`
|
|
14
|
+
- Classification: `new-wave` or `revision`
|
|
15
|
+
- Evidence: Explain the explicit user guidance, design handoff, source lineage, prior plan/work/history records, or highest-wave fallback used to choose this coordinate.
|
|
16
|
+
|
|
17
|
+
## Phase Map
|
|
18
|
+
|
|
19
|
+
List the phase detail files in this plan directory with a one-line description of each. Every plan has at least one phase file even when the work is small.
|
|
20
|
+
|
|
21
|
+
| File | Purpose |
|
|
22
|
+
| ---- | ------- |
|
|
23
|
+
| `01-{{UPPER_SNAKE}}.md` | {{PHASE_PURPOSE}} |
|
|
24
|
+
| `02-{{UPPER_SNAKE}}.md` | {{PHASE_PURPOSE}} |
|
|
25
|
+
|
|
26
|
+
## Dependencies
|
|
27
|
+
|
|
28
|
+
Call out external dependencies, upstream artifacts, or prerequisites that must be resolved before or during execution.
|
|
29
|
+
|
|
30
|
+
## Validation
|
|
31
|
+
|
|
32
|
+
Describe how success of the overall plan is verified once all phases complete. Reference the review pass or acceptance gate that closes the plan.
|