Airlock

Risk-aware checkpoint guardrails for AI coding agents.

Airlock helps Claude Code and Codex move quickly on ordinary changes, then pause before high-risk work such as payments, auth, data migrations, production config, and financial logic. It starts in advisor mode by default: guidance, workflow docs, and the explicit $airlock skill are available, but mechanical Claude/Codex checkpoint hooks stay inactive until governance is approved.

AI agents are fast, but not every change should go straight from prompt to patch. Airlock adds a lightweight human checkpoint layer:

• Small and medium changes stay lightweight.
• High-risk changes explain the risk before implementation planning.
• Temporary governance can be enabled for one change, then turned off again.
• Claude Code and Codex can share the same project workflow state.
• OpenSpec and vendored Superpowers are installed locally for repeatable planning, debugging, TDD, verification, and archive flows.

Quick Start

Initialize Airlock in a target project:

./scripts/airlock init /path/to/project
./scripts/airlock doctor /path/to/project

Use Airlock from the agent:

$airlock help me implement wallet transfer limits

For small and medium changes, the agent should stay in advisor behavior and run focused checks. For high-risk changes, it should explain the risk and ask whether to enable temporary governance before implementation planning.

New users should start with the 5-minute guide: Quick Start. It shows the shortest install path, the first checkpoint path, and a concept map before the full reference details below.

What It Installs

• OpenSpec project structure under openspec/
• OpenSpec local skills for Codex and Claude
• Explicit airlock skills for Codex and Claude. Codex discovers the repo skill from .agents/skills/airlock/SKILL.md; .codex/skills/airlock is not generated so Codex does not show duplicate Airlock completions. Claude keeps its compatibility copy under .claude/skills/airlock/SKILL.md.
• Vendored Superpowers 5.1.0 skills copied into the project for Codex and Claude
• Claude slash commands under .claude/commands/opsx/
• Standard root AGENTS.md and CLAUDE.md agent entry files
• Canonical workflow docs under .ai-workflow/docs/
• Universal .ai-workflow/docs/risk-policy.md, .ai-workflow/docs/security-baseline.md, and .ai-workflow/docs/context-budget-policy.md
• Generated .ai-workflow/docs/profiles.md manifest for active stack and domain policies
• Optional composable policy profiles under .ai-workflow/docs/profiles/
• Claude local permission allowlist for OpenSpec commands only in governance mode
• Optional Claude SessionStart hook that injects a short project-local Superpowers bootstrap hint on startup, clear, and compact events
• Optional Claude checkpoint hooks that record explicit active-change selections and approvals, then block ordinary implementation writes and shell commands outside a small pre-implementation allowlist until Checkpoint 2 approval
• Optional Codex project hooks under .codex/hooks.json that inject the same Superpowers bootstrap, record the same approvals, and gate Codex patches and commands with the shared checkpoint state
• Standard .gitignore entries for local workflow backups and common generated artifacts; existing project entries are preserved

By default, the installer uses the compact layout: canonical workflow docs, runtime skills and commands, optional governance hooks, state, backups, and version metadata live under .ai-workflow/, while thin Claude/Codex compatibility files stay in their default discovery paths. Legacy root-level workflow documents from older bootstrap versions are backed up and removed during update.

Commit And CI Boundaries

The initializer updates files in the target project only. For existing repositories, it does not commit, push, or open pull requests. Developers choose the final commit contents in their IDE or Git client.

After initialization or update, shared workflow files normally belong in the project repository:

