Machine Bootstrap

Portable machine-level AI-agent setup and one-time project guidance seeding for a workspace of independent sibling repositories.

This repository is a direct child of the workspace it administers. It does not turn that workspace into a parent repository or an instruction scope.

Ownership hierarchy

The layout is intentionally sibling-only:

Workspace/
|-- MACHINE.md                  # optional, machine-local, inert
|-- machine-bootstrap/          # its own Git repository
|   |-- AGENTS.md
|   |-- CLAUDE.md
|   |-- machine-templates/
|   |-- project-templates/
|   `-- scripts/
|-- project-a/                  # its own Git repository and guidance
|-- project-b/                  # its own Git repository and guidance
`-- scratch/                    # optional, non-project experiments

The workspace root has no live AGENTS.md, CLAUDE.md, or _templates/. Codex and Claude sessions for normal project work start in the target project root or relevant scoped directory. A bootstrap session may initialize, audit, repair, install, inspect the registry, or route a sibling project, but it must not become that project's long-lived coding session.

Filesystem access to the parent registry or a sibling target may require sandbox authorization. Access does not load that sibling repository's instructions into the current session.

What belongs here

• AGENTS.md and CLAUDE.md — instructions for this repository only.
• machine-templates/MACHINE.example.md — starter for the optional inert parent registry.
• project-templates/ — the single canonical starter source for project-owned guidance, Git workflow, PR template, and ignore entries.
• docs/engineering/git-workflow.md — this repository's Git/publication contract; the project starter has its own project-owned contract.
• .github/workflows/bootstrap.yml — Linux, Windows, and macOS verification.
• skills.json and scripts/install-skills.mjs — reviewed shared skill roster and missing-only installer.
• workflows/ and scripts/install-workflows.mjs — provider-neutral workflow packages and deterministic adapters.
• scripts/init-workspace.mjs — parent registry plus shared capabilities.
• scripts/init-project.mjs — explicit, target-scoped, one-time project seeding.
• scripts/test-bootstrap.mjs — disposable regression suite.
• CONTINUITY.md — bounded current state; docs/continuity/ is on-demand, append-only history.

project-templates/TEMPLATE-USAGE.md documents the starter set but is never copied into a project or renamed as its README. Once starter files are copied, they are project-owned and are not synchronized against machine-bootstrap.

What stays machine-local

The optional parent MACHINE.md records project inventory, relative or local paths, port reservations, cross-project relationships, machine capabilities, and lifecycle notes. It is not automatically loaded by Codex or Claude. Machine-bootstrap reads it deliberately only for administration, discovery, port allocation, or sibling routing. Project sessions normally do not need it.

Do not put credentials, private keys, tokens, private documents, sensitive data, secret filenames, or provider responses in this repository or MACHINE.md.

The optional scratch/ folder is for disposable experiments, downloaded samples, fixtures, or non-project work. It carries no inherited repository policy. Promote durable work into its own sibling project with its own guidance.

Set up another machine

Prerequisites: Git, Node.js 24 or newer, Claude Code and/or Codex.

Choose either setup style:

• Agent-assisted setup (recommended for normal use): open an agent session in this repository and ask: “Set up this workspace using machine-bootstrap. Follow INIT.md, preserve existing files, stop for anything requiring manual review, and report what changed. Do not commit or publish anything.” The user does not need to name or memorize script commands. The agent reads the contracts, confirms scope, requests any required filesystem permission, and uses the repository's audited scripts for the actual setup and verification.
• Direct CLI setup: follow the commands below yourself. This is useful for automation, repeatable machine provisioning, or inspecting each command directly.

1. Clone this repository as a direct child of the dedicated non-Git folder that will contain sibling projects. The filesystem root and user home are rejected as unsafe workspace targets.

2. Initialize the optional registry and shared capabilities:

   node scripts/init-workspace.mjs

   The command creates ../MACHINE.md only when missing, installs or verifies shared skills and workflows, and generates provider adapters. The canonical machine template must be a real in-checkout file and is snapshot-read with no-follow access before any workspace write. The command never creates parent guidance or a parent template copy.

