drawbore 0.1.0 → 0.1.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/CHANGELOG.md +28 -20
- package/LICENSE +20 -20
- package/README.md +75 -75
- package/bin/drawbore.js +334 -266
- package/lib/checker.js +398 -398
- package/lib/index.js +3 -1
- package/lib/installer.js +404 -404
- package/lib/prompts.js +375 -373
- package/package.json +42 -42
- package/skills/discover/SKILL.md +76 -76
- package/skills/frame/SKILL.md +84 -84
- package/skills/frame/references/change-brief.md +54 -54
- package/skills/init-project/SKILL.md +85 -85
- package/skills/recall/SKILL.md +61 -61
- package/skills/record/SKILL.md +98 -98
- package/skills/record/references/artifact-formats.md +130 -130
- package/skills/release/SKILL.md +107 -107
- package/skills/review/SKILL.md +116 -116
- package/templates/instruction.md +8 -8
- package/templates/manifest.json +11 -11
- package/templates/record/context.md +13 -13
- package/templates/record/glossary.md +6 -6
- package/templates/record/index.md +15 -15
- package/templates/record/principles.md +2 -2
- package/templates/record/stack.md +6 -6
- package/templates/record/system.md +2 -2
|
@@ -1,86 +1,86 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: init-project
|
|
3
|
-
description: Scaffold a new project repository in a provider-neutral way — README, LICENSE, CHANGELOG, .gitattributes, .gitignore, a root AGENTS.md with a ## Release section, and a package manifest when the project publishes a package. Generates a release pipeline from the project's answers when a CI provider is named and a pipeline is wanted, and lists the manual setup steps that cannot live in files (forge mirror configuration, registry publishing setup). Use when starting a new repository, standardizing an existing one's project-level files, or setting up a release pipeline.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Initialize a project
|
|
7
|
-
|
|
8
|
-
This skill owns the **repository layer only**. It does not assume a forge, a registry, a CI provider, or a language ecosystem. Ask the user before generating anything:
|
|
9
|
-
|
|
10
|
-
1. **Project name and repository path.**
|
|
11
|
-
2. **Public or private?** If public and mirrored to another forge, note it; mirror setup is manual (see the checklist).
|
|
12
|
-
3. **Does it publish a package?** If yes, settle the package name now: verify availability with the registry's lookup command (`npm view <name> version`, `cargo search <name>`, `pip index versions <name>`, or the ecosystem equivalent). Remember that many registries never recycle names — a bare name may be a dead package forever. Follow the ecosystem's naming conventions.
|
|
13
|
-
4. **Primary language and package manager**, so ignore rules and manifests match reality.
|
|
14
|
-
|
|
15
|
-
## Files to generate
|
|
16
|
-
|
|
17
|
-
- `.gitattributes` — `* text=auto eol=lf`. CRLF from Windows working trees otherwise creeps into published archives and diffs.
|
|
18
|
-
- `LICENSE` — the license the user chooses, current year, consistent copyright line.
|
|
19
|
-
- `CHANGELOG.md` — dated sections (Keep a Changelog style) with compare links between tags on the canonical forge.
|
|
20
|
-
- `README.md` — title, one-paragraph description, install and use sections, and a build/test badge if the forge provides one. If the repository is mirrored, state which forge is canonical and that issues and releases live there.
|
|
21
|
-
- `.gitignore` — language-appropriate, minimal. Never ignore a path that carries project truth the user wants shared.
|
|
22
|
-
- `AGENTS.md` (repository root, committed) — include a `## Release` section:
|
|
23
|
-
```markdown
|
|
24
|
-
## Release
|
|
25
|
-
- package: <name, or: none — repository-only project>
|
|
26
|
-
- package shape: <library | cli | application | assets | other>
|
|
27
|
-
- build needed before release: <no | exact steps>
|
|
28
|
-
- version stamps: <files whose contents carry vX.Y.Z>
|
|
29
|
-
- publish targets: <registry or artifact store, or none>
|
|
30
|
-
- publish mode: <staged | direct | none>
|
|
31
|
-
- pipeline: <path to the CI file, or none — release manually>
|
|
32
|
-
- verify after release: <commands or URLs that prove the release>
|
|
33
|
-
```
|
|
34
|
-
The `release` skill reads this at every release — it must stay accurate. `publish mode` decides which publish tail runs; `pipeline` says whether a pipeline exists to run it.
|
|
35
|
-
- `package.json` (or the ecosystem manifest) — **only if publishing**: name, `version: 0.1.0`, the files whitelist (ship only what consumers need), repository and bug-tracker URLs pointing at the **canonical** forge, and any ecosystem-specific entry field the registry requires.
|
|
36
|
-
- CI configuration — **only when the user names a CI provider and asks for it.** Never add a workflow file for a provider the project does not use, and never for a forge that only mirrors the repository: a mirror does not carry tags, so tag-triggered jobs there can never fire. When a pipeline is wanted, generate it from the answers under "Generate the pipeline" — do not copy a template — and record its path under `pipeline:` in `## Release`.
|
|
37
|
-
|
|
38
|
-
This skill owns the repository layer only. Do not scaffold language-specific build setups that vary per project (native executables, framework solutions, container recipes); those are built separately when the user asks.
|
|
39
|
-
|
|
40
|
-
## Manual steps that cannot live in files (print as a checklist)
|
|
41
|
-
|
|
42
|
-
1. **Mirror (public only):** configure the push mirror in the canonical forge's repository settings. Tags may not mirror — that is expected and fine.
|
|
43
|
-
2. **First publication:** if the package does not exist on the registry, publish the first version once with an authenticated account. A brand-new package cannot configure a trusted publisher until it has been published at least once — the bootstrap publish is what makes CI-based publishing available, not a workaround for it. Do not commit a long-lived registry token in its place.
|
|
44
|
-
3. **Registry publishing identity:** configure whatever the registry requires for CI-based publishing (trusted publisher, OIDC binding, or a scoped token) **right before the first release**, not at project creation — a fresh configuration can expire if no real publish completes within its validity window. Complete that first real publish inside the window.
|
|
45
|
-
4. **Registry hardening (once):** require two-factor authentication and disallow long-lived tokens where the registry supports it. OIDC-based publishing is unaffected.
|
|
46
|
-
|
|
47
|
-
## Generate the pipeline
|
|
48
|
-
|
|
49
|
-
Only when the user named a CI provider and asked for a pipeline. Settle three answers first, then write the file; every shape below follows from them.
|
|
50
|
-
|
|
51
|
-
1. **Publish mode** — `none`, `direct`, or `staged`.
|
|
52
|
-
- `none`: the pipeline builds and tests, and never publishes.
|
|
53
|
-
- `direct`: CI publishes with a registry token or OIDC identity in one step.
|
|
54
|
-
- `staged`: CI stages the version and a maintainer approves it out of band. Choose this when the registry supports a staging area and you want human approval before publication.
|
|
55
|
-
2. **Build steps** — the exact commands that produce what ships, or `none` when the manifest ships source as-is. Anything the package needs at publish time (compile, bundle, minify, copy assets) goes here, before the publish step.
|
|
56
|
-
3. **Provider** — the forge whose CI runs the pipeline. The release itself still uses the canonical forge's remote; the provider only decides the file name and syntax.
|
|
57
|
-
|
|
58
|
-
### Required job content (every shape)
|
|
59
|
-
|
|
60
|
-
- Trigger on tags matching the release tag pattern, and nothing else. Release pipelines exist to run at the tagged commit.
|
|
61
|
-
- Gate: fail when the tag does not match `v` + the manifest version. A mismatched tag publishes the wrong version.
|
|
62
|
-
- Gate: fail when the version is already on the registry. Registry versions are immutable — a re-push cannot succeed, and the pipeline is only exercised by real new version tags.
|
|
63
|
-
- Run the project's own checks before publishing (`npm ci && npm test`, or the ecosystem equivalent). Never publish an artifact the tests have not seen.
|
|
64
|
-
- Print what will ship, then publish. For `staged`, print the approval command the maintainer must run.
|
|
65
|
-
|
|
66
|
-
### Shape by publish mode
|
|
67
|
-
|
|
68
|
-
| Mode | Steps, in order |
|
|
69
|
-
|---|---|
|
|
70
|
-
| `none` | build → test → verify (tag exists, changelog link resolves) |
|
|
71
|
-
| `direct` | build → test → publish with the registry's CI credential |
|
|
72
|
-
| `staged` | build → test → stage publish → print `stage list` / `stage approve` for the maintainer |
|
|
73
|
-
|
|
74
|
-
### Provider file names
|
|
75
|
-
|
|
76
|
-
| Provider | File | Notes |
|
|
77
|
-
|---|---|---|
|
|
78
|
-
| GitLab | `.gitlab-ci.yml` | Needs `id_tokens` for the registry audience; the publish job must declare a matching `environment: name:` when the registry's trusted-publisher config sets one, or publishing 403s. |
|
|
79
|
-
| GitHub | `.github/workflows/release.yml` | Tag-triggered; `id-token: write` on the publish job only. |
|
|
80
|
-
| Other | whatever the provider documents | State the file name in `## Release`, and say plainly that Drawbore has no template for it. |
|
|
81
|
-
|
|
82
|
-
The `release` skill's provider notes carry the version floors, token audiences, and YAML parser traps that apply to these files — read them before writing pipeline YAML.
|
|
83
|
-
|
|
84
|
-
Record the result in `## Release`: `publish mode: <mode>` and `pipeline: <path>`. When the user declines a pipeline, write `pipeline: none — release manually` so the release skill knows to skip the publish tail.
|
|
85
|
-
|
|
1
|
+
---
|
|
2
|
+
name: init-project
|
|
3
|
+
description: Scaffold a new project repository in a provider-neutral way — README, LICENSE, CHANGELOG, .gitattributes, .gitignore, a root AGENTS.md with a ## Release section, and a package manifest when the project publishes a package. Generates a release pipeline from the project's answers when a CI provider is named and a pipeline is wanted, and lists the manual setup steps that cannot live in files (forge mirror configuration, registry publishing setup). Use when starting a new repository, standardizing an existing one's project-level files, or setting up a release pipeline.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Initialize a project
|
|
7
|
+
|
|
8
|
+
This skill owns the **repository layer only**. It does not assume a forge, a registry, a CI provider, or a language ecosystem. Ask the user before generating anything:
|
|
9
|
+
|
|
10
|
+
1. **Project name and repository path.**
|
|
11
|
+
2. **Public or private?** If public and mirrored to another forge, note it; mirror setup is manual (see the checklist).
|
|
12
|
+
3. **Does it publish a package?** If yes, settle the package name now: verify availability with the registry's lookup command (`npm view <name> version`, `cargo search <name>`, `pip index versions <name>`, or the ecosystem equivalent). Remember that many registries never recycle names — a bare name may be a dead package forever. Follow the ecosystem's naming conventions.
|
|
13
|
+
4. **Primary language and package manager**, so ignore rules and manifests match reality.
|
|
14
|
+
|
|
15
|
+
## Files to generate
|
|
16
|
+
|
|
17
|
+
- `.gitattributes` — `* text=auto eol=lf`. CRLF from Windows working trees otherwise creeps into published archives and diffs.
|
|
18
|
+
- `LICENSE` — the license the user chooses, current year, consistent copyright line.
|
|
19
|
+
- `CHANGELOG.md` — dated sections (Keep a Changelog style) with compare links between tags on the canonical forge.
|
|
20
|
+
- `README.md` — title, one-paragraph description, install and use sections, and a build/test badge if the forge provides one. If the repository is mirrored, state which forge is canonical and that issues and releases live there.
|
|
21
|
+
- `.gitignore` — language-appropriate, minimal. Never ignore a path that carries project truth the user wants shared.
|
|
22
|
+
- `AGENTS.md` (repository root, committed) — include a `## Release` section:
|
|
23
|
+
```markdown
|
|
24
|
+
## Release
|
|
25
|
+
- package: <name, or: none — repository-only project>
|
|
26
|
+
- package shape: <library | cli | application | assets | other>
|
|
27
|
+
- build needed before release: <no | exact steps>
|
|
28
|
+
- version stamps: <files whose contents carry vX.Y.Z>
|
|
29
|
+
- publish targets: <registry or artifact store, or none>
|
|
30
|
+
- publish mode: <staged | direct | none>
|
|
31
|
+
- pipeline: <path to the CI file, or none — release manually>
|
|
32
|
+
- verify after release: <commands or URLs that prove the release>
|
|
33
|
+
```
|
|
34
|
+
The `release` skill reads this at every release — it must stay accurate. `publish mode` decides which publish tail runs; `pipeline` says whether a pipeline exists to run it.
|
|
35
|
+
- `package.json` (or the ecosystem manifest) — **only if publishing**: name, `version: 0.1.0`, the files whitelist (ship only what consumers need), repository and bug-tracker URLs pointing at the **canonical** forge, and any ecosystem-specific entry field the registry requires.
|
|
36
|
+
- CI configuration — **only when the user names a CI provider and asks for it.** Never add a workflow file for a provider the project does not use, and never for a forge that only mirrors the repository: a mirror does not carry tags, so tag-triggered jobs there can never fire. When a pipeline is wanted, generate it from the answers under "Generate the pipeline" — do not copy a template — and record its path under `pipeline:` in `## Release`.
|
|
37
|
+
|
|
38
|
+
This skill owns the repository layer only. Do not scaffold language-specific build setups that vary per project (native executables, framework solutions, container recipes); those are built separately when the user asks.
|
|
39
|
+
|
|
40
|
+
## Manual steps that cannot live in files (print as a checklist)
|
|
41
|
+
|
|
42
|
+
1. **Mirror (public only):** configure the push mirror in the canonical forge's repository settings. Tags may not mirror — that is expected and fine.
|
|
43
|
+
2. **First publication:** if the package does not exist on the registry, publish the first version once with an authenticated account. A brand-new package cannot configure a trusted publisher until it has been published at least once — the bootstrap publish is what makes CI-based publishing available, not a workaround for it. Do not commit a long-lived registry token in its place.
|
|
44
|
+
3. **Registry publishing identity:** configure whatever the registry requires for CI-based publishing (trusted publisher, OIDC binding, or a scoped token) **right before the first release**, not at project creation — a fresh configuration can expire if no real publish completes within its validity window. Complete that first real publish inside the window.
|
|
45
|
+
4. **Registry hardening (once):** require two-factor authentication and disallow long-lived tokens where the registry supports it. OIDC-based publishing is unaffected.
|
|
46
|
+
|
|
47
|
+
## Generate the pipeline
|
|
48
|
+
|
|
49
|
+
Only when the user named a CI provider and asked for a pipeline. Settle three answers first, then write the file; every shape below follows from them.
|
|
50
|
+
|
|
51
|
+
1. **Publish mode** — `none`, `direct`, or `staged`.
|
|
52
|
+
- `none`: the pipeline builds and tests, and never publishes.
|
|
53
|
+
- `direct`: CI publishes with a registry token or OIDC identity in one step.
|
|
54
|
+
- `staged`: CI stages the version and a maintainer approves it out of band. Choose this when the registry supports a staging area and you want human approval before publication.
|
|
55
|
+
2. **Build steps** — the exact commands that produce what ships, or `none` when the manifest ships source as-is. Anything the package needs at publish time (compile, bundle, minify, copy assets) goes here, before the publish step.
|
|
56
|
+
3. **Provider** — the forge whose CI runs the pipeline. The release itself still uses the canonical forge's remote; the provider only decides the file name and syntax.
|
|
57
|
+
|
|
58
|
+
### Required job content (every shape)
|
|
59
|
+
|
|
60
|
+
- Trigger on tags matching the release tag pattern, and nothing else. Release pipelines exist to run at the tagged commit.
|
|
61
|
+
- Gate: fail when the tag does not match `v` + the manifest version. A mismatched tag publishes the wrong version.
|
|
62
|
+
- Gate: fail when the version is already on the registry. Registry versions are immutable — a re-push cannot succeed, and the pipeline is only exercised by real new version tags.
|
|
63
|
+
- Run the project's own checks before publishing (`npm ci && npm test`, or the ecosystem equivalent). Never publish an artifact the tests have not seen.
|
|
64
|
+
- Print what will ship, then publish. For `staged`, print the approval command the maintainer must run.
|
|
65
|
+
|
|
66
|
+
### Shape by publish mode
|
|
67
|
+
|
|
68
|
+
| Mode | Steps, in order |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `none` | build → test → verify (tag exists, changelog link resolves) |
|
|
71
|
+
| `direct` | build → test → publish with the registry's CI credential |
|
|
72
|
+
| `staged` | build → test → stage publish → print `stage list` / `stage approve` for the maintainer |
|
|
73
|
+
|
|
74
|
+
### Provider file names
|
|
75
|
+
|
|
76
|
+
| Provider | File | Notes |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| GitLab | `.gitlab-ci.yml` | Needs `id_tokens` for the registry audience; the publish job must declare a matching `environment: name:` when the registry's trusted-publisher config sets one, or publishing 403s. |
|
|
79
|
+
| GitHub | `.github/workflows/release.yml` | Tag-triggered; `id-token: write` on the publish job only. |
|
|
80
|
+
| Other | whatever the provider documents | State the file name in `## Release`, and say plainly that Drawbore has no template for it. |
|
|
81
|
+
|
|
82
|
+
The `release` skill's provider notes carry the version floors, token audiences, and YAML parser traps that apply to these files — read them before writing pipeline YAML.
|
|
83
|
+
|
|
84
|
+
Record the result in `## Release`: `publish mode: <mode>` and `pipeline: <path>`. When the user declines a pipeline, write `pipeline: none — release manually` so the release skill knows to skip the publish tail.
|
|
85
|
+
|
|
86
86
|
After scaffolding: commit, push to the canonical forge, then cut the first release with the `release` skill.
|
package/skills/recall/SKILL.md
CHANGED
|
@@ -1,62 +1,62 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: recall
|
|
3
|
-
description: Use this skill when a project's Drawbore instruction directs you to consult durable context before work or reconcile the implementation with project truth afterward. It reads principles, glossary, decisions, current behavior, technical choices, and active Change Briefs, then surfaces conflicts and offers specific context updates.
|
|
4
|
-
license: MIT
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Recall project context
|
|
8
|
-
|
|
9
|
-
Use the current working-tree `.drawbore/` as curated project truth, including tracked records and intentionally local or ignored Change Briefs. Do not duplicate its content in the conversation and do not silently change it.
|
|
10
|
-
|
|
11
|
-
## Resolve the record
|
|
12
|
-
|
|
13
|
-
1. Resolve the project root. Prefer the version-control repository root; otherwise use the current working directory.
|
|
14
|
-
2. Read `.drawbore/index.md` when it exists. Treat it as a map, not an exhaustive inventory. **Enumerate `decisions/` by listing the directory (do not rely on the index alone) and read every `accepted` decision whose subject overlaps the requested change.** Skipping `decisions/` before a change that touches current truth is a consultation failure: a superseding decision cannot be identified if the owning record was never read.
|
|
15
|
-
3. Read the relevant durable records and active Change Briefs:
|
|
16
|
-
- `context.md` — purpose, scope, architecture, and relationships;
|
|
17
|
-
- `glossary.md` — canonical terms and discouraged aliases;
|
|
18
|
-
- `principles.md` — rules that constrain future work;
|
|
19
|
-
- `decisions/` — durable choices and their rationale;
|
|
20
|
-
- `system.md` — current shipped capabilities and contracts;
|
|
21
|
-
- `stack.md` — current technical choices and architecture;
|
|
22
|
-
- `work/` — transient Change Briefs currently being shaped or implemented.
|
|
23
|
-
4. Treat Change Briefs as guidance for the current scope, not as settled project truth.
|
|
24
|
-
5. If the record does not exist, use the `discover` skill when the user wants to adopt Drawbore. Otherwise continue normally and do not create one unasked.
|
|
25
|
-
|
|
26
|
-
## Consult before work
|
|
27
|
-
|
|
28
|
-
Before a feature, bug fix, refactor, design change, or other implementation work:
|
|
29
|
-
|
|
30
|
-
1. Identify the relevant context areas, terms, principles, decisions, current behavior, technical choices, and active Change Briefs. When the change touches a current-truth artifact (`context.md`, `stack.md`, `system.md`, `glossary.md`, `principles.md`) or a domain rule, this MUST include reading `decisions/` — the list step above is not optional for these changes.
|
|
31
|
-
2. If the request conflicts with a principle, decision, term, or boundary, state the conflict, cite the record, and use the `frame` skill to resolve it with the developer before implementation. Stating the conflict alone does not authorize proceeding.
|
|
32
|
-
3. If the request introduces a new durable choice, offer a decision record only when the choice should affect future work.
|
|
33
|
-
4. If purpose, scope, or a boundary remains materially ambiguous, use the `frame` skill to resolve it with the developer before implementation. Do not ask about details the repository or record can answer.
|
|
34
|
-
5. Do not block straightforward implementation on ceremony, but every record write still requires the `record` skill's per-update **apply**, **edit**, or **skip** confirmation.
|
|
35
|
-
|
|
36
|
-
## Reconcile after work
|
|
37
|
-
|
|
38
|
-
After implementation:
|
|
39
|
-
|
|
40
|
-
1. Inspect the actual diff and the behavior exercised by verification. Reconcile only changes attributable to this task; exclude pre-existing and unrelated working-tree changes, and do not propose record updates for changes whose ownership is unclear.
|
|
41
|
-
2. Identify only durable consequences:
|
|
42
|
-
- changed purpose, scope, boundary, terminology, or relationships;
|
|
43
|
-
- a new or revised principle;
|
|
44
|
-
- a durable technical or development decision;
|
|
45
|
-
- changed user-visible behavior or contracts;
|
|
46
|
-
- changed runtime, framework, persistence, or architecture choices;
|
|
47
|
-
- a current-truth artifact (context, stack, system, glossary, principles) whose change supersedes an accepted decision—identify the owning decision and propose superseding it in the same atomic update.
|
|
48
|
-
3. Base current-behavior claims on successful verification that exercised the behavior. Cite the exact developer statement, record section, diff, or verification result supporting each proposal, and label inferences. If verification was absent, failed, or did not exercise the claim, say so and do not present that behavior as verified.
|
|
49
|
-
4. Use the `record` skill to propose the necessary updates.
|
|
50
|
-
5. Present each proposal with its evidence, target record, and rationale. Offer **apply**, **edit**, or **skip**, and wait for the developer's response. **Apply** approves exactly the displayed proposal. **Edit** requests revised wording; it is not consent to write, so display the revision and obtain explicit approval before writing it. **Skip** changes nothing.
|
|
51
|
-
6. When the work touched a current-truth artifact or a domain rule, include an explicit `Decisions consulted: <ids and titles, or "none">` line in the reconcile output. A blank or missing line means the decision records were not consulted, which is the consultation failure the resolution step is meant to prevent.
|
|
52
|
-
7. After the developer approves and the updates are applied, run `drawbore check`. If it reports a structural error (duplicate or mismatched decision IDs, broken supersession, invalid status), propose the correction and re-check before reporting the work reconciled.
|
|
53
|
-
|
|
54
|
-
Do not treat an unreviewed source diff alone as proof that context is stale. Verified behavior, an explicit contract change, or developer confirmation is evidence of a stale current-state record. Treat principles, decisions, terms, and boundaries as governing constraints, and `system.md` and `stack.md` as claims about current state. If records conflict with one another or with verified repository behavior, cite the conflicting sources and do not choose silently. Resolve governing-record conflicts with the developer and propose stale current-state corrections through `record`.
|
|
55
|
-
|
|
56
|
-
## Boundaries
|
|
57
|
-
|
|
58
|
-
- Do not create milestones, task registries, approval gates, or execution plans.
|
|
59
|
-
- Do not assume an issue tracker platform. Use tools the harness provides when external issue state matters.
|
|
60
|
-
- Do not mirror mutable external issue state in the record.
|
|
61
|
-
- Do not treat a Change Brief as settled truth. Settle and remove it only through the `frame` and `record` workflow after acceptance passes and approved durable consequences have been written. Otherwise leave the brief in place.
|
|
1
|
+
---
|
|
2
|
+
name: recall
|
|
3
|
+
description: Use this skill when a project's Drawbore instruction directs you to consult durable context before work or reconcile the implementation with project truth afterward. It reads principles, glossary, decisions, current behavior, technical choices, and active Change Briefs, then surfaces conflicts and offers specific context updates.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Recall project context
|
|
8
|
+
|
|
9
|
+
Use the current working-tree `.drawbore/` as curated project truth, including tracked records and intentionally local or ignored Change Briefs. Do not duplicate its content in the conversation and do not silently change it.
|
|
10
|
+
|
|
11
|
+
## Resolve the record
|
|
12
|
+
|
|
13
|
+
1. Resolve the project root. Prefer the version-control repository root; otherwise use the current working directory.
|
|
14
|
+
2. Read `.drawbore/index.md` when it exists. Treat it as a map, not an exhaustive inventory. **Enumerate `decisions/` by listing the directory (do not rely on the index alone) and read every `accepted` decision whose subject overlaps the requested change.** Skipping `decisions/` before a change that touches current truth is a consultation failure: a superseding decision cannot be identified if the owning record was never read.
|
|
15
|
+
3. Read the relevant durable records and active Change Briefs:
|
|
16
|
+
- `context.md` — purpose, scope, architecture, and relationships;
|
|
17
|
+
- `glossary.md` — canonical terms and discouraged aliases;
|
|
18
|
+
- `principles.md` — rules that constrain future work;
|
|
19
|
+
- `decisions/` — durable choices and their rationale;
|
|
20
|
+
- `system.md` — current shipped capabilities and contracts;
|
|
21
|
+
- `stack.md` — current technical choices and architecture;
|
|
22
|
+
- `work/` — transient Change Briefs currently being shaped or implemented.
|
|
23
|
+
4. Treat Change Briefs as guidance for the current scope, not as settled project truth.
|
|
24
|
+
5. If the record does not exist, use the `discover` skill when the user wants to adopt Drawbore. Otherwise continue normally and do not create one unasked.
|
|
25
|
+
|
|
26
|
+
## Consult before work
|
|
27
|
+
|
|
28
|
+
Before a feature, bug fix, refactor, design change, or other implementation work:
|
|
29
|
+
|
|
30
|
+
1. Identify the relevant context areas, terms, principles, decisions, current behavior, technical choices, and active Change Briefs. When the change touches a current-truth artifact (`context.md`, `stack.md`, `system.md`, `glossary.md`, `principles.md`) or a domain rule, this MUST include reading `decisions/` — the list step above is not optional for these changes.
|
|
31
|
+
2. If the request conflicts with a principle, decision, term, or boundary, state the conflict, cite the record, and use the `frame` skill to resolve it with the developer before implementation. Stating the conflict alone does not authorize proceeding.
|
|
32
|
+
3. If the request introduces a new durable choice, offer a decision record only when the choice should affect future work.
|
|
33
|
+
4. If purpose, scope, or a boundary remains materially ambiguous, use the `frame` skill to resolve it with the developer before implementation. Do not ask about details the repository or record can answer.
|
|
34
|
+
5. Do not block straightforward implementation on ceremony, but every record write still requires the `record` skill's per-update **apply**, **edit**, or **skip** confirmation.
|
|
35
|
+
|
|
36
|
+
## Reconcile after work
|
|
37
|
+
|
|
38
|
+
After implementation:
|
|
39
|
+
|
|
40
|
+
1. Inspect the actual diff and the behavior exercised by verification. Reconcile only changes attributable to this task; exclude pre-existing and unrelated working-tree changes, and do not propose record updates for changes whose ownership is unclear.
|
|
41
|
+
2. Identify only durable consequences:
|
|
42
|
+
- changed purpose, scope, boundary, terminology, or relationships;
|
|
43
|
+
- a new or revised principle;
|
|
44
|
+
- a durable technical or development decision;
|
|
45
|
+
- changed user-visible behavior or contracts;
|
|
46
|
+
- changed runtime, framework, persistence, or architecture choices;
|
|
47
|
+
- a current-truth artifact (context, stack, system, glossary, principles) whose change supersedes an accepted decision—identify the owning decision and propose superseding it in the same atomic update.
|
|
48
|
+
3. Base current-behavior claims on successful verification that exercised the behavior. Cite the exact developer statement, record section, diff, or verification result supporting each proposal, and label inferences. If verification was absent, failed, or did not exercise the claim, say so and do not present that behavior as verified.
|
|
49
|
+
4. Use the `record` skill to propose the necessary updates.
|
|
50
|
+
5. Present each proposal with its evidence, target record, and rationale. Offer **apply**, **edit**, or **skip**, and wait for the developer's response. **Apply** approves exactly the displayed proposal. **Edit** requests revised wording; it is not consent to write, so display the revision and obtain explicit approval before writing it. **Skip** changes nothing.
|
|
51
|
+
6. When the work touched a current-truth artifact or a domain rule, include an explicit `Decisions consulted: <ids and titles, or "none">` line in the reconcile output. A blank or missing line means the decision records were not consulted, which is the consultation failure the resolution step is meant to prevent.
|
|
52
|
+
7. After the developer approves and the updates are applied, run `drawbore check`. If it reports a structural error (duplicate or mismatched decision IDs, broken supersession, invalid status), propose the correction and re-check before reporting the work reconciled.
|
|
53
|
+
|
|
54
|
+
Do not treat an unreviewed source diff alone as proof that context is stale. Verified behavior, an explicit contract change, or developer confirmation is evidence of a stale current-state record. Treat principles, decisions, terms, and boundaries as governing constraints, and `system.md` and `stack.md` as claims about current state. If records conflict with one another or with verified repository behavior, cite the conflicting sources and do not choose silently. Resolve governing-record conflicts with the developer and propose stale current-state corrections through `record`.
|
|
55
|
+
|
|
56
|
+
## Boundaries
|
|
57
|
+
|
|
58
|
+
- Do not create milestones, task registries, approval gates, or execution plans.
|
|
59
|
+
- Do not assume an issue tracker platform. Use tools the harness provides when external issue state matters.
|
|
60
|
+
- Do not mirror mutable external issue state in the record.
|
|
61
|
+
- Do not treat a Change Brief as settled truth. Settle and remove it only through the `frame` and `record` workflow after acceptance passes and approved durable consequences have been written. Otherwise leave the brief in place.
|
|
62
62
|
- Do not promote generic engineering advice into a project principle without developer confirmation.
|
package/skills/record/SKILL.md
CHANGED
|
@@ -1,99 +1,99 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: record
|
|
3
|
-
description: Use this skill when durable project knowledge crystallizes and should be recorded with developer confirmation, including glossary terms, principles, consequential decisions, current system behavior, technical choices, or the durable consequences of a Change Brief. Also use when the developer says to remember, register, amend, or supersede project context.
|
|
4
|
-
license: MIT
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Record durable context
|
|
8
|
-
|
|
9
|
-
Record only knowledge that should influence future work. Keep curated truth compact, evidence-backed, and under the developer's control.
|
|
10
|
-
|
|
11
|
-
## Select the artifact
|
|
12
|
-
|
|
13
|
-
| Knowledge | Destination |
|
|
14
|
-
| --- | --- |
|
|
15
|
-
| Project vocabulary and discouraged aliases | `.drawbore/glossary.md` |
|
|
16
|
-
| Project purpose, scope boundaries, and domain-level relationships | `.drawbore/context.md` |
|
|
17
|
-
| Normative enduring constraints | `.drawbore/principles.md` |
|
|
18
|
-
| Durable choices, rationale, and history | `.drawbore/decisions/NNNN-<slug>.md` |
|
|
19
|
-
| Observable shipped capabilities and contracts | `.drawbore/system.md` |
|
|
20
|
-
| Current runtime, framework, persistence, versions, and technical topology | `.drawbore/stack.md` |
|
|
21
|
-
|
|
22
|
-
Use one canonical owner for each fact. Do not copy the same fact into multiple artifacts. A decision retains the historical outcome and rationale; a current-truth artifact states the present outcome. When both reflect the same choice, propose both updates together so they cannot disagree.
|
|
23
|
-
|
|
24
|
-
Do not create an issue record. External issue state belongs to the external tracker and may be accessed through whatever tools the harness provides.
|
|
25
|
-
|
|
26
|
-
## Test whether knowledge is durable
|
|
27
|
-
|
|
28
|
-
Capture a record only when at least one condition applies:
|
|
29
|
-
|
|
30
|
-
- future work should preserve it;
|
|
31
|
-
- it constrains implementation choices;
|
|
32
|
-
- it establishes an important boundary;
|
|
33
|
-
- it has non-obvious trade-offs;
|
|
34
|
-
- changing it later would be costly or disruptive;
|
|
35
|
-
- a future contributor would reasonably ask why the alternative was not chosen;
|
|
36
|
-
- the developer explicitly asks to remember it.
|
|
37
|
-
|
|
38
|
-
Do not persist an ephemeral implementation choice. Leave it in code, tests, a transient Change Brief, version-control history, or the external tracker.
|
|
39
|
-
|
|
40
|
-
## Inspect existing records
|
|
41
|
-
|
|
42
|
-
Before proposing an update:
|
|
43
|
-
|
|
44
|
-
1. Read `.drawbore/index.md` and every existing record that could cover the fact.
|
|
45
|
-
2. Search by the project concept, not only by the proposed filename.
|
|
46
|
-
3. Identify the exact existing entry to amend, or state that no equivalent entry was found.
|
|
47
|
-
4. Maintain one canonical glossary entry, one rule, and one current behavior or technical choice per subject. Amend the identified entry instead of appending a duplicate.
|
|
48
|
-
5. Maintain one current accepted decision per choice. When a choice changes, supersede the previous decision rather than rewriting its historical outcome.
|
|
49
|
-
6. Before proposing an amendment to a current-truth artifact (`context.md`, `stack.md`, `system.md`, `glossary.md`, `principles.md`), identify the accepted decision that owns that fact. If one exists, the proposal MUST supersede it—create the next decision, mark the old record `superseded` with `superseded_by`, and update the current-truth artifact—all in the same atomic proposal. Amending the current-truth artifact without superseding its owning decision is incomplete: it leaves an `accepted` record contradicting shipped behavior.
|
|
50
|
-
|
|
51
|
-
## Confirm before writing
|
|
52
|
-
|
|
53
|
-
For every proposed update:
|
|
54
|
-
|
|
55
|
-
1. State the evidence: the developer statement, prompt, code, diff, verification result, or history that supports it.
|
|
56
|
-
2. Name the target record and show the proposed addition or replacement.
|
|
57
|
-
3. Offer **apply**, **edit**, or **skip**, then wait for the developer's response.
|
|
58
|
-
4. Treat **apply** as approval of exactly the displayed proposal, **edit** as a request to revise it, and **skip** as no change.
|
|
59
|
-
5. For **edit**, use the developer's wording, display the revised proposal, and obtain approval before writing it.
|
|
60
|
-
6. Preserve the developer's wording when they supply it.
|
|
61
|
-
7. Treat dependent edits—such as a decision, an affected current-truth artifact, and an index correction—as one atomic proposal: apply all or none.
|
|
62
|
-
|
|
63
|
-
Do not write or delete any record record until the developer explicitly approves the displayed proposal. A request to "remember" a fact starts this workflow but does not approve unseen wording.
|
|
64
|
-
|
|
65
|
-
## Follow artifact rules
|
|
66
|
-
|
|
67
|
-
Read [the artifact formats](references/artifact-formats.md) before writing.
|
|
68
|
-
|
|
69
|
-
- Keep glossary definitions short and prefer one canonical term over several synonyms.
|
|
70
|
-
- Keep principles load-bearing. Include rationale and provenance so future agents understand the rule.
|
|
71
|
-
- Create a durable decision only when it should affect future work. Use `significance: durable` or `architectural`; do not create both a decision log and a parallel ADR system.
|
|
72
|
-
- For glossary, principles, context, system, and stack, an amendment replaces the identified existing entry and removes its conflicting old wording.
|
|
73
|
-
- Do not rewrite the outcome or rationale of an `accepted` decision to represent a later choice. When a change supersedes an owning decision (see Inspect existing records 6), create the next decision and mark the old record superseded with `superseded_by`, updating every affected current-truth artifact in the same proposal.
|
|
74
|
-
- Keep `system.md` in the present tense. Amend only the affected behavior in place; preserve unrelated entries.
|
|
75
|
-
- Keep `stack.md` as current truth. Put the reason for a consequential choice in `decisions/`.
|
|
76
|
-
- Update `.drawbore/index.md` only when its map becomes inaccurate, and include any required index correction in the confirmed proposal.
|
|
77
|
-
- Allocate decision IDs at write time. Immediately before writing, enumerate `.drawbore/decisions/`, find the highest numeric prefix, and allocate the next unused sequential ID with the existing padding width. Never reuse an ID, including IDs of deprecated or superseded records, and never reuse an ID allocated in an earlier turn: a record proposed before a write is not reserved, so re-enumerate and re-allocate at the moment of writing.
|
|
78
|
-
|
|
79
|
-
## Reconcile a settled Change Brief
|
|
80
|
-
|
|
81
|
-
Only the developer may mark a brief settled, and only after the implementation is complete and its acceptance conditions have been verified.
|
|
82
|
-
|
|
83
|
-
1. Identify its durable consequences.
|
|
84
|
-
2. Propose only those consequences and the brief removal together.
|
|
85
|
-
3. Delete the brief only after every approved consequence update has been written successfully.
|
|
86
|
-
4. If a skipped or deferred consequence has unique durable rationale in the brief, keep the brief unless the developer explicitly approves discarding that rationale.
|
|
87
|
-
5. Ensure no unique **durable** rationale remains only in the brief. Promote rationale only when it explains a durable choice; ephemeral implementation rationale may be discarded with the brief.
|
|
88
|
-
6. Remove only the settled brief file from `.drawbore/work/`, but keep the `work/` directory.
|
|
89
|
-
|
|
90
|
-
During brief reconciliation, write `system.md` only when evidence shows the capability or contract is present in the shipped product. Write `stack.md` only when the technical choice is already current in the repository or runtime. Accepted scope alone is not evidence of shipped behavior.
|
|
91
|
-
|
|
92
|
-
Do not create a settled-work archive.
|
|
93
|
-
|
|
94
|
-
## Boundaries
|
|
95
|
-
|
|
96
|
-
- Do not silently mutate curated truth.
|
|
97
|
-
- Do not invent rationale the developer did not provide; mark an inference as an inference.
|
|
98
|
-
- Do not add generic preferences or universal engineering advice as project truth.
|
|
1
|
+
---
|
|
2
|
+
name: record
|
|
3
|
+
description: Use this skill when durable project knowledge crystallizes and should be recorded with developer confirmation, including glossary terms, principles, consequential decisions, current system behavior, technical choices, or the durable consequences of a Change Brief. Also use when the developer says to remember, register, amend, or supersede project context.
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Record durable context
|
|
8
|
+
|
|
9
|
+
Record only knowledge that should influence future work. Keep curated truth compact, evidence-backed, and under the developer's control.
|
|
10
|
+
|
|
11
|
+
## Select the artifact
|
|
12
|
+
|
|
13
|
+
| Knowledge | Destination |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Project vocabulary and discouraged aliases | `.drawbore/glossary.md` |
|
|
16
|
+
| Project purpose, scope boundaries, and domain-level relationships | `.drawbore/context.md` |
|
|
17
|
+
| Normative enduring constraints | `.drawbore/principles.md` |
|
|
18
|
+
| Durable choices, rationale, and history | `.drawbore/decisions/NNNN-<slug>.md` |
|
|
19
|
+
| Observable shipped capabilities and contracts | `.drawbore/system.md` |
|
|
20
|
+
| Current runtime, framework, persistence, versions, and technical topology | `.drawbore/stack.md` |
|
|
21
|
+
|
|
22
|
+
Use one canonical owner for each fact. Do not copy the same fact into multiple artifacts. A decision retains the historical outcome and rationale; a current-truth artifact states the present outcome. When both reflect the same choice, propose both updates together so they cannot disagree.
|
|
23
|
+
|
|
24
|
+
Do not create an issue record. External issue state belongs to the external tracker and may be accessed through whatever tools the harness provides.
|
|
25
|
+
|
|
26
|
+
## Test whether knowledge is durable
|
|
27
|
+
|
|
28
|
+
Capture a record only when at least one condition applies:
|
|
29
|
+
|
|
30
|
+
- future work should preserve it;
|
|
31
|
+
- it constrains implementation choices;
|
|
32
|
+
- it establishes an important boundary;
|
|
33
|
+
- it has non-obvious trade-offs;
|
|
34
|
+
- changing it later would be costly or disruptive;
|
|
35
|
+
- a future contributor would reasonably ask why the alternative was not chosen;
|
|
36
|
+
- the developer explicitly asks to remember it.
|
|
37
|
+
|
|
38
|
+
Do not persist an ephemeral implementation choice. Leave it in code, tests, a transient Change Brief, version-control history, or the external tracker.
|
|
39
|
+
|
|
40
|
+
## Inspect existing records
|
|
41
|
+
|
|
42
|
+
Before proposing an update:
|
|
43
|
+
|
|
44
|
+
1. Read `.drawbore/index.md` and every existing record that could cover the fact.
|
|
45
|
+
2. Search by the project concept, not only by the proposed filename.
|
|
46
|
+
3. Identify the exact existing entry to amend, or state that no equivalent entry was found.
|
|
47
|
+
4. Maintain one canonical glossary entry, one rule, and one current behavior or technical choice per subject. Amend the identified entry instead of appending a duplicate.
|
|
48
|
+
5. Maintain one current accepted decision per choice. When a choice changes, supersede the previous decision rather than rewriting its historical outcome.
|
|
49
|
+
6. Before proposing an amendment to a current-truth artifact (`context.md`, `stack.md`, `system.md`, `glossary.md`, `principles.md`), identify the accepted decision that owns that fact. If one exists, the proposal MUST supersede it—create the next decision, mark the old record `superseded` with `superseded_by`, and update the current-truth artifact—all in the same atomic proposal. Amending the current-truth artifact without superseding its owning decision is incomplete: it leaves an `accepted` record contradicting shipped behavior.
|
|
50
|
+
|
|
51
|
+
## Confirm before writing
|
|
52
|
+
|
|
53
|
+
For every proposed update:
|
|
54
|
+
|
|
55
|
+
1. State the evidence: the developer statement, prompt, code, diff, verification result, or history that supports it.
|
|
56
|
+
2. Name the target record and show the proposed addition or replacement.
|
|
57
|
+
3. Offer **apply**, **edit**, or **skip**, then wait for the developer's response.
|
|
58
|
+
4. Treat **apply** as approval of exactly the displayed proposal, **edit** as a request to revise it, and **skip** as no change.
|
|
59
|
+
5. For **edit**, use the developer's wording, display the revised proposal, and obtain approval before writing it.
|
|
60
|
+
6. Preserve the developer's wording when they supply it.
|
|
61
|
+
7. Treat dependent edits—such as a decision, an affected current-truth artifact, and an index correction—as one atomic proposal: apply all or none.
|
|
62
|
+
|
|
63
|
+
Do not write or delete any record record until the developer explicitly approves the displayed proposal. A request to "remember" a fact starts this workflow but does not approve unseen wording.
|
|
64
|
+
|
|
65
|
+
## Follow artifact rules
|
|
66
|
+
|
|
67
|
+
Read [the artifact formats](references/artifact-formats.md) before writing.
|
|
68
|
+
|
|
69
|
+
- Keep glossary definitions short and prefer one canonical term over several synonyms.
|
|
70
|
+
- Keep principles load-bearing. Include rationale and provenance so future agents understand the rule.
|
|
71
|
+
- Create a durable decision only when it should affect future work. Use `significance: durable` or `architectural`; do not create both a decision log and a parallel ADR system.
|
|
72
|
+
- For glossary, principles, context, system, and stack, an amendment replaces the identified existing entry and removes its conflicting old wording.
|
|
73
|
+
- Do not rewrite the outcome or rationale of an `accepted` decision to represent a later choice. When a change supersedes an owning decision (see Inspect existing records 6), create the next decision and mark the old record superseded with `superseded_by`, updating every affected current-truth artifact in the same proposal.
|
|
74
|
+
- Keep `system.md` in the present tense. Amend only the affected behavior in place; preserve unrelated entries.
|
|
75
|
+
- Keep `stack.md` as current truth. Put the reason for a consequential choice in `decisions/`.
|
|
76
|
+
- Update `.drawbore/index.md` only when its map becomes inaccurate, and include any required index correction in the confirmed proposal.
|
|
77
|
+
- Allocate decision IDs at write time. Immediately before writing, enumerate `.drawbore/decisions/`, find the highest numeric prefix, and allocate the next unused sequential ID with the existing padding width. Never reuse an ID, including IDs of deprecated or superseded records, and never reuse an ID allocated in an earlier turn: a record proposed before a write is not reserved, so re-enumerate and re-allocate at the moment of writing.
|
|
78
|
+
|
|
79
|
+
## Reconcile a settled Change Brief
|
|
80
|
+
|
|
81
|
+
Only the developer may mark a brief settled, and only after the implementation is complete and its acceptance conditions have been verified.
|
|
82
|
+
|
|
83
|
+
1. Identify its durable consequences.
|
|
84
|
+
2. Propose only those consequences and the brief removal together.
|
|
85
|
+
3. Delete the brief only after every approved consequence update has been written successfully.
|
|
86
|
+
4. If a skipped or deferred consequence has unique durable rationale in the brief, keep the brief unless the developer explicitly approves discarding that rationale.
|
|
87
|
+
5. Ensure no unique **durable** rationale remains only in the brief. Promote rationale only when it explains a durable choice; ephemeral implementation rationale may be discarded with the brief.
|
|
88
|
+
6. Remove only the settled brief file from `.drawbore/work/`, but keep the `work/` directory.
|
|
89
|
+
|
|
90
|
+
During brief reconciliation, write `system.md` only when evidence shows the capability or contract is present in the shipped product. Write `stack.md` only when the technical choice is already current in the repository or runtime. Accepted scope alone is not evidence of shipped behavior.
|
|
91
|
+
|
|
92
|
+
Do not create a settled-work archive.
|
|
93
|
+
|
|
94
|
+
## Boundaries
|
|
95
|
+
|
|
96
|
+
- Do not silently mutate curated truth.
|
|
97
|
+
- Do not invent rationale the developer did not provide; mark an inference as an inference.
|
|
98
|
+
- Do not add generic preferences or universal engineering advice as project truth.
|
|
99
99
|
- Do not create a second source of truth for external issue state.
|