Norms and practices

Norms and practices

Status: Draft — may change (2026-10-19)

1. The question

How does the series separate decisions from living specifications, and which outside norms does it follow?

2. What we propose

Glossary: adapter, plugin and profile

The terms follow Specs-workspace-adapters. The examples describe that design proposal, not a claim that every adapter or plugin already ships.

Term	Meaning	Examples in the proposal
adapter	One of several interchangeable implementations of something the core needs; pick one.	Workspace: headless (built in), herdr, tmux. Registry storage: files, a database, Redis, an online service.
plugin	An optional add-on that brings a new capability; none, one or many.	A knowledge base or a future chat connector.
profile	How TeamCLI drives one CLI.	claude-code, codex, grok, cursor, antigravity, jules, muse, gemini.

Original §3. The rule for this series

	The RFC (this repository, private)	The spec (floor/teamcli, public)
Holds	the problem, the decision, the commitments, the security boundary, alternatives, drawbacks, open questions	formats, fields, exit codes, JSON schemas, event kinds, file layouts, default values
Changes	rarely, through a round	with the code, in a release
Checked by	reviewers	CI, against the code
Rule of thumb	it changes only when the design changes	it could change in a patch release

1. An RFC MUST link to the spec and leave the specification there. Each commitment names the spec section that implements it and the conformance or acceptance test that proves it, where one exists; where none exists the commitment says so.

2. Commitments MUST use BCP 14 keywords (RFC 2119 as clarified by RFC 8174): MUST, MUST NOT, SHOULD, SHOULD NOT and MAY, in capitals only where they are normative; a lower-case "must" is ordinary prose. A commitment's promise is the keyword; its Today line is a fact and carries none.

3. Today MUST be read at a tag or a sha, named once at the head of the Today section, and every Today line of the text is read at it; a line read at another ref says which.

4. An accepted text MUST remain frozen. A change is a new amendment that names what it supersedes, with a status line on the old text (the review process, rules 1 and 4). An editorial correction (a typo, a broken link, a wrong cross-reference) is allowed with a dated line in the text's revision log saying what changed and that no commitment did, confirmed by the board in a batch (the Charter's editorial confirmations are the precedent); it is never silent.

5. Enumerations MUST live in registries in the spec: event kinds, exit codes, policy names, tested CLI version ranges, delivery legs, prompt kinds. A new entry needs a spec change and its check, not an RFC round, unless it breaks a commitment.

   Alongside the eight registries assembled in this refactor, one key registry is shared by team config, team settings and team seat, targeting 0.5.3: config-keys in the config spec draft, under an owner decision. The port manifest keeps a row for each of the eight.

6. The spec MUST NOT link to this private repository. It is public.

7. An RFC MUST keep the Charter's six parts (Part 3: the question; what we propose, as commitments; why; what it costs and what it does not cover; what would change our mind; what is true today) and adds the sections this series uses, in this order after them: the security boundary; where it sits and what it leaves to others; open questions; the review record; and, from this page on, prior art and alternatives where the text argues a choice, and the links to the spec. The Rust template is the model for the additions, not a replacement for the six parts.

Spec: none (these seven rules are governance rules; no spec section implements them). Proof: none (they are reviewed, not tested).

Where the spec side already is (floor/teamcli at v0.5.0)

