drawbore 0.0.0-stage → 0.1.0

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.
@@ -0,0 +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
+
86
+ After scaffolding: commit, push to the canonical forge, then cut the first release with the `release` skill.
@@ -0,0 +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.
62
+ - Do not promote generic engineering advice into a project principle without developer confirmation.
@@ -0,0 +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.
99
+ - Do not create a second source of truth for external issue state.
@@ -0,0 +1,131 @@
1
+ # Durable artifact formats
2
+
3
+ ## Context
4
+
5
+ `.drawbore/context.md` describes the project's purpose, scope, important areas, and relationships.
6
+
7
+ ```markdown
8
+ # Project Context
9
+
10
+ ## Purpose
11
+
12
+ <Why the project exists and the outcome it serves.>
13
+
14
+ ## Scope
15
+
16
+ - <included boundary>
17
+ - <excluded boundary>
18
+
19
+ ## Architecture and relationships
20
+
21
+ - **<Area or component>** — <responsibility and relationship to other areas>
22
+ ```
23
+
24
+ ## Glossary
25
+
26
+ `.drawbore/glossary.md` defines canonical project vocabulary.
27
+
28
+ ```markdown
29
+ # Glossary
30
+
31
+ ## <Context or area>
32
+
33
+ **Canonical term**:
34
+ <One or two-sentence definition.>
35
+ _Avoid_: <discouraged alias, alternative name>
36
+ ```
37
+
38
+ Use only project-specific terms. Prefer one canonical term. Do not put implementation instructions here.
39
+
40
+ ## Principles
41
+
42
+ `.drawbore/principles.md` contains short, load-bearing rules.
43
+
44
+ ```markdown
45
+ # Principles
46
+
47
+ 1. **<Rule>** — <why it matters>. <Source: decision NNNN or user-confirmed constraint>
48
+ ```
49
+
50
+ A rule must change how future work is done. Do not include style preferences that the repository already communicates unambiguously.
51
+
52
+ ## Decisions
53
+
54
+ Store durable choices at `.drawbore/decisions/NNNN-<slug>.md`.
55
+
56
+ ```markdown
57
+ ---
58
+ id: NNNN
59
+ status: accepted
60
+ significance: durable | architectural
61
+ date: YYYY-MM-DD
62
+ ---
63
+
64
+ # <Decision title>
65
+
66
+ ## Context
67
+
68
+ <Why a decision was needed.>
69
+
70
+ ## Decision
71
+
72
+ <What was chosen.>
73
+
74
+ ## Rationale
75
+
76
+ <Why it was chosen. Mark any inference.>
77
+
78
+ ## Alternatives considered
79
+
80
+ - <Alternative> — <why it was not chosen>
81
+
82
+ ## Consequences
83
+
84
+ - <Positive or negative consequence>
85
+ ```
86
+
87
+ Before creating a decision, list all existing decision IDs and allocate the next unused sequential ID using the existing padding width. Never reuse an ID, including IDs of deprecated or superseded records. The `id` field and filename prefix must match exactly. If that filename exists, allocate a different ID or slug rather than overwrite it.
88
+
89
+ Use `status: proposed`, `accepted`, `deprecated`, or `superseded`. `accepted` is the only authoritative decision status. `proposed` is non-binding and must not be cited as established project guidance. `deprecated` means no longer recommended and not replaced. `superseded` means replaced by another accepted decision and requires `superseded_by: NNNN` in the front matter.
90
+
91
+ If evidence does not support a required decision section, write `Not recorded` rather than inventing content or omitting the section. Do not fabricate alternatives. An inference may be included only when explicitly labeled as an inference and does not substitute for missing evidence.
92
+
93
+ `significance: architectural` is appropriate when the choice shapes system boundaries, major dependencies, data ownership, or long-lived direction. Other future-relevant choices use `significance: durable`.
94
+
95
+ ## Current system behavior
96
+
97
+ `.drawbore/system.md` describes what the shipped system does today.
98
+
99
+ ```markdown
100
+ # System Behavior
101
+
102
+ ## <Capability or domain>
103
+
104
+ - <Observable behavior or contract>
105
+
106
+ _Rewritten in place when behavior changes; decisions retain the history._
107
+ ```
108
+
109
+ Describe current capabilities and contracts, not implementation detail or rationale.
110
+
111
+ ## Current technical choices
112
+
113
+ `.drawbore/stack.md` describes the current project stack and architecture.
114
+
115
+ ```markdown
116
+ # Technical Choices
117
+
118
+ ## <Category>
119
+
120
+ - **<Choice>** — <version or specificity where useful>
121
+
122
+ ## Architecture
123
+
124
+ - <Component, boundary, or relationship>
125
+ ```
126
+
127
+ Record current truth. Put the reason for a consequential choice in `decisions/`.
128
+
129
+ ## Index
130
+
131
+ `.drawbore/index.md` is a directory-level map, not a second index of record contents. Include one link and a one-line purpose for each existing top-level durable artifact and `work/`; represent decisions through `decisions/` rather than individual decisions. Update it when a mapped path or purpose is missing or stale. Ordinary content changes do not require an index change unless the existing one-line purpose becomes inaccurate.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: release
3
+ description: Cut a release for any project — bump version, changelog, tag, push, and verify the pipeline or publish step. Works for repository-only releases and for projects that publish a package to a registry through CI. Includes optional provider notes for common CI systems. Use for any release, tag, publish, or release-pipeline debugging task, including re-tagging and failed publish pipelines.
4
+ ---
5
+
6
+ # Release flow (provider-neutral)
7
+
8
+ Determine the project shape first:
9
+
10
+ 1. Read the root `AGENTS.md` `## Release` section (package name, version stamps, build steps, verify commands, publish mode, pipeline path). Missing or stale → fix it as part of the release.
11
+ 2. Settle the publish mode. Use `publish mode:` when present; otherwise infer it and say which inference you made:
12
+ - a staging flow described in prose → `staged`;
13
+ - a package with a CI publish job and no staging step → `direct`;
14
+ - no package, or `npm package: none` → `none`.
15
+ Older sections write the package field as `npm package:` rather than `package:`; read either.
16
+ 3. Settle the pipeline. Use `pipeline:` when present; otherwise treat the repository's CI configuration as the pipeline. A publish job in the CI file means CI publishes on the tag; no publish job means the release is cut by hand.
17
+
18
+ Never assume a forge or registry: use the remotes, CI configuration, and `## Release` facts the repository actually has.
19
+
20
+ ## Common flow (every project)
21
+
22
+ 1. Bump `version` in the package manifest (if present) and every version-stamped file listed under `## Release`.
23
+ 2. Add a dated `CHANGELOG.md` section for the new version, with a compare link to the previous tag.
24
+ 3. Commit the release (`chore(release): vX.Y.Z`). Commit only with the developer's explicit consent.
25
+ 4. `git tag vX.Y.Z && git push origin vX.Y.Z`.
26
+ Tag pipelines trigger on tags matching `^v\d+\.\d+\.\d+$`; when a package manifest exists, the tag must equal `v` + its version — the pipeline gates on it.
27
+ 5. Wait for the tag pipeline (or the forge's equivalent) to go green.
28
+
29
+ ### First publish bootstrap
30
+
31
+ If the registry reports that the package does not exist, the package must exist before CI-based publishing can be configured. Publish the first version once with an authenticated account (normally locally), configure the forge/registry publishing identity, and then continue with the publish tail. Do not add a long-lived registry token to CI as a workaround; the one-time bootstrap publish is not the ongoing release mechanism.
32
+
33
+ ## Publish tail (publish mode is `direct` or `staged`)
34
+
35
+ Run this after the tag pipeline is green when `pipeline:` names a CI file, or by hand when it says `none`.
36
+
37
+ **`direct`** — the registry's publish command runs with the CI credential, and the version is public as soon as it succeeds:
38
+
39
+ ```
40
+ <registry> publish --provenance --access public
41
+ ```
42
+
43
+ **`staged`** — the version now sits in the registry's **staging area**, not public yet. A maintainer approves it out of band; never automate that step:
44
+
45
+ 1. Review and approve (human proof-of-presence — never automate):
46
+ ```
47
+ <registry> stage list
48
+ <registry> stage view <stage-id> # metadata; commit = exact published revision
49
+ <registry> stage download <stage-id> # inspect the actual artifact
50
+ <registry> stage approve <stage-id> # prompts 2FA → LIVE
51
+ ```
52
+
53
+ 2. Verify: the registry's version endpoint, the verify commands or URLs from `## Release`, and provenance state. A staged release publishes at approval time on the maintainer's machine, with no CI/OIDC build context — expect `attestations: null` and check rather than assume.
54
+
55
+ ## Repository-only tail (publish mode is `none`, or no `## Release` section)
56
+
57
+ 1. Verify the tag exists on the canonical forge and the changelog compare link resolves. Optionally attach the changelog section to a forge release on the tag.
58
+
59
+ ## Re-tagging the same version
60
+
61
+ 1. Publishing projects: **reject any staged version for it in the registry first** — the staging area holds one package per version and a re-push collides.
62
+ 2. `git tag -d vX.Y.Z && git push origin :refs/tags/vX.Y.Z`
63
+ 3. Re-tag at the fixed commit, push.
64
+
65
+ Remember: tag pipelines run the CI **at the tag's commit** — a pipeline fix on the main branch does not retro-fix a tagged release.
66
+
67
+ ## Optional provider notes
68
+
69
+ Read only the note that matches the repository. Do not add a workflow file for a provider the project does not use.
70
+
71
+ ### GitLab CI
72
+
73
+ - Tag pipelines run the CI config **at the tag's commit**. Recovery is tag surgery (delete tag local + remote, re-tag at the fix commit, push) — safe only if staging never ran for that tag.
74
+ - GitLab's YAML parser (Ruby Psych, YAML 1.1) treats an UNQUOTED scalar containing `: ` (colon+space) as a mapping. Symptom: "script config should be a string or a nested array of strings". Rule: single-quote any script line containing `": "`.
75
+ - The push mirror to another forge does **not** carry tags, so tag-triggered jobs on the mirror can never fire. Release CI lives on the canonical forge.
76
+ - If an `environment` is set in the registry's publishing configuration, the CI job must declare the matching `environment: name: <value>`, or publishing 403s.
77
+
78
+ ### GitHub Actions
79
+
80
+ - Tag-triggered workflows (`on: push: tags: ['v*']`) run at the tag's commit. Re-running a failed job after fixing the workflow on the main branch does not help a tag that already exists.
81
+ - Keep publishing permissions least-privilege (`id-token: write` only for the publish job, `contents: read` elsewhere).
82
+ - A mirror repository does not receive tags; do not put release workflows there.
83
+
84
+ ### npm registry
85
+
86
+ - Publishing from CI with provenance compares the manifest's `repository.url` against the CI provider in the OIDC token. A mismatch fails with `422 Unprocessable Entity — Error verifying sigstore provenance bundle`. Point the manifest at the forge the pipeline runs on.
87
+ - The OIDC audience must be `npm:registry.npmjs.org` (the `npm:` prefix is required); the sigstore token uses `aud: sigstore`.
88
+ - `--provenance` on `stage publish` is accepted, but the publish happens at `stage approve` on the maintainer's machine, where no CI/OIDC build context exists — staged releases have come out with `attestations: null`. Treat the provenance badge as absent for staged releases unless proven otherwise.
89
+ - Staged publishing requires npm CLI >= 11.15 and Node >= 22.14; `node:24` bundles an older npm, so the job must `npm install -g npm@11`.
90
+ - Staging holds ONE package per version. Re-tagging the same version while a stage is pending collides — reject the stale staged version first.
91
+ - A brand-new package's first stage publishes a public `0.0.0-stage` placeholder — that is how the name gets claimed before first approval.
92
+ - A brand-new package cannot configure a trusted publisher until it has been published at least once. Publish the first version with an authenticated account, configure trusted publishing, then complete a real stage within the configuration's validity window.
93
+ - The review subcommands (list/view/download/approve) cannot use OIDC by design — they are the interactive proof-of-presence steps.
94
+ - Registry versions are immutable; the pipeline is only exercised by real new version tags.
95
+ - Trusted-publisher configurations expire if not exercised by a real stage within their validity window (commonly 2 days).
96
+ - CRLF creep from Windows working trees lands in tarballs unless `.gitattributes` has `* text=auto eol=lf`.
97
+
98
+ ### Package hygiene (any registry)
99
+
100
+ - Ship only what consumers need: an explicit files whitelist, not an ignore list.
101
+ - For style packages, set the manifest field bundlers read for the main stylesheet.
102
+ - CDN verify URL shape: `https://cdn.jsdelivr.net/npm/<name>@<version>/<file>`. jsDelivr auto-minifies a DOTTED filename as `<base>.min.<ext>`.
103
+
104
+ ### Security posture
105
+
106
+ - Prefer short-lived OIDC tokens bound to (forge, project, CI file) over long-lived credentials.
107
+ - Staging may not require 2FA (safe for automation); approval always needs interactive 2FA. A compromised CI can stage junk but nothing goes public without the maintainer.
108
+ - Recommended per-package hardening: require two-factor authentication and disallow tokens.
@@ -0,0 +1,117 @@
1
+ ---
2
+ name: review
3
+ description: Full read-only analysis of the working repository with a prioritized enhancement proposal, plus an approval-gated implementation phase — shape and stack, architecture and entry points, correctness and risk, hygiene and conventions, dependency and CI health, docs, and repository-specific convention drift. Use when asked to analyze, audit, review, assess, or improve a repo, codebase, or project, including "what should we improve", "review this project", "propose enhancements", "audit then fix", and post-change sanity audits. Analysis never edits; implementation runs only after explicit approval of a numbered plan.
4
+ ---
5
+
6
+ # Repository review (analysis + gated implementation)
7
+
8
+ Two phases. Phase 1 produces **one report** and never edits anything. Phase 2 runs only after the user approves specific numbered items, and only those.
9
+
10
+ ## Rules
11
+
12
+ - **Evidence or nothing.** A finding without `path:line`, a file list, or a command's output is `[INFERENCE]` — it goes in the `Unverified` section, never in the ranked list.
13
+ - **Report what is there.** Missing files are findings only when a convention the repository itself declares requires them; do not grade the repo against an imagined ideal.
14
+ - **Read the repo's own checks before judging them.** Manifest scripts, `Makefile`, `justfile`, CI configuration, and lint rules are evidence of intent.
15
+ - **Rank, don't dump.** Order by `(impact × confidence) / effort`. A 30-item flat list is a failed audit.
16
+ - **Phase 1 ends at the report.** One question, at the end: what to implement.
17
+ - **Phase 2 is narrow.** Approved items only, in the approved order. No opportunistic cleanup, no adjacent refactor, no reformatting of touched files.
18
+
19
+ ## Phase 1 — analysis
20
+
21
+ ### 1. Shape
22
+
23
+ Confirm the workspace is the repository (resolve its root with the version-control tool the project uses), inspect working-tree state and recent history, and read the remotes. Then map it: read the root directory (one level), read the manifests (`package.json`, `Cargo.toml`, `pyproject.toml`, `*.csproj`, `go.mod`, `pom.xml`, …), and check for build, task-runner, and CI files. Note language, package manager, lockfile, entry points, test runner, linter, and CI provider. Record size per area with `find`/`xargs wc -l` when the tree is big enough to matter.
24
+
25
+ ### 2. Architecture
26
+
27
+ Identify entry points and follow them: `main`/`index`/CLI parsers, HTTP handlers, exported public API. Then the dependency direction between modules — one `mermaid` block, only if there is genuine structure (layering, cross-cutting imports, a plugin boundary). Note cycles, layering violations, god files (> ~500 LOC), duplicated logic, and dead code. For dead code, use a language server's `references` on the symbol when one is configured; a text grep for a rename-class claim silently drops dynamic callsites.
28
+
29
+ ### 3. Correctness and risk
30
+
31
+ Swallowed exceptions, empty `catch`, `any`/unchecked casts, and a `TODO`/`FIXME`/`HACK`/`XXX` inventory with locations. Unawaited promises, unlocked shared state, leaked handles, unvalidated input at trust boundaries. Then the things that page someone at 3am: missing timeouts, unbounded loops, unindexed queries, non-idempotent retries.
32
+
33
+ ### 4. Hygiene and conventions
34
+
35
+ Tracked build output, secrets, `.env`, key material; ignore-file gaps; CRLF vs `.gitattributes`; inconsistent naming or formatting within one tree; stray debug logging; version stamps that disagree across files (manifest vs changelog vs header comments).
36
+
37
+ If the repository declares its own conventions (a root `AGENTS.md` or contributor guide, a documented release process, a required file layout), check the repository against them explicitly — that is the highest-yield pass. Compare declarations with reality and report every disagreement as a finding.
38
+
39
+ ### 5. Dependencies and CI
40
+
41
+ Run the project's audit command (`npm audit`, `bun audit`, `cargo audit`, or the ecosystem equivalent; report advisories, never fix silently), note majors behind current, duplicated functionality across dependencies, dependencies never imported, and install scripts. For CI: read the pipeline definition, confirm every `needs`/stage edge is real, check that the pipeline runs on the branches and tags the project actually uses, and that the README badge URL matches the project path.
42
+
43
+ ### 6. Security
44
+
45
+ If the harness exposes a security-scan or vulnerability-discovery tool, offer it as a **follow-up**, not a pass here — it has its own review flow and is opt-in. Run discovery, then validate each candidate before calling it real; report unvalidated candidates as leads. If no such tool is available, say so and list manual checks worth doing (dependency advisories, secret scanning, permission boundaries).
46
+
47
+ ### 7. Docs
48
+
49
+ Does `README.md` answer what/why/install/use for a newcomer? Is `CHANGELOG.md` current against the latest tag? Does the contributor or agent guidance file match reality? License present and current-year?
50
+
51
+ ### 8. Report
52
+
53
+ Lead with a 3–5 line verdict: what the repo is, its strongest and weakest aspect. Then, in order:
54
+
55
+ 1. **Shape** — one paragraph, no restating the tree.
56
+ 2. **Findings** — grouped by severity (`Blocker`, `Should fix`, `Nice to have`). Each carries a **stable id** (`F1`, `F2`, …), in this exact order: claim, evidence (`path:line` or command output), why it matters, concrete fix, effort (`S`/`M`/`L`).
57
+ 3. **Comparison table** — id / finding / severity / area / effort / confidence.
58
+ 4. **Proposed order of work** — 3–5 numbered steps referencing those ids, highest ratio first, each with a verifiable done-condition.
59
+ 5. **Unverified** — `[INFERENCE]` items and what check would settle each.
60
+
61
+ End with exactly one question:
62
+
63
+ > Which items should I implement? Reply with ids or step numbers (e.g. `F1, F4` or `do step 2`). Anything not named stays untouched.
64
+
65
+ Then stop. Do not start implementing from a vague "yes" or "go ahead" — that authorizes nothing specific.
66
+
67
+ ## Phase 2 — approval-gated implementation
68
+
69
+ Enter only on an explicit selection of ids or step numbers.
70
+
71
+ ### 2.1 Confirm the scope, in writing
72
+
73
+ Before the first edit, restate the selected ids with: files each will touch, the change in one line, the done-condition, and the verification command. Then require an explicit confirmation naming that scope. A single "yes" to the phase-1 question is not this confirmation.
74
+
75
+ ### 2.2 Baseline first
76
+
77
+ Run the verification command **before** editing, and record the output. A verification step is worthless if it was already failing, and a red baseline tells you the repo was broken before you arrived — report that rather than attributing it to your change.
78
+
79
+ ### 2.3 Implement in plan order
80
+
81
+ One id at a time, in the approved order. Each item:
82
+
83
+ 1. Read the target code; check references for any exported symbol before renaming.
84
+ 2. Make the change.
85
+ 3. Run the done-condition check.
86
+ 4. Report `id — done | failed: <output>`. Then next id.
87
+
88
+ If an item turns out to be wrong, larger than stated, or to require touching files outside its declared scope: **stop, report, ask.** Do not widen the change to keep momentum.
89
+
90
+ ### 2.4 Final verification
91
+
92
+ Re-run the repository's own checks once, after all items: build, tests, lint. Fix only failures your changes caused — a pre-existing failure goes in the report, not into a drive-by fix.
93
+
94
+ ### 2.5 Close out
95
+
96
+ Report what changed (id → file → what), what verification proved, and what was left undone. Update docs or changelog if the change is user-visible.
97
+
98
+ ## Boundaries that never move
99
+
100
+ - **No commits, no pushes, no tags, no version bumps** in either phase unless the user explicitly asks for that step. Phase 2 authorizes edits only.
101
+ - **No dependency changes** unless the user named the item as a dependency change.
102
+ - **No touching unrelated code**, however tempting. "I fixed a typo nearby" turns an approved change into an unapproved diff.
103
+ - **Nothing outside the repository** unless the user explicitly authorizes it: harness configuration, global tool configuration, system installs.
104
+ - **Items the user did not select are not implemented.** Not partially, not "while I was there".
105
+
106
+ ## Large repositories
107
+
108
+ If the harness offers session checkpoints or a rewind mechanism, snapshot before exploration and keep only the report. Delegate independent areas (build, tests, dependencies, CI, docs) as parallel read-only subagents in one dispatch when a single pass would be shallow; per-area finders return evidence, not prose. You keep the synthesis, the prioritization, and phase 2.
109
+
110
+ ## Anti-patterns
111
+
112
+ - Formatting nits as findings. Mention once, in aggregate.
113
+ - Proposing a framework or rewrite without naming what it buys over the current design.
114
+ - Findings the repo already documents as intentional (search the docs first).
115
+ - Running builds or test suites during phase 1 unless a finding requires it; an audit observes, it does not verify work.
116
+ - Editing anything in phase 1. The moment you fix a typo, it is not an audit.
117
+ - Treating "yes, implement" as approval for all findings. It is approval for the ones you listed.
@@ -0,0 +1,9 @@
1
+ <!-- drawbore:start -->
2
+ ## Drawbore
3
+
4
+ This project uses `.drawbore/` as its curated, durable project context. Drawbore installs portable skills into the agent harness; use the `discover`, `recall`, `frame`, `record`, `review`, `init-project`, and `release` skills where the task calls for them.
5
+
6
+ Before implementing a feature, bug fix, refactor, design change, or other technical change, consult the relevant project context, glossary and canonical terms, principles, decisions, current behavior, technical choices, and active Change Briefs. If purpose, scope, or a boundary is materially ambiguous, or the request conflicts with a recorded principle, decision, term, or boundary, collaborate with the developer to resolve it before implementation.
7
+
8
+ After completing work, reconcile the implementation and verified behavior with durable project context. Offer specific evidence-backed updates and wait for explicit **apply** or approval of edited wording; **skip** or no decision leaves the record unchanged. If no durable consequence changed, explicitly state **No record update needed**. Never silently change curated project truth.
9
+ <!-- drawbore:end -->
@@ -0,0 +1,12 @@
1
+ {
2
+ "namespace": "drawbore",
3
+ "skills": [
4
+ "discover",
5
+ "recall",
6
+ "frame",
7
+ "record",
8
+ "review",
9
+ "init-project",
10
+ "release"
11
+ ]
12
+ }