@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,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,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
|