A simple, evidence-first way to let AI do serious software work and stay in control of what ships.

Nuclear Grade Context Engineering

Your AI agent wrote the code, the tests, and the PR description. Who checked?

A small, dependency-free toolkit that keeps agent work questioned, controlled, and reviewable:

• Every claim linked to evidence, with a record of who generated, selected, and presented it, so you can see when an agent graded its own work.
• Checks that ignore the agent's narrative: a CI validator, receipts with file digests, and an opt-in hook that stops agents editing the files that judge them.
• Rigor that scales with the stakes: a typo needs nothing; a permission change gets the full record. Skills and prompt cards for Claude Code, Codex, Cursor, and more.

Borrows high-consequence engineering discipline, not its regulations (limits).

Contents

See it work · Quick start · The one idea · The skills · Adopt at your pace · Keep the approved version · Common way vs. nuclear-grade · Does it work? · Limits · Project

See it work

A finished change record for a change that should make you nervous: letting an agent write files and call external APIs. Passing tests for the narrow claim, named gaps for the rest, and an honest note that its evidence path is mostly coupled to one AI-assisted maintainer. Standard library only; needs git and Python 3.11+.

git clone https://github.com/FlyFission/nuclear-grade-context-engineering
cd nuclear-grade-context-engineering
python tools/ng.py validate docs/03-worked-examples/ai-agent-tool-permissions/.nuclear/changes/add-agent-tool-permissions --strict-custody
# OK: the record links claims to evidence and discloses custody/coupling (or a named gap).

python -m pytest docs/03-worked-examples/ai-agent-tool-permissions/tests/test_workspace_guard.py -v   # needs pytest
# 4 passed: every write outside the agent's workspace was denied and logged.

echo '{"tool_name":"Write","tool_input":{"file_path":".github/workflows/ci.yml"},"cwd":"'"$PWD"'"}' | python hooks/pre_tool_use.py
# {"hookSpecificOutput": {... "permissionDecision": "deny", ... "protected trust surface (.github/workflows/**)" ...}}

python tools/ng.py validate docs/03-worked-examples/ai-agent-tool-permissions/.nuclear/changes/add-agent-tool-permissions --json
# "ok": true, "evidence_statuses": {"pass": 5, "deferred": 2, ...}, "open_evidence_items": 2, "inputs": {"digest": "..."}

Copy that example as your template; QUICKSTART.md is the guided tour. It is a teaching example, not a production guarantee.

Test your own agent: challenge/ is a 15-minute game. A routine request quietly widens a toy agent's authority; score.py checks whether your agent recorded it, named what is unproven, and left the release to a human. One seeded trap, not a safety rating.

Quick start

Claude Code (the repo is its own plugin marketplace):

/plugin marketplace add FlyFission/nuclear-grade-context-engineering
/plugin install nuclear-grade@nuclear-grade         # skills and command cards
/plugin install nuclear-grade-guard@nuclear-grade   # optional: the guard
/reload-plugins

The main plugin adds the skills and command cards: no hooks, nothing runs on its own, and no ng on your PATH; the CLI runs from a checkout. The optional guard is a separate plugin that stops the agent editing the files that judge it and asks before a tag, publish, or force-push (HOOKS.md).

Any tool, or plain files:

1. Clone and install (no third-party dependencies; the installed command is nuclear-grade): INSTALL.md.
2. python tools/ng.py doctor . and python tools/ng.py list.
3. python tools/ng.py new <slug> --mode quick, fill two files, then python tools/ng.py validate .nuclear/changes/<slug>.

Using an agent? Point it at AGENTS.md, the brief agents read first.

Repo map: docs/README.md. Live catalog: nuclear-grade.yaml; counts here are snapshots.

The one idea

Go fast while exploring. Slow down the moment the work becomes a promise.

Throwaway ideas are cheap; let the agent try them. Rules tighten when work becomes a claim, a controlled file, a public statement, an approved version, a release, or a change to what the agent may do.

