ADR 0026: PR packet, CI generator, and team policy section
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-06-01 |
| Deciders | Project maintainers |
| Supersedes | — |
| Superseded by | — |
| Related ADRs | ADR-0011 (Zod schema), ADR-0014 (parsed manifests) |
Summary
Three small, deterministic team-workflow helpers land together:
aidokit pr packetassembles a markdown PR review packet (summary, changed files fromgit diff --name-only main...HEAD, linked task brief, validation commands, risks/rollback) to stdout or--output.aidokit ci init --provider <github|gitlab|bitbucket>emits a CI config that runspnpm -r build,pnpm -r test, andaidokit verify --all-facets. Read-before-write: it refuses to clobber an existing target without--force.- The verify policy schema gains an optional, additive
teamsection (allowedMcps?,commitFormat?,prChecklist?). It does not change any existingverifybehavior.
All three are zero-LLM, zero-network, deterministic runtime helpers. None
touch init emission or the byte-compare fixtures.
Context
Teams adopting aidokit asked for three recurring chores to be scaffolded rather than hand-rolled per project: a consistent PR description, a CI pipeline that runs the same gates aidokit defines, and a place to declare team conventions (allowed MCP servers, commit format, PR checklist) next to the existing verify policy.
These are productivity helpers, not new verification semantics. They follow
the existing aidokit audit export pattern (read artifacts off disk, render
markdown, never invent evidence) and the existing aidokit eval brief
resolution.
Decision
1. aidokit pr packet
A pr parent command with a packet subcommand. Brief resolution reuses the
eval rules: --task <id> → agent-artifacts/task-briefs/<id>.md,
--brief <path> override, or a lone brief in the directory. The packet lifts
the brief's ## Goal, ## Validation commands, and any ## Risks /
## Rollback sections via a case-insensitive heading extractor, falling back
to honest placeholders when absent. Changed files come from
git diff --name-only <base>...HEAD (--base, default main) run via
execFile (no shell). Output goes to stdout or --output.
2. aidokit ci init
A ci init subcommand with a required --provider. Plain-string templates
(no template engine, CLAUDE.md §6 principle 1) per provider:
| Provider | Target |
|---|---|
github |
.github/workflows/aidokit.yml |
gitlab |
.gitlab-ci.yml |
bitbucket |
bitbucket-pipelines.yml |
Each runs pnpm -r build, pnpm -r test, aidokit verify --all-facets.
Read-before-write (principle 8): an existing target is a BAD_INVOCATION
error unless --force is passed.
3. Team policy section
PolicySchema gains an optional team object: allowedMcps?: string[],
commitFormat?: string, prChecklist?: string[], .strict(). It is absent
by default and never read by the verify runner — purely additive and
backward-compatible. Future team tooling consumes it declaratively.
Consequences
Positive
- One command each for three recurring team chores; deterministic and testable.
- Reuses established patterns (audit-export rendering, eval brief resolution, execFile git access).
teamsection is forward-compatible: tooling can opt in without a schema break.
Negative
- The PR packet's risks/rollback depend on brief authors writing those sections; absent them, the packet shows placeholders. Acceptable — the packet is a scaffold, not a guarantee.
Neutral
- CI templates are opinionated (pnpm + Node 20). Teams edit the emitted file freely; aidokit does not own it after emission.
Validation
- [ ]
aidokit pr packetrenders summary / changed-files / validation / risks sections; lifts brief content when present. - [ ]
aidokit ci init --provider <p>writes the provider target and refuses to clobber without--force. - [ ]
PolicySchemaaccepts an optionalteamsection and rejects unknown keys; existing verify defaults unchanged.
References
- ADR-0011 — Zod schema library (policy schema home).
init/audit-export.ts— the packet/render pattern this follows.commands/eval.ts— brief resolution reused by the PR packet.