Skip to content

chore(skills): load skills/ directly in Codex and delete the generated copy - #1188

Merged
boshu2 merged 2 commits into
mainfrom
chore/drop-codex-skill-copy
Oct 3, 2026
Merged

chore(skills): load skills/ directly in Codex and delete the generated copy#1188
boshu2 merged 2 commits into
mainfrom
chore/drop-codex-skill-copy

Conversation

@boshu2

@boshu2 boshu2 commented Oct 3, 2026

Copy link
Copy Markdown
Owner

What changes

The repo shipped a generated second copy of every skill under skills-codex/ for the Codex plugin. This deletes the copy and everything that existed only to generate or police it. The Codex plugin now reads skills/ directly.

  • .codex-plugin/plugin.json points skills at ./skills. skills-codex/ and skills-codex-overrides/ are gone. regen-all.sh no longer generates a second skill tree.
  • Removed: 22 files under scripts/ (the generator, hash and parity tooling, scripts/lint/), 5 bats files, 10 other test scripts, 4 gate-registry entries (skill.codex-parity-drift, -runtime-sections, -override-coverage, -generated-artifacts), about 770 lines of non-test Go and the doctor failure mode fm-skills-stale-codex-sync.
  • 451 files changed, about 38,800 lines deleted.

Why it is safe

On origin/main the copy was the source: the supporting files were byte-identical, all 28 names and descriptions matched, the 18 bodies that differed did so by one leading blank line, and all 28 catalog rows were generated. Linked installs and npx skills already gave Codex skills/ directly.

What a Codex user gets now

  • All 28 skills load from skills/ with 0 load errors in Codex 0.156.1, as a plugin install and as a linked install (checked through codex app-server skills/list under a temp home, no model session).
  • The four explicit-only skills (craft-goal, interview, postmortem, rpi) stay hidden from implicit selection. Each carries agents/openai.yaml; the one for interview used to be derived by the generator and is now a source file. A check fails when that file is missing, invalid YAML or lacks the policy.
  • Full frontmatter now ships to Codex instead of only name and description. prompt.md is no longer shipped; Codex does not read it.

Changes beyond a straight deletion

  • skills/_fixtures/ moved to tests/fixtures/skill-eval/. Codex walks the whole skill tree and was loading the fixture skills; the copy had hidden that.
  • Two sentences in the Skill Builder skill that named the deleted generator were rewritten.
  • Repo-root detection in ao uses skills/ plus registry.json and PRODUCT.md instead of the skills-codex/ sibling.
  • The eval task evals/skills-rpi/tasks/builder-recovery was ported off the deleted projection.

Evidence

  • At 1e846180e: go build, go vet, go test ./... (65 packages), check-go-lint.sh, ao gate check --full (66 pass), bats (1,388 pass, 2 skipped), regen-all.sh --check, validate-doc-release.sh and ci-local-release.sh --quick all pass. The second commit changes one paragraph of a contract doc.
  • One fresh author-distinct read at 1e846180e: every deleted check had the copy as its only live subject, and the out-of-scope changes above were necessary and correct. Its one defect, an overclaim in docs/contracts/codex-skill-api.md, is fixed in the second commit.

