@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,49 @@
1
+ # Writing a PRD
2
+
3
+ **Answers:** what are we building, and why?
4
+ **Scope:** one feature. Name it by feature (`guided-setup`); its design uses
5
+ the same slug.
6
+ **Versioning:** optional. Unversioned by default; use
7
+ `contracts new prd <slug> --versioned` when other docs pin it.
8
+
9
+ ## When to write one
10
+
11
+ A PRD is optional. Write one when any of these holds:
12
+ - it's a new user-facing capability;
13
+ - the what and why need agreement before design;
14
+ - it spans several PRs or specs; or
15
+ - the reasoning should outlive the Issue thread.
16
+
17
+ Otherwise, an Issue or the PR description is enough. An Issue is lightweight
18
+ discovery; a PRD is the durable, agreed version.
19
+
20
+ ## Belongs here
21
+ - the problem, and who has it
22
+ - the outcome we want, and how we'll know we got it
23
+ - objectives (required) and nice-to-haves (optional), listed separately
24
+ - scope: what's in, and explicitly what's out
25
+ - constraints that come from the business or users
26
+
27
+ ## Doesn't belong here
28
+ - **how to build it** → design
29
+ - **exact behavior or UX rules** → spec
30
+ - **architectural choices** → ADR
31
+
32
+ ## Required sections
33
+ 1. **Problem:** who's affected, and what happens today.
34
+ 2. **Outcome:** the change we want to see.
35
+ 3. **Objectives:** numbered, one per item. Each is required ("must") or
36
+ optional ("should" or "may").
37
+ 4. **Scope:** in and out.
38
+ 5. **Success measures:** how we'll know it worked.
39
+ 6. **Open questions:** resolve them before the PRD is `accepted`.
40
+
41
+ ## Bumps
42
+ - **patch:** wording.
43
+ - **minor:** a new optional objective.
44
+ - **major:** an objective made required, changed, or dropped.
45
+
46
+ ## Lifecycle
47
+ A PRD is `proposed` while being shaped and `accepted` when agreed. Once its
48
+ feature ships, the specs govern behavior. Keep the PRD as the record of why;
49
+ mark it `superseded` only if the feature is replaced.
@@ -0,0 +1,34 @@
1
+ # Writing a procedure
2
+
3
+ **Answers:** how do we work or operate?
4
+ **Scope:** cross-cutting. Name it by activity (`releasing`, `incident-response`,
5
+ `code-review`).
6
+ **Versioning:** optional. Unversioned by default; use `--versioned` when
7
+ automation or other docs pin it.
8
+
9
+ ## Belongs here
10
+ - a repeatable process: triggers, roles, steps, and what counts as done
11
+ - who may do each step: a human, an agent, or CI
12
+ - where the evidence of each step is recorded
13
+
14
+ ## Doesn't belong here
15
+ - **rules that apply to all work** → standard
16
+ - **product behavior** → spec
17
+ - **the framework's own delivery rules.** They're in the managed
18
+ `contracts-workflow.md`; link to it instead of restating it.
19
+
20
+ ## Required sections
21
+ 1. **When to use it:** the trigger.
22
+ 2. **Roles:** who takes part, and what each may do.
23
+ 3. **Steps:** numbered, one action each.
24
+ 4. **Done when:** the exit criteria, and where the evidence lives.
25
+
26
+ ## Bumps (when versioned)
27
+ - **patch:** wording.
28
+ - **minor:** a new optional step.
29
+ - **major:** a step added, changed, or removed that people or automation must
30
+ follow.
31
+
32
+ ## Managed procedures
33
+ Files marked as managed by `@bizibot/contracts` are never edited by hand. Put
34
+ project-specific rules in your own procedure and link to the managed one.
@@ -0,0 +1,41 @@
1
+ # Writing a spec
2
+
3
+ **Answers:** how must it behave, including what users see and do?
4
+ **Scope:** a domain. Name it by domain (`auth`). One living spec per domain;
5
+ features change it over time.
6
+ **Versioning:** versioned by default. Specs are what code pins most often.
7
+
8
+ ## Belongs here
9
+ - observable behavior: inputs, outputs, states, errors, limits
10
+ - UX behavior: flows, states, and copy that is required
11
+ - interfaces other parts depend on: API shapes, events, file formats
12
+ - success criteria that a test or reviewer can verify
13
+
14
+ ## Doesn't belong here
15
+ - **how it's implemented** (classes, libraries, algorithms) → design
16
+ - **why the architecture is shaped this way** → ADR
17
+ - **the feature's business case** → PRD
18
+
19
+ ## Required sections
20
+ 1. **Purpose:** one paragraph on what this domain does.
21
+ 2. **Numbered behavior sections:** one obligation per numbered item.
22
+ - Use "must" for required behavior, and "should" or "may" for optional
23
+ behavior.
24
+ - Keep each item testable: someone should be able to say yes or no.
25
+ 3. **Success criteria:** a short list of checks that prove the spec is met.
26
+
27
+ ## Writing obligations well
28
+ - ✅ "A session must expire after 30 minutes without activity."
29
+ - ❌ "Sessions should be reasonably short." This isn't testable, and nobody
30
+ could tell whether a change to it breaks anything.
31
+ - Prefer adding a new numbered item over expanding an existing one. That keeps
32
+ each bump decision local.
33
+
34
+ ## Bumps
35
+ - **patch:** wording or a correction that doesn't change behavior.
36
+ - **minor:** a new optional capability, or a relaxed limit.
37
+ - **major:** an obligation added, changed, or removed. Existing code may no
38
+ longer comply.
39
+
40
+ Adding a required behavior is **major**, even though it feels like a feature.
41
+ The code that implements this spec doesn't do it yet.
@@ -0,0 +1,31 @@
1
+ # Writing a standard
2
+
3
+ **Answers:** what rules does all work follow?
4
+ **Scope:** cross-cutting. Name it by topic (`code-style`, `api-design`,
5
+ `security-baseline`).
6
+ **Versioning:** optional. Unversioned by default; use `--versioned` when code
7
+ or docs should pin it.
8
+
9
+ ## Belongs here
10
+ - rules that apply across many domains: style, naming, security, testing,
11
+ accessibility
12
+ - the reason behind each rule, briefly
13
+ - short examples of right and wrong
14
+
15
+ ## Doesn't belong here
16
+ - **domain behavior** → spec
17
+ - **one domain's architectural choices** → ADR
18
+ - **step-by-step processes** → procedure
19
+ - **anything a linter or formatter already enforces.** Point to the tool's
20
+ config instead of restating its rules.
21
+
22
+ ## Required sections
23
+ 1. **Applies to:** which work this covers. Keep it consistent with the
24
+ standard's `CONTRACTS` lines.
25
+ 2. **Rules:** numbered, one per item, each with "must", "should", or "may".
26
+ 3. **Exceptions:** how to request one, if that's allowed.
27
+
28
+ ## Bumps (when versioned)
29
+ - **patch:** wording.
30
+ - **minor:** a new optional practice.
31
+ - **major:** a rule added, changed, or removed.
@@ -0,0 +1,16 @@
1
+ <!-- BEGIN @bizibot/contracts {{version}} (managed: do not edit; run `contracts init --update`) -->
2
+ ## Contracts
3
+
4
+ This repository declares which docs govern which files in `CONTRACTS`.
5
+
6
+ - Before editing a file, run `contracts list <path>` and follow the docs that
7
+ govern it.
8
+ - When records conflict, the higher one wins: `prd → adr → spec → design → code`.
9
+ - After changing a versioned doc, set its next version with
10
+ `contracts version <level> <path>` (the check verifies it). Use major when
11
+ the change adds, changes, or removes an obligation.
12
+ - Never edit a file managed by `@bizibot/contracts`.
13
+ - When writing or changing a governing doc, use the `contracts-write` and
14
+ `contracts-change` skills.
15
+ - Run `contracts check` before pushing. CI's run is the authority.
16
+ <!-- END @bizibot/contracts -->
@@ -0,0 +1,21 @@
1
+ ---
2
+ status: proposed
3
+ version: 0.1.0
4
+ title: {{title}}
5
+ ---
6
+
7
+ ## Context
8
+
9
+ <!-- The situation and the forces that make a decision necessary. -->
10
+
11
+ ## Decision
12
+
13
+ 1. <!-- One decision or constraint per item. -->
14
+
15
+ ## Consequences
16
+
17
+ -
18
+
19
+ ## Alternatives considered
20
+
21
+ - **<!-- alternative -->:** <!-- why it lost -->
@@ -0,0 +1,22 @@
1
+ ---
2
+ status: proposed
3
+ title: {{title}}
4
+ ---
5
+
6
+ ## Summary
7
+
8
+ <!-- What changes, in a few sentences. -->
9
+
10
+ ## Governing docs
11
+
12
+ <!-- The specs and ADRs this implements, matching their CONTRACTS lines. -->
13
+
14
+ -
15
+
16
+ ## Approach
17
+
18
+ ## Testing
19
+
20
+ ## Risks and trade-offs
21
+
22
+ <!-- Add "## As shipped" when the change lands. -->
@@ -0,0 +1,29 @@
1
+ ---
2
+ status: proposed
3
+ title: {{title}}
4
+ ---
5
+
6
+ ## Problem
7
+
8
+ <!-- Who is affected, and what happens today? -->
9
+
10
+ ## Outcome
11
+
12
+ <!-- The change we want to see. -->
13
+
14
+ ## Objectives
15
+
16
+ 1. <!-- Required: "must …". One objective per item. -->
17
+
18
+ ## Scope
19
+
20
+ - **In:**
21
+ - **Out:**
22
+
23
+ ## Success measures
24
+
25
+ -
26
+
27
+ ## Open questions
28
+
29
+ -
@@ -0,0 +1,16 @@
1
+ ---
2
+ status: proposed
3
+ title: {{title}}
4
+ ---
5
+
6
+ ## When to use it
7
+
8
+ ## Roles
9
+
10
+ ## Steps
11
+
12
+ 1.
13
+
14
+ ## Done when
15
+
16
+ <!-- The exit criteria, and where the evidence is recorded. -->
@@ -0,0 +1,17 @@
1
+ ---
2
+ status: proposed
3
+ version: 0.1.0
4
+ title: {{title}}
5
+ ---
6
+
7
+ ## Purpose
8
+
9
+ <!-- One paragraph: what this domain does. -->
10
+
11
+ ## 1. <!-- Behavior area -->
12
+
13
+ 1. <!-- One testable obligation per item, using "must", "should", or "may". -->
14
+
15
+ ## Success criteria
16
+
17
+ -
@@ -0,0 +1,16 @@
1
+ ---
2
+ status: proposed
3
+ title: {{title}}
4
+ ---
5
+
6
+ ## Applies to
7
+
8
+ <!-- Which work this standard covers. -->
9
+
10
+ ## Rules
11
+
12
+ 1. <!-- One rule per item, using "must", "should", or "may", with a brief reason. -->
13
+
14
+ ## Exceptions
15
+
16
+ <!-- How to request one, if allowed. -->
@@ -0,0 +1,28 @@
1
+ name: contracts / check
2
+ on:
3
+ pull_request_target:
4
+ types: [opened, synchronize, reopened, edited]
5
+ jobs:
6
+ check:
7
+ runs-on: ubuntu-latest
8
+ permissions:
9
+ contents: read
10
+ pull-requests: read
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ with:
14
+ ref: ${{ github.event.pull_request.base.sha }}
15
+ - uses: actions/setup-node@v4
16
+ with:
17
+ node-version: 22
18
+ - id: contracts
19
+ run: |
20
+ set -euo pipefail
21
+ version="$(sed -n '1s/^# @bizibot\/contracts //p' CONTRACTS)"
22
+ [[ "$version" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]
23
+ echo "version=$version" >> "$GITHUB_OUTPUT"
24
+ - run: npx --yes "@bizibot/contracts@$CONTRACTS_VERSION" check --github-pr "${{ github.event.pull_request.number }}"
25
+ env:
26
+ CONTRACTS_VERSION: ${{ steps.contracts.outputs.version }}
27
+ # Required to read PR metadata and changed files as data.
28
+ CONTRACTS_GITHUB_TOKEN: ${{ github.token }}
@@ -0,0 +1,29 @@
1
+ name: contracts / release
2
+ on:
3
+ push:
4
+ concurrency:
5
+ group: contracts-release-${{ github.repository }}
6
+ cancel-in-progress: false
7
+ jobs:
8
+ release:
9
+ if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
10
+ runs-on: ubuntu-latest
11
+ permissions:
12
+ contents: write
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+ with:
16
+ fetch-depth: 0
17
+ - uses: actions/setup-node@v4
18
+ with:
19
+ node-version: 22
20
+ - id: contracts
21
+ run: |
22
+ set -euo pipefail
23
+ version="$(sed -n '1s/^# @bizibot\/contracts //p' CONTRACTS)"
24
+ [[ "$version" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]
25
+ echo "version=$version" >> "$GITHUB_OUTPUT"
26
+ - run: npx --yes "@bizibot/contracts@$CONTRACTS_VERSION" release
27
+ env:
28
+ CONTRACTS_VERSION: ${{ steps.contracts.outputs.version }}
29
+ - run: git push origin --tags