3. Replace MACHINE.md TODOs with verified local facts, then run:

   node scripts/init-workspace.mjs --check

   Check mode is read-only. It allows the optional registry to be absent, but fails on unresolved placeholders when the file exists, shared-capability drift, or retired parent guidance/template entries. Use --skip-skills or --skip-workflows to omit that layer from both setup and verification.

4. If an older bootstrap generated parent AGENTS.md, CLAUDE.md, or _templates/, initialization stops without moving anything. Automatic migration is not currently supported. Review those entries and move them manually outside the workspace root before rerunning; never move MACHINE.md or sibling project guidance as part of that cleanup.

5. Seed one existing project root:

   node scripts/init-project.mjs ../project-a

   For a missing directory, add --create. The initializer does not initialize Git. It creates only missing project-owned files and preserves existing files. Git boundary probes clear inherited repository/worktree path overrides before evaluating their explicit -C targets. For an existing .gitignore with no environment rules, it appends the complete ordered .env, .env.*, !.env.example policy plus missing independent safety rules. An existing canonical environment block is preserved only when Git confirms the resulting rules still ignore local environment files and expose .env.example; ineffective, incomplete, or ambiguous rules stop for manual review before any project writes. The initializer never copies TEMPLATE-USAGE.md and never creates or replaces a README. Canonical template sources must remain real files inside this checkout and are snapshotted with no-follow reads before project writes. Newly created parents use an atomic no-replace directory claim and are identity-snapshotted before use. Managed reads, writes, and rollback recovery are anchored to real parent-directory identities pinned for the full run; symbolic-link, parent, leaf, or backup replacement stops safely instead of being followed or deleted. Every seeded file is identity-and-byte checked again before success; a preflighted starter that disappears stops before replacement. On failure, rollback moves run-owned files to named recovery paths instead of deleting them, and leaves identity-changed concurrent entries at their original paths. It never deletes directories by pathname; file and directory cleanup is reported for manual review.

6. Replace project placeholders with verified project facts. Start a new Codex or Claude session in that project root or relevant scoped directory.

To initialize only one project through an agent, specify its exact path: “Initialize ../project-a using machine-bootstrap. Preserve existing files, stop for review-required conditions, verify the result, and do not commit or publish anything.”

Product delivery workflow

Alongside guidance and skills, this repository owns a portable, provider-neutral workflow foundation. It owns the process; each project keeps owning its product behavior, architecture, engineering rules, and required verification.

Activation

Installation makes the workflow available, not universally active. The complete flow activates only when the user selects Product Partner or Delivery Lead, explicitly requests the complete workflow, continues an active Product Brief or Delivery Plan, or a project requires it for a named class of work. Selecting the Verifier activates only independent verification for the supplied change; it does not retroactively create missing upstream gates or artifacts. Ordinary work creates neither by default.

For this repository, AGENTS.md names the activating contracts: installation ownership and recovery, acquisition integrity, provider formats/discovery, workflow policy, hard invariants, and propagation to siblings. Mechanical maintenance that preserves those contracts stays outside the full flow. Every implementation still receives self-verification and fresh independent review before local completion. Record the classification rather than judging a task by its apparent size. Existing project-owned starters are never synchronized when these defaults change.

The Git contracts and PR templates use a 500-line target and a 1,000-line review gate, measured as additions plus deletions. Changes over 1,000 require a split or an explicit reviewer exception; generated/lockfile/rename/binary changes are reported separately. See docs/engineering/git-workflow.md for counting, exceptions, and review requirements. These gates are guidance for both providers, not an automated CI size limit.

The three roles

Role	Owns	Claude agent	Codex agent
Product Partner	Why and what	mb-product-partner	mb_product_partner
Delivery Lead	How and delivery	mb-delivery-lead	mb_delivery_lead
Verifier	Independent evidence	mb-verifier	mb_verifier

The standard handoff

