@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.
Files changed (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +131 -0
  3. package/conformance/patterns.json +12 -0
  4. package/dist/chunk-6OQSBZG4.js +709 -0
  5. package/dist/chunk-6OQSBZG4.js.map +1 -0
  6. package/dist/chunk-LONUJCLW.js +50 -0
  7. package/dist/chunk-LONUJCLW.js.map +1 -0
  8. package/dist/cli.js +258 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/index.js +41 -0
  11. package/dist/index.js.map +1 -0
  12. package/dist/package-T64HPNWA.js +7 -0
  13. package/dist/package-T64HPNWA.js.map +1 -0
  14. package/dist/src/artifacts/discover.d.ts +28 -0
  15. package/dist/src/check/release.d.ts +12 -0
  16. package/dist/src/check/repository.d.ts +19 -0
  17. package/dist/src/check/snapshot.d.ts +37 -0
  18. package/dist/src/check/version-transitions.d.ts +23 -0
  19. package/dist/src/ci.d.ts +20 -0
  20. package/dist/src/cli.d.ts +2 -0
  21. package/dist/src/contracts-file/matcher.d.ts +2 -0
  22. package/dist/src/contracts-file/parse.d.ts +26 -0
  23. package/dist/src/contracts-file/pin.d.ts +10 -0
  24. package/dist/src/contracts-file/ranges.d.ts +11 -0
  25. package/dist/src/contracts-file/resolve.d.ts +16 -0
  26. package/dist/src/index.d.ts +15 -0
  27. package/dist/src/local.d.ts +8 -0
  28. package/dist/src/managed.d.ts +17 -0
  29. package/dist/src/runtime/handoff.d.ts +11 -0
  30. package/dist/src/versioning/paths.d.ts +2 -0
  31. package/dist/src/versioning/validate.d.ts +13 -0
  32. package/dist/src/versioning/version.d.ts +3 -0
  33. package/docs/agents.md +65 -0
  34. package/docs/checks.md +102 -0
  35. package/docs/contracts-file.md +112 -0
  36. package/docs/cross-repo.md +39 -0
  37. package/docs/practices.md +40 -0
  38. package/docs/taxonomy.md +77 -0
  39. package/docs/versioning.md +73 -0
  40. package/docs/workflow.md +49 -0
  41. package/package.json +50 -0
  42. package/skills/contracts-adopt/SKILL.md +70 -0
  43. package/skills/contracts-change/SKILL.md +74 -0
  44. package/skills/contracts-triage/SKILL.md +46 -0
  45. package/skills/contracts-write/SKILL.md +80 -0
  46. package/skills/contracts-write/references/adr.md +34 -0
  47. package/skills/contracts-write/references/design.md +37 -0
  48. package/skills/contracts-write/references/prd.md +49 -0
  49. package/skills/contracts-write/references/procedure.md +34 -0
  50. package/skills/contracts-write/references/spec.md +41 -0
  51. package/skills/contracts-write/references/standard.md +31 -0
  52. package/templates/agents-section.md +16 -0
  53. package/templates/kinds/adr.md +21 -0
  54. package/templates/kinds/design.md +22 -0
  55. package/templates/kinds/prd.md +29 -0
  56. package/templates/kinds/procedure.md +16 -0
  57. package/templates/kinds/spec.md +17 -0
  58. package/templates/kinds/standard.md +16 -0
  59. package/templates/workflows/check.yml +28 -0
  60. 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.
@@ -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)).
@@ -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.