Repository navigation
v1.3.0
Three experimental stack plugins join the marketplace at 0.1.0: agent-be-go (a Go HTTP service on
PostgreSQL), agent-be-axum (Rust and Axum on PostgreSQL) and agent-ios-swiftui (a SwiftUI app that
calls such an API). Each keeps the kit's four contracts: a line budget per file, one closed
error-code registry with an RFC 9457 body, no missing translation, and 100% coverage in its own
tool's metrics. Three reusable quality gates come with them. Their callers hold the release
placeholder, so setup keeps them back until the release that pins them.
In the same release, every stack mints its problem type from the error code under one https base
per API, payload refusals stop sending internal messages, the payload contract is ported to the Go
and Rust servers and the iOS client with a shared key-agreement vector, migration-guard learns an
append-only mode for hand-written migrations, and every plugin component now passes a SkillSpector
scan in CI. agent-be-hono is a major release: its check:openapi now requires the Problem
contract.
Reusable workflows and actions
Added
be-go-quality-gate.yml,be-axum-quality-gate.ymlandios-swiftui-quality-gate.yml
(workflow_call,contents: read). The two backends startpostgres:18.6, pinned by its
multi-arch index digest, as a service on127.0.0.1:5432with trust auth;database: false
starts none, for a repo that owns no schema. The iOS gate runs three jobs: the Linux-safe checks
on Linux, the build and tests on macOS (runs-on, elseCI_RUNNER_MACOS, elsexcode-27, with
the Xcode thatxcode-versionnames throughDEVELOPER_DIR) only after those passed, and a final
job, Quality Gate (ios-swiftui), that is the one check to require.actions/quality-gateknows the stacksbe-go,be-axumandios-swiftui
(scripts/stacks/*.sh) and the inputsphase,database,pgbouncer-tests,
pgbouncer-max-prepared-statements,xcode-versionandscheme. For the backends:
db/roles.sqlbefore the tests, every migration from zero on an empty database (goose or sqlx),
the.sqlxquery cache against that schema (Rust), a foreign key without a leading index or an
INVALID index fails, the migrations against the base branch and squawk over the new ones, the
pool and server settings, govulncheck orcargo deny, the release build and the Docker build.scripts/install-release.shand the pin tablescripts/tools.lock: golangci-lint 2.14.0,
squawk 2.68.0, cargo-llvm-cov 0.9.1, cargo-nextest 0.9.148, cargo-deny 0.20.2, SwiftLint 0.65.1
(swiftlint-staticon Linux) and Periphery 3.8.0, each refused unless its SHA-256 and the
version it reports match; sqlx-cli 0.9.0, which ships no binary, is built with
cargo install --locked.- An optional PgBouncer check for be-go and be-axum (
pgbouncer-tests: true):
scripts/pgbouncer.shstartsghcr.io/cloudnative-pg/pgbouncer:1.26.0, pinned by digest and
version-checked, on127.0.0.1:6432in transaction mode and runs the repo's
scripts/check/pooler.shbehind it. - The coverage floor reads Go's cover profile (
coverage/coverage.out, statements).
Changed
- The gate refuses more names in the env file, the ones that steer a Go, Rust, sqlx or Xcode
toolchain:GOFLAGSand Go's otherGO…names,CGO_*,CARGO_*,RUSTUP_*,RUSTC*,
RUSTFLAGS,RUSTDOCFLAGS,SQLX_*andDEVELOPER_DIR.GOOGLE_CLIENT_IDand similar stay
allowed.
Repository checks
Added
- Self Test runs a SkillSpector (plugins) job:
scripts/skills-plugins.shlays every plugin
out as a user's repo would hold it (commands and agents under.claude/, skills under
.claude/skills/, hook scripts under.claude/hooks/) and runs the template'sskills.shwith
the template's baseline, unchanged. A scan that fails or reads a file only in part fails the job,
as does a pull request that adds a line to the baseline. All eleven plugins pass with nothing at
MEDIUM or above. scripts/check-comment-style.mjs, run by Self Test: the kit's JavaScript and TypeScript use
/** */for a file or a declaration and/* */for other notes, and keep//for tool
directives.--fixrewrites the rest; every existing comment was converted, with no change in
behaviour.tests/setup/conflicts.batsderives the primary stacks from the plugins on disk and checks that
everyconflictsWithpair is mutual.
Changed
scripts/workflow-policy.pyfails a job that runs steps withouttimeout-minutes.scripts/catalog.mjsrefusesgo run|generate|get|install,cargo run|install|add,
swift run|packageand barexcodebuildorxcrunin a template'sallowlist, and
cargo install,rustup,brew installandmint installin hook and runtime scripts. A Go
build constraint is never read as a file's description..github/gitleaks.tomlallows theh1:checksums in agent-be-go'sgo.sum.starter, that file
only; gitleaks already skipsgo.sumin users' repos.
Fixed
scripts/catalog.mjsmatches**across folders. It matched within one folder, so the README
called agent-be-hono's payload tests always installed when setup treats them as payload-only.scripts/catalog.mjsescapes a backslash before a pipe in a README table cell, so a backslash in
a description can no longer undo the pipe's escape, andscripts/version-sync.mjsescapes every
regular-expression metacharacter in a plugin name and version (CodeQL
js/incomplete-sanitization). The generated READMEs do not change.
agent-core 1.2.0
Added
- The
languagequestion also takesgo,rustandswift(one choice), and setup reads
go.mod,Cargo.toml,Package.swiftand*.xcodeprojto suggest it. Each answer installs
.claude/rules/<language>/types.mdanddead-code.md, which load only while Claude edits that
language. A lock written withtypescript,pythonorbothstays in sync. - The agent
agent-core:spec-reviewerchecks a diff against the spec it implements (the linked
issue, the approved plan, or a named spec file) and reports missing or partial requirements,
unrequested behaviour and wrong implementations, each quoting its spec line. - The hook setting
appendOnlyMigrationsDirs(default empty) inlib.sh, documented in
.claude/agent-config.example.json,.claude/OPERATIONS.example.mdand the README's table.
hook-probes.shproves migration-guard's append-only mode, and generated-guard's Go and Rust
markers, where the repo has the guard. - post-edit gives feedback for
*.go(golangci-lint fmt, then golangci-lint run on the package,
capped at 20 s;gofmt -wandgo vetwithout golangci-lint;GOTOOLCHAIN=local GOPROXY=off GOFLAGS=-mod=readonly),*.rs(rustfmt on stdin, written back only when it differs;cargo clippy --locked --all-targetsfrom a rootCargo.toml, this file's lines, capped at 10 s;
RUSTUP_AUTO_INSTALL=0 CARGO_NET_OFFLINE=true SQLX_OFFLINE=true),*.swift(xcrun swift-format, then swiftlint; a version mismatch says nothing),*.xcstrings(valid JSON, every
key in every locale the catalog uses, state translated) and*.pbxproj(plutil -lint). A
package-wide note stops after 40 lines. - folder-shape.mjs knows Rust (
src/main.rsandsrc/lib.rsare entrypoints,mod.rsdoes not
count,target/is skipped) and Swift packages (Packages/*/SourcesandTests, or a root
Package.swift:XTests.swiftmirrorsX.swift;GeneratedSources/is skipped). Go stays
outside its roots, and.claude/rules/common/folder-shape.mdsays so. - ai-config.sh check 5: every path in CLAUDE.md's "On-demand references" table (a cell that is one
backticked path) exists, or its*.example.*sibling or a glob match does. A repo whose CLAUDE.md
keeps rows for docs it never installed fails the gate until the row goes or the file is added.
Changed
/agent-core:reviewruns two axes in separate subagents, started together: standards (the
stack reviewer, elseagent-core:reviewer, with security-guard and the specialists) and spec.
The report keeps them in two sections, never merged or reranked, each with its worst finding;
every finding cites a rule or a spec line; what a linter or gate enforces is skipped; neither
subagent may run/agent-core:reviewagain or start more subagents. The verdict is per axis./agent-core:shipputs a spec-axis finding on the worklist as HIGH when the change misses or
misimplements a requirement, and leaves behaviour the spec never asked for to the user.- post-edit also passes on
path:line:findings without a column (revive's file length). CI-RUNNERS.example.mdaddsCI_RUNNER_MACOSand explains the iOS gate's split.help.mdlists the commands of the three new plugins.
Fixed
- SkillSpector reads
help,setup,review,security-guardand the setup-check hook in full
with no finding: they name.envin backticks, say "does not check who is calling" instead of
"without checking", and show the workflow expression in a fenced block.
agent-be-hono 2.0.0
Changed
- Breaking:
check:openapialso checks the spec'sProblemcontract:components.schemas.Problem
exists,codecarries theERROR_CODESenum inline (a$refis not followed) and every code
matches^[A-Z][A-Z0-9_]*$,typeisformat: uriwith a validx-problem-type-base(an
absolute https URI ending in/, with no query or fragment), andabout:blankis no default,
const or enum value. A repo set up earlier fails its gate after sync until
src/lib/errors/problem.tspublishes that contract (by hand, below). To defer, run
agent-sync own scripts/check/openapi.ts: sync stops replacing the file, and
agent-sync own --undo scripts/check/openapi.tshands it back onceproblem.tsis ready. createPayloadMiddlewaretakes a requiredproblemTypeBase, refuses to start with a base that
cannot prefix a type, and puts the request id fromrequestId()in the refusal.error-codes.md,hono.md,patterns.md, the payload contract and its short rule, and
reviewerdescribe the problem type:PROBLEM_TYPE_BASEplus the code, a fixed title per code, a
registered code for 404, 405,HTTPExceptionand 500, upstream problems minted again under this
API's base, and the placeholderhttps://example.invalid/problems/refused in production.scripts/check/ci-env.shrecognises a caller of any<stack>-quality-gate.ymland refuses the
same toolchain names as the gate (one regex, the same bytes as the gate'sQG_REFUSED_ENV).scripts/check/coverage-policy.mjs(the same bytes in every stack) also checks a repo whose
coverage runs fromscripts/check/coverage.sh: the script hands its report to
coverage-per-file.mjs,gates.listruns it throughci-env.sh, and every line of
scripts/check/coverage-exempt.txtreads<path or glob> # composition root: <why>or
# generated: <why>. A repo with a bun, vitest or pyproject coverage config is checked as before.CLAUDE.md.startermarks the On-demand rows for files only one setup answer installs with
"(with<answer>=yes)", so a fresh default setup passes agent-core's pointer check. Rule 26 in
AGENTS.md.startersays blank lines and comments do not count, as.oxlintrc.jsonsets.
Seeded files: existing repos are not changed.conflictsWithnames agent-be-go, agent-be-axum and agent-ios-swiftui.- Comments in the shipped scripts are block comments; no behaviour changes.
Added
- migration-guard's append-only mode for hand-written migrations (
appendOnlyMigrationsDirs): a
new migration, or one only the work branch has, stays editable; a write to a file any
protectedBranchesbranch already holds (locally or asorigin/<branch>) is refused, and so is
one where git cannot answer. ADR 0007. Drizzle folders behave as before. src/lib/payload/refusal.ts(seeded withpayload-encryption=yes) builds the refusal:
{ type: <base><CODE>, title, status, code, requestId? }, one title per code, and
checkProblemTypeBase; it imports nothing from Hono. Its test is__tests__/refusal.test.ts.- The shared payload vectors carry a key-agreement answer:
agreements(a fixed server JWK and
client scalar, the ECDH shared bytes, the HKDF-SHA-256 session key and an envelope sealed under
it) andpointRejects(a point off the curve, 64 bytes without the prefix, a compressed point).
The existing keys are unchanged.check:crypto-interopruns them through the synced helper
scripts/lib/payload-agreement.ts: WebCrypto derives the shared bytes from both sides and the key
with HKDF, andsrc/lib/payload/ecdh.tsmust open the envelope from either side and refuse every
bad point withENVELOPE_MALFORMED.
Fixed
- The payload middleware's default refusal sent the internal error message as
detail, which
names route patterns and server state; it now sends the code and nodetail. - A sealed response carries
Vary: x-payload-epk, x-payload-kid, so a shared cache never serves
one caller's envelope to another. - The payload contract's error table says what both implementations do: an unknown version or a
missing field isENVELOPE_REQUIRED, notENVELOPE_MALFORMED. Each code documents its title and
status. check:endpointsandgenerate:endpointsrefuse apayload.config.jsonencryptionthat is
neitherstrictnoroff; a typo such asstirctused to read as strict. An absent value still
means strict.deriveSessionKeyrefuses a peer key that is not the 65-byte uncompressed point. Node and Bun
imported a compressed point, which the Go, Rust and Swift ports refuse.- A Serena
replace_in_filesthat reaches a migrations folder says "reaches migrations
(migrationsDirs or appendOnlyMigrationsDirs)".
By hand
Seeded files never sync. Where payload-encryption=yes:
- Copy
src/lib/payload/refusal.tsandsrc/lib/payload/__tests__/refusal.test.tsfrom the
template. - In
src/middlewares/payload.middleware.ts, take the template's version, or dropdetailfrom
the default refusal, build it withpayloadRefusal(base, status, error.code, requestIdOf(c)),
addproblemTypeBaseto the options (checked withcheckProblemTypeBase), and
headers.append('vary', 'x-payload-epk, x-payload-kid')where the response is sealed. Update its
test the same way. - In
src/app.ts, passproblemTypeBase: PROBLEM_TYPE_BASEtocreatePayloadMiddleware. - Copy the length and prefix check from the template's
src/lib/payload/ecdh.ts(and its test),
orcheck:crypto-interopreportspoint reject compressed point: accepted. SSOT.md"Error Contract" andAGENTS.md§C: the new shape and the base (the starters show the
wording).
In every repo, the project-owned src/lib/errors/problem.ts:
export const PROBLEM_TYPE_BASE = 'https://api.example.com/problems/';with your own domain,
set once and never changed. Refuse to start in production while its host ends in.invalid.- Mint every body's
typeas${PROBLEM_TYPE_BASE}${code}, give each code a fixedtitle, and
map 404, 405, everyHTTPExceptionand unknown 500s to registered codes; a relayed upstream
problem keeps its code and status under this base. - Make the registered
Problemschema carrytypeasformat: uriwith
x-problem-type-base: PROBLEM_TYPE_BASE,codewith theERROR_CODESenum inline, both
required, and noabout:blankdefault; thenbun run spec:export, runcheck:openapi, and
copyopenapi.jsonto every frontend.
agent-fe-nextjs 1.3.0
Added
check:error-codescompares the spec'sx-problem-type-basewith aPROBLEM_TYPE_BASEexport
insrc/lib/errors/problem-key.ts. It fails when the spec's base is malformed, when the spec
publishes a base and the export is missing or differs, and when the export exists but the spec
publishes none; a spec with neither passes and says that problems resolve by code. Action is
needed only once your API publishes a base.- The shared payload vectors carry the key-agreement answer, and
check:crypto-interopderives it
from both sides throughscripts/lib/payload-agreement.ts. A repo that holds the browser client
(src/lib/payload/client.ts) is the client side, so the bad-point vectors are the server's to
refuse and a repo that adopted the contract earlier keeps passing. The template'secdh.ts
refuses a compressed point, as every server does. - generated-guard also refuses a write to an existing Go file whose header has a whole
// Code generated ... DO NOT EDIT.line before the package clause, and to a Rust file with
@generatedin a comment among its first five lines, wherever the file lives. Such a file that a
hand edit used to reach is now refused;"generatedPaths": []no longer switches this part off
(disable the plugin for that). A folder-widereplace_in_filesis still judged by
generatedPathsonly.
Changed
error-codes.md(identical to agent-be-hono's) gives the order a frontend resolves a problem in:
the base plus a known code gets its message; an absent orabout:blanktype falls back to the
code; anything else is unknown.reviewerflags a mapping that ignorestype, and the payload
contract asks the proxy route to sendVaryon what it seals for the browser.- generated-guard's refusal says the API contract is exported by the service that owns it or
copied from it. scripts/check/coverage-policy.mjs: the shared copy, as in agent-be-hono.CLAUDE.md.startermarks the On-demand rows for files only one setup answer installs, as in
agent-be-hono.conflictsWithnames the three new stacks.scripts/lib.shcopy updated.- Comments in the shipped scripts are block comments; no behaviour changes.
Fixed
- The payload contract's error table (
ENVELOPE_REQUIREDfor an unknown version or a missing
field), andcheck:endpointsrefuses a misspelledencryptionswitch, as in agent-be-hono. - SkillSpector reads the
react-doctorandskeletonskills in full: their paths and the
CLI-choosing line moved toreferences/cli.mdandreferences/files.md, and the rule-explain
command sits in a fenced block. What the skills tell Claude is unchanged.
By hand
-
Seeded files:
AGENTS.mdRule 37 (resolve a problem by its type; the starter shows the
wording); the comment onENVELOPE_REQUIREDandENVELOPE_MALFORMEDin
src/lib/payload/errors.ts(wording only). -
Project-owned
src/lib/errors/problem-key.ts: exportPROBLEM_TYPE_BASE, equal to the spec's
x-problem-type-base, and resolve a body by its type before the code:export const PROBLEM_TYPE_BASE = 'https://api.example.com/problems/'; export function problemCodeOf(body: unknown): string | undefined { if (typeof body !== 'object' || body === null) return undefined; const code: unknown = Reflect.get(body, 'code'); const raw: unknown = Reflect.get(body, 'type'); const type = typeof raw === 'string' ? raw : 'about:blank'; if (typeof code !== 'string') return undefined; return type === `${PROBLEM_TYPE_BASE}${code}` || type === 'about:blank' ? code : undefined; }
A proxy route that seals for the browser also sets
Vary: x-payload-epk, x-payload-kid, and a
refusal it raises itself sends the contract's body.
agent-ai-fastapi 1.3.0
Added
- migration-guard's append-only mode, as in agent-be-hono; Alembic folders behave as before.
Changed
PayloadMiddlewaretakes a requiredproblem_type_basekeyword and refuses to start with a base
that cannot prefix a type. The seeded tests assert whole refusal bodies and stay at 100% branch
coverage.fastapi.mdandtesting.mddescribe the shape{type, title, status, code}withcode
required andtype == PROBLEM_TYPE_BASE + code;ai-reviewerflagsabout:blank, a hand-built
type, a per-occurrence title,instanceset to a resource id, and a changed base.scripts/check/payload-vectors.jsongains theagreementsandpointRejectssections every
stack shares. The Python service is a server caller with no key agreement, so its seeded tests
read only the AES vectors and pass unchanged.scripts/check/coverage-policy.mjs: the shared copy, as in agent-be-hono.CLAUDE.md.startermarks the On-demand rows for files only one setup answer installs.conflictsWithnames the three new stacks.scripts/lib.shcopy updated.
Fixed
- The payload middleware's refusal sent the internal error message as
detailand notype
(which reads asabout:blank); it now sends{ type: <base><CODE>, title, status, code }with
one title per code. - A sealed response carries
Vary: x-payload-epk, x-payload-kid. - The payload contract's error table, as in agent-be-hono.
By hand
- Seeded files, where
payload-encryption=yes: take the template's
src/app/core/payload/middleware.pyandtests/unit/core/payload/test_middleware.py, or drop
"detail": str(error)from_refuse, addtypeand the per-code titles, add the
problem_type_basekeyword, and add thevarypair to the sealed response's headers. Pass
problem_type_base=PROBLEM_TYPE_BASEwheremain.pyadds the middleware. - Seeded starters:
AGENTS.mdRule 10 (the shape is{type, title, status, code}plus an
optional client-safedetail) and the widget recipe (a per-typetitle, no
instance=widget_id:instancenames an occurrence, RFC 9457 section 3.1.5);SSOT.md"Error
contract". - Project-owned
src/app/core/errors/problems.py: definePROBLEM_TYPE_BASE(your own https base,
set once, refused in production while its host ends in.invalid), mint
type = PROBLEM_TYPE_BASE + codefor every body, makecoderequired (404, 422 and unhandled
500s get registered codes), keeptitlefixed per code, and leaveinstanceout unless it names
the occurrence.
agent-docs-nextra 1.2.0
Added
- generated-guard recognises the Go and Rust generated-code markers, as in agent-fe-nextjs, and its
refusal names where the API contract comes from.
Changed
CLAUDE.md.startermarks the On-demand rows for files only one setup answer installs.conflictsWithnames the three new stacks.scripts/lib.shcopy updated.
agent-fe-nextjs-static 1.1.3
Changed
conflictsWithnames the three new stacks.- Comments in the shipped check scripts are block comments; no behaviour changes.
agent-fe-threejs 1.0.3
Fixed
setupsays the budget check runs "without a permission prompt", a wording SkillSpector no
longer reads as an agent acting unasked. Comments in the shipped check script are block comments.
agent-deploy 1.1.3
Fixed
syncsays a missingaskrule lets a network script run "with no permission prompt", a wording
SkillSpector no longer reads as an agent acting unasked.
agent-be-go 0.1.0
Added
- A new, experimental stack plugin for Go HTTP services on PostgreSQL:
net/httpwith a server
oapi-codegen v2.8.0 generates fromapi/openapi.yaml(spec first), pgx v5 and sqlc for queries,
goose for migrations, golangci-lint v2.14.0. Rule numbers, layout and setup questions may still
change before 1.0.0. - Hooks:
migration-guard(the shared script; setup seedsappendOnlyMigrationsDirs: ["db/migrations"]) andgenerated-guard(setup seedsgeneratedPathsforapi/openapi.json,
internal/httpapi/api.gen.goandinternal/postgres/db). - Commands
/agent-be-go:setupand/agent-be-go:sync; theagent-be-go:reviewersubagent (the
standards axis of/agent-core:review); the skillsapi-endpoint(contract first, one tracer
bullet per behaviour) anddb-migration(expand, backfill, contract). - What setup installs: a 32-rule
AGENTS.mdindex (Rules 28 to 32 apply with
payload-encryption=yes) and a 0.5 KBCLAUDE.mdstarter; path-scoped rules for the Go service,
PostgreSQL (byte-identical with agent-be-axum's), testing, error codes and coverage; 17
anti-patterns (7 for Go, 10 PostgreSQL ones shared with agent-be-axum); a service skeleton with
every hand-written file at 100% statement coverage: the closed error-code registry (apperr.Code
with unexported fields, a go/ast registry test,reassign), the one RFC 9457 writer withtype=
apperr.TypeBase+ code and a production refusal of theexample.invalidplaceholder, the router
with spec validation (kin-openapi) and problem answers for 404 and 405, the handler-size test (15
lines), the server with all four timeouts, an explicit pool that refuses timeouts in the
connection string anddescribe_exec, and tests that migrate the test database themselves and
run as the service's role;db/roles.sql(migrator, service and read-only agent roles, timeouts
on the role); the gate scripts (lint.sh,generated.sh,migrations.sh,endpoints.sh,
coverage.sh,pooler.sh, the payload registry check) withgates.list,.githooks/pre-commit,
.golangci.yml,sqlc.yaml,.squawk.toml,go.modandgo.sumstarters (or a by-hand snippet
with thetoollines), PR templates, CODEOWNERS, an optional DeepSeek review caller, and the
caller ofbe-go-quality-gate.yml, held back until the release that pins it. - Setup questions:
migrations,ci-gate,deepseek-review,pr-templates,analytics,
serena-workspaceandpayload-encryption(recommended no). Yes installs the payload contract in
Go, standard library only (crypto/ecdh,crypto/hkdf,crypto/aesandcrypto/cipher):
internal/payload(AES-256-GCM envelopes bound to method, route and status; P-256 key agreement
with browsers and apps throughx-payload-epk;kid:base64keyrings withPAYLOAD_KEY_NEXT; the
strict/off switch; the registry generated fromapi/openapi.json), thenet/httpmiddleware and
its buffering writer ininternal/httpapi(outside the kin-openapi validator, matched through a
privateServeMux,Vary: x-payload-epk, x-payload-kidon every sealed answer), the five
ENVELOPE_*codes ininternal/apperr/payload_codes.go,config.LoadPayload,
payload.config.json(the handshake namedGetPayloadHandshake, as oapi-codegen exports it),
scripts/generate/payload-server-key.mjs, the shared contract, short rule and vectors, and
.claude/rules/backend/go-payload.md. The seeded tests reach 100% of statements and open the
shared vectors, the key agreement included;boundary_test.gokeepsinternal/payloadbehind
internal/httpapiandcmd/. scripts/{lib,generate,check}/payload-registry.mjs, the same bytes in the three new stacks (plain
Node, no dependencies), are installed in every repo. The generator writes the registry from the
spec andpayload.config.jsonin the layout gofmt keeps. The check fails on a switch other than
strict, registry drift, a stale exemption or one without a reason, a spec whoseProblem.code
lacks anENVELOPE_*code, a handshake that is missing, not a GET or not exemptednone, and
spec or exemption drift from a checked-out peer of any stack. Withoutpayload.config.jsonit
says the contract is not adopted and passes.apperr.Error.WithStatusanswers an error with another 4xx or 5xx status than its code's, for
ENVELOPE_MALFORMEDas a 500 when a service cannot seal its own answer.
By hand, once per repo
- Replace
example.com/servicewith the module path ingo.mod,.golangci.ymland the seeded Go
files. - Set
apperr.TypeBaseandx-problem-type-baseinapi/openapi.yamlto this API's own https
base before the first release; production refuses to start with the placeholder. git config core.hooksPath .githooksonce per clone.- With
payload-encryption=yes: add the five codes toRegistered()and toProblem.code, add
GET /api/payload/handshakeand exempt it (and the health probe) asnonewhen browsers or apps
call the service, wiresealBodiesintoNewRouterand the edge intomain, and regenerate. The
gates stay red until then, on purpose. The rule file shows each step.
agent-be-axum 0.1.0
Added
- A new, experimental stack plugin for Rust and Axum services on PostgreSQL (axum 0.8, tower-http
0.7, sqlx 0.9, utoipa 6). Names and rules may still change before 1.0.0. - Hooks: migration-guard keeps hand-written sqlx migrations append-only once a protected branch has
them (appendOnlyMigrationsDirs), and generated-guard refuses hand edits to the sqlx query cache
and the exportedopenapi.json(generatedPaths). Both are the shared copies. - Commands
/agent-be-axum:setupand/agent-be-axum:sync. Setup asks seven questions
(migrations,ci-gate,deepseek-review,pr-templates,analytics,serena-workspace,
payload-encryption) and installs nopackage.json; a new repo getsCargo.tomlfrom a starter,
an existing one a by-hand block (_kit/snippets/cargo.toml: the[lints]tables and
[profile.release]). - The agent
agent-be-axum:reviewer, the standards axis of a review. The skillsapi-endpoint
(code first: path constant, annotated handler, one red request test, green, regenerated spec) and
db-migration(expand, backfill, contract; the no-transaction marker; the FK index in the same
file; the offline query cache). - The template: a 34-rule
AGENTS.mdindex (Rules 30 to 34 apply withpayload-encryption=yes)
with aCLAUDE.mdstarter of about 0.5 KB; rules for the service layout, PostgreSQL, testing,
error codes and Rust coverage; 20 anti-patterns (10 for Rust, 10 PostgreSQL ones shared with
agent-be-go); clippy, rustfmt, cargo-deny, nextest and toolchain config;.cargo/config.toml
with[build] warnings = "deny"and[env] SQLX_OFFLINE = "true"; a service skeleton whose error
module (RFC 9457,type=PROBLEM_TYPE_BASE+ code, the startup check),ValidJsonextractor,
layers, pool and tests pass every gate at 100% of lines and functions per file;openapi.json
withx-problem-type-baseand the inline code enum; the gate scriptsrustfmt.sh,
cargo-policy.sh,rust-source.mjs(LINES, HANDLERS, ROUTES, LAYERS, SQL, ALLOW),
migrations.sh,coverage.sh,pooler.shand the payload registry check withgates.listand
.githooks/pre-commit; a pull-request-only caller ofbe-axum-quality-gate.yml(held back until
the release that pins it), an optional DeepSeek review, PR templates and a CODEOWNERS starter. payload-encryption=yesinstalls the payload contract:src/payload/(AES-256-GCM envelopes
bound to method, route and status; P-256 key agreement for public clients such as an iOS app;
pre-shared key rings with_NEXTrotation for server callers; thestrict/offswitch,off
refused in production; the generated endpoint registry) andsrc/routes/payload.rswith
payload_layer.rs(aroute_layerthat finds the route throughMatchedPath, opens a sealed
request beforeValidJson, seals the answer withVary: x-payload-epk, x-payload-kid, and the
GET /api/payload/handshakehandler). The seeded tests reach 100% of lines and functions and
include the shared vectors and their key-agreement answer. It also installs
payload.config.json,scripts/check/payload-vectors.json,
scripts/generate/payload-server-key.mjs, the contract document and two rules
(.claude/rules/common/payload-contract.md, and.claude/rules/backend/payload.mdfor the Rust
specifics). RustCrypto only (p256 0.14.0, aes-gcm 0.11.1, sha2 0.11.0, base64 0.22.1): no C
library, no build script, and no duplicate version undercargo deny check.- The shared
payload-registry.mjsscripts, installed in every repo, write the registry in the
layout rustfmt keeps;rust-source.mjsLAYERS refusescrate::payloadoutsidesrc/routes/,
src/lib.rsandsrc/payload/. - The error seed has a crate-private
WireCodetrait:problem()is generic over it, so
PayloadCodeuses the one problem writer without becoming a variant ofErrorCode. The
problemslayer keeps any error body whose media type ends in+json, so a sealed 4xx answer is
never replaced by a plaintext problem.
By hand, once per repo
- With
payload-encryption=yes, wire the module in assrc/payload/mod.rslists:cargo addthe
four crates at those versions; the fourPAYLOAD_*fields inConfig; thePAYLOAD_HANDSHAKE
path;mod payload;,payload::routes()andpayload::documentinroutes/mod.rs;
routes::payload::sealinlib.rsafter every route is merged;check_payload_settingsin
main.rs. A module nothing declares is not compiled, so the skeleton stays green until then; the
registry gate stays red untilopenapi.jsonlists the fiveENVELOPE_*codes and the handshake.
agent-ios-swiftui 0.1.0
Added
- A new, experimental plugin for a SwiftUI iOS app on Xcode 27 and Swift 6.4, on top of agent-core:
rules, reviewers and checks. Names, rules and checks may still change before 1.0.0. - Hook:
generated-guard(the shared script) refuses hand edits to the generated API client, the
copied OpenAPI spec and the generated payload registry (generatedPaths). - Commands:
/agent-ios-swiftui:setupand/agent-ios-swiftui:sync(user-only), and
/agent-ios-swiftui:a11y-audit, which runs the accessibility audit UI tests on a simulator and
reports each issue. Agents:reviewer(the standards axis) andi18n-guard. Skills:
swiftui-screen(one screen as a tracer bullet, model first) andopenapi-client-update. - Setup installs a 33-rule
AGENTS.mdindex (Rules 29 to 33 apply withpayload-encryption=yes)
and a shortCLAUDE.md; rules for the app target, the logic package, strings, tests, error codes
and coverage; 12 anti-patterns;Config/*.xcconfig(Swift 6, approachable concurrency, MainActor
default isolation, warnings as errors,SWIFT_PACKAGE_NAME = appcore); a strict.swiftlint.yml
pinned to SwiftLint 0.65.1 with custom rules for views, strings, routes, problem codes, tokens and
suppressions;.swift-format;.periphery.yml; aPackages/AppCorestarter withAppProblem(an
RFC 9457 problem the generated client decodes into throughtypeOverrides, read member by member,
resolved bytype= base + code) and its tests at 100%; a privacy manifest;
.githooks/pre-commit; a pull-request-only caller ofios-swiftui-quality-gate.yml(held until
the release pins it), an optional DeepSeek review, PR templates and a CODEOWNERS starter. Setup
questions:ci-gate,deepseek-review,pr-templates,serena-workspace,min-ios,locales,
analytics,payload-encryption. - Check scripts:
lint-suppressions.sh(a reason on everyswiftlint:disable, no nested config, no
swift-format-ignore, no lowering@diagnose),xcode-settings.sh(settings in
Config/*.xcconfig, noSWIFT_*key in the project file, ATS on, no secret in an xcconfig),
package-graph.sh(layers, a test target per library target,exact:pins, both
Package.resolvedfiles agree, plugins and macros only by decision),i18n-catalog.mjs(every
locale translated, no stale key, and with--stringsdatathe catalog against the build),
error-codes.sh(the app's codes and problem-type base equal the spec's, each code has its
message),privacy-manifest.sh(python3 plistlib, so it runs on Linux),coverage.sh(swift test+llvm-cov export -format=lcov+coverage-per-file.mjs, never xccov) and the shared
payload registry check; named scriptsscripts/ios/app.sh(simulator build and tests by udid, no
signing, zero warnings from the result bundle) andscripts/ios/api-client.sh(the generator's
command plugin,--checkfor drift). payload-encryption=yes(yes when the backend seals bodies) installs the app's half of the
payload contract, seeded:Payload*.swiftinPackages/AppCore/Sources/APIClient(envelope and
AAD, AES-256-GCM, ECDH P-256 with HKDF-SHA-256 and the browser hop's label
payload-envelope/v1/browser, aPayloadSessionactor with one handshake in flight and the
agreed key in memory only, never pinned and dropped afterENVELOPE_REJECTED, a
PayloadMiddlewareplaced last in the client's list, andAppProblem(failure:), the one error
mapper for payload failures) with Swift Testing tests at 100% of lines and functions, and
payload.config.json(language: swift, the handshake exemptednone; its operation id is
copied from the backend's spec,GetPayloadHandshakefor an agent-be-go backend). Every payload
type isinternal; a Release build seals even when the handshake or the committed switch says
off;PayloadSession(serverURL:)sends through a URLSession with no URLCache.- The generated client is
internaltoAPIClient, behind hand-writtenpackagecalls: with
accessModifier: packagethe generator'spackage importlines are flagged as unused under
Swift 6.4 for every component section the spec leaves empty, and the package treats warnings as
errors.