@brucewaynedecoy/make-docs 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +93 -0
  3. package/dist/chunk-HP3HBG7F.js +626 -0
  4. package/dist/chunk-HP3HBG7F.js.map +1 -0
  5. package/dist/chunk-QRFH4J6H.js +1194 -0
  6. package/dist/chunk-QRFH4J6H.js.map +1 -0
  7. package/dist/chunk-WM3OXYTW.js +2630 -0
  8. package/dist/chunk-WM3OXYTW.js.map +1 -0
  9. package/dist/index.js +1720 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/skills-command-3ESCZ75U.js +547 -0
  12. package/dist/skills-command-3ESCZ75U.js.map +1 -0
  13. package/dist/uninstall-GQE4SJF2.js +150 -0
  14. package/dist/uninstall-GQE4SJF2.js.map +1 -0
  15. package/package.json +49 -0
  16. package/skill-registry.json +276 -0
  17. package/skill-registry.schema.json +64 -0
  18. package/template/.make-docs/scripts/check_path_hygiene.py +435 -0
  19. package/template/AGENTS.md +3 -0
  20. package/template/CLAUDE.md +3 -0
  21. package/template/docs/AGENTS.md +15 -0
  22. package/template/docs/CLAUDE.md +15 -0
  23. package/template/docs/assets/AGENTS.md +9 -0
  24. package/template/docs/assets/CLAUDE.md +9 -0
  25. package/template/docs/assets/archive/AGENTS.md +20 -0
  26. package/template/docs/assets/archive/CLAUDE.md +20 -0
  27. package/template/docs/assets/history/AGENTS.md +12 -0
  28. package/template/docs/assets/history/CLAUDE.md +12 -0
  29. package/template/docs/assets/prompts/AGENTS.md +8 -0
  30. package/template/docs/assets/prompts/CLAUDE.md +8 -0
  31. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +14 -0
  32. package/template/docs/assets/prompts/designs-to-plan.prompt.md +10 -0
  33. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +27 -0
  34. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +8 -0
  35. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +6 -0
  36. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +10 -0
  37. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +6 -0
  38. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +6 -0
  39. package/template/docs/assets/prompts/request-to-design.prompt.md +16 -0
  40. package/template/docs/assets/prompts/session-to-history-record.prompt.md +19 -0
  41. package/template/docs/assets/prompts/update-readme-green-field.prompt.md +6 -0
  42. package/template/docs/assets/prompts/work-to-commit-message.prompt.md +27 -0
  43. package/template/docs/assets/prompts/work-to-guides.prompt.md +18 -0
  44. package/template/docs/assets/references/AGENTS.md +9 -0
  45. package/template/docs/assets/references/CLAUDE.md +9 -0
  46. package/template/docs/assets/references/commit-message-convention.md +198 -0
  47. package/template/docs/assets/references/design-contract.md +62 -0
  48. package/template/docs/assets/references/design-workflow.md +60 -0
  49. package/template/docs/assets/references/execution-workflow.md +157 -0
  50. package/template/docs/assets/references/guide-contract.md +159 -0
  51. package/template/docs/assets/references/harness-capability-matrix.md +52 -0
  52. package/template/docs/assets/references/history-record-contract.md +137 -0
  53. package/template/docs/assets/references/output-contract.md +221 -0
  54. package/template/docs/assets/references/path-and-link-hygiene.md +49 -0
  55. package/template/docs/assets/references/planning-workflow.md +160 -0
  56. package/template/docs/assets/references/prd-change-management.md +129 -0
  57. package/template/docs/assets/references/wave-model.md +76 -0
  58. package/template/docs/assets/templates/AGENTS.md +8 -0
  59. package/template/docs/assets/templates/CLAUDE.md +8 -0
  60. package/template/docs/assets/templates/design.md +30 -0
  61. package/template/docs/assets/templates/guide-developer.md +54 -0
  62. package/template/docs/assets/templates/guide-user.md +58 -0
  63. package/template/docs/assets/templates/history-record.md +62 -0
  64. package/template/docs/assets/templates/plan-overview.md +32 -0
  65. package/template/docs/assets/templates/plan-prd-change.md +99 -0
  66. package/template/docs/assets/templates/plan-prd-decompose.md +70 -0
  67. package/template/docs/assets/templates/plan-prd.md +124 -0
  68. package/template/docs/assets/templates/prd-architecture.md +51 -0
  69. package/template/docs/assets/templates/prd-change-addition.md +45 -0
  70. package/template/docs/assets/templates/prd-change-revision.md +45 -0
  71. package/template/docs/assets/templates/prd-glossary.md +15 -0
  72. package/template/docs/assets/templates/prd-index.md +45 -0
  73. package/template/docs/assets/templates/prd-overview.md +43 -0
  74. package/template/docs/assets/templates/prd-reference.md +17 -0
  75. package/template/docs/assets/templates/prd-risk-register.md +55 -0
  76. package/template/docs/assets/templates/prd-subsystem.md +49 -0
  77. package/template/docs/assets/templates/work-index.md +21 -0
  78. package/template/docs/assets/templates/work-phase.md +34 -0
  79. package/template/docs/designs/AGENTS.md +21 -0
  80. package/template/docs/designs/CLAUDE.md +21 -0
  81. package/template/docs/guides/AGENTS.md +15 -0
  82. package/template/docs/guides/CLAUDE.md +15 -0
  83. package/template/docs/plans/AGENTS.md +20 -0
  84. package/template/docs/plans/CLAUDE.md +20 -0
  85. package/template/docs/prd/AGENTS.md +9 -0
  86. package/template/docs/prd/CLAUDE.md +9 -0
  87. package/template/docs/work/AGENTS.md +18 -0
  88. package/template/docs/work/CLAUDE.md +18 -0
