@brucewaynedecoy/make-docs 1.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +93 -0
- package/dist/chunk-HP3HBG7F.js +626 -0
- package/dist/chunk-HP3HBG7F.js.map +1 -0
- package/dist/chunk-QRFH4J6H.js +1194 -0
- package/dist/chunk-QRFH4J6H.js.map +1 -0
- package/dist/chunk-WM3OXYTW.js +2630 -0
- package/dist/chunk-WM3OXYTW.js.map +1 -0
- package/dist/index.js +1720 -0
- package/dist/index.js.map +1 -0
- package/dist/skills-command-3ESCZ75U.js +547 -0
- package/dist/skills-command-3ESCZ75U.js.map +1 -0
- package/dist/uninstall-GQE4SJF2.js +150 -0
- package/dist/uninstall-GQE4SJF2.js.map +1 -0
- package/package.json +49 -0
- package/skill-registry.json +276 -0
- package/skill-registry.schema.json +64 -0
- package/template/.make-docs/scripts/check_path_hygiene.py +435 -0
- package/template/AGENTS.md +3 -0
- package/template/CLAUDE.md +3 -0
- package/template/docs/AGENTS.md +15 -0
- package/template/docs/CLAUDE.md +15 -0
- package/template/docs/assets/AGENTS.md +9 -0
- package/template/docs/assets/CLAUDE.md +9 -0
- package/template/docs/assets/archive/AGENTS.md +20 -0
- package/template/docs/assets/archive/CLAUDE.md +20 -0
- package/template/docs/assets/history/AGENTS.md +12 -0
- package/template/docs/assets/history/CLAUDE.md +12 -0
- package/template/docs/assets/prompts/AGENTS.md +8 -0
- package/template/docs/assets/prompts/CLAUDE.md +8 -0
- package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +14 -0
- package/template/docs/assets/prompts/designs-to-plan.prompt.md +10 -0
- package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +27 -0
- package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +8 -0
- package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +6 -0
- package/template/docs/assets/prompts/prd-change-to-work.prompt.md +10 -0
- package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +6 -0
- package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +6 -0
- package/template/docs/assets/prompts/request-to-design.prompt.md +16 -0
- package/template/docs/assets/prompts/session-to-history-record.prompt.md +19 -0
- package/template/docs/assets/prompts/update-readme-green-field.prompt.md +6 -0
- package/template/docs/assets/prompts/work-to-commit-message.prompt.md +27 -0
- package/template/docs/assets/prompts/work-to-guides.prompt.md +18 -0
- package/template/docs/assets/references/AGENTS.md +9 -0
- package/template/docs/assets/references/CLAUDE.md +9 -0
- package/template/docs/assets/references/commit-message-convention.md +198 -0
- package/template/docs/assets/references/design-contract.md +62 -0
- package/template/docs/assets/references/design-workflow.md +60 -0
- package/template/docs/assets/references/execution-workflow.md +157 -0
- package/template/docs/assets/references/guide-contract.md +159 -0
- package/template/docs/assets/references/harness-capability-matrix.md +52 -0
- package/template/docs/assets/references/history-record-contract.md +137 -0
- package/template/docs/assets/references/output-contract.md +221 -0
- package/template/docs/assets/references/path-and-link-hygiene.md +49 -0
- package/template/docs/assets/references/planning-workflow.md +160 -0
- package/template/docs/assets/references/prd-change-management.md +129 -0
- package/template/docs/assets/references/wave-model.md +76 -0
- package/template/docs/assets/templates/AGENTS.md +8 -0
- package/template/docs/assets/templates/CLAUDE.md +8 -0
- package/template/docs/assets/templates/design.md +30 -0
- package/template/docs/assets/templates/guide-developer.md +54 -0
- package/template/docs/assets/templates/guide-user.md +58 -0
- package/template/docs/assets/templates/history-record.md +62 -0
- package/template/docs/assets/templates/plan-overview.md +32 -0
- package/template/docs/assets/templates/plan-prd-change.md +99 -0
- package/template/docs/assets/templates/plan-prd-decompose.md +70 -0
- package/template/docs/assets/templates/plan-prd.md +124 -0
- package/template/docs/assets/templates/prd-architecture.md +51 -0
- package/template/docs/assets/templates/prd-change-addition.md +45 -0
- package/template/docs/assets/templates/prd-change-revision.md +45 -0
- package/template/docs/assets/templates/prd-glossary.md +15 -0
- package/template/docs/assets/templates/prd-index.md +45 -0
- package/template/docs/assets/templates/prd-overview.md +43 -0
- package/template/docs/assets/templates/prd-reference.md +17 -0
- package/template/docs/assets/templates/prd-risk-register.md +55 -0
- package/template/docs/assets/templates/prd-subsystem.md +49 -0
- package/template/docs/assets/templates/work-index.md +21 -0
- package/template/docs/assets/templates/work-phase.md +34 -0
- package/template/docs/designs/AGENTS.md +21 -0
- package/template/docs/designs/CLAUDE.md +21 -0
- package/template/docs/guides/AGENTS.md +15 -0
- package/template/docs/guides/CLAUDE.md +15 -0
- package/template/docs/plans/AGENTS.md +20 -0
- package/template/docs/plans/CLAUDE.md +20 -0
- package/template/docs/prd/AGENTS.md +9 -0
- package/template/docs/prd/CLAUDE.md +9 -0
- package/template/docs/work/AGENTS.md +18 -0
- package/template/docs/work/CLAUDE.md +18 -0
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: Plan to PRD (Green Field)
|
|
3
|
+
description: Instructs the agent to generate a comprehensive set of PRD documents based from a specific plan document. Agent will automatically determine if parallel agents are needed, based on scope and complexity. If there are already requirements documents in `docs/prd`, they will be archived in a dated sub-folder (per agent instructions in `AGENTS.md` and `CLAUDE.md`).
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
I think we're ready to create the PRD documents in `docs/prd`. Please be as detailed as possible. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this. The resulting PRD set should be a comprehensive design based on the details you captured in the {{PLAN DOC}} plan doc.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: PRD Change to Work Backlog
|
|
3
|
+
description: Instructs the agent to generate a dated delta backlog from one or more PRD change docs and the baseline docs they affect.
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please review these PRD change docs: {{CHANGE DOCS}}.
|
|
7
|
+
|
|
8
|
+
Also review the baseline PRD docs they affect: {{AFFECTED PRD DOCS}}.
|
|
9
|
+
|
|
10
|
+
Then generate a dated delta backlog in `docs/work/`. Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/prd-change-management.md`. The backlog should stay scoped to the requested change, remain dependency-ordered, and cite both the new change docs and the affected baseline docs in each phase's source-traceability section.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: PRD to Work Backlog (Full PRD Set)
|
|
3
|
+
description: Instructs the agent to generate a work backlog document or set of documents from the full PRD.
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please generate a work backlog based on what's in the PRD set (in `docs/prd/`). We will need a work backlog document or documents (in `docs/work/`) for a full implementation of all of the features. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: PRD to Work (for Single PRD Feature)
|
|
3
|
+
description: Instructs the agent to generate a work backlog document or set of documents for a single requirement document from the PRD set. Generally, a requirement document encapsulates a single feature or epic.
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please review the requirement document {{REQUIREMENT DOC}} to understand the requirements for the specific epic or feature captured in that document. Then generate a document (or possibly documents) for our work backlog in `docs/work/`. Follow the instructions, references, and templates provided to you in the `docs` directory (and appropriate child directories) on how to do this.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: Request to Design
|
|
3
|
+
description: Instructs the agent to turn a user request into a design doc by updating an existing related design or creating a new dated design doc.
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please review the request below and then either generate or update a design doc for the request.
|
|
7
|
+
|
|
8
|
+
Before writing anything, inspect `docs/designs/` for related design docs. If a related design clearly covers the same decision area, update it. Otherwise create a new dated design doc in `docs/designs/`.
|
|
9
|
+
|
|
10
|
+
Follow the instructions, references, and templates in the `docs` directory, especially `docs/assets/references/design-workflow.md`, `docs/assets/references/design-contract.md`, and `docs/assets/templates/design.md`.
|
|
11
|
+
|
|
12
|
+
The resulting design doc should include an explicit `## Intended Follow-On` section with either `baseline-plan` or `change-plan` and the matching prompt link. Do not create a plan as part of this workflow.
|
|
13
|
+
|
|
14
|
+
Here is the request:
|
|
15
|
+
|
|
16
|
+
{{REQUEST}}
|
|
@@ -0,0 +1,19 @@
|
|
|
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}}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: Update README (Green Field)
|
|
3
|
+
description: Instructs the agent to review design docs and a plan doc and to generate or update the project's README file. Assumes the project contains little-to-no code (or possibly only contains scaffolded template code).
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please review {{DESIGN DOCS}} and {{PLAN DOC}}. Inferring from these, can you please help me update the project's `./README.md` file (or create a new one if one doesn't already exist)? Since we haven't written any code yet, it would probably be appropriate not to be overly-specific regarding technical details yet, but the functional aspects of this project are probably fixed in place enough that you can include them. To be clear, you can also include details about future repo structure, and you can include technical details as well -- I would just like to avoid being painted into a corner by including detail that might necessitate wide-ranging rewrites if the project shifts direction later on.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
___
|
|
2
|
+
name: Work to Commit Message
|
|
3
|
+
description: Instructs the agent to draft or create a commit message that follows the project wave/revision/phase convention.
|
|
4
|
+
___
|
|
5
|
+
|
|
6
|
+
Please prepare a commit message for the current work using the make-docs commit message convention.
|
|
7
|
+
|
|
8
|
+
Before drafting or committing, read `docs/assets/references/commit-message-convention.md`. Use it as the authority for subject shape, body source, and commit execution rules.
|
|
9
|
+
|
|
10
|
+
Inspect the local context first:
|
|
11
|
+
|
|
12
|
+
- `git status --short`
|
|
13
|
+
- recent commit subjects with `git log --format='%h %s' -n 30`
|
|
14
|
+
- the relevant design, plan, work, and history records for the requested coordinate
|
|
15
|
+
- `docs/assets/history/` for current history records, falling back to legacy records only when needed
|
|
16
|
+
|
|
17
|
+
If the user explicitly asks you to commit, stage only the requested change set, create the commit with the drafted subject/body, and verify it with `git log -1 --format=%B`. Do not stage unrelated edits, do not rewrite user work, and do not create a commit when the request is only to draft a message.
|
|
18
|
+
|
|
19
|
+
If the user does not explicitly ask you to commit, return only the proposed commit message in a fenced `text` block plus any brief source note needed to explain where the body came from.
|
|
20
|
+
|
|
21
|
+
Optional hints (leave blank to infer from the repository):
|
|
22
|
+
|
|
23
|
+
- Intent: {{INTENT}}
|
|
24
|
+
- Coordinate: {{COORDINATE}}
|
|
25
|
+
- History record: {{HISTORY_RECORD}}
|
|
26
|
+
- Plan or design path: {{PLAN_OR_DESIGN_PATH}}
|
|
27
|
+
- Commit mode: {{COMMIT_MODE}}
|
|
@@ -0,0 +1,18 @@
|
|
|
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}}
|
|
@@ -0,0 +1,9 @@
|
|
|
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.
|
|
@@ -0,0 +1,9 @@
|
|
|
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.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Commit Message Convention
|
|
2
|
+
|
|
3
|
+
Use this reference when drafting or creating project commits from wave, revision, phase, plan, work, or history artifacts.
|
|
4
|
+
|
|
5
|
+
Commit messages use one short subject line, then one blank line, then one required body paragraph. Prefer copying or deriving the body from the authoritative source document described below; when that source is missing, draft the body from the actual change set.
|
|
6
|
+
|
|
7
|
+
## Output Format
|
|
8
|
+
|
|
9
|
+
Always return one fenced `text` block containing the full commit message:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
subject line
|
|
13
|
+
|
|
14
|
+
body paragraph
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Rules:
|
|
18
|
+
|
|
19
|
+
- Return the subject line, one blank line, and one body paragraph in the same block.
|
|
20
|
+
- Never return only a subject line or title.
|
|
21
|
+
- Keep the body to a single paragraph.
|
|
22
|
+
- Do not include tables, verification lists, source notes, or extra commentary inside the commit message block.
|
|
23
|
+
|
|
24
|
+
Example:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
feat: [W1 R2 P1] CLI Agent Terminology and Help Flags - Active PRD Contract Revision
|
|
28
|
+
|
|
29
|
+
Adds the active PRD revision for REQ02, updates baseline PRD backlinks, and marks W1 R2 P1 complete so downstream parser and documentation phases can cite the effective `--agent`, `-a`, help, and rejected `--harness` contract.
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Document Commits
|
|
33
|
+
|
|
34
|
+
Use document commits for documentation changes that don't fit into the other categories.
|
|
35
|
+
|
|
36
|
+
Subject:
|
|
37
|
+
|
|
38
|
+
If a wave or revision is indicated, use `[W{wave} R{revision}]` to indicate the wave and revision. Example:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
docs: [W{wave} R{revision}] {documentation target purpose}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
If documentation is specific to a phase, use `[W{wave} R{revision} P{phase}]` to indicate the wave, revision, and phase. Example:
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
docs: [W{wave} R{revision} P{phase}] {documentation target purpose}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Otherwise simply capture the document purpose in the subject line.
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
docs: {document target purpose}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Rules:
|
|
57
|
+
|
|
58
|
+
- If a wave or revision was not specified or defined while creating the documentation, do not include them in the subject line.
|
|
59
|
+
- Otherwise, include them in the subject line.
|
|
60
|
+
- Do not make up wave, revision, or phase coordinates that are not present in the source document.
|
|
61
|
+
|
|
62
|
+
Body:
|
|
63
|
+
|
|
64
|
+
- Summarize the changes made to the documentation in a single paragraph.
|
|
65
|
+
- Do not include tables, verification lists, or extra commentary in the commit body.
|
|
66
|
+
- DO include links to relevant documentation sections or files, but only if they are directly relevant to the changes.
|
|
67
|
+
- Favor the principle of progressive-disclosure, and only include links that, if followed, would provide immediate context for the changes.
|
|
68
|
+
|
|
69
|
+
## Feature Commits
|
|
70
|
+
|
|
71
|
+
Use feature commits for implemented phase work.
|
|
72
|
+
|
|
73
|
+
Subject:
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
feat: [W{wave} R{revision} P{phase-or-range}] {wave name} - {phase name}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Rules:
|
|
80
|
+
|
|
81
|
+
- Include wave, revision, and phase inside square brackets.
|
|
82
|
+
- Use `P1`, `P5`, or a phase range such as `P1-2`.
|
|
83
|
+
- Do not include commas in the coordinate. Use `[W8 R0 P5]`, not legacy `[W8, R0, P5]`.
|
|
84
|
+
- Use the wave name from the plan/work/history title.
|
|
85
|
+
- Use the phase name from the implemented work phase or matching history record.
|
|
86
|
+
- If the phase commit intentionally spans multiple phases, use the exact phase range and a concise combined phase label.
|
|
87
|
+
|
|
88
|
+
Body:
|
|
89
|
+
|
|
90
|
+
- Copy the first paragraph under `## Changes` from the matching history record.
|
|
91
|
+
- Prefer `docs/assets/history/`.
|
|
92
|
+
- If the repo has not migrated yet, accept legacy history records identified by the legacy router.
|
|
93
|
+
- Do not include tables, documentation sections, verification lists, or extra commentary in the commit body.
|
|
94
|
+
|
|
95
|
+
Example:
|
|
96
|
+
|
|
97
|
+
```text
|
|
98
|
+
feat: [W8 R0 P5] CLI command simplification - Apply and sync output polish
|
|
99
|
+
|
|
100
|
+
Implemented a Wave 8 follow-up phase for the `make-docs` apply/sync review output, framed by the command simplification design (`docs/designs/2026-04-20-cli-command-simplification.md`) and the completed Phase 4 validation work in the Phase 4 history record (`docs/assets/history/2026-04-20-w8-r0-p4-cli-command-simplification.md`). This phase focused on making the already-installed no-op sync readout clearer, less redundant, and consistent with Clack-rendered CLI screens.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Plan Commits
|
|
104
|
+
|
|
105
|
+
Use plan commits for pre-work planning, design, decomposition, or backlog generation that establishes a wave/revision before implementation phases are committed.
|
|
106
|
+
|
|
107
|
+
Subject:
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
plan: [W{wave} R{revision}] {wave name}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Rules:
|
|
114
|
+
|
|
115
|
+
- Include wave and revision inside square brackets.
|
|
116
|
+
- Do not include phase in plan commit coordinates.
|
|
117
|
+
- Do not include commas in the coordinate. Use `[W9 R0]`, not legacy `[W9, R0]`.
|
|
118
|
+
- Use the wave name from the design, plan overview, or work index.
|
|
119
|
+
|
|
120
|
+
Body:
|
|
121
|
+
|
|
122
|
+
- Copy the first paragraph under `## Purpose` from the design document that seeded the plan.
|
|
123
|
+
- If there is no clear design document, copy the first paragraph under `## Purpose` from the plan overview.
|
|
124
|
+
- If neither source has a clean first paragraph, draft a concise one-paragraph body from the actual staged or unstaged diff being summarized.
|
|
125
|
+
|
|
126
|
+
Example:
|
|
127
|
+
|
|
128
|
+
```text
|
|
129
|
+
plan: [W9 R1] Docs Assets Resource Namespace Overhaul
|
|
130
|
+
|
|
131
|
+
Define the replacement architecture for non-project document resources under `docs/` after Wave 9. The new model removes the collection of top-level hidden resource directories, consolidates document resources under one visible `docs/assets/` directory, and moves make-docs runtime state out of `docs/` into root `.make-docs/`.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Inference Workflow
|
|
135
|
+
|
|
136
|
+
Use this workflow when the user asks for a commit message but does not provide the exact commit kind, coordinate, or label.
|
|
137
|
+
|
|
138
|
+
Commit kind:
|
|
139
|
+
|
|
140
|
+
- Use `feat:` when the change set implements phase work, especially source, tests, generated template assets, packaged docs, or behavior described by a work phase.
|
|
141
|
+
- Use `plan:` when the change set creates or updates pre-implementation design, plan, decomposition, or backlog artifacts and does not implement the phase itself.
|
|
142
|
+
- If the change set includes both planning docs and implementation work, prefer `feat:` when implementation files are part of the requested commit; otherwise prefer `plan:`.
|
|
143
|
+
|
|
144
|
+
Coordinate:
|
|
145
|
+
|
|
146
|
+
Resolve the coordinate in this order, stopping at the first unambiguous match:
|
|
147
|
+
|
|
148
|
+
1. Explicit user-provided coordinate or commit kind.
|
|
149
|
+
2. Matching history record frontmatter, title, or filename.
|
|
150
|
+
3. Changed work phase path such as `docs/work/YYYY-MM-DD-w8-r0-<slug>/05-<phase>.md`.
|
|
151
|
+
4. Changed plan phase path such as `docs/plans/YYYY-MM-DD-w8-r0-<slug>/05-<phase>.md`.
|
|
152
|
+
5. Changed plan overview, work index, or design metadata for wave/revision-only plan work.
|
|
153
|
+
6. Branch name or current task name if it contains `w{wave}-r{revision}` and optional `p{phase}`.
|
|
154
|
+
7. Nearby recent commit subjects that share the same changed wave slug and continue the phase sequence.
|
|
155
|
+
|
|
156
|
+
Names:
|
|
157
|
+
|
|
158
|
+
- Derive the wave name from the design H1, plan overview H1, work index H1, or history record H1.
|
|
159
|
+
- Remove suffixes such as `- Implementation Plan`, `- Work Backlog`, or `- Phase N: ...` when deriving the wave name.
|
|
160
|
+
- Derive the phase name from the matching work phase heading, plan phase heading, or history record title.
|
|
161
|
+
- Remove leading `Phase N`, `Phase N:`, or equivalent numbering from the phase name before placing it after ` - `.
|
|
162
|
+
|
|
163
|
+
Body source:
|
|
164
|
+
|
|
165
|
+
- For `feat:`, use the matching history record `## Changes` first paragraph.
|
|
166
|
+
- For `plan:`, use the seeding design `## Purpose` first paragraph, then the plan overview `## Purpose` first paragraph.
|
|
167
|
+
- If the expected body source is missing, draft a concise one-paragraph body from the actual staged or unstaged diff being summarized.
|
|
168
|
+
- Do not invent source-document facts for a fallback body; describe only what the diff, changed paths, and nearby plan/work artifacts support.
|
|
169
|
+
|
|
170
|
+
Ambiguity:
|
|
171
|
+
|
|
172
|
+
- If one coordinate is clearly dominant from changed paths and docs, use it.
|
|
173
|
+
- If multiple plausible coordinates remain, draft the best candidate with a source note, but do not create a commit without user confirmation.
|
|
174
|
+
- If staged files and unstaged files point to different coordinates, use only the staged set when the user has staged changes; otherwise ask which change set should be committed.
|
|
175
|
+
|
|
176
|
+
## Source Resolution
|
|
177
|
+
|
|
178
|
+
Before drafting or committing:
|
|
179
|
+
|
|
180
|
+
- Inspect `git status --short` to understand the staged and unstaged change set.
|
|
181
|
+
- Inspect recent history with `git log --format='%h %s' -n 30` to preserve the current naming style.
|
|
182
|
+
- Find the relevant coordinate from the changed files, branch name, plan/work paths, history record frontmatter, or nearby commit subjects.
|
|
183
|
+
- For feature commits, read the matching history record and extract only the first `## Changes` paragraph.
|
|
184
|
+
- For plan commits, read the seeding design first, then the plan overview if needed, and extract only the first `## Purpose` paragraph.
|
|
185
|
+
- If the preferred body source is missing, inspect the relevant staged or unstaged diff and draft one concise body paragraph from that change set.
|
|
186
|
+
- If the source documents disagree, prefer the artifact closest to the committed work: history records for feature work, design or plan overview for plan work.
|
|
187
|
+
|
|
188
|
+
## Commit Execution
|
|
189
|
+
|
|
190
|
+
Only create the commit when the user explicitly asks for a commit.
|
|
191
|
+
|
|
192
|
+
When committing:
|
|
193
|
+
|
|
194
|
+
- Stage only files that belong to the requested change set.
|
|
195
|
+
- Do not stage unrelated user edits.
|
|
196
|
+
- Do not rewrite, revert, or clean existing user changes to make the commit easier.
|
|
197
|
+
- Use `git commit` with the full subject-plus-body block exactly as drafted.
|
|
198
|
+
- Verify both subject and body with `git log -1 --format=%B`.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Design Contract
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this contract for agent-generated design docs under `docs/designs/`.
|
|
6
|
+
|
|
7
|
+
User-authored design docs may not fully conform. Apply this contract to newly generated design docs and to substantial agent-authored updates.
|
|
8
|
+
|
|
9
|
+
## Required Path
|
|
10
|
+
|
|
11
|
+
- `docs/designs/YYYY-MM-DD-<slug>.md`
|
|
12
|
+
|
|
13
|
+
`YYYY-MM-DD` is today's date (never backdated). `<slug>` is lowercase, hyphens only.
|
|
14
|
+
|
|
15
|
+
## Archiving
|
|
16
|
+
|
|
17
|
+
Archive designs only when the user explicitly asks. Never archive proactively.
|
|
18
|
+
|
|
19
|
+
Defer to `docs/assets/archive/AGENTS.md` for archive structure and procedure.
|
|
20
|
+
|
|
21
|
+
## Required Headings
|
|
22
|
+
|
|
23
|
+
Generated design docs must include:
|
|
24
|
+
|
|
25
|
+
- `## Purpose`
|
|
26
|
+
- `## Context`
|
|
27
|
+
- `## Decision`
|
|
28
|
+
- `## Alternatives Considered`
|
|
29
|
+
- `## Consequences`
|
|
30
|
+
- `## Intended Follow-On`
|
|
31
|
+
|
|
32
|
+
## Intended Follow-On Contract
|
|
33
|
+
|
|
34
|
+
The `## Intended Follow-On` section must include:
|
|
35
|
+
|
|
36
|
+
- `Route:` `baseline-plan` or `change-plan`
|
|
37
|
+
- `Next Prompt:` a relative Markdown link to the matching prompt template
|
|
38
|
+
- `Why:` a short explanation of why that route is the correct downstream workflow
|
|
39
|
+
- `Coordinate Handoff:` when known, a short note that names the related completed coordinate and the recommended downstream W/R coordinate
|
|
40
|
+
|
|
41
|
+
Required prompt targets:
|
|
42
|
+
|
|
43
|
+
- `baseline-plan` → `[designs-to-plan.prompt.md](../prompts/designs-to-plan.prompt.md)`
|
|
44
|
+
- `change-plan` → `[designs-to-plan-change.prompt.md](../prompts/designs-to-plan-change.prompt.md)`
|
|
45
|
+
|
|
46
|
+
For `change-plan` designs, include `Coordinate Handoff` whenever the design revises, reworks, corrects, standardizes, or finishes earlier wave work. The handoff should identify the prior coordinate, the recommended downstream coordinate, and the basis for treating the work as a revision rather than a new wave. If the coordinate cannot be resolved from the request or repository history, write `Coordinate Handoff: unresolved; planner must resolve before writing.`
|
|
47
|
+
|
|
48
|
+
## Optional Design Lineage
|
|
49
|
+
|
|
50
|
+
Add `## Design Lineage` when a generated design materially updates prior design intent or when a new design doc is closely related to an earlier design.
|
|
51
|
+
|
|
52
|
+
When present, include:
|
|
53
|
+
|
|
54
|
+
- `Update Mode:` `updated-existing` or `new-doc-related`
|
|
55
|
+
- `Prior Design Docs:` relative Markdown links
|
|
56
|
+
- `Reason:` a short explanation of the lineage relationship
|
|
57
|
+
|
|
58
|
+
## Link Rules
|
|
59
|
+
|
|
60
|
+
- Use relative Markdown links between design docs and related plans, PRD docs, or work items.
|
|
61
|
+
- Apply `docs/assets/references/path-and-link-hygiene.md` for repo-relative path rules, sanitized placeholders, and full-path exceptions.
|
|
62
|
+
- If a design is intended to feed planning, the `Next Prompt` link in `## Intended Follow-On` must resolve.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Design Workflow
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Use this workflow when the user wants to turn a request into one or more design docs before planning, PRD generation, or backlog generation.
|
|
6
|
+
|
|
7
|
+
This workflow ends with design docs in `docs/designs/` using the form `docs/designs/YYYY-MM-DD-<slug>.md`. It does not draft a plan.
|
|
8
|
+
|
|
9
|
+
## Preflight
|
|
10
|
+
|
|
11
|
+
Before writing:
|
|
12
|
+
|
|
13
|
+
1. Inspect `docs/designs/` for related design docs.
|
|
14
|
+
2. Inspect related plans, PRD docs, or work backlogs only as needed for context or route classification.
|
|
15
|
+
3. Determine whether the request belongs to the same decision area as an existing design.
|
|
16
|
+
4. Choose whether to update an existing design or create a new dated design doc.
|
|
17
|
+
|
|
18
|
+
## Create Vs Update Rules
|
|
19
|
+
|
|
20
|
+
- Prefer updating an existing design when the request clearly concerns the same decision area and the existing doc can absorb the change without obscuring prior intent.
|
|
21
|
+
- Create a new dated design doc when no clear related design exists, when the request spans a distinct decision area, or when a substantial direction change would make the existing design misleading.
|
|
22
|
+
- One design doc is the default output unit. Create more than one only when the request clearly spans multiple distinct decision areas.
|
|
23
|
+
|
|
24
|
+
## Lineage Rules
|
|
25
|
+
|
|
26
|
+
- If a generated update materially changes prior design intent, add an optional `## Design Lineage` section before `## Intended Follow-On`.
|
|
27
|
+
- Use `## Design Lineage` to record:
|
|
28
|
+
- `Update Mode:` `updated-existing` or `new-doc-related`
|
|
29
|
+
- `Prior Design Docs:` relative links to the earlier design docs
|
|
30
|
+
- `Reason:` a short explanation of why the prior design was updated or why a related new design doc was needed
|
|
31
|
+
- If the request is only a minor clarification and does not materially change prior design intent, the lineage section is optional.
|
|
32
|
+
|
|
33
|
+
## Intended Follow-On Rules
|
|
34
|
+
|
|
35
|
+
- Every generated design doc must include `## Intended Follow-On`.
|
|
36
|
+
- Allowed `Route` values:
|
|
37
|
+
- `baseline-plan`
|
|
38
|
+
- `change-plan`
|
|
39
|
+
- Required prompt links:
|
|
40
|
+
- `baseline-plan` → `docs/assets/prompts/designs-to-plan.prompt.md`
|
|
41
|
+
- `change-plan` → `docs/assets/prompts/designs-to-plan-change.prompt.md`
|
|
42
|
+
- Downstream planners should treat the explicit route in `## Intended Follow-On` as authoritative unless the user explicitly overrides it.
|
|
43
|
+
- Route guidance:
|
|
44
|
+
- use `baseline-plan` when the design should feed a fresh baseline planning flow
|
|
45
|
+
- use `change-plan` when the design should feed additive change, enhancement, revision, or removal planning against the active PRD namespace
|
|
46
|
+
|
|
47
|
+
## Stop Rule
|
|
48
|
+
|
|
49
|
+
- Stop after the design docs are created or updated.
|
|
50
|
+
- Do not draft a plan as part of the request-to-design workflow.
|
|
51
|
+
|
|
52
|
+
## Validation Checklist
|
|
53
|
+
|
|
54
|
+
Before closing the task, confirm:
|
|
55
|
+
|
|
56
|
+
1. The output lives in `docs/designs/` and follows `YYYY-MM-DD-<slug>.md` naming.
|
|
57
|
+
2. The generated design uses the required design template structure.
|
|
58
|
+
3. The create-vs-update choice is justified by the current design tree.
|
|
59
|
+
4. `## Design Lineage` is present when the design materially updates prior intent.
|
|
60
|
+
5. `## Intended Follow-On` includes both the route and the matching prompt link.
|
|
@@ -0,0 +1,157 @@
|
|
|
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.
|