• Minimum sufficient context. The smallest set of instructions, facts, limits, and evidence that does the job. A field that does not improve execution, verification, review, or a decision gets cut.
• Who authored the evidence? The agent that builds a change also drafts its evidence, writes the narrative, and frames the decision, so a confident mistake can arrive wrapped in convincing proof. Records track evidence custody and an actor–evidence coupling profile (actor, context, mechanism, authority, resource), and the load-bearing claim's evidence must be reproducible by the reviewer or produced by someone independent (details).

Every change walks one path. Zoomed out it is three moves, PRO: Plan · Run · Operate. With the gate named it is five, PROVE: Plan · Run · Observe · Verdict · Educate. The step you never fold away is Verdict, where a draft becomes a decision.

flowchart TB
  classDef plan fill:#DCE6FA,stroke:#3A5BA8,color:#12203F;
  classDef run fill:#E4DEF7,stroke:#5B49A6,color:#1E1640;
  classDef emb fill:#DCEFDE,stroke:#2E7D45,color:#102810;
  classDef gate fill:#FFD24D,stroke:#B07400,color:#3A2600,stroke-width:2px;
  subgraph LP["P — PLAN"]
    direction LR
    A1(["Question"]) --> A2(["Discover"]) --> A3(["Specify"]) --> A4(["Plan"])
  end
  subgraph LRUN["R — RUN"]
    direction LR
    B1(["Execute"]) --> B2(["Verify"]) --> B3(["Review"]) --> B4{"Decide"}
  end
  subgraph LOPS["O — OPERATE"]
    direction LR
    C1(["Baseline"]) --> C2(["Operate"]) --> C3(["Learn"])
  end
  A4 --> B1
  B4 -->|"ship"| C1
  B4 -.->|"block / defer"| A4
  C3 -.->|"lessons feed the next basis"| A1
  class A1,A2,A3,A4 plan
  class B1,B2,B3 run
  class B4 gate
  class C1,C2,C3 emb

In text (for PyPI and other places SVGs do not render):

Question -> Discover -> Specify -> Plan -> Execute -> Verify -> Review -> Decide -> Baseline -> Operate -> Learn

Each step stops one failure and leaves one artifact you can point at; a skipped step is a failure mode you chose to accept (WORKFLOWS.md). Under the path sit optional habits from high-reliability work, HPI for AI agents (Human Performance Improvement): brief before a risky step, double-check critical actions, hand off cleanly, get independent eyes when trust is on the line, learn from near misses.

The skills

Each skill is one job, with a trigger, a procedure, the record it leaves, and the decision it can block. A host shows the agent only each skill's name and one-line description; the full instructions load only when a skill is picked.

flowchart LR
    A[Auto-match on name + description] --> S
    R[Router: using-nuclear-grade] --> S
    C["Explicit /ng- command"] --> S
    S[Skill body loads] --> D[Decision contract] --> Rec[Record in .nuclear/changes/] --> G[ng validate + CI gate] --> T{Tier: block / warn / observe}
    T --> O[Proceed / stop / escalate to a human]

How they fit together: the core path every change walks, and the heavier skills that switch on when the change calls for them (each arrow is labeled with its trigger):

All 31 by family, with a one-line "use when" for each: SKILLS.md. Which skills fire for which kind of change: CORE.md.

Adopt at your pace

Rigor scales with consequence, not effort.

• Start with the Core 7, always-on habits that fit any change (CORE.md).
• Add skills by trigger when a change touches users, data, dependencies, permissions, AI authority, or a release; starter-kit/ has ready-made bundles.
• Grow into the full system once the lighter path works for your team.

Which record does a change need? Both kinds live in .nuclear/changes/<name>/:

flowchart TD
    Start([Change request]) --> Q0{Purely administrative,<br/>instantly reversible,<br/>no new trust boundary?}
    Q0 -->|yes| Floor[Administrative floor<br/>no packet — the commit message is the record]
    Q0 -->|no| Q1{Local, reversible,<br/>obvious proof,<br/>no new trust boundary?}
    Q1 -->|yes| Quick[Quick packet<br/>risk.md + proof.md]
    Q1 -->|no| Q2{User / data / dep /<br/>permission / AI authority /<br/>release consequence?}
    Q2 -->|yes| Standard[Standard packet<br/>6 files]
    Q2 -->|severe, silent,<br/>irreversible, external trust| Strong[Human-reviewed<br/>stronger mode]
    Q2 -->|already went wrong| Incident[Incident pattern]