@@ -0,0 +1,159 @@
1
+ # Guide Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract for developer and user guides under `docs/guides/developer/` and `docs/guides/user/`.
6
+
7
+ This contract does NOT apply to history records, which use `docs/assets/references/history-record-contract.md`.
8
+
9
+ Guides are living documentation for the current usable or maintainable product surface. They should not read like phase logs, release notes, or implementation summaries. Use phase, plan, PRD, design, and history docs as evidence, then write the guide around what a reader needs to do next.
10
+
11
+ ## Audience Contract
12
+
13
+ ### Developer Guides
14
+
15
+ Developer guides live in `docs/guides/developer/`. Write them for contributors, maintainers, integrators, and operators who need to understand, extend, validate, troubleshoot, or safely change the project.
16
+
17
+ A developer guide should help a capable developer quickly reach a first useful PR or maintenance action. Prefer:
18
+
19
+ - codebase and documentation navigation
20
+ - local setup, validation, release, or operational procedures
21
+ - extension points, generated files, contracts, and source-of-truth boundaries
22
+ - maintainer workflows, troubleshooting, and safe-change notes
23
+ - links to deeper designs, PRDs, work backlogs, and reference contracts
24
+
25
+ Avoid writing developer guides as implementation diaries. Historical context belongs only where it helps the reader make a current decision.
26
+
27
+ ### User Guides
28
+
29
+ User guides live in `docs/guides/user/`. Write them for people who use what the project ships, including novices who need orientation and advanced users who want to explore deeper workflows.
30
+
31
+ A user guide should help the reader understand the product from a user's perspective and complete real tasks. Prefer:
32
+
33
+ - getting-started orientation and first successful use
34
+ - task-based workflows, product concepts, and decision points
35
+ - practical examples, prerequisites, expected results, and troubleshooting
36
+ - progressive depth: start with the common path, then link or section advanced usage
37
+
38
+ Avoid exposing internal implementation detail unless it directly affects user behavior, configuration, or troubleshooting.
39
+
40
+ ## Required Frontmatter
41
+
42
+ Every guide must begin with a YAML frontmatter block. Required fields:
43
+
44
+ | Field | Type | Description |
45
+ | --- | --- | --- |
46
+ | `title` | string | Display title of the guide. |
47
+ | `path` | string | Virtual grouping and publication path. Lowercase, forward-slash separated, no leading or trailing slash. 1-3 segments. Examples: `cli/development`, `getting-started`, `template/customization`. |
48
+ | `status` | enum | One of `draft`, `published`, `deprecated`. |
49
+
50
+ ## Optional Frontmatter
51
+
52
+ | Field | Type | Description |
53
+ | --- | --- | --- |
54
+ | `version` | string | Guide version (freeform, e.g., `1.0`, `2026-04-16`). When omitted, freshness is tracked via git history. |
55
+ | `order` | integer | Sort weight within the guide's path group. Lower numbers sort first. Default: `100`. |
56
+ | `tags` | list of strings | Freeform labels for search and cross-referencing. |
57
+ | `applies-to` | list of strings | Package names or capability areas the guide covers (e.g., `cli`, `template`, `skills`). |
58
+ | `related` | list of strings | Relative paths to related guides, designs, plans, PRDs, work backlogs, history records, or reference files. |
59
+
60
+ Do not add frontmatter fields for deferred guide work. Use `## Future Coverage` in the guide body instead.
61
+
62
+ ## Guide Coverage Decision
63
+
64
+ Before creating a guide, inspect existing guides for overlap. Prefer updating or linking an existing guide when that produces a clearer documentation set than adding a new file.
65
+
66
+ Resolve each documentation-worthy capability to one of these outcomes:
67
+
68
+ | Outcome | Use when |
69
+ | --- | --- |
70
+ | `developer` | The durable knowledge is maintainer-facing, contributor-facing, operational, validation-related, or extension-related. |
71
+ | `user` | The durable knowledge helps people use the shipped product, understand a concept, or complete a task. |
72
+ | `both` | The capability has distinct user and developer needs that should not be collapsed into one audience. |
73
+ | `update-existing` | A current guide already owns the topic and should be expanded instead of creating a new guide. |
74
+ | `link-only` | The capability is covered well enough by a related guide, reference, design, PRD, or existing navigation surface. |
75
+ | `none` | The capability is obsolete, too internal, too narrow, or only useful as a history entry. |
76
+
77
+ When both audiences are relevant, avoid duplicating the same guide in both directories. Put the detailed guide in the primary audience directory and use `related` frontmatter plus concise companion coverage when the secondary audience needs a different entry point.
78
+
79
+ After creating or updating guide content, re-check overlapping developer and user guides. Add reciprocal links, `related` frontmatter, or concise supplemental context when the new guide work helps an existing guide become easier to discover, navigate, or apply.
80
+
81
+ When no guide is needed during closeout or generation, record the no-guide decision in the history entry or planning artifact with the reason.
82
+
83
+ ## Partial and Future Coverage
84
+
85
+ Do not block useful guide work just because downstream capabilities are incomplete. Write or update the guide with the current confirmed behavior, and defer only the blocked portion.
86
+
87
+ Use a `## Future Coverage` section when a guide would benefit from a known downstream capability, phase, or decision that is not complete yet. Keep it as an actionable guide-maintenance note, not a risk register replacement.
88
+
89
+ Each future coverage item should state:
90
+
91
+ - `Blocked by`: the missing downstream phase, capability, decision, or artifact
92
+ - `Update when`: the concrete signal that should trigger the guide update
93
+ - `Guide change`: what should be added, revised, or removed later
94
+
95
+ Do not create a design doc, architecture decision, or PRD risk-register item solely to remember future guide work. Use those artifacts only when the repo already needs them for product or architecture decisions beyond guide maintenance.
96
+
97
+ ## Slug Convention
98
+
99
+ Guide filenames follow the pattern:
100
+
101
+ ```
102
+ <path-prefix>-<descriptive-slug>.md
103
+ ```
104
+
105
+ `<path-prefix>` is the `path` frontmatter value with `/` replaced by `-`. The descriptive suffix must be unique within the directory.
106
+
107
+ Rules:
108
+
109
+ - Slugs are lowercase, hyphens only, no special characters.
110
+ - The path-prefix portion of the slug must exactly match the `path` field with `/` replaced by `-`.
111
+ - No date prefix. Guides are living documents; freshness is tracked via `version` or git history.
112
+
113
+ Examples:
114
+
115
+ | `path` value | Filename |
116
+ | --- | --- |
117
+ | `cli/development` | `cli-development-local-build-and-install.md` |
118
+ | `cli/testing` | `cli-testing-smoke-pack.md` |
119
+ | `getting-started` | `getting-started-installing-make-docs.md` |
120
+ | `template/customization` | `template-customization-adding-capabilities.md` |
121
+
122
+ ## Path Rules
123
+
124
+ The `path` field is limited to 1-3 segments. This prevents deeply nested virtual paths from undermining the flat-file layout.
125
+
126
+ | Depth | Example | Use case |
127
+ | --- | --- | --- |
128
+ | 1 | `getting-started` | Top-level topics without subsystem specificity. |
129
+ | 2 | `cli/development` | Subsystem plus topic area, which is most common. |
130
+ | 3 | `cli/testing/integration` | Subsystem plus topic plus sub-topic. Use sparingly. |
131
+
132
+ The `path` field serves dual purposes:
133
+
134
+ 1. **Logical grouping**: guides sharing the same `path` form a virtual section for search and discovery.
135
+ 2. **Publication routing**: external documentation pipelines can map `path` to URL structure.
136
+
137
+ ## Status Lifecycle
138
+
139
+ | Status | Meaning | Publication |
140
+ | --- | --- | --- |
141
+ | `draft` | Work in progress. May be incomplete or inaccurate. | Excluded from publication pipelines by default. |
142
+ | `published` | Complete and current. | Included in publication pipelines. |
143
+ | `deprecated` | Superseded or no longer applicable. Retained with a deprecation note at the top. | Excluded from publication pipelines. |
144
+
145
+ New guides always start as `draft`. An agent must never set `status: published` on a newly created guide. Only the user or an explicit user request promotes a guide to `published`.
146
+
147
+ Transitions: `draft` to `published` to `deprecated`. A `deprecated` guide may return to `draft` for substantial rewrites. Archival, moving to `docs/assets/archive/guides/`, follows existing archive rules and happens only when the user explicitly asks.
148
+
149
+ ## Scope
150
+
151
+ - Applies to `docs/guides/developer/` and `docs/guides/user/` only.
152
+ - Does NOT apply to history records, which use `docs/assets/references/history-record-contract.md`.
153
+
154
+ ## Link Rules
155
+
156
+ - Use relative Markdown links between guides and related designs, plans, PRDs, work backlogs, history records, or reference files.
157
+ - Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
158
+ - Every internal link must resolve.
159
+ - Use `related` frontmatter for companion guides and high-value source artifacts.
@@ -0,0 +1,52 @@
1
+ # Harness Capability Matrix
2
+
3
+ ## Purpose
4
+
5
+ Use this matrix to translate environment signals into safe defaults. The capability probe should help, but the current session still needs explicit confirmation before the skill assumes MCP access or agent-spawning support.
6
+
7
+ ## Matrix
8
+
9
+ | Harness | Likely signals | Likely config paths | Delegation default | MCP note |
10
+ | --- | --- | --- | --- | --- |
11
+ | Codex | `CODEX_*` env vars, `CODEX_THREAD_ID`, `CODEX_HOME` | `~/.codex/config.toml`, `~/.codex/config.json` | Parallel agents first, then subagents, then single-agent fallback. Coordinator write scope `none` when delegation works. | Confirm live MCP access in-session even if config lists servers |
12
+ | Claude Code | `CLAUDE_CODE_*` env vars, Claude project metadata | `~/.claude/.claude.json` | Parallel agents first, then subagents, then single-agent fallback. Coordinator write scope `none` when delegation works. | Confirm live MCP access in-session and check project-level overrides |
13
+ | OpenCode | `OPENCODE_*` env vars, OpenCode config files if present | `~/.config/opencode/*`, `~/.opencode*`, repo-local OpenCode config | Subagents first if explicit agent tools exist, otherwise single-agent fallback. Coordinator write scope `none` when delegation works. | Confirm live MCP access in-session; config shapes may vary |
14
+ | Unknown | No clear harness markers | repo-local config only | Single-agent fallback only after delegation support cannot be confirmed | Treat MCP access as unknown until proven in-session |
15
+
16
+ ## Detection Notes
17
+
18
+ - Environment variables are stronger evidence of the active harness than dormant config files.
19
+ - Config files show likely local setup, not guaranteed current-session capabilities.
20
+ - When Codex and Claude markers both appear, prefer the active-session evidence over passive config presence.
21
+
22
+ ## Planning Default
23
+
24
+ Regardless of harness, default to planning mode first unless the user explicitly approves direct execution.
25
+
26
+ ## Execution Default
27
+
28
+ When execution is approved, use this delegation ladder:
29
+
30
+ 1. parallel agents
31
+ 2. subagents
32
+ 3. single-agent fallback
33
+
34
+ When execution is approved and the harness supports parallel agents:
35
+
36
+ - split work by subsystem or doc family
37
+ - keep scopes disjoint
38
+ - keep coordinator write scope at `none`
39
+ - require each agent to re-index in its own session if MCP tools are in use
40
+
41
+ When the harness supports only subagents:
42
+
43
+ - still delegate before broad single-agent execution
44
+ - keep the coordinator focused on workstream management, routing, and status reporting
45
+ - keep coordinator write scope at `none`
46
+ - require each delegated worker to confirm MCP access in its own session
47
+
48
+ When the harness does not clearly support delegated workers:
49
+
50
+ - execute sequentially
51
+ - keep the same output contract
52
+ - keep the same validation step
@@ -0,0 +1,137 @@
1
+ # History Record Contract
2
+
3
+ ## Purpose
4
+
5
+ Use this contract for session history records under `docs/assets/history/`.
6
+
7
+ History records are **breadcrumbs**: concise, point-in-time references for a future auditor. A reader should be able to skim one and know what was touched and why, then follow links to deeper detail. They are not verbose narratives and not live logs.
8
+
9
+ ## Required Path
10
+
11
+ - When wave, revision, and phase are known: `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-p{P}-<slug>.md`
12
+ - When only wave and revision are known: `docs/assets/history/YYYY-MM-DD-w{W}-r{R}-<slug>.md`
13
+ - When no coordinate is known: `docs/assets/history/YYYY-MM-DD-<slug>.md`
14
+
15
+ Use today's date in `YYYY-MM-DD`. Never backdate.
16
+
17
+ ## Frontmatter
18
+
19
+ Use flexible YAML frontmatter. Include fields when the session knows them and omit fields when it does not. Do not invent unknown `client`, `model`, or `provider` values.
20
+
21
+ Recommended fields when known:
22
+
23
+ ```yaml
24
+ ---
25
+ client: "Codex Desktop"
26
+ model: "gpt-5.4"
27
+ date: "2026-04-20"
28
+ coordinate: "W9 R0 P1"
29
+ ---
30
+ ```
31
+
32
+ Useful optional dimensions:
33
+
34
+ ```yaml
35
+ provider: "OpenAI"
36
+ repo: "make-docs"
37
+ branch: "main"
38
+ status: "completed"
39
+ summary: "Updated history routing and documentation contracts."
40
+ ```
41
+
42
+ The `coordinate` field replaces separate `wave`, `revision`, `phase`, `stage`, and `task` frontmatter fields.
43
+
44
+ ## Naming Components
45
+
46
+ | Component | Meaning |
47
+ | --- | --- |
48
+ | `YYYY-MM-DD` | Date the session summary is written. |
49
+ | `w{W}-r{R}-p{P}` | Coordinate prefix for phase-scoped work when wave, revision, and phase are known. |
50
+ | `w{W}-r{R}` | Coordinate prefix when only wave and revision are known. |
51
+ | `<slug>` | Lowercase, hyphens only, no special characters. Default is `summary`. Use a more specific slug (for example `auth-refactor`) when the session's focus is narrower. |
52
+
53
+ Encode known wave/revision/phase position in the filename for phase-scoped history records. Keep stage and task detail only in `coordinate` frontmatter, not in filenames. Do not invent missing coordinate levels.
54
+
55
+ ## Coordinate Rules
56
+
57
+ See `docs/assets/references/wave-model.md` for W/R/P semantics and general resolution rules. The rules below are specific to history records and extend (do not replace) the general model.
58
+
59
+ Coordinates use one combined abbreviation that captures as much positioning as is known for the session:
60
+
61
+ ```yaml
62
+ coordinate: "W9 R0 P1"
63
+ ```
64
+
65
+ When deeper granularity is known, append stage and task suffixes:
66
+
67
+ ```yaml
68
+ coordinate: "W9 R0 P1 S2 T4"
69
+ ```
70
+
71
+ Unknown deeper levels should be omitted rather than filled with placeholders.
72
+
73
+ ## Required Headings
74
+
75
+ Each history record must include, in order:
76
+
77
+ - `# {{TITLE}}` — level-1 title capturing the session focus.
78
+ - `## Changes` — free-form prose, markdown tables, and/or file trees summarizing what was touched. May use sub-headings.
79
+ - `## Documentation` — contains all required sub-sections below.
80
+ - `### Project`
81
+ - `### Developer`
82
+ - `### User`
83
+
84
+ ## Documentation Tables
85
+
86
+ All sub-sections under `## Documentation` are markdown tables with columns `Path` and `Description`.
87
+
88
+ - `### Project` — project-level documentation created or updated in the session: READMEs, agent instructions (`AGENTS.md`/`CLAUDE.md`), designs, plans, work backlogs, and reference or template files.
89
+ - `### Developer` — developer guides created or updated in the session.
90
+ - `### User` — user guides created or updated in the session.
91
+
92
+ If a sub-section has no entries, state `None this session.` in place of the table.
93
+
94
+ Example:
95
+
96
+ ```markdown
97
+ ## Documentation
98
+
99
+ ### Project
100
+
101
+ | Path | Description |
102
+ | --- | --- |
103
+ | [docs/designs/2026-04-16-w2-r0-auth-redesign.md](../../designs/2026-04-16-w2-r0-auth-redesign.md) | New design for the auth module redesign. |
104
+
105
+ ### Developer
106
+
107
+ | Path | Description |
108
+ | --- | --- |
109
+ | [docs/guides/developer/auth-module.md](../developer/auth-module.md) | New developer reference for the auth module. |
110
+
111
+ ### User
112
+
113
+ None this session.
114
+ ```
115
+
116
+ ## When to Create
117
+
118
+ Create a history record:
119
+
120
+ - at the end of a work session,
121
+ - on an explicit "summarize this session" request, or
122
+ - at a meaningful checkpoint.
123
+
124
+ History records are written once at the end of the relevant span. Do not maintain them as live logs during the session.
125
+
126
+ ## Update Rules
127
+
128
+ - Each session gets its own new file. History records are immutable breadcrumbs.
129
+ - Edit a prior history record in place only to correct factual errors.
130
+ - Never append new session work to a prior session's summary; write a new file instead.
131
+
132
+ ## Link Rules
133
+
134
+ - Use relative Markdown links when referencing specific files, plans, designs, or work items that the session touched.
135
+ - Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
136
+ - Make sure every internal link resolves.
137
+ - Link back to the active plan, design, or backlog phase that frames the session whenever one exists.
@@ -0,0 +1,221 @@
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.
@@ -0,0 +1,49 @@
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.