User ⇄ Product Partner
        └─ approved Product Brief ─▶ Delivery Lead
                                      └─ approved Delivery Plan ─▶ execution
                                                                     └─▶ Verifier ─▶ user acceptance

There are two distinct gates, and each needs the user's explicit approval of an exact artifact version. A Product Brief approves the problem, workflow, constraints, and acceptance criteria — never a technical design. A Delivery Plan approves the technical approach and authorizes execution within that scope only. A discovery that changes user-facing behavior, weakens a criterion, materially expands scope, risks destructive migration, or adds a security or privacy implication requires a structured Change Request rather than a quiet widening.

These are process and authority rules, not authentication. No file or command here proves that a human approved anything.

Every implementation is self-verified by the Delivery Lead and then reviewed by at least one fresh independent Verifier by default. Only the user may waive that review for a specific change. The user may request more reviewers; after the mandatory review, the Delivery Lead states firmly whether another review is warranted and why, then honors the request.

Installed paths

What	Path
Canonical workflow package	~/.agents/workflows/product-delivery/
Claude agents	$CLAUDE_CONFIG_DIR/agents/mb-*.md when set; otherwise ~/.claude/agents/mb-*.md
Codex agents	$CODEX_HOME/agents/mb_*.toml when set; otherwise ~/.codex/agents/mb_*.toml
Codex profiles	$CODEX_HOME/mb-product-partner.config.toml and $CODEX_HOME/mb-delivery-lead.config.toml when set; otherwise the same filenames under ~/.codex/

The canonical package holds manifest.json, WORKFLOW.md, the three role contracts in roles/, and seven artifact templates in templates/. The Markdown role contracts are the source of truth; every provider file is generated from them, carries a provenance comment naming its source contract, and pins no model, so each provider keeps its own default.

The seven templates are available building blocks, not universally required files. An activated task using the full discovery-to-delivery sequence normally uses five: Product Brief, Delivery Plan, Alignment Review, Implementation Report, and Verification Report. Decision Logs and Change Requests are created only when needed; empty placeholder artifacts are not created. Active task artifacts stay local by default. If a project tracks agent guidance/configuration and CONTINUITY.md, it removes the starter .agent-work/ ignore rule and also tracks completed task folders referenced with [TASK <task-id>] so continuity never points to missing local files.

Implementation Reports contain the implementer's scope, coverage, and self-verification. Verification Reports alone own final independent passed, failed, unverified, and skipped judgments or an explicit user waiver.

The installer owns exactly those namespaced paths. It never treats the whole ~/.agents, Claude configuration root, or Codex home as bootstrap-owned, and it does not read or write settings.json in the Claude configuration root or config.toml in the Codex home.

Launching a role

Codex desktop (primary workspace)

Open a task in the target repository, then state the outcome in ordinary language. Root guidance routes routine work; inspect the nearest scoped guide before editing a subtree. Use a fresh task starting in that scope when relying on automatic nested instruction discovery.

For ordinary implementation:

Implement the requested change within the existing contract. Run the affected checks, then delegate a fresh independent review to mb_verifier. Report the evidence and unresolved findings. Keep changes local.

For a review without implementation:

Delegate review of the current changes to mb_verifier. Inspect the actual diff and checks; report findings without editing or publishing. Missing full workflow artifacts are a limitation only where that workflow was required.

For the complete discovery-to-delivery workflow:

Use the complete product-delivery workflow for this task. Read its installed contract, begin Product Partner discovery, and follow its separate brief and plan approval gates. Keep the approved artifacts available for role handoffs.

These are task instructions, not an app profile selector. The CLI profile commands below configure a primary CLI session; do not assume they select the role of an existing desktop task. Custom agents are delegated specialists. Codex currently supports delegation explicitly requested by the user or by applicable project/skill instructions. Leave model and reasoning settings inherited unless the user chooses otherwise; bootstrap adapters pin neither.

