@bizibot/contracts 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.
- package/LICENSE +21 -0
- package/README.md +131 -0
- package/conformance/patterns.json +12 -0
- package/dist/chunk-6OQSBZG4.js +709 -0
- package/dist/chunk-6OQSBZG4.js.map +1 -0
- package/dist/chunk-LONUJCLW.js +50 -0
- package/dist/chunk-LONUJCLW.js.map +1 -0
- package/dist/cli.js +258 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/package-T64HPNWA.js +7 -0
- package/dist/package-T64HPNWA.js.map +1 -0
- package/dist/src/artifacts/discover.d.ts +28 -0
- package/dist/src/check/release.d.ts +12 -0
- package/dist/src/check/repository.d.ts +19 -0
- package/dist/src/check/snapshot.d.ts +37 -0
- package/dist/src/check/version-transitions.d.ts +23 -0
- package/dist/src/ci.d.ts +20 -0
- package/dist/src/cli.d.ts +2 -0
- package/dist/src/contracts-file/matcher.d.ts +2 -0
- package/dist/src/contracts-file/parse.d.ts +26 -0
- package/dist/src/contracts-file/pin.d.ts +10 -0
- package/dist/src/contracts-file/ranges.d.ts +11 -0
- package/dist/src/contracts-file/resolve.d.ts +16 -0
- package/dist/src/index.d.ts +15 -0
- package/dist/src/local.d.ts +8 -0
- package/dist/src/managed.d.ts +17 -0
- package/dist/src/runtime/handoff.d.ts +11 -0
- package/dist/src/versioning/paths.d.ts +2 -0
- package/dist/src/versioning/validate.d.ts +13 -0
- package/dist/src/versioning/version.d.ts +3 -0
- package/docs/agents.md +65 -0
- package/docs/checks.md +102 -0
- package/docs/contracts-file.md +112 -0
- package/docs/cross-repo.md +39 -0
- package/docs/practices.md +40 -0
- package/docs/taxonomy.md +77 -0
- package/docs/versioning.md +73 -0
- package/docs/workflow.md +49 -0
- package/package.json +50 -0
- package/skills/contracts-adopt/SKILL.md +70 -0
- package/skills/contracts-change/SKILL.md +74 -0
- package/skills/contracts-triage/SKILL.md +46 -0
- package/skills/contracts-write/SKILL.md +80 -0
- package/skills/contracts-write/references/adr.md +34 -0
- package/skills/contracts-write/references/design.md +37 -0
- package/skills/contracts-write/references/prd.md +49 -0
- package/skills/contracts-write/references/procedure.md +34 -0
- package/skills/contracts-write/references/spec.md +41 -0
- package/skills/contracts-write/references/standard.md +31 -0
- package/templates/agents-section.md +16 -0
- package/templates/kinds/adr.md +21 -0
- package/templates/kinds/design.md +22 -0
- package/templates/kinds/prd.md +29 -0
- package/templates/kinds/procedure.md +16 -0
- package/templates/kinds/spec.md +17 -0
- package/templates/kinds/standard.md +16 -0
- package/templates/workflows/check.yml +28 -0
- package/templates/workflows/release.yml +29 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Suggested practices
|
|
2
|
+
|
|
3
|
+
None of this is enforced or installed. It's how the framework's authors like
|
|
4
|
+
to work; adopt any of it in your own procedures if it fits.
|
|
5
|
+
|
|
6
|
+
## Touch only what the change affects
|
|
7
|
+
|
|
8
|
+
The chain `prd → adr → spec → design → code` ranks **authority**. It isn't a
|
|
9
|
+
list of steps every change has to go through.
|
|
10
|
+
|
|
11
|
+
- Change only the docs your change actually affects.
|
|
12
|
+
- If it affects several, work top-down: each lower doc must conform to the ones
|
|
13
|
+
above it.
|
|
14
|
+
|
|
15
|
+
| The change | What you touch |
|
|
16
|
+
|---|---|
|
|
17
|
+
| A bug where the code breaks its spec | Code only |
|
|
18
|
+
| The spec was wrong or silent | The spec, then the code |
|
|
19
|
+
| A new architectural choice | The ADR, then whatever it affects below |
|
|
20
|
+
| A non-trivial build approach | A design, then the code |
|
|
21
|
+
| A new feature that needs agreement on what and why | A PRD, then the specs, designs and code |
|
|
22
|
+
|
|
23
|
+
## Issues and PRDs
|
|
24
|
+
|
|
25
|
+
Both are optional.
|
|
26
|
+
|
|
27
|
+
- An **Issue** is lightweight discovery: a bug report, an idea, a discussion.
|
|
28
|
+
Label it `defect` (the code breaks a contract) or `contract-gap` (a contract
|
|
29
|
+
is wrong or missing).
|
|
30
|
+
- A **PRD** is the durable, agreed version: what we're building, and why.
|
|
31
|
+
- An Issue becomes a PRD only when it needs that durability.
|
|
32
|
+
|
|
33
|
+
**Write a PRD when** any of these holds:
|
|
34
|
+
- it's a new user-facing capability, not an internal change;
|
|
35
|
+
- the what and why need agreement before anyone designs it;
|
|
36
|
+
- it spans several PRs or several specs; or
|
|
37
|
+
- the reasoning should outlive the Issue thread.
|
|
38
|
+
|
|
39
|
+
Fixes, refactors, internal changes and small enhancements don't need a PRD.
|
|
40
|
+
The Issue or the PR description frames them.
|
package/docs/taxonomy.md
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Taxonomy
|
|
2
|
+
|
|
3
|
+
A **governing artifact** is a Markdown file that code or other docs must follow.
|
|
4
|
+
Each one has a kind, and the folder it lives in sets that kind.
|
|
5
|
+
|
|
6
|
+
| Kind | Folder | Scope | Answers |
|
|
7
|
+
|---|---|---|---|
|
|
8
|
+
| `prd` | `docs/prds/` | one feature | What are we building, and why? |
|
|
9
|
+
| `adr` | `docs/adr/` | a domain | What did we decide, for the long term? |
|
|
10
|
+
| `spec` | `docs/specs/` | a domain | How must it behave, including UX? |
|
|
11
|
+
| `design` | `docs/designs/` | one feature | How will we build this change? |
|
|
12
|
+
| `standard` | `docs/standards/` | cross-cutting | What rules does all work follow? |
|
|
13
|
+
| `procedure` | `docs/procedures/` | cross-cutting | How do we work and operate? |
|
|
14
|
+
|
|
15
|
+
The folders are fixed. Files outside them, such as scratch
|
|
16
|
+
notes, aren't governing artifacts and can't appear in `CONTRACTS`. Inside a
|
|
17
|
+
kind folder, at any depth, `INDEX.md` and `README.md` aren't governing either.
|
|
18
|
+
Any other file there with an invalid slug, such as `My Doc.md`, is an error.
|
|
19
|
+
|
|
20
|
+
## Authority chain
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
prd → adr → spec → design → code
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- The chain ranks **authority**. It isn't a sequence of steps: a change
|
|
27
|
+
touches only the docs it affects, working top-down (see
|
|
28
|
+
[Delivery workflow](workflow.md#touch-only-what-the-change-affects)).
|
|
29
|
+
PRDs, like every kind, are optional.
|
|
30
|
+
- When two records conflict, the higher one wins.
|
|
31
|
+
- **Standards** and **procedures** cut across the chain and can govern any
|
|
32
|
+
path, including other docs.
|
|
33
|
+
- The chain is guidance, not a check. `CONTRACTS` is the authority on what
|
|
34
|
+
depends on what, and review catches a line that doesn't make sense. A doc
|
|
35
|
+
never depends on itself, even when a broad pattern like `*` matches it.
|
|
36
|
+
|
|
37
|
+
## Naming
|
|
38
|
+
|
|
39
|
+
- File names are kebab-case slugs, with no numbers and no kind prefix.
|
|
40
|
+
- **Domain docs** (adr, spec, standard, procedure) are named by domain, for
|
|
41
|
+
example `docs/specs/auth.md`. They're living documents.
|
|
42
|
+
- **Change docs** (prd, design) are named by feature. A PRD and its design share
|
|
43
|
+
a slug: `docs/prds/guided-setup.md` and `docs/designs/guided-setup.md`.
|
|
44
|
+
- Subfolders are allowed and become part of the slug, for example
|
|
45
|
+
`docs/procedures/roles/reviewer.md`.
|
|
46
|
+
- A doc's **id** is `<kind>/<slug>`, derived from its path: `spec/auth`,
|
|
47
|
+
`procedure/roles/reviewer`. Moving a file changes its id, and
|
|
48
|
+
`contracts check` reports every reference the move breaks.
|
|
49
|
+
|
|
50
|
+
## Living ADRs
|
|
51
|
+
|
|
52
|
+
ADRs are revised in place. Reversing a decision is a major version, not a new
|
|
53
|
+
immutable record.
|
|
54
|
+
|
|
55
|
+
## Frontmatter
|
|
56
|
+
|
|
57
|
+
```yaml
|
|
58
|
+
---
|
|
59
|
+
status: accepted # proposed | accepted | deprecated | superseded
|
|
60
|
+
version: 2.3.0 # optional; its presence makes the doc versioned
|
|
61
|
+
title: Authentication
|
|
62
|
+
---
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
| Status | Meaning |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `proposed` | Under design; not in force yet |
|
|
68
|
+
| `accepted` | Current and in force |
|
|
69
|
+
| `deprecated` | No longer true, with no replacement |
|
|
70
|
+
| `superseded` | Replaced; `superseded_by` names the replacement id |
|
|
71
|
+
|
|
72
|
+
- There's no `id` field: the id comes from the path.
|
|
73
|
+
- `version` changes in the PR that changes the doc, by hand or with
|
|
74
|
+
`contracts version`. `contracts check` verifies it moved exactly one step.
|
|
75
|
+
New docs start at `0.1.0`.
|
|
76
|
+
- Frontmatter never declares dependencies. `CONTRACTS` is the only place they
|
|
77
|
+
exist.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Versioning
|
|
2
|
+
|
|
3
|
+
Versioned docs use SemVer, and **you set the version**: whoever changes a doc
|
|
4
|
+
picks its next version in the same PR. Each doc gets its own level, based on
|
|
5
|
+
how that doc changed, so one PR can take a spec to a new minor and an ADR to a
|
|
6
|
+
new patch.
|
|
7
|
+
|
|
8
|
+
The framework reads no PR titles or commit messages and needs no commit
|
|
9
|
+
convention. If you want automation, build it on `contracts version`, for
|
|
10
|
+
example by deriving a level from your own PR titles.
|
|
11
|
+
|
|
12
|
+
Only docs are versioned. Releasing your product or packages stays with your own
|
|
13
|
+
release tooling (semantic-release, release-please, or your own workflow).
|
|
14
|
+
|
|
15
|
+
## Docs are versioned in the PR
|
|
16
|
+
|
|
17
|
+
When a PR changes a versioned doc, the new version goes **in the PR**, so
|
|
18
|
+
reviewers see it. Edit `version:` yourself, or:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
contracts version major docs/specs/auth.md
|
|
22
|
+
# docs/specs/auth.md 2.4.0 → 3.0.0
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
With no path, `contracts version <level>` bumps every versioned doc you
|
|
26
|
+
changed relative to the default branch.
|
|
27
|
+
|
|
28
|
+
`contracts check` verifies the mechanics:
|
|
29
|
+
- **A changed doc moves exactly one step:** to the next patch, minor or major
|
|
30
|
+
(`2.4.0` → `2.4.1`, `2.5.0` or `3.0.0`).
|
|
31
|
+
- **An unchanged doc keeps its version.** "Changed" means anything other than
|
|
32
|
+
the `version` line.
|
|
33
|
+
- A new doc starts at `0.1.0` (`contracts new` writes it).
|
|
34
|
+
- An existing unversioned doc opts in by adding `version: 0.1.0`.
|
|
35
|
+
- A version can never be removed.
|
|
36
|
+
- A renamed doc keeps its version.
|
|
37
|
+
- These rules start once `CONTRACTS` exists on the base branch. The PR that
|
|
38
|
+
adopts contracts can rename and edit docs freely; the versions it leaves
|
|
39
|
+
are the baseline.
|
|
40
|
+
|
|
41
|
+
The check can't tell whether you picked the right level; review does. Ranges
|
|
42
|
+
are then checked against the **real** versions in the PR.
|
|
43
|
+
|
|
44
|
+
## What "breaking" means for a doc
|
|
45
|
+
|
|
46
|
+
For an API, adding something is compatible. For a contract, **adding an
|
|
47
|
+
obligation breaks** the code that implements it. So breaking is judged from the
|
|
48
|
+
implementer's side:
|
|
49
|
+
|
|
50
|
+
> If anything downstream must change to stay correct, it's major.
|
|
51
|
+
|
|
52
|
+
| Kind | patch | minor | major |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| prd | Wording | New optional objective | Objective required, changed, or dropped |
|
|
55
|
+
| adr | Clarification | New allowed option | Decision reversed or constraint added |
|
|
56
|
+
| spec | Wording or correction | New optional capability | Obligation added, changed, or removed |
|
|
57
|
+
| design | Correction | More approach detail | Approach changes the implementation |
|
|
58
|
+
| standard / procedure | Wording | New optional practice | Rule added, changed, or removed |
|
|
59
|
+
|
|
60
|
+
## What happens after merge
|
|
61
|
+
|
|
62
|
+
`contracts release` runs on the default branch. It:
|
|
63
|
+
- tags each doc whose version has no tag yet (`spec/auth@3.0.0`);
|
|
64
|
+
- never edits a file or makes a commit; and
|
|
65
|
+
- refuses to tag anything if the merged tree fails the range check.
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
spec/auth@3.0.0
|
|
69
|
+
adr/sessions@1.0.1
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The tags are the history, and they're also the registry other repositories read
|
|
73
|
+
(see [Across repos](cross-repo.md)).
|
package/docs/workflow.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Delivery workflow
|
|
2
|
+
|
|
3
|
+
The framework relies on a few delivery rules. `contracts init` installs them
|
|
4
|
+
into your repo as a managed procedure (`docs/procedures/contracts-workflow.md`),
|
|
5
|
+
so your own docs don't need to restate them.
|
|
6
|
+
|
|
7
|
+
## The rules
|
|
8
|
+
|
|
9
|
+
The framework owns only the rules its mechanism depends on. How your team
|
|
10
|
+
merges, branches, reviews, stacks PRs, or tracks work is up to you: put that in
|
|
11
|
+
your own procedures. For ideas, see `docs/practices.md` in the
|
|
12
|
+
`@bizibot/contracts` package.
|
|
13
|
+
|
|
14
|
+
1. **Contracts travel with their dependents.**
|
|
15
|
+
- A contract change, and the updates its dependents need, land in the same
|
|
16
|
+
PR to the default branch. `contracts check` enforces this.
|
|
17
|
+
- A behavior change updates its spec in the same PR, and an enduring
|
|
18
|
+
decision updates its ADR there too.
|
|
19
|
+
2. **Versions move with their docs.**
|
|
20
|
+
- A PR that changes a versioned doc sets its next version, choosing patch,
|
|
21
|
+
minor or major for that doc (see the table in the package's
|
|
22
|
+
`docs/versioning.md`).
|
|
23
|
+
- `contracts check` verifies it moved exactly one step.
|
|
24
|
+
3. **The higher record wins.** When records conflict, follow the authority chain
|
|
25
|
+
`prd → adr → spec → design → code`.
|
|
26
|
+
|
|
27
|
+
## One change, end to end
|
|
28
|
+
|
|
29
|
+
Suppose `spec/auth` is at `2.4.0`, and `CONTRACTS` has the line
|
|
30
|
+
`/src/auth/ spec/auth@^2`.
|
|
31
|
+
|
|
32
|
+
1. **Edit.** You add a required MFA rule to `docs/specs/auth.md`. A new
|
|
33
|
+
obligation is major, so you run `contracts version major docs/specs/auth.md`
|
|
34
|
+
to set `version: 3.0.0`.
|
|
35
|
+
2. **Check.** `2.4.0` → `3.0.0` is one step. `/src/auth/` needs `^2`, so the
|
|
36
|
+
check fails and comments with what to update.
|
|
37
|
+
3. **Fix.** In the same PR, you implement MFA and change the line to
|
|
38
|
+
`spec/auth@^3`. The check passes.
|
|
39
|
+
4. **Merge,** with whatever merge method your repo uses.
|
|
40
|
+
5. **Release.** `spec/auth@3.0.0` is tagged. Your own release tooling
|
|
41
|
+
releases the product as it always has.
|
|
42
|
+
|
|
43
|
+
## Managed files
|
|
44
|
+
|
|
45
|
+
- Managed files are marked with the package version that installed them.
|
|
46
|
+
- `contracts check` fails if one is edited by hand.
|
|
47
|
+
- After upgrading the package, run `contracts init --update` to refresh them.
|
|
48
|
+
- Put project-specific rules in your own procedures, which can link to the
|
|
49
|
+
managed one.
|
package/package.json
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@bizibot/contracts",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Contract dependency checks for spec-driven delivery.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"publishConfig": {
|
|
7
|
+
"access": "public"
|
|
8
|
+
},
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/bizibot-hq/bizibot2.git",
|
|
12
|
+
"directory": "packages/contracts"
|
|
13
|
+
},
|
|
14
|
+
"type": "module",
|
|
15
|
+
"bin": {
|
|
16
|
+
"contracts": "./dist/cli.js"
|
|
17
|
+
},
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./dist/index.d.ts",
|
|
21
|
+
"import": "./dist/index.js"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"dist",
|
|
26
|
+
"docs",
|
|
27
|
+
"skills",
|
|
28
|
+
"templates",
|
|
29
|
+
"conformance"
|
|
30
|
+
],
|
|
31
|
+
"sideEffects": false,
|
|
32
|
+
"dependencies": {
|
|
33
|
+
"semver": "^7.8.4",
|
|
34
|
+
"yaml": "^2.9.0"
|
|
35
|
+
},
|
|
36
|
+
"devDependencies": {
|
|
37
|
+
"@types/node": "^20",
|
|
38
|
+
"@types/semver": "^7.7.1",
|
|
39
|
+
"rimraf": "^6.1.3",
|
|
40
|
+
"tsup": "^8.5.1",
|
|
41
|
+
"tsx": "^4.22.4",
|
|
42
|
+
"typescript": "^5"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "rimraf dist && tsup && tsc -p tsconfig.build.json",
|
|
46
|
+
"typecheck": "tsc --noEmit",
|
|
47
|
+
"test": "node --import tsx --test tests/*.test.ts",
|
|
48
|
+
"clean": "rimraf dist"
|
|
49
|
+
}
|
|
50
|
+
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: contracts-adopt
|
|
3
|
+
description: Adopt @bizibot/contracts in an existing repository - run init, sort existing docs into the six kinds, and propose CONTRACTS lines. Use when asked to set up contracts, CONTRACTS, or spec governance in a repo that already has docs.
|
|
4
|
+
---
|
|
5
|
+
<!-- @bizibot/contracts {{version}} managed; run `contracts init --update` -->
|
|
6
|
+
|
|
7
|
+
# Adopting contracts in an existing repo
|
|
8
|
+
|
|
9
|
+
Adoption is reviewed by a human. Propose changes in one PR, and don't push
|
|
10
|
+
anything straight to the default branch.
|
|
11
|
+
|
|
12
|
+
## 1. Bootstrap
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npx @bizibot/contracts init --agents <your-agents>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
This creates the starter `CONTRACTS` file, the kind folders, the workflows, the
|
|
19
|
+
managed procedure, the `AGENTS.md` section, and the skills.
|
|
20
|
+
|
|
21
|
+
## 2. Inventory the existing docs
|
|
22
|
+
|
|
23
|
+
Find every durable Markdown doc: `docs/`, ADR folders, wikis checked into the
|
|
24
|
+
repo, root `CONTRIBUTING.md`, and similar.
|
|
25
|
+
|
|
26
|
+
Sort each one:
|
|
27
|
+
|
|
28
|
+
| It mostly answers… | Kind |
|
|
29
|
+
|---|---|
|
|
30
|
+
| What and why, for one feature | `prd` |
|
|
31
|
+
| A long-term decision and its reasons | `adr` |
|
|
32
|
+
| How something must behave | `spec` |
|
|
33
|
+
| How a specific change was or will be built | `design` |
|
|
34
|
+
| Rules for all work | `standard` |
|
|
35
|
+
| How we work or operate | `procedure` |
|
|
36
|
+
| None of these (notes, analysis, drafts) | not governing: leave it out |
|
|
37
|
+
|
|
38
|
+
When a doc mixes kinds, propose splitting it rather than forcing it into one.
|
|
39
|
+
|
|
40
|
+
## 3. Propose moves and names
|
|
41
|
+
|
|
42
|
+
- Move each doc to its kind folder, with a kebab-case slug: no numbers, no kind
|
|
43
|
+
prefix.
|
|
44
|
+
- Domain docs are named by domain. Feature docs are named by feature.
|
|
45
|
+
- Present a table of old path → new path for the human to approve before you
|
|
46
|
+
move anything.
|
|
47
|
+
|
|
48
|
+
## 4. Start unversioned
|
|
49
|
+
|
|
50
|
+
- Map dependencies as **linked** entries (plain paths) first.
|
|
51
|
+
- Suggest versioning only for the docs code depends on most: usually specs and
|
|
52
|
+
ADRs. Opt them in by adding `version: 0.1.0`, or keep their existing
|
|
53
|
+
versions when they're moved (renames keep versions).
|
|
54
|
+
- Never invent a version history. Start at `0.1.0`.
|
|
55
|
+
|
|
56
|
+
## 5. Propose CONTRACTS lines
|
|
57
|
+
|
|
58
|
+
- Map code folders to the specs and ADRs that describe them.
|
|
59
|
+
- Map specs to the ADRs they follow, and designs to the specs they implement.
|
|
60
|
+
- Use broad patterns (`/src/auth/`), not one line per file.
|
|
61
|
+
- Put cross-cutting standards on `*` or on the folders they cover.
|
|
62
|
+
- Check: `contracts list <path>` for a few key files should show the docs a
|
|
63
|
+
human would expect.
|
|
64
|
+
|
|
65
|
+
## 6. Finish
|
|
66
|
+
|
|
67
|
+
- Run `contracts check`, and fix every error. Report the warnings: dead
|
|
68
|
+
patterns and ungoverned paths.
|
|
69
|
+
- Open one PR (e.g. `chore: adopt contracts`) listing what was moved, what was
|
|
70
|
+
left out as non-governing, and what still needs a human decision.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: contracts-change
|
|
3
|
+
description: Change an existing governing doc (PRD, ADR, spec, design, standard, or procedure) in a repository that uses a CONTRACTS file. Use whenever a governing doc is edited, so each doc's version and its dependents are handled correctly in the same PR.
|
|
4
|
+
---
|
|
5
|
+
<!-- @bizibot/contracts {{version}} managed; run `contracts init --update` -->
|
|
6
|
+
|
|
7
|
+
# Changing a governing doc
|
|
8
|
+
|
|
9
|
+
## 1. Find what depends on it
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
contracts list <id-or-path> --dependents
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Everything this lists might have to change in the same PR.
|
|
16
|
+
|
|
17
|
+
## 2. Decide the bump level
|
|
18
|
+
|
|
19
|
+
Ask: **must anything downstream change to stay correct?**
|
|
20
|
+
|
|
21
|
+
| Kind | patch | minor | major |
|
|
22
|
+
|---|---|---|---|
|
|
23
|
+
| prd | Wording | New optional objective | Objective required, changed, or dropped |
|
|
24
|
+
| adr | Clarification | New allowed option | Decision reversed or constraint added |
|
|
25
|
+
| spec | Wording or correction | New optional capability | Obligation added, changed, or removed |
|
|
26
|
+
| design | Correction | More approach detail | Approach changes the implementation |
|
|
27
|
+
| standard / procedure | Wording | New optional practice | Rule added, changed, or removed |
|
|
28
|
+
|
|
29
|
+
- **Adding a required behavior is major**, even though it feels like a
|
|
30
|
+
feature: the existing code doesn't do it yet.
|
|
31
|
+
- If you're unsure between minor and major, choose major and say why in the
|
|
32
|
+
PR. Under-declaring breaks other people's code without warning.
|
|
33
|
+
- Decide **per doc**. One PR can take one doc to a new minor and another to a
|
|
34
|
+
new patch.
|
|
35
|
+
- Unversioned docs (designs, and any doc without `version`) don't bump. Their
|
|
36
|
+
dependents get review reminders instead.
|
|
37
|
+
|
|
38
|
+
## 3. Set the new version
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
contracts version major docs/specs/auth.md
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
This writes the next version at that level into the doc. You can also edit
|
|
45
|
+
`version:` yourself. The check verifies that every changed versioned doc moved
|
|
46
|
+
exactly one step, and that unchanged ones didn't move.
|
|
47
|
+
|
|
48
|
+
The PR title doesn't affect versions. Title it however the repository's own
|
|
49
|
+
procedures say.
|
|
50
|
+
|
|
51
|
+
## 4. Update the dependents in the same PR
|
|
52
|
+
|
|
53
|
+
For a major bump, each dependent from step 1 needs one of:
|
|
54
|
+
- **an update** to code or docs, so it meets the new obligation, and then its
|
|
55
|
+
`CONTRACTS` range raised (`spec/auth@^2` → `spec/auth@^3`); or
|
|
56
|
+
- **a range raised without code changes**, only if you've confirmed it already
|
|
57
|
+
complies. Say so in the PR.
|
|
58
|
+
|
|
59
|
+
Never lower a contract's bump just to avoid updating dependents.
|
|
60
|
+
|
|
61
|
+
## 5. Check
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
contracts check
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
It verifies the version changes and fails on any dependent still pinned to the
|
|
68
|
+
old range. The run in CI is the authority; this local run is a preview.
|
|
69
|
+
|
|
70
|
+
## Never
|
|
71
|
+
- Remove a `version`, or change one by more than one step.
|
|
72
|
+
- Edit a managed file.
|
|
73
|
+
- Leave a dependent unsatisfied, planning to "fix it in a follow-up PR". The
|
|
74
|
+
check will block the merge, and that's intended.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: contracts-triage
|
|
3
|
+
description: Triage a GitHub Issue (bug report, unexpected behavior, or idea) in a repository that uses a CONTRACTS file. Use to decide whether the code broke a contract or the contract itself is wrong or missing, and to label and link the Issue.
|
|
4
|
+
---
|
|
5
|
+
<!-- @bizibot/contracts {{version}} managed; run `contracts init --update` -->
|
|
6
|
+
|
|
7
|
+
# Triaging an Issue
|
|
8
|
+
|
|
9
|
+
## 1. Find the affected files
|
|
10
|
+
|
|
11
|
+
Use the Issue's stack traces, file names, error messages, and the feature it
|
|
12
|
+
describes. If none is clear, search the code for the behavior it describes.
|
|
13
|
+
|
|
14
|
+
## 2. Find the governing docs
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
contracts list <path>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Run it for each affected file. Read the governing specs first, then the ADRs.
|
|
21
|
+
|
|
22
|
+
## 3. Classify
|
|
23
|
+
|
|
24
|
+
| What you find | Label | The fix is |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| A governing doc says what should happen, and the code doesn't do it | `defect` | A `fix` PR that changes code; the contracts stay as they are |
|
|
27
|
+
| The governing docs are silent, ambiguous, or wrong about this case | `contract-gap` | A PR that changes the contract first (see `contracts-change`), then the code |
|
|
28
|
+
| It asks for something new that no doc covers | `contract-gap` | Usually a PRD or a spec change |
|
|
29
|
+
| No governing doc covers these files at all | `contract-gap` | Add the missing doc and a `CONTRACTS` line |
|
|
30
|
+
|
|
31
|
+
If a doc and the reported expectation disagree, the doc wins until someone
|
|
32
|
+
changes it. Say that in the Issue rather than "fixing" code against the doc.
|
|
33
|
+
|
|
34
|
+
## 4. Record it on the Issue
|
|
35
|
+
|
|
36
|
+
- Apply the label.
|
|
37
|
+
- List the governing ids, with versions (for example `spec/auth@2.4.0`).
|
|
38
|
+
- Quote the specific numbered item that was violated, or say which is missing.
|
|
39
|
+
- For a `contract-gap`, suggest which doc should change and whether it's
|
|
40
|
+
likely a major bump.
|
|
41
|
+
|
|
42
|
+
## Don't
|
|
43
|
+
- Don't fix a `contract-gap` by changing code alone. The contract must change
|
|
44
|
+
first, or the code and contract drift apart.
|
|
45
|
+
- Don't close an Issue as "works as designed" without linking the doc that
|
|
46
|
+
says so.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: contracts-write
|
|
3
|
+
description: Write or revise a governing doc (PRD, ADR, spec, design, standard, or procedure) in a repository that uses a CONTRACTS file. Use when creating a new doc, restructuring one, or unsure what belongs in which kind.
|
|
4
|
+
---
|
|
5
|
+
<!-- @bizibot/contracts {{version}} managed; run `contracts init --update` -->
|
|
6
|
+
|
|
7
|
+
# Writing governing docs
|
|
8
|
+
|
|
9
|
+
A governing doc is a contract: code or other docs depend on it, often at a
|
|
10
|
+
version range. Write it so a reader can tell exactly what it requires, and so
|
|
11
|
+
the next editor can tell whether a change breaks anything.
|
|
12
|
+
|
|
13
|
+
## 1. Pick the kind
|
|
14
|
+
|
|
15
|
+
| If the doc answers… | Kind | Scope |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| What are we building, and why? | `prd` | one feature |
|
|
18
|
+
| What did we decide, for the long term, and why? | `adr` | a domain |
|
|
19
|
+
| How must it behave, including UX? | `spec` | a domain |
|
|
20
|
+
| How will we build this change? | `design` | one feature |
|
|
21
|
+
| What rules does all work follow? | `standard` | cross-cutting |
|
|
22
|
+
| How do we work or operate? | `procedure` | cross-cutting |
|
|
23
|
+
|
|
24
|
+
Write only the kinds your change affects; none is required. If several are
|
|
25
|
+
affected, work top-down. PRDs are optional: use one only for a new feature
|
|
26
|
+
whose what and why need durable agreement.
|
|
27
|
+
|
|
28
|
+
If content fits two kinds, split it. The most common mistakes:
|
|
29
|
+
- implementation detail in a spec (it belongs in a design)
|
|
30
|
+
- behavior in an ADR (it belongs in a spec)
|
|
31
|
+
- a decision buried in a design (it belongs in an ADR)
|
|
32
|
+
|
|
33
|
+
## 2. Create it with the CLI
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
contracts new <kind> <slug>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
This puts the file in the right folder, with the right name, frontmatter, and
|
|
40
|
+
template.
|
|
41
|
+
- Don't create governing docs by hand.
|
|
42
|
+
- New versioned docs start at `0.1.0`. To version an existing doc, add
|
|
43
|
+
`version: 0.1.0`. After that, bump it in each PR that changes the doc
|
|
44
|
+
(`contracts version`).
|
|
45
|
+
- Slugs are kebab-case: domain docs are named by domain (`auth`), change docs
|
|
46
|
+
by feature (`guided-setup`).
|
|
47
|
+
- A PRD and its design share a slug.
|
|
48
|
+
|
|
49
|
+
## 3. Read the reference for that kind
|
|
50
|
+
|
|
51
|
+
Load only the one you need:
|
|
52
|
+
- [references/prd.md](references/prd.md)
|
|
53
|
+
- [references/adr.md](references/adr.md)
|
|
54
|
+
- [references/spec.md](references/spec.md)
|
|
55
|
+
- [references/design.md](references/design.md)
|
|
56
|
+
- [references/standard.md](references/standard.md)
|
|
57
|
+
- [references/procedure.md](references/procedure.md)
|
|
58
|
+
|
|
59
|
+
## 4. Rules for every kind
|
|
60
|
+
|
|
61
|
+
- **One obligation per numbered item.** Then "did this change add, change, or
|
|
62
|
+
remove an obligation?" has a clear answer.
|
|
63
|
+
- **Say "must" only for real requirements.** Use "should" or "may" for
|
|
64
|
+
guidance. Optional items aren't obligations.
|
|
65
|
+
- **Link, don't restate.** If a higher doc already says it, link to it.
|
|
66
|
+
Duplicated rules drift apart.
|
|
67
|
+
- **Declare dependencies in `CONTRACTS`, never in the doc.** If this doc
|
|
68
|
+
follows an ADR, add a line for it in `CONTRACTS`.
|
|
69
|
+
- **Respect the authority chain** (`prd → adr → spec → design → code`). A doc
|
|
70
|
+
may depend only on kinds above it. Standards and procedures may depend on a
|
|
71
|
+
PRD or an ADR.
|
|
72
|
+
|
|
73
|
+
## 5. Revising an existing doc
|
|
74
|
+
|
|
75
|
+
Use the `contracts-change` skill. It covers choosing the bump level and
|
|
76
|
+
updating dependents.
|
|
77
|
+
|
|
78
|
+
## 6. Before you finish
|
|
79
|
+
|
|
80
|
+
Run `contracts check`. It validates placement, frontmatter, and `CONTRACTS`.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Writing an ADR
|
|
2
|
+
|
|
3
|
+
**Answers:** what did we decide, for the long term, and why?
|
|
4
|
+
**Scope:** a domain. Name it by domain (`sessions`), not by the decision's date
|
|
5
|
+
or number.
|
|
6
|
+
**Versioning:** versioned by default. ADRs are living documents.
|
|
7
|
+
|
|
8
|
+
## Belongs here
|
|
9
|
+
- the forces and constraints that made a decision necessary
|
|
10
|
+
- the decision itself, as numbered, enforceable statements
|
|
11
|
+
- the consequences, good and bad
|
|
12
|
+
- the alternatives considered, and why each was rejected
|
|
13
|
+
|
|
14
|
+
## Doesn't belong here
|
|
15
|
+
- **required behavior in detail** → spec
|
|
16
|
+
- **step-by-step implementation** → design
|
|
17
|
+
- **one-off choices** that don't constrain future work → leave them out
|
|
18
|
+
|
|
19
|
+
## Required sections
|
|
20
|
+
1. **Context:** the situation and the forces at play.
|
|
21
|
+
2. **Decision:** numbered statements, one decision or constraint each.
|
|
22
|
+
3. **Consequences:** what becomes easier or harder, and what this rules out.
|
|
23
|
+
4. **Alternatives considered:** each one, and why it lost.
|
|
24
|
+
|
|
25
|
+
## Living ADRs
|
|
26
|
+
Revise the ADR in place as the decision evolves.
|
|
27
|
+
- **Reversing or tightening a decision is a major bump**, not a new file.
|
|
28
|
+
- Mark it `superseded` only when the whole domain decision is abandoned and
|
|
29
|
+
replaced by a different ADR, and set `superseded_by` to that ADR.
|
|
30
|
+
|
|
31
|
+
## Bumps
|
|
32
|
+
- **patch:** a clarification that changes no decision.
|
|
33
|
+
- **minor:** a new allowed option, or a relaxed constraint.
|
|
34
|
+
- **major:** a decision reversed, or a constraint added or tightened.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Writing a design
|
|
2
|
+
|
|
3
|
+
**Answers:** how will we build this change?
|
|
4
|
+
**Scope:** one feature or change. Name it by feature (`guided-setup`), with the
|
|
5
|
+
same slug as its PRD if there is one.
|
|
6
|
+
**Versioning:** never versioned. Designs are linked only, because once the
|
|
7
|
+
change ships, the specs and ADRs govern.
|
|
8
|
+
|
|
9
|
+
## Belongs here
|
|
10
|
+
- the approach: components, data flow, the order of the work
|
|
11
|
+
- which specs and ADRs this implements, as `CONTRACTS` lines pointing at the
|
|
12
|
+
pinned versions
|
|
13
|
+
- the risks, the trade-offs, and the testing plan
|
|
14
|
+
- the open questions, resolved before implementation starts
|
|
15
|
+
|
|
16
|
+
## Doesn't belong here
|
|
17
|
+
- **new required behavior** → put it in the spec first, then design against it
|
|
18
|
+
- **new enduring decisions** → put them in an ADR first
|
|
19
|
+
- **the business case** → PRD
|
|
20
|
+
|
|
21
|
+
If writing the design reveals that a spec or ADR is wrong or missing, fix that
|
|
22
|
+
doc first. A design must never quietly contradict a higher doc.
|
|
23
|
+
|
|
24
|
+
## Required sections
|
|
25
|
+
1. **Summary:** what changes, in a few sentences.
|
|
26
|
+
2. **Governing docs:** the specs and ADRs implemented, matching the `CONTRACTS`
|
|
27
|
+
lines.
|
|
28
|
+
3. **Approach:** how it will be built.
|
|
29
|
+
4. **Testing:** how we'll know it meets the specs.
|
|
30
|
+
5. **Risks and trade-offs.**
|
|
31
|
+
6. **As shipped:** added when the change lands. Record where the result
|
|
32
|
+
differs from the plan.
|
|
33
|
+
|
|
34
|
+
## Lifecycle
|
|
35
|
+
- `proposed` while under review, `accepted` once approved.
|
|
36
|
+
- After it ships, keep it as the record of how the change was built. Add the
|
|
37
|
+
"As shipped" section, and leave the specs as the authority.
|