• .ai-workflow/config.yml
• .ai-workflow/version
• .ai-workflow/docs/**
• .ai-workflow/runtime/**
• .agents/skills/airlock/SKILL.md
• AGENTS.md
• CLAUDE.md
• .gitignore
• openspec/** when it contains project requirements or active change specs

When governance mode is enabled, the hook configuration files created or updated by Airlock also normally belong in the project repository: .codex/hooks.json and .claude/settings.local.json.

Local workflow state and compatibility copies should stay local: .ai-workflow/state/**, .ai-workflow/backups/**, .ai-workflow/bin/**, .ai-workflow/tools/**, .claude/skills/**, .codex/skills/**, .claude/hooks/**, .codex/hooks/**, .claude/commands/**, .agents/** except .agents/skills/airlock/SKILL.md, docs/superpowers/**, and docs/ai-workflow/**.

This script does not generate .github/workflows/test.yml or .gitlab-ci.yml for business projects. Add GitHub Actions, GitLab CI, protected branches, and required PR/MR checks separately according to the target repository platform.

Usage

Airlock's local CLI wrapper is the preferred entrypoint for day-to-day use:

<bootstrap-dir>/scripts/airlock init /path/to/project

The lower-level initializer remains available for compatibility:

<bootstrap-dir>/scripts/init-ai-workflow.sh /path/to/project

Recommended for a new project:

<bootstrap-dir>/scripts/airlock init --git /path/to/project

This is advisor mode. It installs the workflow, airlock skills, OpenSpec, and project-local Superpowers skills, but it does not install active Claude or Codex checkpoint hooks.

Opt into governance only when the user or project explicitly wants enforcement:

<bootstrap-dir>/scripts/airlock init --governance /path/to/project

--enable-hooks is an alias for --mode governance; governance init installs resident hook wiring and turns session enforcement on for the approved change. For normal temporary governance shutdown, use the runtime switch instead of removing hook wiring:

<bootstrap-dir>/scripts/airlock guard off /path/to/project

--disable-hooks remains available when you intentionally want to remove Airlock-managed hook commands from Claude and Codex configuration. --strict-permissions is valid only with governance mode because advisor mode does not install active Claude gate hooks.

For projects that already have resident hooks installed, use the guard state switch for this-change governance:

<bootstrap-dir>/scripts/airlock guard on /path/to/project --change <change-name>
<bootstrap-dir>/scripts/airlock guard status /path/to/project
<bootstrap-dir>/scripts/airlock guard off /path/to/project

Update an already initialized project with the latest bootstrap templates and Airlock files:

<bootstrap-dir>/scripts/airlock init /path/to/project

The script always writes the compact layout. It prints the bootstrap version at startup, writes it to .ai-workflow/version, and records layout metadata in .ai-workflow/config.yml. --compact-layout is accepted as a harmless compatibility flag for older command snippets, but it is not required.

If no openspec command is available on PATH, the script installs the vendored OpenSpec runtime into the target project's local .ai-workflow/tools/ and .ai-workflow/bin/ directories and uses that command for initialization. These local tool directories are ignored by git.

--git initializes a git repository when the target does not already have one and creates a chore: initialize AI workflow baseline commit for that new repository. Existing repositories are never committed automatically. Without git, the workflow still works, but Superpowers branch/worktree steps are treated as optional and skipped.

--strict-permissions resets Claude's OpenSpec allowlist to the standard template. It requires governance mode. Use this for new governed projects or when a governed project's .claude/settings.local.json has drifted.

--preserve-docs keeps existing AGENTS.md, CLAUDE.md, and existing canonical docs under .ai-workflow/docs/ instead of replacing them. Use this only for projects with deliberate local customizations.

--legacy-layout is not supported. Older root-level workflow artifacts are treated as migration input, backed up, and removed from the project root.

--dry-run prints the planned actions without writing files, including OpenSpec initialization/update, vendored Superpowers skill copy, Claude and Codex hook installation or removal according to the selected mode, settings merge, .gitignore merge, and optional git initialization.

--rollback restores the latest manifest-backed workflow bootstrap update:

<bootstrap-dir>/scripts/init-ai-workflow.sh --rollback /path/to/project

Rollback only restores workflow-managed files recorded in the latest manifest. It is not a business-code rollback and does not undo unrelated source changes. Before restoring, it creates a protective backup of the current workflow-managed paths. Backups created by older bootstrap versions without manifest.json cannot be rolled back automatically; use the printed backup path for manual recovery.

--profile <name> installs an optional stack policy profile. It can be repeated. Available initial stack profiles:

• react-frontend
• n8n-workflow

--domain <name> installs an optional domain policy profile. It can be repeated. Available initial domain profiles:

• internal-admin
• financial
• public-api

Profiles do not replace the universal workflow. They add focused policy documents under .ai-workflow/docs/profiles/, and .ai-workflow/docs/profiles.md tells agents which documents are active. When profile selection changes, previously copied profile documents may remain for history, but only the manifest entries are active.

Example:

<bootstrap-dir>/scripts/init-ai-workflow.sh \
  --git \
  --mode governance \
  --strict-permissions \
  --profile react-frontend \
  --domain internal-admin \
  /path/to/project

The script fails if it cannot verify OpenSpec, the vendored Superpowers skills, generated OpenSpec skills, Claude opsx commands, optional Claude and Codex hook templates, and Codex opsx prompts. It copies Superpowers skills into the project so both agents have a local fallback even when a global plugin does not inject them automatically.

Advisor And Governance Modes

airlock is the explicit entrypoint for Airlock behavior. In Codex, run /skills and choose Airlock, or mention $airlock in the prompt. Use it when the host agent does not auto-start the desired workflow.

Advisor mode is the default for fresh projects. It installs guidance, workflow docs, airlock skills, OpenSpec, vendored Superpowers, and policy profiles, but it leaves Claude and Codex active hook enforcement disabled. In advisor mode, Airlock can recommend OpenSpec, Superpowers, risk review, and verification steps; it does not mechanically block ordinary edits, installs, or commands.

Governance enforcement is opt-in and should usually be temporary for a specific high-risk change. The runtime state lives in .ai-workflow/state/airlock-enforcement.local.json. Use scripts/airlock guard on /path/to/project --change <change-name> only after the user explicitly approves mechanical checkpoint enforcement for the current change. After the change is complete, return to advisor behavior with scripts/airlock guard off /path/to/project and verify with scripts/airlock doctor. Long-lived governance is not the normal Airlock recommendation because every project eventually has small routine changes.

When $airlock classifies a request as high-risk and enforcement is not already session, the agent must stop before OpenSpec, Superpowers, checkpoint artifact preparation, visual preview, mockup generation, or implementation planning. It should state the high-risk reason, say whether the checkout currently has a mechanical gate, recommend temporary governance, and wait for explicit approval. If the user declines, it may continue in advisor behavior while making clear that no mechanical gate is active.

$airlock is also the resume entrypoint. If the user says $airlock, $airlock continue, $airlock resume, or an equivalent phrase such as $airlock 继续 / $airlock 恢复, the agent should inspect active OpenSpec changes before asking for a new requirement. When an active change contains openspec/changes/<change-name>/.comet.yaml, Airlock keeps the user-facing entrypoint and resumes through Comet's underlying phase detection rules. The user should not need to switch manually to $comet just to continue a task started through Airlock. If multiple active changes exist, the agent asks the user to choose; if no active change exists, it says there is no Airlock or Comet task to resume.

Small and medium Airlock work does not require archive. When a high-risk governed change used an OpenSpec change and final verification or Checkpoint 3 has passed, the agent should ask whether to run openspec archive <change-name> before returning to advisor behavior. Archive is optional and user-approved because it merges and moves OpenSpec change artifacts. Whether archive is accepted or deferred, completion should still run scripts/airlock guard off /path/to/project and verify with scripts/airlock doctor, unless the user explicitly keeps enforcement active.

If an already initialized project contains Airlock-managed hook commands, a plain update preserves resident hook wiring. Use scripts/airlock guard off when the current governed change is complete and the project should return to advisor behavior. Use --disable-hooks only when you want to remove the hook wiring itself.

Run Airlock doctor to separate repository Airlock state from host runtime problems:

<bootstrap-dir>/scripts/airlock doctor /path/to/project

The report shows Airlock config, hook intent, whether managed hook commands are present, local runtime artifacts, and host runtime signals such as Git, Node, package manager, Java, Maven, Gradle, and Docker availability.

Install the user-level Codex Airlock skill when you want new Codex windows to discover Airlock before a project is initialized:

<bootstrap-dir>/scripts/airlock install-skill

In an uninitialized project, the global Airlock skill can only diagnose that .ai-workflow/config.yml is missing and ask before initializing workflow files. It must not claim project enforcement, checkpoints, or resident hooks are active.

Testing

Run the complete bootstrap test suite from the repository root:

npm test

The suite runs Node unit tests for manifest rollback, hook locking, checkpoint recording, checkpoint gating, and Stop-hook behavior, then runs the shell end-to-end initialization test. GitHub Actions in this bootstrap repository runs the same command.

Team Adoption Gate

Before a team relies on Airlock for governed high-risk changes, complete docs/TEAM_ONBOARDING_CHECKLIST.md. Target business projects need their own repository merge gate; optional local hooks are guardrails, not a replacement for protected branches and required CI checks. The GitHub branch protection example is documented in docs/CI_BRANCH_PROTECTION.md.

For GitHub repositories, apply branch protection after the remote exists:

scripts/configure-github-branch-protection.sh --repo OWNER/REPO --branch main

The release-hardening chain retest is recorded in docs/REAL_WORKFLOW_CHAIN_RETEST.md.

When OpenSpec is already initialized, the script compares generated local skills, Claude commands, and user-level Codex prompts against a clean OpenSpec reference. Damaged generated files are backed up and refreshed with OpenSpec. Existing user-level ~/.codex/prompts/opsx-*.md files are also backed up under the project's timestamped .ai-workflow/backups/ directory before OpenSpec replaces them.

Installer and hook events are written to .ai-workflow/state/workflow-audit.local.jsonl. This local audit log is for troubleshooting workflow behavior only. It is not a compliance system, does not prove human identity, and does not replace repository review or CI checks.

The Claude and Codex checkpoint hooks are optional governance guardrails, not a security sandbox. They keep normal agent tool calls aligned with the three-checkpoint process after governance is enabled, but they do not replace repository permissions, review, or final verification. Airlock cannot bypass Codex, Claude, OS, Docker, npm, Maven, network, connector authentication, or tool-approval sandbox boundaries. Use airlock doctor to distinguish Airlock configuration from those host/runtime limits. Both agents share .ai-workflow/state/workflow-checkpoints.local.json. In governance mode, read-only project exploration such as rg, find, ls, cat, sed without in-place editing, git status, git -C <project> rev-parse, git diff, and OpenSpec read/validate commands is allowed before Checkpoint 1. The narrow recovery form cd <project-root> && openspec <read-command> is also allowed so agents can recover when their shell working directory drifts into a subproject. The vendored Superpowers visual companion start and stop scripts are allowed only for project-owned preview sessions, so agents can open and clean up local previews without broad ps or kill access. Writes, installs, commits, pushes, redirects, ordinary shell chaining, and implementation edits remain gated. Before Checkpoint 1, the gate allows only OpenSpec preparation artifacts: proposal.md, design.md, tasks.md, risk.json, optional .openspec.yaml, and specs/**/spec.md. Do not batch implementation-scope.json or implementation plans into that patch; write and validate the proposal first, approve Checkpoint 1, then prepare the Checkpoint 2 implementation scope. Use these exact commands as complete user messages:

CHECKPOINT SELECT <change-name>
CHECKPOINT APPROVE 1 <change-name>
CHECKPOINT APPROVE RISK <change-name>
CHECKPOINT APPROVE 2 <change-name>
CHECKPOINT APPROVE 3 <change-name>
CHECKPOINT PAUSE <change-name>
CHECKPOINT CLOSE <change-name>

The selection command is required when switching between active OpenSpec changes. Approval commands also select their named change. Generic replies such as Proceed do not advance checkpoint state. Approval commands also automatically pause the current active change without deleting its artifacts or approvals. CHECKPOINT SELECT only selects an existing OpenSpec change; it never creates one. The agent must create a missing change with openspec new change <change-name> or the OpenSpec propose flow before asking for approval. After final delivery, close the completed change. Closing clears its active selection and resets its local approval, preventing a later task from inheriting implementation permission from stale state.

One workspace directory supports one selected active change at a time. Use a separate git worktree for concurrent work instead of trying to run multiple implementation tracks in the same directory. CHECKPOINT PAUSE can temporarily clear the active selection without deleting OpenSpec artifacts; closing an unapproved change is also selection-only and does not archive or delete the change.

Checkpoint approvals are mechanically constrained. Checkpoint 1 is rejected unless the required OpenSpec artifacts and risk.json exist and openspec validate <change-name> --strict succeeds. Checkpoint 2 is rejected unless Checkpoint 1 has already been recorded. Checkpoint 3 is rejected unless Checkpoint 2 has already been recorded. Checkpoint 3 records human delivery acceptance after the agent reports verification evidence; it does not automatically run project-specific verification commands.

