Getting Started
Begin with an approved project profile and a disposable adoption trial, not a promise that copying the kit makes a repository production-ready.
- Inventory the existing environment, current instructions, authority/data boundaries and applicable controls.
- Review the selected host's skill installation and permissions (§4.4); inspect the Usage section in
setup/bootstrap.shandsetup/ADOPTION-TRIAL.mdbefore use. Dry-run against the intended target first and preserve local edits. The bootstrap installs templates, not remote repository settings or the future workspace. - Read the byte-budgeted operating card and linked sources. Configure actual commands, events, identities and required checks; verify both allowed and adverse paths. The Stop hook is an advisory reminder.
- Record adopted versions, installed scope, test results, exceptions and unassessed capabilities. Do not grant production/data authority through an onboarding checklist.
Adoption Tiers:
The labels below describe control design, not verified installation in every adopter. Core-mechanized names a check/control that must be configured and assessed; it does not mean the rule holds automatically. Core-asserted identifies a policy still dependent on accountable review, with no complete shipped detector.
In prose: naming a mechanism is the first step. Installation, effective permissions, real execution and failure behaviour must still be established. Human judgment remains needed for meaning and acceptance.
Core-mechanized — named mechanisms requiring verified adoption:
| Component | Per-occurrence cost | Enforcement mechanism | Retirement condition |
|---|---|---|---|
| Required candidate CI checks on the target branch, using the adopted complete test/lint selection | Measured CI runtime | templates/workflows/pr-review.yml invokes a configured gate; repo-config: branch protection makes named checks required. The local templates/hooks/pre-push-gate.sh has narrower event scope and is not equivalent to server enforcement | Retain while applicable; replace only with an approved equivalent control |
| CODEOWNERS-backed human review on safety paths | Reviewer time | repo-config: CODEOWNERS plus repo-config: branch protection; verify effective ownership, required review and bypasses | Narrow when a surface is retired or an approved equivalent replaces it |
| A deterministic safety-floor eval subset where there is a user-facing safety surface | Measured eval runtime | repo-config: required status check over the project's supplied, verified subset; the kit ships no application eval harness | When the safety surface is removed or the control is replaced |
| Single-source copy detection (§4.5) | Script runtime | scripts/check-single-source.sh detects scoped long verbatim copies; exemptions and paraphrased/semantic conflicts remain review concerns | Reassess if instruction generation removes authored duplication; generator correctness still needs checks |
Core-asserted — no complete shipped detector for the policy:
| Component | Per-occurrence cost | Enforcement mechanism | Retirement condition |
|---|---|---|---|
| Brainstorm Gate including safety-policy changes | Proportionate design/review effort | none (human-asserted) — owner/reviewer checks applicable triggers and accepted scope | Verified trigger/approval enforcement with known limits, not merely a file-presence test |
| Silent-failure discipline R1–R3 | Investigation and regression effort | none (human-asserted) — R1 explicit failure, R2 verified versus hypothesized cause, R3 observable-outcome regression | Evaluated detectors plus meaningful error-path evidence for the supported scope |
| Worktree isolation for agent work | Setup/reconciliation effort | none (human-asserted) — the controller verifies actual ownership and scope | Host enforcement that covers the intended actors and paths without unsafe cleanup |
| Testing standard, migration oracle and required real-boundary checks | Depends on actual services, cases and permissions | none (human-asserted) — configured runners and review provide partial evidence, not a complete policy detector | Verified expected/executed-case receipts, boundary identity and approved-exception enforcement; grepping for a comment alone is insufficient |
Recommended and Project-specific:
| Tier | Components | Value Provided |
|---|---|---|
| Recommended | Reviewer definitions, memory discipline, hook templates, appropriately generated state reports and consolidation reviews | Useful patterns to evaluate; effectiveness depends on implementation and use |
| Project-specific | Domain controls, documentation renderer, MCP adapters and deployment stack | Adopt only where required, with explicit ownership, permissions and evidence |
scripts/check-tier-mechanisms.sh checks table shape, declared mechanism references and required fields. It does not inspect every implementation or certify live enforcement. Use the reviewed policy and scripts/check-repo-config.sh for its supported read-only repository assessment (§7.6), and execute application/control checks separately.
Permission mode is a security control, not a preference. Auto-approval and production-reaching permissions require an explicit organizational decision and scoped grants. A plan-mode label or team agreement alone does not constrain credentials, tools or direct access; verify the actual action boundary. Adoption does not authorize a deployment.