Confirm mb_product_partner, mb_delivery_lead, and mb_verifier are available in a fresh task after installation. If the harness cannot expose an installed role, report that limit and request a replacement reviewer or explicit waiver when review is required. A new user-owned task is not needed for each subagent.

Claude Code and Codex CLI

Launching Product Partner or Delivery Lead activates the complete workflow. Launching the Verifier activates only its independent verification portion for the supplied change.

Claude Code runs an agent as the whole session with --agent:

claude --agent mb-product-partner

claude --agent mb-delivery-lead

The Verifier is normally invoked through Claude Code's native subagent delegation: ask the Delivery Lead to delegate independent verification to the installed mb-verifier agent. It can also be launched directly with claude --agent mb-verifier.

Codex launches a primary session through the matching profile:

codex --profile mb-product-partner

codex --profile mb-delivery-lead

The Codex Verifier is available as the custom agent mb_verifier; ask the Delivery Lead to spawn it through Codex's native subagent delegation. It has no profile because it is not a primary-session role.

Start a new session after installation so the provider rediscovers the definitions.

Claude retains its native --agent entry and @AGENTS.md shared-guidance adapter. Its lazy nested CLAUDE.md loading differs from Codex's startup guide chain; use the provider-specific checks in docs/guidance-loading-smoke.md.

Updating a workflow

Edit the canonical contract or template in workflows/, bump workflowVersion in that package's manifest.json, then rerun installation. Adapters regenerate deterministically, so nothing drifts between the contract and the provider files.

Installation is missing-only. A destination that exists but differs fails closed with a review message before anything is written. After review:

node scripts/install-workflows.mjs --replace

Reviewed replacement renames each existing entry to a timestamped backup before writing, so a customized adapter is recoverable and a symlinked destination is never written through.

Adding project-specific requirements

A project may name work that activates the workflow and add Change Request triggers, required checks, specialist review, or artifact-retention policy without copying the workflow into the repository. The starter project template contains only this conditional hook. Once active, a project may strengthen but not weaken exact user approval, scope-change escalation, or honest verification.

Updating

Shared skill content lives in ~/.agents/skills/, which Codex discovers directly. Claude links live under $CLAUDE_CONFIG_DIR/skills/ when set, or ~/.claude/skills/ otherwise. Checks for redundant Codex-specific copies use $CODEX_HOME/skills/ when set, or ~/.codex/skills/ otherwise. Changing a provider configuration root does not relocate canonical shared skills. Relative override paths resolve from the command's working directory; empty overrides use the defaults, matching workflow installation. Inactive default provider directories and unrelated entries remain untouched.

The installer adds only missing skills and rejects content that differs from skills.json. To update a skill, review the upstream change at its repository, then revise its exact sourceRevision, sourcePath when needed, expected version when applicable, and contentSha256 together. A changed skill must not pass bootstrap verification until that portable manifest is updated intentionally. Generated global lockfiles from other skill managers remain machine state and are not authoritative for this bootstrap.

Print the installed content hashes after review with:

node scripts/install-skills.mjs --print-hashes

Keep project-specific architecture, commands, safety invariants, and verification in each project's own AGENTS.md and engineering documentation.

Verification

node scripts/test-bootstrap.mjs
node scripts/init-workspace.mjs --check

The regression suite uses disposable workspaces, projects, Git repositories, and home directories. It covers parent boundary checks, registry initialization, manual-only legacy detection, explicit project target safety, missing-only seeding, existing guidance preservation, order-aware .gitignore handling, ownership-safe rollback, sibling byte isolation, import topology, byte budgets, skill integrity, workflow validation, deterministic adapter generation, check-only behavior, and Linux/Windows/macOS CI contracts. It makes no model or API calls and never points setup scripts at the live parent workspace or provider roots.

Manual provider loading checks live in docs/guidance-loading-smoke.md. Static tests are not runtime loading evidence.

Provider contracts checked against official documentation on 2026-09-07: Codex instructions, Codex skills, Codex subagents, Claude memory, and Claude configuration directories. These sources establish supported contracts, not successful loading on every installed provider version.