Every OpenSpec change carries a machine-readable risk.json. Its canonical fingerprint is recorded at Checkpoint 1 and checked before later approvals and implementation writes. L3 requires CHECKPOINT APPROVE RISK <change-name> before Checkpoint 2. L4 cannot receive implementation authorization. This local gate reduces routine agent mistakes; it is not a security sandbox.

Codex trust prompts: the first Codex CLI or Desktop session for a new directory asks whether to trust the project. Trust the directory first. Advisor mode does not install active Codex checkpoint hooks; use /skills or $airlock when you want an explicit Airlock entrypoint. In governance mode, if Codex reports that project-local hooks are disabled until restart, close and reopen the project. The next launch asks you to review the project hooks. Review them, then choose trust all and continue. If you continue without trusting, the Codex guardrails will not run.

Claude Code caveat: plugin installation alone does not prove automatic Superpowers triggering works in a new session. Advisor mode provides airlock as the explicit Airlock skill. Governance mode adds a local SessionStart hook to improve startup behavior, but ordinary natural-language auto-triggering can still vary by Claude Code runtime. Use these acceptance checks inside the project:

claude -p "/brainstorming Let's make a react todo list" --output-format json --tools "Read,Bash,Glob,Grep,Task"
claude -p "Let's make a react todo list. Do not write files or install packages; only start the required workflow." --output-format json --tools "Read,Bash,Glob,Grep,Task"

