In short — dev-standards-bootstrap is an AI agent skill (and a plain git repo, installable into any coding agent) that injects development governance into any repository: an AGENTS.md entry point every coding agent reads first, five mandatory quality gates (doc-first, test-first, evidence, traceability, independent verification), risk-classified change management, and Git/CI enforcement — installed once, kept current by the upgrade chain.
| Register the skill (one time) | npx skills add geekma/dev-standards-bootstrap -g — or pick any route in Step 1 |
| Initialize any repo | say: "Use dev-standards-bootstrap to initialize this repo." |
dev-standards-bootstrap is a reusable AI agent skill: one sentence injects a battle-tested development-governance system into any repository. It was extracted from a production codebase where agents wrote hundreds of millions of tokens a day — and packages the loop that kept that output shippable: docs before code, tests before features, evidence before "done", independent review before merge.
AGENTS.md is the context layer every coding agent reads first. An optional deterministic gate (agent-gate) blocks non-compliant writes through client hooks and Git hooks, and CI is the final cross-client arbiter. Install once in a repo, then start every future change by just telling your agent what you want — the process runs itself.
This README is a reference manual. Every command in it is invoked automatically by the skill, the Git hooks, or CI at the right moment. Running them by hand is always optional.
The design is measured, not hypothetical. A CIKM '26 study of production agent memory (arXiv:2608.22752) shows /compact retains only 53% of safety rules after one round, 10% after five; the AI-Native SDLC Playbook documents intent drift and incidents that never feed back. The answer is architectural: never trust agent memory or self-reports — governance state lives on disk as versioned artifacts, a dependency-free gate reads the filesystem (not the conversation) at every write, CI is the final arbiter, and the governance package tests itself (see Key Features).
The failure-diagnosis side is grounded the same way. AgentRx (arXiv:2602.02475) shows root-cause attribution stays reliable only when causes go through mutually-exclusive categories with disambiguation checklists and evidence-cited judgments. This project folds both into its bug process: root causes anchor at the earliest unrecovered failure point, and every gate/audit checker follows a guard→assertion design rule.
Two field notes from the production repository this standard was extracted from:
Field note 1 — code is not the bottleneck. Real token-counter capture: 93.9M tokens in a single day for $2.36, 192.6M across seven days. Output is now measured in hundreds of millions; what breaks is the process wrapped around it.
Field note 2 — the standard lives on disk, not in context. The agent's first move on a task is wc -l docs/DEVELOPMENT_STANDARDS.md and ls docs/: it locates the standard as a file it must read, rather than a rule it happens to remember from a conversation that may already be compacted.
Not theory — a three-way contribution analysis measured on 11 real working sessions (session-DB data cross-checked against git history and governance artifacts; full analysis):
| Dimension | Model (LLM) | Agent Harness | dev-standards-bootstrap |
|---|---|---|---|
| Average contribution across 20 SDLC stages | 36% | 17% | 44% |
| Strongest stages | Coding 70% | Test execution 70% | Knowledge retention 70% |
| Without it, what survives | — | — | Coding/testing keep 85–95%; retention, cross-session handoff, compliance audit, change intent drop to 25–40% |
| Paired-config attainment (with vs without) | — | — | ~59% → 100% (≈41 points higher) |
What this buys you:
- Variance compression, not cleverness. Governance does not make the model smarter — it nails down "smart but amnesiac, locally strong but globally weak, accurate once but unreproducible" with machine enforcement, memory, and independence. Without it, delivery quality is a dice roll: real samples include six consecutive fixes to the same function and a family of fabricated test-assertion values.
- Organizational memory is where the value concentrates. The moment a session compacts or ends, an ungoverned agent restarts from amnesia; here, state lives in the 13-volume master set and disk artifacts.
- The tax is measured and being cut. The governance machinery costs ~25% of tool calls and a resident context base — and 97.5%+ of token spend is cache-read prefill from un-switched sessions. v3.38/v3.39 turned session discipline into machine enforcement (water-level gate, exploration-budget yellow light, review-input contract) targeting exactly that: ~90% attainment at a 30–50% cost reduction — governance-grade quality at near-ungoverned cost.
Evidence boundary. The table is an analyst-coded contribution analysis over 11 sessions (session DB cross-checked against git history), not a controlled trial; the paired-config figure is an estimate derived from that comparison, and the ~90% / 30–50% figures are the v3.38–v3.39 design target rather than a measured outcome. Read them as directional evidence, not as a benchmark.
Data boundary. Telemetry is local-only. Hooks and adapters append JSON/TSV under .agent-state/ (session-water.json, session-tool-stats.json, gate-friction.tsv), and agent-gate metrics derives its JSON Lines from local git history. No telemetry client, endpoint, or upload path ships with this skill; nothing leaves the machine unless you commit or copy it yourself.
| Feature | Description |
|---|---|
| 5 Quality Gates + Two-Layer Acceptance | Doc-First, Test-First, Evidence, Traceability, Independent Verification — non-bypassable; every stage passes machine-verifiable A-layer markers plus independent-role B-layer judgment (§2.5) |
| Risk Classification × Role Independence | L0–L3 matrix drives independence: separate execution entities, L2/L3 distinct platform/model vendors, L3 needs human Release Owner approval (§0.5) |
| Stage-Gated Expert Review (9 experts, §2.2) | Business/Industry/Tech/Architecture/PM/Security/Performance/Test/Acceptance experts as refined subjects of existing roles; PMP-aligned per-stage review matrix, context-grounding contract (a template review without project evidence is rejected), session-cost guardrails |
| RTVM Traceability + One Change, One Document Set (一次变更一组文档) | REQ→DES→TASK→TC full-chain matrix; every change opens a fresh docs/changes/<new-id>/ group meeting the eight-category minimum (§1.1) and carries a date-qualified globally unique change_uid (§1.2, G2b); every defect a fresh six-file bug group |
| 10-Stage Lifecycle + AI Anti-Skip Rules | ReAct (Thought→Action→Observation) on every step; anti-skip rules ban summary-style "done", silent downgrades, premature completion (§2.16) |
| Test Coverage Standard (11 dimensions) | Per-dimension design or explicit N/A; branch coverage ≥60% (L2+); LLM eval-set regression; business-scenario coverage ≥80% (SC-xxx, L3 ≥90%) |
| Methodology Selection Layer (M0–M3) | METHODOLOGY.md answers "which methodologies are allowed / forbidden"; methodologies/ provide per-item engineering rationale (weak-typing ban, LLM I/O schema separation, state-trigger-audit) |
| Bug Fix Log + Same-Family Scan + Root-Cause Classification | Repo-level append-only bugfix-log.md index; root-cause tables carry a same-family scan row and a mutually-exclusive classification anchored at the earliest unrecovered failure point (AgentRx-derived; §2.5 Stage 6) — fix without family scan is rejected |
| Deterministic Gate + Pipeline Automation | One dependency-free validator shared by write-time hooks, Git hooks, and CI; spec merge auto-dispatches skeletons, changelog merge auto-opens a release checklist, incidents auto-create BUG-<ts> intent PRs; autonomy capped at A2 (§2.17) |
| Release Integrity + Evidence Reuse | One version authority (scripts/release.sh check|bump) verifies every carrier and rewrites only declared sites; CI runs the full suite once, uploads a tree-keyed receipt, and reuses it for hard audit gates; a workspace suite lock admits one full run at a time and reclaims dead owners |
| Golden-Case Self-Tests | tests/run-tests.sh regression-tests the gate and the installer (1308 golden-case assertions) in throwaway git repos — bash + git only (§2.17.4) |
agent-gate metrics emits read-only JSON Lines pipeline metrics from git history — observation only, never a substitute for DoD (§2.17.5). Specialized standards cover deployment/config/DB changes, AI/LLM pipelines, test data isolation, emergency hotfixes, release, monitoring, and supply chain (§2.6–§2.13). The single version history is resources/STANDARDS_CHANGELOG.md (shipped to target repos, machine-pinned by audit G1).
AGENTS.md is a context mechanism, not an enforcement mechanism; support varies by client. Natively reads AGENTS.md: Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Antigravity, Qoder, Trae, OpenCode. Clients without a known hook schema get no fabricated config — their enforcement path is Git hooks + CI, which validate the repository rather than the editor. The final cross-client control is protected branches plus required CI checks.
The "one sentence" in Step 2 needs your agent to know this skill first. Pick any one route (A/B/D verified end-to-end; C is plain English for your agent — nothing to install):
A. Universal skill store — works today, in any repo, for every supported client:
npx skills add geekma/dev-standards-bootstrap -gB. Claude Code plugin — marketplace-managed install and updates:
claude plugin marketplace add geekma/dev-standards-bootstrap
claude plugin install dev-standards-bootstrap@geekma-dev-standardsC. Just tell your agent (no command line at all):
"Install the dev-standards-bootstrap skill from https://github.com/geekma/dev-standards-bootstrap into your skill directory (clone the repo, then link its
SKILL.md+resources/+scripts/), then reload your skills."
D. The repo's own installer — take the one command and append --as-skill claude: it symlinks into ~/.claude/skills (semantics and other clients in --as-skill details).
Reload your client afterwards (/reload-skills in Claude Code, or restart the session).
Open your AI coding tool in the target repository and say:
"Use dev-standards-bootstrap to initialize this repo."
That's it. The agent detects existing files (never overwrites silently — it diffs first and asks), runs the installer, wires the hooks, and reports what remains (one platform-side step, below). Upgrading later is the same sentence — the skill detects the version diff and upgrades.
Keeping the skill copy itself current (routes A/B/D install a copy or link of this repo into your client): route A — npx skills update geekma/dev-standards-bootstrap -g; route B — claude plugin update dev-standards-bootstrap@geekma-dev-standards (marketplace-managed); route D — the symlink tracks the checkout, so bash <skill-dir>/scripts/bootstrap.sh --self-update updates it in place. Route C agents re-clone or git pull the checkout themselves. Skill-copy currency and target-repo governance upgrades are two independent halves — see Installation & Upgrades.
Skip skill registration entirely? Run the one command exactly as written there (no extra flag) — it installs governance straight into the repository, agent-agnostic (the AGENTS.md context layer is natively read by every supported tool), and auto-becomes an upgrade if the target is already governed.
After either path there is nothing left to wire by hand:
Filing a change is the agent's job, not yours: the agent writes CHG-044's full artifact set (intent → governance → spec → impact analysis → plan → tasks → test scripts) plus the defect document groups for BUG-016/BUG-017 — every file before the first line of source code.
One command (install or upgrade, auto-detected):
curl -fsSL https://raw.githubusercontent.com/geekma/dev-standards-bootstrap/main/scripts/install.sh | bash -s -- .- Default target is the current directory; pass a path as the first argument instead.
- The skill checkout is kept at
~/.dev-standards-bootstrap/dev-standards-bootstrap(override with--skill-dir <path>); an existing checkout is reused and fast-forward pulled — local changes there are never overwritten (the command refuses and tells you). If the pull fails (e.g. offline), the command continues with the existing local copy, which may be stale — it says so; rerun when back online, or runbash <skill-dir>/scripts/bootstrap.sh --self-updateto update the skill copy on its own. - Already-governed target → automatic
--upgrade: governance-owned files (standards, templates, scripts, hooks, workflows, tests) move to the carried version — except files you have modified locally, which are kept untouched and reported (pass--forceto overwrite them with the carried version); a dirty target work tree blocks the upgrade until committed or stashed (--forceoverrides). Live records always stay untouched:bugfix-log.md, delivery summaries, 06.5 records, your.agent-governance.yml, and everything underdocs/changes/**anddocs/bugs/BUG-*/. Commit the target repo first so git history preserves any customization. - Offline / pinned installs:
--from <local-checkout>,--repo <url>,--ref <branch-or-tag>. - Platforms: macOS and Linux with bash 3.2+ (the shipped gate targets stock macOS
/bin/bash 3.2); native Windows is not supported — use WSL. Git Bash/MSYS is unverified, not a compatibility claim. - Supply chain: the
curl | bashform executes whatever is atmainat that moment. When you need a fixed input, pin it —curl -fsSL …/vX.Y.Z/scripts/install.sh | bash -s -- . --ref vX.Y.Z, or clone the repo, inspect it, and runscripts/bootstrap.shlocally. The trust anchors are the git tag/commit and the reviewed checkout; this project publishes no checksums or signed artifacts, so do not treat any such file as authentic. - Selective layers (
--layer core|claude|ci|guard|pipeline) and custom directory roots (--docs-dir,--scripts-dir,--tests-dir,--githooks-dir) pass through to the installer. Omit them for the full--allinstall with default roots. - The target should be a git repository: hook wiring (
core.hooksPath) requires.git/— a bare directory gets the files but no Git-hook enforcement (CI still applies once connected). - Version check without side effects:
--checkcompares carried / upstream / installed versions and exits 1 on drift (CI-friendly). Update the skill copy itself (not the target repo) with--self-update— it pulls the checkout--ff-onlyand touches nothing else.
Route D symlinks the checkout into the client's skill directory — same one command, different argument:
--as-skill opencode→ symlink into~/.config/opencode/skills/--as-skill all→ both clients--as-skill ~/.agents/skills/dev-standards-bootstrap→ any other client — pass the full link path including the skill name (the symlink is created exactly at that path, no suffix is appended)
Registration is a symlink to the checkout (zero copies — self-updates flow through), fail-closed (an existing non-symlink destination is never touched; --force only retargets a symlink or replaces an empty directory), mutually exclusive with --install/--upgrade/--check/--layer (a combined call is a usage error, exit 2), and independent from governing a repository — both paths compose. Reload afterwards (/reload-skills in Claude Code, or restart the session).
Manual equivalent (two commands, if you prefer):
git clone https://github.com/geekma/dev-standards-bootstrap.git
bash dev-standards-bootstrap/scripts/bootstrap.sh --all <target-repo>Checking your version: the carried standards version is written into SKILL.md in three places — frontmatter version:, the tail of the description, and a banner right under the title — so it is visible in the skill list and again whenever the skill loads. Compare it with the Standards Version badge at the top of this README, or run bash <skill-dir>/scripts/bootstrap.sh --check <target>.
Custom directory roots: the defaults are docs/, scripts/, tests/, .githooks/ (plus .github/, whose location the platform mandates and which is therefore not movable). Only directory roots are configurable: AGENTS.md, the gate filename, the fifteen change artifacts, the six defect artifacts and the required-check name are cross-repo contracts — making them configurable would break comparison and migration.
After install, enforcement is event-driven — you never run the gate yourself:
| Event | What happens automatically |
|---|---|
| Agent is about to write source code | Client pre-write hook validates the active change's artifacts and governance state |
| You (or the agent) commit | pre-commit/commit-msg hooks verify staged artifacts and change attribution; a code commit without a change id is rejected |
| A turn ends after source edits | The stop hook requires the coding record (with script-stamped provenance), test evidence, and a changelog with ReAct Observation records |
| A session starts / goes idle | Session gate runs the consistency audit at start and a stop-equivalent check at idle — stale red lights become visible in-session (v3.28.0); a red light also prints the defect-signal interactive options (scaffold / register FU / ignore with a 09 justification, v3.43.0) |
| A PR opens | CI re-runs the artifact checks and the project's real verification command, then requires the agent-governance check |
01-spec.md merges to main |
A scaffold branch with 02/03/03.5/04 skeleton PRs is created (artifact pipeline) |
09-changelog.md merges to main |
A release-checklist issue is opened automatically |
| A production incident fires | repository_dispatch type=incident creates a BUG-<UTC-timestamp> intent skeleton PR — every incident re-enters the pipeline as recorded intent |
| A main-branch test run fails | regression-to-bug workflow calls scripts/bug-autointent: a full six-file defect skeleton (flat daily batch, metadata pre-filled) is scaffolded with fingerprint rate-limiting — the same failing set inside the window (default 24h, env-overridable) only appends a reproduction line instead of a new group (v3.43.0) |
Command reference (invoked by the above; manual runs are for debugging):
| Command | Purpose |
|---|---|
begin <change-id> / end |
Activate or clear the active change; requires the eight change artifacts and validates governance state (risk level, distinct execution owners; L3 additionally the three release_authorized_by-family authorization fields) plus A-layer content markers |
--stage pre-write |
Validates the active change before an agent writes source code; fails closed if the target path cannot be parsed from hook input |
--stage staged |
Staged source changes must ship with matching change artifacts, otherwise the commit is rejected |
--stage commit-msg <msgfile> |
Attribution gate: a code-bearing commit must reference a valid change id (merge / revert / docs-only exempt) |
--stage stop |
Ending a turn after source edits requires 04.5-coding-record.md, 05-test-results.md, 09-changelog.md (with ReAct Observation records), plus a passing verification command (L0: 04.5/05 may be §1.1 single-line declarations, v3.44.0); changelog REQ ids must be backfilled in 01.5-rtvm-matrix.md (Gate 4 closure) |
--stage ci [--base <ref>] |
Rechecks the branch/PR diff and runs the real verification command |
metrics |
Read-only pipeline metrics as JSON Lines — observations only; aggregates the gate-friction ledger (die codes → counts, v3.43.0) |
File provenance: the coding record must carry a <!-- provenance --> block produced by scripts/stamp-provenance.sh <change-id> — author, committer, commit, host, platform and UTC time are read from the running environment, so they cannot be typed by hand. --all stamps every *.md artifact of the change directory (the governance JSON is deliberately excluded); since v3.41.0 the pre-commit hook runs it automatically, and v3.42.0 adds --trace — the changelog's §4 traceability ids are derived from the 01.5-rtvm-matrix.md instead of hand-typed. The gate checks block shape and producer; truthfulness of author itself is not machine-verifiable, and the design says so. No retroactive stamping: history is never back-filled, because back-filling would forge generated_at — the very thing the block exists to prevent.
Verification command auto-detection: at bootstrap, the real build/test command is detected from the project layout (package.json / Makefile / pom.xml / go.mod / pyproject / Cargo) and prefilled into .agent-governance.yml — edit it there, or override with AGENT_GUARD_VERIFY_COMMAND (highest priority). A yml verification command is not executed while the file itself is part of the pending change (anti-tamper — a PR cannot inject commands into the reviewer's hook); commit it first, or use the env var.
The one manual step (platform-side, cannot be done by files): mark the agent-governance workflow as a required branch-protection check (Settings → Branches, or via gh api). State files and checkboxes are declarations, not proof: CI re-runs the real command and is mandatory for enforcement.
Screenshots — the gate doing its job with zero manual steps:
The minimum artifact set of a new change staged as new files — begin refuses to activate the gate without them.
agent-gate blocking a non-compliant source commit inside the IDE: no artifacts under docs/changes/<change-id>/, no commit — and the enforcement is not tied to any single editor.
The same gate on the defect path: a commit missing docs/changes/BUG-021/00-intent.md is rejected before it ever reaches the branch.
A change passing through the gates accumulates its full artifact chain, from 01-spec.md all the way to 09-changelog.md:
[ Gate 1: Doc-First ] Requirements/design must exist before any code change
│
▼
[ Gate 2: Test-First ] Test cases (TDD red-green) must exist before implementation
│
▼
[ Gate 3: Evidence ] Real test output required — no verbal claims of "done"
│
▼
[ Gate 4: Traceability ] RTVM must be closed: REQ ↔ DES ↔ CODE ↔ TC
│
▼
[ Gate 5: Independent ] Test & review by different agents/humans; high-risk needs human approval
Any change that fails any gate is blocked from merge to main.
One change's full artifact chain, 01-spec.md → 09-changelog.md. Every stage ends by committing a version-controlled artifact; the next stage begins by reading it — in target repositories that keep the ledger in-tree, the commit chain itself is the audit trail. In this source repository the private ledger (docs/**) is intentionally gitignored (CHG-017), so source-side claims are traced to tagged versions, not to commits of the ledger.
The same chain seen from inside the AI client: a todo list whose order is pinned by the standard — docs first, then the failing test (red), then code — and every item carries its REQ/DES/TASK/TC/CHG traceability id.
Gate 4's RTVM matrix: every REQ row must resolve to DES / TASK / TC and to verification evidence — an unclosed row blocks the merge.
Gate 3 / §2.16.3 in practice: the DoD is closed item by item with each gate's evidence cited inline. A single line saying "completed per the standard" is rejected — the checklist is the deliverable.
Gate 5 starts from real evidence, not a claim: green recheck (PASS 24 / FAIL 0, EXIT=0) plus a frozen baseline hash, then two read-only sub-tasks are dispatched — one for test recheck, one for code review.
Independence is dispatched, not declared: separate sub-tasks for independent test recheck and independent code review — and the review comes back rejected with a blocking finding, which is the system working.
The rework is then verified by a new independent reviewer: the author cannot self-certify, so "fixed" requires evidence produced after the fix.
| Level | Criteria | Independence | Cross-Platform | Human Approval |
|---|---|---|---|---|
| L0 Very Low | No logic change (docs, comments, formatting) | Roles may merge | Not required | No |
| L1 Low | Non-core modules, no external interfaces | Separate sub-tasks | Not required | No |
| L2 Medium (default) | Core business logic, P0/P1 priority | Separate execution entities | Recommended | No |
| L3 High | Sensitive personal data (PII), auth, prod DB, AI/Prompt, breaking API changes, P0 hotfix | Mandatory cross-platform/cross-model | Mandatory (≥2 model vendors) | Mandatory |
- Execution-side token discipline (v3.24.0/v3.25.0; recalibrated to 15 rules in this version): the shipped
AGENTS.mdcarries a 15-rule "Agent execution resource discipline" section (piped filtering / single-pass grep / locate-then-window reads / delegated exploration / no-match ≠ pass / parallel batches / targeted verification / stateful mock isolation / no parallel integration tests / long-task waiting / environment-attribution resume / call batching / tail-incremental reads / frozen-tree parallel dispatch / phased minimal read set); §2.9.6 session-context discipline (one topic per session, handoff beyond 50 turns or on topic switch); §2.5 minimal-expression artifact shapes with a ≤40-line soft cap — targeting cache_read (= context level × turns). Read-set rule: DS is never read in full; read it in phases per discipline 15 (this version removes the old rule 1 vs rule 15 contradiction). - Same-day change batches (v3.18.0; defaulted in v3.24.0; sequence clarified in v3.61.2): the first L0/L1 change (or defect) of the day creates
<docs>/changes/BATCH-YYYYMMDD/immediately; later same-day L0/L1 changes join it via section anchors instead of opening their own directories. Only the directory is relaxed — artifact filenames are unchanged, bundled changes are told apart by a## <change-id>section anchor, and the batch's change set is read from the authoritative roster in00-governance.json(never inferred from headings). The risk ceiling is not relaxed: L2/L3 must live in their own directory, and the gate refuses an L2/L3 record found inside a batch (per the governance roster). - Defect groups join daily batches by default (v3.35.0, flat since v3.36.0): the first same-day defect creates one flat
docs/bugs/BATCH-YYYYMMDD/directory and later same-day defects join it — six files named exactly as before, told apart by## BUG-xxxsection anchors, same-day appends land in the same files (per-defect subdirectories remain a legal legacy form). The append-onlydocs/bugfix-log.mdindex (one dated row per bug) stays the day-level retrieval layer, and a defect's change-track entry (BUG-*) may still join a change batch like any other change. - Methodology selection (M0–M3):
docs/METHODOLOGY.mdis the sole authority for which methodologies are allowed at which level;docs/methodologies/development.md,docs/methodologies/data-structures.md,docs/methodologies/state-trigger-audit.md,docs/methodologies/expert-capabilities.mdanddocs/methodologies/project-masters.mdcarry the per-item engineering rationale (SOLID/DRY applicability, weak-typing ban, implicit state/trigger-link three-way traversal, expert theory toolboxes).docs/STAGE_PLAYBOOK.mdcarries the operational detail migrated from DS §2.5 / §2.16.6 (clause authority stays in DS, v3.61.0). - Self-evolution: skills derived from this one (declaring
derived_from: dev-standards-bootstrap) live and evolve independently, and every installer/upgrade write path skips them;--forcedoes not override that.bash scripts/bootstrap.sh --derived-reportlists them. - Cross-document consistency audit:
bash tests/audit-docs-consistency.sh(G1 version chain / G2 numbering continuity + globally unique change UID / G3 archive sync / G4 bugfix cross-registration / G5 RTVM backfill / G6 required sections / G7 batch self-consistency / G8 defect six-file existence / G9 project masters presence+self-attestation+backfill ledger+out-of-table feature-dir reviews sweep / G10 deprecation-marker sweep — a deprecation marker must carry its replaced-by version pointer (v3.41.0) / G11 UJ↔REQ coverage / G12 five-party evidence / G13 three-dimensional cross-check / G14 source cross-check / G15 source-artifact mapping closure / A-group provenance cross-checks) runs in CI or locally; failed items are the backfill list.
Three surfaces — keep them distinct (CHG-113). A file being public does not make it part of the shipped capability, and a file being useful to maintainers does not make it installable:
| Surface | Paths (representative) | Reaches a target repo? |
|---|---|---|
| A. Public capability | SKILL.md, resources/**, .claude-plugin/**, installer entrypoints scripts/bootstrap.sh / scripts/install.sh; tests/run-tests.sh and scripts/lib-suite-*.sh are installed by --guard |
Yes — copied or consumed by the installers |
| B. Source-public, not shipped | this README pair, MAINTAINER.md, CAPABILITY-COMPARISON.md, 能力对比分析.md, screenshots/**, tests/audit-standards-src.sh, tests/audit-docs-consistency.sh (source-layout mirror; the shipped copy is resources/templates/audit-docs-consistency.sh), scripts/update-assertion-count.sh, scripts/release.sh, scripts/selfcheck.sh, scripts/setup-branch-protection.sh, the CHG-115 verification toolchain (scripts/facts.sh, scripts/verify-all.sh, scripts/pre-review-check.sh, scripts/mutation-check.sh, scripts/ci-summary.sh, scripts/batch-metrics.sh and their shared scripts/lib-source-facts.sh), .github/**, and the scripts/agent-gate / scripts/session-gate.sh source-layout mirrors |
No — maintainer and CI only |
| C. Repository-private (gitignored) | docs/** (CHG-017: the private change/bug ledger), .agent-state/**, .claude/, .opencode/, local working mirrors |
Never |
Claims in this README are backed by surface A behavior and surface B evidence; surface C contains project-specific material and is not part of the product contract.
dev-standards-bootstrap/
├── SKILL.md # Skill manifest (trigger, execution steps, red lines)
├── README.md # English documentation (this file)
├── README.zh-CN.md # Chinese documentation
├── LICENSE # MIT License
├── MAINTAINER.md # Maintainer notes (NOT shipped with the skill): file roles / change-coupling table / the two self-tests and their order / version carriers / per-version upgrade actions
├── CAPABILITY-COMPARISON.md # Three-way contribution analysis (model / harness / governance) behind the Measured Impact section
├── 能力对比分析.md # Chinese edition of the capability comparison
├── .github/
│ └── workflows/ci.yml # This repo's own CI (not shipped as a template): runs both self-test suites once each on every PR and push to main, and hard-gates the committed suite baseline against the run's receipt
├── .claude-plugin/
│ ├── plugin.json # Claude Code plugin manifest — this repo IS the plugin (skill discovered at repo root)
│ └── marketplace.json # Marketplace entry: claude plugin marketplace add geekma/dev-standards-bootstrap
├── scripts/
│ ├── bootstrap.sh # Manifest-driven installer (not shipped): copies resources/ into a target repo by layer, idempotent, conflict-safe
│ ├── install.sh # One-command installer (not shipped): clone + install/upgrade in a single step
│ ├── update-assertion-count.sh # Source-layer only (NOT shipped): regenerates README assertion-count claims + audit executed-count baseline
│ ├── release.sh # Source-layer only (NOT shipped): release carrier check / mechanical version bump / local annotated tag; never generates the CHANGELOG prose
│ ├── selfcheck.sh # Source-layer only (NOT shipped): single dogfood entry — delegates to verify-all (carriers, ledger, audit, suite) + eval cases
│ ├── facts.sh # Source-layer only (NOT shipped): one read-only JSON snapshot (HEAD, version, baselines, suite receipt freshness) — <1s, never runs the suite
│ ├── verify-all.sh # Source-layer only (NOT shipped): one serial verification entry (release → ledger → audit → suite → gate), collects all failures, reuses a fresh same-tree suite receipt
│ ├── pre-review-check.sh # Source-layer only (NOT shipped): mechanical "ready for review" gate over the 16 change artifacts (FILL residue, confirmation, evidence, owners, stamps, counts)
│ ├── mutation-check.sh # Source-layer only (NOT shipped): checker self-test — four fixed mutations must turn the fast checkers red, inside throwaway copies only
│ ├── ci-summary.sh # Source-layer only (NOT shipped): renders the CI run summary and hard-gates tests/.suite-baseline against the receipt's passed count
│ ├── batch-metrics.sh # Source-layer only (NOT shipped): per-batch cost ledger (turns / edits / polls / full-suite runs / wall time) in .agent-state
│ ├── lib-source-facts.sh # Source-layer only (NOT shipped): shared read-only fact helpers used by the six tools above
│ ├── setup-branch-protection.sh # Source-layer only (NOT shipped): prints the gh api payload for the required check (dry run); `--apply` mutates the remote
│ ├── lib-suite-tree-fingerprint.sh # Shared library: suite tree fingerprint used by receipt keying (installed with tests/run-tests.sh by --guard)
│ ├── lib-suite-lock.sh # Shared library: workspace suite lock — one full run at a time, dead-owner reclaim (installed by --guard)
│ ├── eval-cases # Eval-case derivation runner (experimental; source-layer wrapper of resources/templates/eval-cases.sh)
│ └── eval-rescore # Eval rescore runner (experimental; source-layer wrapper of resources/templates/eval-rescore.sh)
├── screenshots/ # README screenshots (motivation, gate blocking, artifacts, gate-5 review)
├── tests/
│ ├── run-tests.sh # Golden-case regression suite for governance templates incl. gate & bootstrap (copied to target tests/ — target-repo adaptive: unshipped/skipped cases auto-skip)
│ ├── audit-docs-consistency.sh # Source-layout mirror of resources/templates/audit-docs-consistency.sh (the shipped copy); run against this repo's private ledger by CI
│ ├── audit-standards-src.sh # Source-layer only (NOT shipped): audits the standards text itself - version chain / keyword matrix / checklist uniqueness / numbering / tautology-proof greps
│ ├── .suite-baseline # Source-layer only (NOT shipped): committed count of the last real green golden-case run — what A3, both READMEs and the CI gate compare against
│ └── .audit-baseline # Source-layer only (NOT shipped): committed baseline of the audit's executed-assertion count (assertion A10 fails on drift)
└── resources/
├── AGENTS.md # Entry point for AI agents (copied to target repo root)
├── CLAUSE_REGISTRY.md # Clause registry: machine index of standards clauses (Rxx id + filename::anchor + type vocab); DS stays the sole prose authority; feeds reading-pack generator (v3.46.0)
├── DEVELOPMENT_STANDARDS.md # Full standards document v3.88.0 (copied to docs/)
├── STANDARDS_CHANGELOG.md # Standards upgrade history (sole home of §2.14 upgrade log, v3.8.0; copied to docs/)
├── METHODOLOGY.md # Methodology selection guide: M0-M3 levels + stage x methodology x applicable / not-applicable table (copied to docs/)
├── STAGE_PLAYBOOK.md # Stage playbook: operational detail carried over from DS §2.5 / §2.16.6 (clause authority stays in DS; copied to docs/)
├── methodologies/
│ ├── development.md # Code standards: SOLID/DRY/KISS/YAGNI applicability & exemptions + 7 engineering dimensions
│ ├── data-structures.md # Data structure standards: 6 model types + weak-typing ban + LLM input/output specifics
│ ├── state-trigger-audit.md # State/trigger-link audit: 6 lessons + 6-step checklist + 3 anti-patterns (v3.4.0)
│ ├── expert-capabilities.md # Expert capability profiles: 9 core + product-usability expert + 3 conditional experts (theory / breadth / experience / adaptation; v3.67.0 adds the UX/UAT card)
│ └── project-masters.md # Project master set detail layer: 13 masters, sections, backfill/annotation semantics (v3.35.0; v3.67.0 adds P12 product-context master)
└── templates/
├── docs-readme.md # One-page docs map (v3.37.0): five layers, roles, update timing (→ <docs>/README.md)
├── communication.md # Communication-first gate artifact (v3.52.0): round-1 communication draft + user overall confirmation record (→ docs/changes/<id>/00.5-communication.md)
├── project # Project master set (v3.67.0): 13 SDLC masters P00–P12 + review-record template (→ docs/templates/project/)
├── entry # Change-entry skeletons (v3.67.0): the eight begin-required artifacts + conditional 03.6-ui-spec.md + shape templates 01.5/05/07/09 (v3.70.0 CHG-045, → docs/templates/entry/)
├── new-change.sh # Change-entry scaffolder (v3.43.0): dedicated-dir vs same-day-batch resolution (→ scripts/new-change)
├── CLAUDE.md # One-line import for Claude Code
├── PULL_REQUEST_TEMPLATE.md # GitHub PR template with gate self-check
├── check-standards-compliance.sh # CI compliance check script
├── agent-gate.sh # Shared pre-write / commit-msg / Git / CI validator (+ metrics, + change-batch resolution)
├── behavior-extract.sh # HTML/JS prototype behavior extractor → JSONL inventory (G13/G14 source dimension, v3.68.0)
├── uninstall-standards.sh # One-step uninstall: tiered removal + marker-verified delete + backup-move for shared assets (v3.43.0)
├── coding-record.md # Per-change coding record template for docs/changes/<CHG>/04.5-coding-record.md (NOT shipped — the agent writes it per change)
├── stamp-provenance.sh # Provenance stamper: reads author/host/time from the environment (v3.17.0; batch-aware v3.18.0; --all v3.22.0)
├── bugfix-log.md # Repo-level bug-fix index template (copied to docs/bugfix-log.md)
├── bug-diagnosis.md, bug-impact.md, bug-test-plan.md, bug-matrix.md, bug-config.md, bug-tasks.md # Six-file defect document set (→ docs/bugs/_templates/)
├── 06.5-deployment-config.md # Deployment/config/DB record template (→ docs/; must declare "未命中，不适用" when not hit)
├── 06-delivery-summary.md # Delivery summary + FU ledger template (→ docs/; four mandatory sections per §2.5 stage 9.5)
├── audit-docs-consistency.sh # Cross-doc consistency audit: version chain / numbering continuity / checklist sync / bugfix cross-registration / RTVM backfill / change-batch self-consistency (copied to tests/)
├── governance-state.json # Template for each change's 00-governance.json (NOT shipped — the agent writes it per change)
├── agent-governance.yml # Team-reviewable governance config record (copied to .agent-governance.yml)
├── pre-commit, pre-push, commit-msg # Git hook templates (commit-msg: attribution gate)
├── install-hook-adapter.sh # Detects local AI clients and wires session-time enforcement (adaptive, v3.34.0)
├── session-gate.sh # Session-time enforcement: start = audit red-light + defect-signal interactive options, idle = gate stop equivalent
├── bug-autointent.sh # Defect discovery entry: signal -> full six-piece skeleton + fingerprint rate-limit (v3.43.0)
├── generate-reading-pack.sh # Reading-pack generator: clause registry -> type-filtered slice, anchors fail-closed (v3.46.0)
├── eval-cases.sh # Eval-asset derived view: defect groups -> reproducible eval cases (experimental, runtime-only, v3.75.0)
├── eval-rescore.sh # Eval rescore: coverage ratio + receipt bound to governance-face hash, drift => re-baseline (experimental, v3.75.0)
├── github-reviewer-rescore.yml # Reviewer rescore loop: daily + governance-face push, drift alerts (v3.75.0)
├── github-agent-governance.yml # Required-check workflow template
├── github-artifact-pipeline.yml # Artifact pipeline: spec merged -> 02/03/03.5/04 skeletons PR; changelog merged -> release checklist issue
├── github-incident-to-intent.yml # Incident loop: alert dispatch -> BUG-<ts> intent skeleton PR
└── github-regression-to-bug.yml # Regression loop: main-branch test failure -> six-piece defect skeleton PR (rate-limited, v3.43.0)
The one-step uninstaller ships with the --guard layer: scripts/uninstall-standards (added by the installer). Run --dry-run first to preview. It must run inside the target git repository; the uninstaller removes itself on a real (non-dry) run — to run it again, reinstall first.
Removal is tiered (what gets deleted depends on what the file is):
| Tier | Files | Behavior |
|---|---|---|
| Runtime files | gate scripts (agent-gate, session-gate.sh, stamp-provenance.sh, check-standards-compliance.sh, eval scripts, install-hook-adapter, bug-autointent, new-change, generate-reading-pack.sh), .agent-state/, .dev-standards-manifest, .git/agent-governance |
Deleted outright, even if modified — they are executable machinery, and keeping a modified gate is a security risk |
| Template files | standards docs, templates, hook templates, workflows, tests | Deleted only when the installer marker is intact; modified files are kept and reported |
| Shared knowledge assets | AGENTS.md, CLAUDE.md, governance history under docs/ (changes/, bugs/, project masters), bugfix-log.md |
Kept — they contain your records; --force backup-moves them to .uninstall-backup-<timestamp>/ instead of deleting |
| Client-adapter config | .claude/settings.json, .cursor equivalents (merged hook entries), .opencode/plugins/dev-standards-gate.js |
The generated plugin file is removed; merged hook entries inside shared settings files are not auto-cleaned — the uninstaller prints the manual follow-up lines to remove |
| Never touched | .gemini/settings.json (never written by the installer), platform-side required checks / branch protection (GitHub-side, files cannot revoke them), core.hooksPath unless it points at the managed hooks dir (then unset for you) |
— |
Reinstall anytime with bootstrap --core/--guard.
Does it modify my code? No. The whole package is documentation, templates, hooks and validators around your workflow. The gate rejects commits; it never edits your source or business files. The only files it ever writes are its own governance artifacts (templates, hooks, client-adapter config such as .claude/settings.json or .opencode/plugins/*.js).
How do I uninstall it? See Uninstalling — the one-step uninstaller shipped with --guard.
Is anything sent to a server? No. The gate, the stamper and the audit are dependency-free shell scripts that read your filesystem and git metadata. install.sh only clones this public repository.
Can several low-risk changes from the same day share one document set? Yes — see Governance Details: the first same-day L0/L1 change opens the BATCH-YYYYMMDD/ directory and later same-day changes join it (filenames unchanged, ## <change-id> anchors). Defect six-file groups follow the same first-creates/join rule in the same-day flat batch by default (v3.35.0/3.36.0); per-bug directories remain legal legacy.
Who generated these files — can I trace it? Every change's coding record (and, with stamp-provenance.sh --all, every artifact of the active change) carries a provenance block read from the running environment: author, committer, commit hash, host, platform, UTC time.
Does this work outside GitHub? The enforcement semantics are platform-neutral (Git hooks + any CI). The four bundled workflows are GitHub Actions reference implementations; §2.17.1 defines the semantics, not the platform.
This repo's own CI (.github/workflows/ci.yml, not shipped as a template) runs two real jobs plus an aggregate required-check gate on every PR and push to main:
| Job | What it does |
|---|---|
| Source-layer audit | tests/audit-standards-src.sh — audits the standards text itself: version chain, keyword matrix, checklist uniqueness, numbering, tautology-proof greps (assertions: 641) |
| Golden-case self-tests | tests/run-tests.sh — regression-tests the gate and the installer (1308 golden-case assertions) in throwaway git repos; bash + git only |
| agent-governance | Aggregate required-check context: fails unless both jobs above succeed (stable name for branch protection) |
There is no soft mode and no double run in CI. golden-case runs the suite once with -j 4 under a 600s wall budget (AGENT_GUARD_CI_WALL_BUDGET_S, so a regression fails loudly instead of drifting into the job timeout) and uploads .agent-state/last-suite-receipt.json for human forensics. source-audit no longer consumes that artifact: A3/A3c/A10 read the committed baselines and run as hard gates (no AGENT_GUARD_AUDIT_SOFT), which is also why it needs no dependency on the suite job and runs in parallel with it. The two real jobs are bounded by timeout-minutes: 15; the aggregate agent-governance gate by 5. A workspace suite lock (lib-suite-lock.sh, shipped with --guard) admits one full run per workspace and reclaims dead owners; receipt and red-report paths are env-overridable (AGENT_GUARD_SUITE_RECEIPT_PATH / AGENT_GUARD_SUITE_RED_PATH) so parallel self-tests never touch live ledgers. A workflow-level concurrency group cancels superseded runs on the same ref.
Since CHG-115 the runtime truth of a number lives in exactly one place. tests/.suite-baseline — the committed count of the last real green run — is what the source audit (assertion A3), both READMEs and the CI gate compare against, so the source audit is now a ~15s read/compare pass instead of an accidental 300s full suite (the machine truth for that number is the audit step duration in .agent-state/verify-receipt.json, not this sentence). CI's single suite run finishes with scripts/ci-summary.sh --check, which fails the job when the baseline and the receipt disagree (a stale committed baseline can no longer quietly document a number nobody ran) and renders the run into the job summary. Reproduce locally (no CI needed, bash + git only):
bash scripts/facts.sh # one read-only JSON snapshot: HEAD, version, baselines, receipt freshness (<1s)
bash scripts/verify-all.sh # one serial entry: carriers → private ledger → source audit → suite → baseline gate; collects every failure
bash scripts/pre-review-check.sh # is this change reviewable? (artifact shape, evidence, owners, stamps, counts)
bash scripts/mutation-check.sh # do the fast checkers actually go red? (throwaway copies only)
bash tests/audit-standards-src.sh # source-layer audit
bash tests/run-tests.sh # golden-case suite (writes .agent-state/last-suite-receipt.json, keyed by tree fingerprint)CI green is the publish gate; the platform-side required-check step is described in What Runs Automatically.
Branch protection is a one-time admin action, not something CI can self-apply. The required context is agent-governance. Preview the exact payload, then apply it with an admin token:
bash scripts/setup-branch-protection.sh --repo <owner>/<repo> # dry run (default)
bash scripts/setup-branch-protection.sh --repo <owner>/<repo> --apply # mutates the remoteThe script never stores credentials; --apply delegates to your authenticated gh CLI. Applying it is deliberately left to a maintainer.
Contributions are welcome! Please follow the standards defined in this repository: documentation before code (Gate 1), tests first (Gate 2), real test output (Gate 3), closed RTVM (Gate 4), independent review (Gate 5). The G13/G14 three-dimensional gate family (v3.68.0) adds source checks (origin_artifact anchors + mechanical behavior inventory), flow checks (chain_change event-flow splitting + data-flow tables) and runtime checks (per-UJ traces + negation tests) — all triggered by 01-spec declarations. Pull requests should use the PR template and complete all gate self-checks. Maintainers should read MAINTAINER.md first; user-visible changes belong in the standards changelog (one row per version).
This project is licensed under the MIT License.
Standards Version: v3.88.0 | Last Updated: 2026-10-21 | Maintainer: geekma | Email: geekma@gmail.com
Report Bug | Request Feature | Read the Standards | Changelog