Not checked

  • A live Codex model session (whether Codex selects and follows a skill).
  • The Docker oracle for the ported eval task.
  • Codex's own bundled plugin validator fails this plugin, as it did before this change, on fields unrelated to loading.
  • Ten evals/agentops-core/*.json suite files still name the copy; nothing runs them.

Gate-Loosen-Reason: the generated Codex skill copy is deleted, so check-codex-parity-drift.sh and the four skill.codex-* registry entries that policed only that copy have no subject; every gate over skills/ is kept
Test-Removal-Reason: the removed Go tests covered Codex-copy parity, manifest-hash and plugin-cache sync code paths that are deleted with the copy

boshu2 added 2 commits October 3, 2026 11:40
@boshu2
chore(skills): load skills/ directly in Codex and delete the generate…
1e84618 
…d copy

The Codex plugin shipped skills-codex/, a generated second copy of skills/
with the frontmatter cut to name and description. The bodies were the source
bodies, all 28 catalog rows were parity_only, and `ao skills link` and
`npx skills` already hand Codex the source tree. .codex-plugin/plugin.json
now ships ./skills and the copy is gone, with the generator and everything
that only policed it.

Deleted: skills-codex/ (278 files), skills-codex-overrides/, scripts/lint/,
18 scripts (codex-sync, regen-codex-hashes, register-new-codex-skill,
append-codex-override-entry, mirror-codex-references,
refresh-codex-artifacts, audit-codex-parity.{py,sh},
check-codex-parity-drift, lint-codex-native, smoke-test-codex-skills,
export-claude-skills-to-codex and six validate-codex-* validators), their
tests, four gate-registry entries, and the doctor failure mode
fm-skills-stale-codex-sync.

Kept and reduced to what still has a subject:
- validate-codex-api-conformance.sh now checks skills/ against the facts the
  Codex loader enforces (observed with skills/list on codex-cli 0.156.1) and
  the explicit-only invocation policy. It stays in regen-all.sh --check.
- skill.runtime-formats, skill.runtime-parity, skill.manifests and
  derived.changed-scope keep their skills/ halves.
- ao skills check, ao skills link and ao workflows link find the repo root by
  skills/ plus registry.json and PRODUCT.md, not by the skills-codex/ sibling.

Carried over so nothing Codex relied on is lost:
- skills/interview/agents/openai.yaml. Codex reads the invocation policy from
  that file, and the generator derived it from disable-model-invocation. It is
  now source-owned and the conformance check fails without it.
- skills/_fixtures moved to tests/fixtures/skill-eval. Codex loads every
  SKILL.md under the plugin skill tree; the fixtures loaded as a skill named
  "Good Skill" and a load error.

prompt.md, .agentops-generated.json and .agentops-manifest.json had no Codex
consumer and are dropped without replacement. The CHANGELOG states what
plugin users lose.

Gate-Loosen-Reason: the generated Codex skill copy is deleted, so check-codex-parity-drift.sh and the four skill.codex-* registry entries that policed only that copy have no subject; every gate over skills/ is kept
Test-Removal-Reason: the removed Go tests covered Codex-copy parity, manifest-hash and plugin-cache sync code paths that are deleted with the copy
@boshu2
docs(contracts): state what the Codex policy check does and does not …
e6c9ecd 
…catch
@boshu2 boshu2 mentioned this pull request Oct 3, 2026
Merged
@boshu2
boshu2 merged commit 02f5f36 into main Oct 3, 2026
9 checks passed
@boshu2
boshu2 deleted the chore/drop-codex-skill-copy branch October 3, 2026 19:23
boshu2 added a commit that referenced this pull request Oct 3, 2026
@boshu2
docs(contract): validate where a mistake is costly; close pre-release…
62834b1 
… gaps (#1189)

Follows #1188, now merged; main was merged into this branch, so the diff
is only this PR's changes.

## What changes

The contract required a fresh author-distinct validation on every
change, a PASS with nothing unchecked, and a re-validation after each
repair. A reviewer asked to find problems always finds one, so that
combination could not converge. In practice review cost exceeded the
cost of the work.

The contract and the skills that drive review now say:

- **Default:** for an ordinary change the author's checks and CI are the
gate. No fresh review is owed.
- **One fresh read only when:** the caller asks; a mistake cannot be
cheaply undone after it lands (a published release or instructions users
will follow, a security boundary, destroying data or tracker state,
deleting a check that protects the product); or no deterministic check
covers the changed behavior.
- **One round:** the reviewer gets the exact subject and one question,
and does not re-run checks.
- **Defects only:** what fails accepted behavior or would mislead a
user, break install or the CLI, or remove protection for the product.
Everything else is an optional note.
- **No re-review:** a repair is confirmed by a check and does not start
another review. `NOT_PROVEN` is reported with its gaps instead of being
chased.
- **Cost:** review stays a fraction of the cost of the work.

A requested binding verdict keeps its existing PASS rule.

## Where

- `AGENTS.md` (still within its 250-line budget, at 249).
- Skills: `rpi`, `validate`, `implement`, `orchestrate`, `craft-goal`,
`navigate`, and one example in `reverse-engineer`. `craft-goal` and
`navigate` no longer give every bead its own validation.
- References: `rpi/references/boundaries.md`, `outer-goal.md`,
`bounded-adapter.md` (now says not to select it for ordinary work), and
two `domain` standards pages.
- Docs: `docs/agent-workflow-reference.md`,
`docs/architecture/rpi-traversal.md`, CHANGELOG.
- Two wording pins moved to the new rule:
`tests/scripts/agents-operating-contract.bats` and
`skills/rpi/scripts/validate.sh`. One now fails if "a repair does not
start another review" disappears.

## Not changed

- Council keeps its caller-set round limit and deadline; it is
caller-selected and already bounded.
- `skills/rpi/scripts/run_once.py`, the fixed-dispatch adapter with
repeated review rounds, is untouched code. Deleting it belongs to the
cleanup that follows.
- README and other docs still describe the product as independently
validated change. That wording is not touched here.

## Gap fixes (second commit)

Found while checking release readiness; fixed here so the release has
one clean pass.

- **Docs:** `PRODUCT.md`, the docs index, how-it-works, architecture,
philosophy, first-value path, migration, CI and scale pages now match
the skills: checks and CI, plus one fresh read where a mistake is
costly.
- **Removed the fixed-dispatch RPI adapter** (`run_once.py`, its tests,
reference page and `rpi.feature`) that modelled repeated review rounds,
and `tests/e2e/rpi-phased-domain.sh`, a no-op tombstone kept only so
that feature file's scenario link resolved. The conformance script keeps
its Validate substrate probe.
- **That probe was blind to in-process calls:** a Git call from the
Validate helper reached the real binary unnoticed. It now intercepts
them; shown by mutation.
- **Skill Builder:** `heal.sh --check` exits 2 when `ao` cannot run
instead of reporting a pass. A new test fails without the fix.
- **Codex policy check:** rejects the `agents/openai.yaml` shapes Codex
silently drops (non-object `interface`, `dependencies` without a `tools`
list, a boolean spelled other than `true`/`false`). Any of them made an
explicit-only skill implicitly selectable.
- **Converter:** the Codex target no longer writes `prompt.md`.

Checks at `2ae5bbb45`: `ao gate check --full` 66 of 66, bats 1,388 pass,
`tests/skills/run-all.sh` pass, `regen-all.sh --check` current, doc
release gate pass, Skill Builder integration tests 9 of 9.

## Checks

`ao gate check --full` 66 of 66, bats 1,388 pass,
`tests/skills/run-all.sh` pass, `regen-all.sh --check` current, doc
release gate pass. No review round, per the rule this PR introduces: it
changes instructions, not a release or a security boundary, and CI
covers the rest.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ci cli docs skills tests

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@boshu2