• contract/cli.json: every command and option, checked by contract:check.
• contract/exit-codes.json, with docs/reference/exit-codes.md beside it, checked by exit-codes:check.
• schema/*.json: forty-one --json documents, JSON Schema 2020-12, checked by schema:check.
• contract/capture-coverage.json, checked by coverage:check; docs/reference/output.md and cli.md; docs/team-file.md, the team file format.
• bun run conformance: the conformance tests against the built binary.

What is missing is registries for event kinds, policy names, delivery legs and prompt kinds. They are listed today inside RFC drafts (002-Communication commitment 25, with the table in Specs-events §3; the policy catalogue; the Runtime's chapter E) and move to the spec at the split of §5.

Original §4. The outside norms we follow

Status: followed (we do it today), adopt (start now), later (planned).

Texts and specs

• BCP 14 (RFC 2119, RFC 8174): normative keywords. Adopt, in new texts from this page on.
• MADR: the common decision-record template (context, options, decision, consequences, status). The owner decisions log already carries that content under its own fields (§6, question 3). Followed in substance; not adopted as a template.
• The Rust RFC template: the model for §3.7's additions. Adopt.

TeamCLI interfaces

• JSON Schema 2020-12 for every --json output. Followed.
• CloudEvents 1.0: the event envelope (specversion, id, source, type; time, subject, datacontentype, dataschema; data). The 0.5.1 bus has its own envelope; whether it can align is a 0.5.2 check. Later.
• The POSIX utility syntax guidelines for options. Followed in the main.

Releases (TeamCLI, material, vlist)

• Semantic Versioning 2.0.0. Followed.
• Keep a Changelog 1.1.0: the Unreleased section and the Added, Changed, Fixed and Removed headings; TeamCLI's CHANGELOG.md says so in its header. Followed in the main.
• Conventional Commits 1.0.0. Followed.
• SLSA provenance: npm publish --provenance from a workflow that holds id-token: write and stores no token (release.yml at v0.5.0). Followed on every publish.

Documentation

• Diátaxis: four kinds of page (tutorials, how-to guides, reference, explanation), kept apart. Adopt: name it in the docs guide.

Security

• ISO/IEC 29147 and 30111, coordinated vulnerability disclosure and handling: a private report path, which SECURITY.md implements through the repository's security advisories. Followed.
• OpenSSF Scorecard: an automated check of repository hygiene, for floor/teamcli, floor/material and floor/vlist. Later: one run each, then decide.

The libraries (material, vlist)

• WCAG 2.2 and the WAI-ARIA Authoring Practices Guide. Adopt: name them in each library's REVIEW.md.
• Material Design 3 (material). Followed.

Original §5. Rollout

1. This page's round: at least three non-Claude reviews (the minimum in Review terms §1), then the board; at acceptance original §3 (the series rule above, in §2) folds into the review process and this page keeps original §§2 and 4.
2. New texts follow the series rule (original §3, above in §2) from this page on, whatever their state: a draft in flight adopts the keywords and the tag at its next revision.
3. After 0.5.1 ships: split the two accepted amendments (the folded Runtime amendment 01 and 002 amendment 01). Their technical sections move into the teamcli repository's specs and registries, and the RFCs keep the commitments and link to the specs.
4. The quick adoptions: BCP 14 keywords; Diátaxis named in the docs guide; WCAG 2.2 and the ARIA practices named in material's and vlist's REVIEW.md.
5. For 0.5.2: the CloudEvents check for the event bus, and one OpenSSF Scorecard run on the three public repositories.

3. Why

Original §1. Why this page exists

Our RFCs mix two things that age differently: the decision (what we commit to, and why) and the specification (formats, fields, codes, defaults). The folded Runtime amendment 01 shows the cost: it lists environment variables, lock-file formats and keychain flags; two of its three review rounds went on those details rather than on the design; and those details change with a patch release while the RFC is meant to stay. Mature projects keep the two apart. This page says how we do it, and which outside norms we follow.

4. What it costs, and what it does not cover

The source identifies review time spent on details that change with patch releases (original §1). It changes no Kernel rule or Charter part. Where it disagrees with the review process, the review process stands until acceptance and the fold.

What this release must not pretend

Adopted, followed and later are distinct statuses; the CloudEvents alignment and Scorecard runs remain planned. The series rule is a proposal pending its round.

5. What would change our mind

No separate reversal criterion is argued in the source. Its unresolved registry-keeper question remains in §10; its rollout requires review and board acceptance.

6. What is true today

Today is v0.5.0 (52db9b75). The implementation inventory remains in original §3 above, with its checks; the status of each outside norm remains in original §4. These are source claims retained for the page’s round, not new adoptions.

7. The security boundary

The spec is public and never links to this private repository (original §3.6). This page changes no Kernel rule. The disclosure and handling standard status stays as original §4 states it.

8. Where it sits, and what it leaves to others

This governance page sits beside the tiers. Acceptance folds original §3 into the review process; the page then keeps original §§2 and 4. The board and review terms govern its round.

9. Prior art and alternatives

Original §2. What the usual practice is

Project	Its decision document	Its living truth
Rust	an RFC on a fixed template (motivation, guide-level and reference-level explanation, drawbacks, rationale and alternatives, prior art, unresolved questions); once merged it is "active", kept roughly in sync with the feature by follow-up pull requests, and it is not the specification	the Reference and the standard library docs
Python	a PEP (PEP 1); once Final it is historical, and later edits are limited to links and typos	the language reference and the docs
Kubernetes	a KEP: motivation, design, a test plan, graduation criteria (alpha, beta, GA), a production readiness review	the API conventions and the OpenAPI spec generated from the code
TC39 (JavaScript)	a proposal through stages 0 to 4; at stage 4 it is merged into the specification and the proposal repository is archived	ECMA-262, one living spec
ADRs	a short record: title, status, context, decision, consequences; never edited, superseded by a new record (Nygard's form; MADR, Markdown Any Decision Records, is the common template)	the specs and API docs
IETF	RFCs with BCP 14 keywords; a published RFC is never edited: corrections are errata, and a later RFC updates or obsoletes it	IANA registries for long lists, each with its own registration policy (many extended by expert review or first-come, without a new RFC; some only by a new RFC)

The shared principles:

1. A decision document is frozen, or nearly so, once accepted. It changes by a new document that supersedes or amends it, and the old text stays readable as history.
2. The spec is living. It is versioned with the code and, wherever possible, generated from it or checked against it.
3. Long lists live in registries, with a stated policy for adding an entry.
4. Normative words are marked. The IETF's MUST, SHOULD and MAY are the common vocabulary; the others use "must" and "should" without the convention.

10. Open questions

Original §6. Open questions

Three were asked in the first draft; this text settles them as far as the architect can, and leaves the owner's word to the round.

1. The registries' home: settled as a proposal. Machine-readable files beside the contract (contract/events.json, contract/policies.json, and the like), each with a :check script and the reference page generated from it, the pattern contract/cli.json and contract/exit-codes.json set at v0.5.0. A hand-kept page under docs/reference/ would be a second copy of what the code knows.
2. Frozen texts and small corrections: settled as a proposal. Original §3.4: an editorial correction is allowed, dated in the revision log, confirmed by the board in a batch, never silent. The IETF's errata and Python's link-and-typo rule are the models; Rust's follow-up pull requests are not, because they let an accepted text drift.
3. The owner decisions log and MADR: settled as a proposal. The log stays as it is: append-only, revoked by status, never deleted, with When, Decision, Meaning, Decided by, Status and Links, which carry MADR's context, decision, consequences and status under other names. Nothing is retrofitted, and new records keep the log's format.
4. Open: who keeps the registries. The TeamCLI team's documentarist, under the orchestrator, is the natural keeper; whether a registry entry that names a new kind needs the architect's read before it lands, or only the check, is the round's to say.

The registries' keeper remains the open question above; assigning the work does not settle the review requirement.

12. Links to the spec

The code inventories and registry names remain at original §3 above. No spec draft is lifted from this governance page; its rule-and-source form is retained.