codex-setup

Files (2)

• SKILL.md
• agents-kernel.md · references/

SKILL.md (first lines)

# Codex Setup

## Trigger

- Keywords: codex setup, codex init, agents.md, setup codex, initialize codex, codex doctor, codex sync
- After: `npx skills add sd0xdev/sd0x-harness`

## Subcommands

| Command | Purpose |
|---------|---------|
| `init` | First-time setup: generate AGENTS.md + install the `commit-msg` hook + copy scripts |
| `doctor` | Verify installation integrity: files exist, AGENTS.md hash matches, and each recorded hook is **active** — hook *bytes* are `sync`'s axis, not this one (§ doctor) |
| `sync` | Re-generate AGENTS.md + update installed hooks/scripts after skill update |

Default (no subcommand): `init`

## Arguments

| Flag | Applies to | Effect |
|------|-----------|--------|
| `--with-push-gate` | `init`, `sync` | Install `pre-push-gate.sh` as the `pre-push` hook. **Off by default** |

The `pre-push` gate is the one hook that **waits for a human** — it reads `/dev/tty`,
so from a non-interactive context it stalls or fails on a terminal that is not there.
That is why it is opt-in, and why every path below reads that choice from state rather
than re-deciding it. `commit-msg` stays a default install because it never prompts:
it guards the attribution anchor (CLAUDE.md rule 3) by reading the message and
deciding, with no `/dev/tty` and no input. **It does still reject** — exit 1 on a
policy violation, exit 3 when the policy cannot be evaluated — and it rejects
interactive and non-interactive commits alike (`scripts/commit-msg-guard.sh`). The
distinction that makes it safe to install by default is *prompts vs. rejects*, not
*blocks vs. does not block*.

**The flag is the opt-in interface — there is no prompt.** `init` must not ask
interactively whether to install the gate: this skill runs under Codex sandboxes and
in non-interactive setup flows where an unanswered prompt would either hang or be
silently defaulted, and a silent default is exactly what opt-in exists to prevent.

## init

### Phase 1: Detect Host Context

1. Find repo root: `git rev-parse --show-toplevel`
2. Read `package.json` if present → extract `name`, `scripts.test`
3. Read `.claude/CLAUDE.md` or `CLAUDE.md` → extract test command pattern
4. Detect plugin root: find `scripts/build-codex-artifacts.js` relative to this skill

### Phase 2: Generate AGENTS.md Kernel

```bash
node <plugin-root>/scripts/build-codex-artifacts.js \
  --project-dir <repo-root> \
  --output <repo-root>/AGENTS.md
```

If the file already exists, warn and ask before overwriting.

Verify output:
- File exists and is non-empty
- Size ≤ 24 KiB (`wc -c < AGENTS.md` ≤ 24576)
- No unresolved placeholders (`{PROJECT_NAME}`, `{VERSION}`, `{TEST_COMMAND}`)

### Phase 3: Multi-Mode Hook Install

Install the git hooks using priority-ordered detection. The mode detection is
identical for both hooks; only *which* hooks are installed differs:

| Priority | Condition | Action |
|----------|-----------|--------|
| 1 | `.husky/` directory exists | Copy the hook's script to `.claude/scripts/`, **then prepend** that hook's executing stanza below to `.husky/<hook>` — `commit-msg-guard.sh` into `.husky/commit-msg`, and (only under `--with-push-gate`) `pre-push-gate.sh` into `.husky/pre-push`. **Two stanzas, not one**: they are shaped by what git hands each hook, and § The Husky commit-msg stanza says where they differ |
| 2 | `git config core.hooksPath` is set | Install to that path |
| 3 | `.git/hooks/` is writable | Direct write |
| 4 | Fallback | Write to `.githooks/` + print `git config core.hooksPath .githooks` — **the write alone does not arm the hook**; see below |

#### Modes 2–4 write the hook **as** the file, so check who owns it first

Mode 1 prepends into a shared container; modes 2–4 put the gate — or the guard — at the resolved
hook path **as that file's whole content**. A write there is a delete of whatever was there, and
the operator's own `pre-push` may be the only thing standing between them and something this
skill knows nothing about. `--with-push-gate` is a request to *add* a guard; taking one away to
honour it is not a lesser reading of that request, it is the opposite of it.

So before any dedicated-file mode writes a hook, classify the destination — **by content, never by
existence**:

| Destination | Action |
|-------------|--------|
| Absent, or present and empty | Write. Nothing is lost |
| **sd0x-owned** — one of the first 20 lines is exactly `# <script> - ` followed by that script's own summary, where `<script>` is `pre-push-gate.sh` or `commit-msg-guard.sh` per hook | Overwrite. This is a refresh of our own file, which is what `sync` exists to do |
| Anything else | **Do not write.** Record `pending`, and report: `<hook>: <resolved> already exists and is not sd0x-owned — the gate was not installed; move or rename that hook, then re-run` |

The marker is the shipped scripts' own second line, so an older shipped version is still recognised
as ours and a refresh across versions is not blocked. It is matched as a prefix of a line rather
than against the whole file because the byte-for-byte alternative refuses every past version — the
one case a refresh most needs to succeed on.

**The predicate is deliberately strict in one direction.** A hand-edited header stops matching and
the install refuses; a foreign file matches only if someone copied our header into it. Refusing an
install costs a re-run, and the operator is told which file to move; clobbering costs a hook nobody
can get back. The asymmetry decides, exactly as it does for `uninstall` below — that row already
said "only after verifying it is sd0x-owned", and this is the same predicate, stated once, on the
side where the file is still there to protect.

**`pending` is the honest record for a refused write**: the operator opted in, the wiring did not
finish, and the transition matrix already treats `pending` as a gate to keep — so a later
`sync` retries rather than reading the refusal as a decline. Recording `declined` would turn
their request into an opt-out they never made.

#### The Husky stanza — prepended, executed, and it hands stdin back

Mode 1 does not write its own file: it goes into `.husky/<hook>`, beside whatever the project
already put there. Two properties of that neighbourhood decide the shape of the stanza, and both
were got wrong by the words this section used to carry ("append sourcing"):

| Property | Consequence | Measured 2026-08-21 |
|----------|-------------|---------------------|
| git delivers the ref list on **stdin, once** | An earlier consumer in the same hook takes it, and the gate then reads EOF — zero refs, nothing protected, nothing rewritten, **exit 0** | An existing `while read …` loop ahead of the gate turned a protected-branch rewrite that the gate refuses with exit 1 into an allowed push |
| `.`/`source` does not change `$0` | The gate's privileged re-exec, which then read `exec … bash -p "$0" "$@"`, named **the Husky hook** rather than the gate | The parent hook's first line printed twice — once at `$-`=`hB`, once at `hpB` — i.e. the user's whole `pre-push` re-ran under a privileged shell, and the gate never ran as the gate. The gate has since switched that word to `${BASH_SOURCE[0]:-$0}`, which resolves correctly under `source`, and an ordinary `source` of the gate now refuses (2026-08-22) — so no *supported* caller reaches this defect. Not "closed entirely": the refusal compares against `$0`, which a sourcing caller supplies, and a forged one walks past it (`4-implementation.md` § 4.3, Round 54). Row 1 above was already reason enough on its own |

From sd0xdev/sd0x-harness, MIT.

More from sd0xdev/sd0x-harness