If that returns Unknown skill, restart Claude Code. If ordinary prompts do not auto-trigger Superpowers, the project rules require manual Superpowers-compatible mode by reading .claude/skills/<skill>/SKILL.md.

Vendored Superpowers

The bootstrap repository carries a pinned copy of Superpowers skills under vendor/superpowers/skills/. Current pinned version: 5.1.0, MIT licensed. This removes the dependency on the target machine's Claude or Codex plugin cache when initializing a new project. vendor/superpowers/VENDOR.json records the source, version, skill list, and SHA-256 checksums for the vendored SKILL.md files.

Vendored OpenSpec

The bootstrap repository also carries OpenSpec CLI distribution artifacts under vendor/openspec/ for intranet use:

• fission-ai-openspec-1.3.1.tgz is the standard npm package tarball for internal registry/cache publication.
• openspec-1.3.1-runtime.tgz is an offline runtime archive with installed npm dependencies for machines that need a local openspec command.

OpenSpec 1.3.1 requires Node.js >=20.19.0. The initializer installs the runtime archive automatically when openspec is absent from PATH; see vendor/openspec/README.md for manual offline install details.

Public Export and Package Hygiene

The development repository may contain local IDE files, tests, CI config, and design notes that should not be copied into a public showcase repository or client package. package.json uses a files whitelist for npm pack, and the same whitelist drives the clean public export helper:

scripts/export-public.sh ../agent-airlock-public

The destination may already be a git repository; its .git directory is preserved while other files are rebuilt from the whitelist. The export excludes development-only paths such as .idea*, .github/, tests/, docs/superpowers/, local outputs, and .DS_Store files.

Workflow Model

• OpenSpec owns specs, changes, validation, application, and archive.
• Superpowers owns requirements exploration, planning discipline, TDD, debugging, review, and completion verification.
• The three checkpoints own human approval gates.
• .ai-workflow/docs/risk-policy.md owns the universal L0-L4 change classification.
• .ai-workflow/docs/security-baseline.md owns cross-language security red lines.
• .ai-workflow/docs/context-budget-policy.md requires selective reads, file maps, and a Context Plan before broad exploration exceeds the planning thresholds.
• .ai-workflow/docs/profiles.md activates optional stack and domain policy documents.
• Specification approval validates OpenSpec delta formatting with openspec validate <change-name> --strict before Checkpoint 1.
• Implementation planning records the project's test, lint/static-analysis, and build/type-check commands before Checkpoint 2 approval. It also records a Context Review: file map, full-read reasons, selective reads, excluded files, and estimated context risk. Missing commands must be noted explicitly.
• Final verification includes OpenSpec validation, tests, and any available lint/static-analysis and build/type-check commands. Missing verification commands must be reported explicitly.

The installed canonical process is documented in .ai-workflow/docs/workflow.md and sourced from templates/AI_WORKFLOW.md.