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