Delivery Protocol

On this page

You are NOT done when the code works. Every code change must complete this checklist before reporting completion to the user.

Preflight Checklist

Before starting any implementation task, verify all of the following. If any check fails, stop and report what is missing — do not write code.

  1. Public visibility: verify the repository is publicly accessible (glab project view or the GitLab API). If private, check for a valid visibility_exception block in .claude/CLAUDE.md (see security baseline). Refuse to work if no valid exception exists.

  2. Mandatory project docs exist: confirm the project’s architecture, services, security, and local-dev pages (docs/modules/ROOT/pages/) exist and contain real content (not placeholders).

  3. .claude/CLAUDE.md is filled in: all required sections present with project-specific content, not template placeholders.

  4. Pre-push hook active: git config core.hooksPath returns .githooks.

  5. Commit signing configured: git config commit.gpgsign returns true and git config user.signingkey returns a non-empty value.

  6. Clean baseline: cargo fmt --check --all and cargo clippy --all-targets — -D warnings pass on the current working tree.

  7. xtask compiles: cargo xtask --help runs successfully.

Architectural Recommendations

Before recommending a new dependency, framework, library, or architectural pattern:

  1. Research current state of the art — search crates.io, official docs, and recent release notes. Do not rely on training data alone.

  2. Identify at least 3 alternatives — including the option you are inclined toward.

  3. Compare on: maintenance activity, community adoption, security posture, and alignment with existing conventions (pure Rust, musl-compatible, AGPL-compatible license).

  4. Present the comparison to the user before proceeding — do not unilaterally choose.

  5. Document the decision in an ADR if it introduces a new architectural choice.

AI agents trend toward recommending older, heavily-documented tools over newer, better alternatives because training data favors established projects. This process exists to counteract that bias. Always verify your recommendation reflects the current landscape, not a historical snapshot.

Library Usage

Before using any crate or library API for the first time in a project:

  1. Read the actual documentation — docs.rs, the crate README, or cargo doc. Do not assume API signatures, feature flags, or return types from training data.

  2. Verify the version — check Cargo.toml/Cargo.lock for the version in use.

  3. Check feature flags — confirm the features enabled in Cargo.toml include what you need.

  4. Test your assumptions — write a minimal test or check cargo doc --document-private-items before building on top of an uncertain API.

Do not write code against an API you have not verified. The cost of reading docs first is minutes; the cost of debugging wrong assumptions is hours.

Debugging Protocol

  1. Diagnose the root cause in source before proposing workarounds. Read the actual implementation that failed. Understand WHY, not just THAT. The fix must follow the diagnosis.

  2. Do not defend a mental model against contradicting evidence — re-examine it. If evidence contradicts your theory, the theory is wrong. Rebuild from the evidence.

  3. Read the actual source of third-party crates before declaring their behavior. "I think it works like X" is not acceptable — verify.

  4. After 2 failed attempts at the same approach, stop and change approach. The approach is likely wrong, not the execution. This bounds repeating a strategy, not diagnosis — multi-attempt root-cause investigation is productive work.

  5. Do not reference other projects unless the user directs you to. Sibling projects have different architectures and constraints.

Delivery Checklist

  1. Create a GitLab issue (if none exists): search first (glab issue list --search "keywords"); only create if none exists.

  2. Implement on a feature branch (feature/Preflight, recommendations, debugging, and the delivery checklist).

  3. Update documentation on the branch — see Documentation Update Checklist.

  4. Test: full battery (see testing).

  5. Commit & push with Closes #N. Run cargo fmt --all before pushing — the pre-push gate runs cargo fmt --check --all first and rejects an unformatted tree instantly, before the slow stages.

  6. Create MR: glab mr create — follow MR standards.

  7. Report the MR URL to the user.

Every todo list for a code task MUST include a final item: "Create issue, commit, push, open MR".

Documentation Update Checklist

Every code change that adds endpoints, tables, events, commands, or public API surface must update:

  • The project’s canonical service/API documentation in the Antora docs site (ROOT module pages, generated OpenAPI pages, etc.) — the primary destination for endpoint/table/event catalog updates.

  • The services page — keep it a concise INDEX that links out to the canonical docs above, NOT an unbounded catalog (agent context budget is finite — see Context Hygiene).

  • .claude/CLAUDE.md — feature status table, architecture summary as applicable.

  • CHANGELOG.adoc — entry under == Unreleased.

  • ADRs and user guides (AsciiDoc) as applicable.