Quick = risk.md + proof.md. Standard = risk.md, basis.md, plan.md, trace.md, verification.md, ship.md. Heavier patterns (high-consequence, incident, research-board, release) are written down; treat them as human-reviewed until your project has tested them.

Keep the approved version

Git, CI, and branch protection stay; this rides on top. A green pipeline says tests passed on a commit, not that someone weighed the leftover risk and chose to ship, or what would force a re-check. Nor do they cover what now drives an agent: prompts, model IDs, eval sets, AGENTS.md/CLAUDE.md, skills, and the agent's own permissions.

A baseline is the version everyone agreed is correct, plus the evidence behind it. Changes reach it only through evidence and a decision:

flowchart LR
    classDef item fill:#DCE6FA,stroke:#3A5BA8,color:#12203F;
    classDef gate fill:#FFD24D,stroke:#B07400,color:#3A2600,stroke-width:2px;
    classDef base fill:#DCEFDE,stroke:#2E7D45,color:#102810;
    CI["Controlled items<br/>code, prompts, models,<br/>deps, docs, releases"]:::item --> CH["A change"]
    CH --> EV["Evidence<br/>pass or gap, named"]
    EV --> DEC{"Decide<br/>on purpose"}:::gate
    DEC -->|"ship"| BL["Saved baseline<br/>the approved version"]:::base
    DEC -.->|"block / defer"| CH
    BL --> OP["Operate"]
    OP --> LE["Lessons learned"]
    LE -.->|"feed the next change"| CI

Common way vs. nuclear-grade

Who it is for: teams whose agents write files, call APIs, touch credentials, or affect releases; reviewers who want evidence instead of a pitch. Works as plain markdown in any tool; native plugins for Claude Code and Codex (INTEGRATIONS.md).

Does it work?

Measured honestly, so far:

• Skills vs. a strong generic prompt (evals/skill-control-ladder/): full skills beat one fixed "careful reviewer" paragraph by +0.10 on 27 repo-authored scenarios (p < 0.0001). That did not replicate on seven harder scenarios. One model family; repo-written rubrics.
• Twelve-scenario comparison (skill-workflow-comparison/): a design inspection, author-judged, not an experiment.
• Not yet done: a preregistered, blinded study of false acceptance and reviewer calibration with independent evidence. Until then the honest claim is narrow: an inspectable implementation of evidence-custody and actor–evidence-coupling controls (novelty review).

Limits

Not a compliance program, certification, regulated quality-assurance system, safety analysis, production sandbox, regulatory submission, or legal advice, and no substitute for qualified engineering, legal, security, safety, or compliance review. Not an agent runtime, approval system, or observability platform either; it sits above those tools.

MIT licensed (LICENSE): you may use, copy, change, publish, distribute, sublicense, and sell copies under its terms. That permission is not a promise about quality. Using this repo does not create formal verification and validation, NQA-1 evidence, an NQA-1 record, compliance, certification, regulatory approval, or any safety, security, procurement, production, warranty, or support guarantee. It does not claim any system is safe, secure, compliant, approved, certified, or fit for regulated use. Named public sources are influences, not standards it claims to meet (source map).

Read before use: DISCLAIMER.md · compliance boundaries · do-not-cite-directly.

Project

Discussions · Contributing · Governance · Security · Code of conduct · Support · Roadmap · Changelog · Maxims · Cite · Plain-concept crosswalk · PMBOK/PMI AI bridge

Why it exists. Complex systems rarely fail in one big step; they fail when authority outruns evidence, one reasonable shortcut at a time. AI agents are gaining that kind of authority over codebases. This ports the habits that keep high-consequence engineering honest (questioning attitude, configuration management, evidence before decisions) into a shape software teams can use at AI speed.

Written and maintained by Ben Huffer (@FlyFission): over a decade in the nuclear field; founder of FlyFission Consulting Group, an independent design-review and advisory practice for nuclear projects; builder of AscertAIn, an AI-powered engineering design-review platform. Field stories welcome in Discussions or on LinkedIn.