Post-Merge Steps

  • Close the issue with a closing comment.

  • Update the epic task list (if applicable).

  • Delete the local branch: git branch -d feature/…​.

  • Prune remote refs: git remote prune origin.

  • After all MRs in a plan merge: run the Plan Completion Audit.

Plan Lifecycle

Plans are .adoc files created + linked BEFORE implementation; update Status after each step (not at session end). The full lifecycle, the living-specs rule, and the canonical Status vocabulary are the single source of truth in coding conventions.

Two rules govern plan quality and durability:

  • Plans live in the repo. The durable artifact is the committed in-repo .adoc (in the project’s plans directory), under version control — never scratch markdown left outside the repo.

  • Never ship a first-draft plan. Iterate it through independent, contextless reviewer passes (typically 3–4 rounds) until a fresh reviewer finds nothing material. The bar: can a contextless agent or human implement this plan, fully per conventions, without further clarification?

Plan Completion Audit

After completing a plan, spawn an agent to audit the work against the plan document: all acceptance criteria met; all listed files touched; documentation updated per the Documentation Update Checklist; test/endpoint counts accurate; no stale references; GitLab issues closed with correct commit SHAs.

Context Hygiene

The information cascade has three tiers, each with a distinct owner — keep facts in exactly one:

  • Agent memory (machine-local, per-user): only what is true for THIS agent+project+user+machine — session scratch, local paths, this-user preferences. Never a work-stream tracker (status → GitLab work items). Audited by cargo xtask audit-memory.

  • .claude/rules/ (synced, in-repo): durable, terse agent directives. Every agent inherits them.

  • Antora docs site (canonical, human+agent): prose, rationale, project knowledge, ADRs, the service/API catalog.

One fact, one home. If the same fact lives in two places, they will drift. Pick the owner (usually the Antora site or the most specific rule) and make the other a pointer. The Documentation Update Checklist routes project knowledge to the docs site precisely so the agent context budget does not grow without bound.

Template Updates

Universal standards (this page and its siblings, the .claude/rules/ digests, the git hooks) are maintained in the gadhs/templates/claude-quickstart template repo and distributed as synced files. When the template updates, cargo xtask check-docs reports DRIFT (read from version stamps: behind = older than the template, just sync; edited = same version, local edits to restore). Repair both the same way:

  1. cargo xtask check-docs --fix --yes (add --allow-exec for hooks).

  2. Review: git diff.

  3. Commit: chore: sync universal standards to template vYYYY.N.

A template host that is unreachable / 5xx degrades to advisory SKIP. For air-gapped/mirrored environments, set CLAUDE_TEMPLATE_URL to an internal mirror’s raw base. An active sync-overrides entry tolerates an intentional divergence (exit 3, advisory); an expired or unknown override blocks.

Template Feedback (the reverse channel)

Template Updates (above) is the one-way distribution channel; this is its counterpart — how a template-level problem gets back UPSTREAM instead of being silently worked around. The first three migrations each hit upstream defects and filed none; that is an R4 violation (file a tracking issue for discovered work).

Micro vs macro — which problems escalate:

  • A problem in a synced surface (.claude/rules/, docs/modules/standards/pages/, .githooks/, or any other .claude/sync-manifest.toml entry) or a *template default is a claude-quickstart template issue — escalate.

  • A purely project-local problem (the project’s own code, config, or docs) stays local.

  • A project-local workaround that fights a template default IS a template issue — escalate. Reaching for a local workaround against a synced default is itself the signal that the template, not the project, is wrong.

How to escalate (not by reaching into the template repo): file a suggestion on the standing "macro feedback / sharp edges" tracking issue in claude-quickstart — the in-repo collection point for agent-filed template suggestions. This respects the "don’t consult sibling projects unless directed" guardrail: escalation is a filed suggestion, not a silent edit of the upstream. Keep recording the local handling per R4 as well, so the defect does not die in a single downstream’s backlog.

The channel. Downstream repos carry a maintainer-provisioned, claude-quickstart-scoped project access token (CQS_CONTRIBUTION_TOKEN), distributed as a CI/CD variable (verified working end-to-end). It gives a downstream agent a recognizable bot identity, label/triage capability (a member token can self-apply labels), and revocable, narrowly-scoped upstream access — chosen over anonymous public-repo issue creation for identity, labeling, and control. Provisioning and rotating the token is the maintainer’s action; the agent uses the injected credential and self-applies agent-suggestion + needs-triage when filing.

Edit this page · latest