AgentOps' 55-skill catalog contained overlapping entry points, stale
routes and descriptions that could lose meaningful guidance in the Codex
projection. This change consolidates 21 roots into existing owners,
leaving 34 distinct skills and a generated, task-oriented menu. README
documents every retired name and its replacement.
Planning now establishes observable behavior in the caller's existing
intent, using proportional Given/When/Then examples and domain language.
Implementation and final validation carry those same examples forward.
Original adaptations informed by Matt Pocock's engineering skills
strengthen existing owners rather than adding a new workflow. Routine
edits need no mandatory plan, coverage report, mutation exercise or
learning artifact.
Codex retains complete source descriptions and translates explicit-only
invocation policy. All descriptions fit the existing 180-character
limit; the root instructions retain their 250-line limit. Generated
catalogs, projections, routers, moved references/helpers and their live
consumers are updated together. RPI remains explicitly selected.
Validation passed: projection/conformance checks, the local aggregate
(10 passed; one existing optional-directory skip), and exact-commit CI
covering the complete gate registry, Bats, Go build/vet/race/coverage,
Windows and security. A fresh author-distinct reviewer passed all
acceptance criteria over the complete 573-path subject at
aa642a55d6, including the installed-link
and protected-backup changes. Review findings were repaired and
revalidated. Existing ranker goldens are regression checks, not
model-quality measurements. A fixed six-case fresh-context pilot
supplied an exact candidate menu: three of four targeted cases loaded
expected guidance, a simple refactor selected no skill, and both
no-skill controls selected none. No wrong owner was selected. This pilot
preceded final wording repairs for existing ranker/context limits; it
does not establish installed automatic activation, coding benefit or
savings. No live coding task was run in that pilot.
## Legible membrane, Train 2: what a stranger meets
Provenance: the 2026-09-02 field audit of this repo against
mattpocock/skills, compound-engineering, and the jsm corpus, findings F5
through F9. This train is sized by a consumer inventory built with `rg`
on the tip before any lane was written; the promoted-set directory move
the audit proposed is deferred because that inventory shows
skill-builder backing two blocking gates, swarm pinned by the cathedral
gate and a routing golden, using-gc required by Go code, and `ao skills
link` unable to install a second root. That inventory is the plan for a
later train.
**What changes.**
- **Archival sweep by consumer disposition.** 172 audit snapshots, 29
pawl receipts, the `evals/workbench` and `evals/membrane` trees with
their two bats consumers, four stray scratch docs, four retired eval
contracts, and nine caller-less `scripts/check-*.sh` are deleted; git
history is the archive. Every machine list that referenced them is
pruned (evidence-grounding baseline, preamble grandfather, broken-links
allowlist, `.gitattributes`, `.gitignore`, two eval fixtures, the
workflow-coverage deferred list). `docs/audits/manifests/` and
`.agents/ao/config.yaml` survive because they have live readers. About
48,000 lines.
- **Three skills retired.** `goals` (alias of fitness), `shared`
(tombstone), and `scope` (folded into plan step 3 as five write-scope
checks). Consumers edited; the probe denominator exclusion for goals
pruned; Codex package and golden count pins updated.
- **Negative routing** on research, codebase-recon, reverse-engineer,
premortem, one-way-door, and council, all within the 180-char budget,
with a teardown golden (`rq-08`). One wording was changed after the
router's prefix stemming showed "repository teardown" leaking into the
wrong skill.
- **Every promoted skill answers "It's working if"** with observable
tells in backticks, and carries a paste-ready `## Prompt` with a
concrete subject. Two fictional `ao` subcommands a draft prompt named
were caught by the body-ref validator and replaced with real commands.
- **Doctrine diet on the core five.** rpi, plan, implement, validate,
and anti-ceremony drop from about 5,100 words to 3,600 (bodies from
4,700 to 3,150) by moving the shared ownership boundary, dated
incidents, and mechanics tables into step-loaded references
(`skills/rpi/references/boundaries.md`,
`skills/validate/references/mechanics.md`,
`skills/plan/references/ground-truth-routing.md`). Every cathedral
canary and every skill validator grep survives unchanged.
- **ADR-0018** records the goals, shared, and scope retirement; the
cathedral gate tombstone and the routing goldens cite it instead of
ADR-0017.
- **Router and twins.** `ao skills find` holds a description's "Not for
X; that is <sibling>." sentence out of its haystack, so premortem no
longer ranks first for "is this live decision reversible" (golden
`rq-10` pins the reciprocal of `rq-02`); a penalty variant was tried and
reverted because it suppressed skills the caller named outright. A
declared trigger phrase of two or more words quoted whole in the query
now earns the name weight once, so "check this change" lands on validate
rather than on reality-check's name token; a live-catalog test pins
seven such queries. Single-quoted YAML descriptions unescape `''`. The
Codex catalog keeps the exclusion sentence, and a closing `>` no longer
turns `<run-id>/codebase-recon.json` into an invocation.
- **Residue the judges found.** handoff, learn, and status open a `##
Contract` heading after their tells; validate's prompt names its helper
at `skills/validate/scripts/validate.py`; the explicit-skill prompt
catalog names only live skills (five stale prompts replaced by nine,
floor 20 restored, TESTING.md names the suite); the corpus-delta receipt
binds the runner's path and SHA-256 and labels a `live_agent` claim as
an unverified caller declaration; the probe README and ledger describe
the 12-skill denominator; SKILL-API counts 30 of 54.
**Evidence on the tip.** Regen check clean; full gate green with a
HEAD-built binary; CI's bats command green; Go build/vet/test green;
lint clean; security gate quick PASS; docs-build warnings did not rise.
Fresh validation by Fable 5.1 (caller-elected) and a cross-family read
by Codex, both recorded in the PR thread.
---------
Co-authored-by: Bo <bofuller55@gmail.com>
## Legible membrane, Train 1: fix what ships
Intent source: `docs/plans/2026-09-02-legible-membrane-plan.md` (added
in this PR). Provenance: the 2026-09-02 field audit of this repo against
mattpocock/skills, compound-engineering, and the jsm corpus.
Three defects a stranger hits today, all verified on `main` before the
change:
1. **Codex projection truncated 51 of 56 skill descriptions mid-clause**
(`scripts/codex-sync.sh` capped prose at 44 chars, so the Codex router
read "Freshly judge whether a finished change is Triggers: …"). Now:
first sentence of the source prose plus the full `Triggers:` clause,
abbreviation- and quote-aware; the per-catalog bound is computed live as
"Codex prose average may not exceed Claude's" (cross-multiplied,
floor-free) with a 180-char hard ceiling. `using-flywheel` is exempted
from runtime-phrase rewriting so its cross-runtime text projects
verbatim. The dormant `ao codex ensure-start` emitter and the `# /x`→`#
$x` title rewrite are removed. A literal oracle pins five twins and a
rule oracle covers all 56.
2. **23 shebang-bearing shell entry points were committed
non-executable**, including `scripts/regen-all.sh` and three gate
scripts. Now `100755`, with an advisory gate `shell.exec-bits`
(fast+full, fail-closed on enumeration error, reads the index blob,
skips symlinks by stated policy).
3. **`tests/run-all.sh` was red on `main`**: the GOALS validator
asserted a pre-08-25 file shape, and validate's description exceeded the
180-char budget. The validator now parses only the `## Gates` block
(stops at any heading, like production), requires cited script paths to
exist, takes its path via argv, and fails closed on tokenization; four
negative fixtures. validate's description is 177 chars and gains the
reality-check negative. `AGENTS.md` quotes CI's authoritative bats and
Go commands.
README and `docs/install-day2-ops.md` replace "No other runtime is
required" with a runtime table derived by reading each skill's procedure
(HARD / OPTIONAL / conditional), covered by a bats test that grounds
every HARD row in an invocation line.
Evidence on the tip: full gate 71/71 (HEAD binary), CI's bats command
green across `tests/scripts/*.bats`, `tests/run-all.sh` green, Go
build/vet/test green, golangci-lint clean, security gate quick PASS,
`scripts/regen-all.sh --check` clean. Each lane was validated by a fresh
context; the integrated train had two cross-family (Codex) review rounds
and every finding is closed on this tip.
Out of scope (successor intent): promoted set / `skills-internal/`, the
process-artifact sweep, "It's working if" blocks, routing clusters,
doctrine diet. One pre-existing drift noted for a follow-up:
`packs/agentops-executor/agents/validator/skills/validate/SKILL.md`
carries a stale third description that no gate binds.
Executes docs/plans/2026-08-07-agentops-operations-layer-alignment.md:
AgentOps is the operations layer for agentic engineering; the federated
integration graph is the topology, the semantic work-and-proof protocol
is the contract, and RPI is the standard one-experiment traversal.
Retires the ao flywheel command family and all knowledge-flywheel
product state, tombstones the seven-move operating-loop workflow,
narrows ao init and the .agents state writers to declared destinations,
renames the core architecture page to rpi-traversal.md with a
compatibility redirect, aligns AGENTS.md, 25 skills, public and package
copy, regenerates every owned projection, and strengthens the
conformance gates with planted-negative proofs.
Both the alignment subject and the follow-up gate-bookkeeping commit
carry fresh author-distinct validation PASS verdicts with empty
not_checked scope.
Test-Removal-Reason: dead knowledge-flywheel and session-store surfaces were deleted with their tests (operations-layer alignment)
Retire the 3.x plugin curl/PowerShell installers as tombstones, delete the
plugin-cache helpers, and rewire CI/doctor/conformance onto the canonical
checkout + ao skills link path. Keep install-bd and the opt-in operator scripts.
Co-authored-by: Cursor <cursoragent@cursor.com>
Migrate SYSTEM and AGENTS-{WORKFLOW,CI,CODEX,RUNTIME} into docs owners,
retarget consumers, rewrite the split gate, and craft-densify AGENTS,
README, PRODUCT, and GOALS under the documentation authority graph.
Co-authored-by: Cursor <cursoragent@cursor.com>
Harvested FRESH against current main per the bead spec (PR predates the 07-03/07-04
churn; PR flow retired — direct-main + pawl is the landing path).
Item 1 (from 0c9b1582e): skill-builder init.sh/build.sh honor
SKILL_BUILDER_REPO_ROOT (HEAL_REPO_ROOT pattern) so the whole scaffold pipeline
— skills/, dispositions ledger, codex catalog, registry regen — points at a
scratch repo in tests; test_skill_builder.bats scaffolds into a setup_file
scratch copy + isolation test proving no bats-builder-test-* trace lands in the
real tree (14/14 green, 0 traces). append-skill-disposition.sh appends
newline-safely (regression test; 12/12 green).
Item 2 (from 30f7b4f80): regen-codex-hashes.sh keys manifest skills[] by name
— last row wins, one row per name; live run collapsed 102 rows -> 62 (the 40-dup
pathology the PR described), 0 duplicate names. regen-codex-hashes-only.bats
regression suite green. skill-builder twin resynced (codex-sync --force) +
hash bookkeeping refreshed; validate-codex-generated-{manifest,artifacts} green.
Item 3 (compile->curate merge) deliberately NOT harvested here: superseded by
the audit retire wave (l6ic.12) which lands the end state (compile+curate ->
post-mortem) in its own arc. #892 closes as superseded after this lands.
Demote compile, forge, flywheel, curate, operationalize, inject (the SKILL, not
the ao inject command) to the experimental tier (reusing the tier .21 created),
and DROP their Codex twins — the corpus/flywheel skill-surface cut.
Twin-drop mechanism: a new `excluded` catalog treatment. codex-sync.sh reads the
excluded set and skips generation (closing the .18 "missing twin regenerated"
escape hatch); validate-codex-override-coverage.sh accepts `excluded` and asserts
the twin+override dirs are truly absent (an excluded record can't mask an orphan).
Removed the two hard skills-codex/inject/* requirements from
validate-codex-rpi-contract.sh + check-hookless-cold-start.sh; pruned
forge/compile/flywheel/inject from images/codex/manifest.json CORE (else
verify.sh / ao codex health break). git rm'd the 6 twin dirs (53 files).
/forge, /compile, /flywheel still resolve (skills kept), with honest
"(experimental — kept, not primary)" notes in operating-loop move 7 / AGENTS.md /
SKILL-ROUTER. regen-check, coverage, parity-drift, cold-start, images verify.sh,
manifests all green; registry all 6 = experimental.
Highest-leverage maintenance move: editing an AMBIENT (non-spine) skill no
longer restains its Codex twin. Regeneration is now gated on the source skill's
`spine: true` frontmatter (the same signal check-spine-integrity.sh pins).
- codex-sync.sh: a non-spine skill whose twin is already complete + registered
is skipped in both --check and regen (frozen in place). A MISSING twin (new
skill) is still generated so validate-codex-override-coverage.sh stays satisfied;
`--force --only <slug>` still deliberately regenerates a frozen twin.
- regen-codex-hashes.sh: for non-spine skills the source_hash is NOT recomputed
from a changed source (frozen/authoritative); generated_hash is still recomputed
so a real twin-content change is still caught.
- validate-codex-lifecycle-guards.sh: partitioned entry/closeout/tracker
assertions into spine (hard require) vs frozen-ambient (assert-if-present), so
the guard survives the freeze and any later twin removal by .19.
NO twin deleted (count unchanged); coverage/parity-drift/lifecycle/cold-start/
manifest all green. Proven: editing account-rotation leaves its twin
byte-identical while editing spine skill `validate` still restains its twin.
age-0js4 asked codex-sync to auto-refresh existing twins' references on source
change. Scoping (the bead's required first step) + a cross-family duel found the
premise unsafe for bespoke twins: they are HAND-MAINTAINED in full — body AND
references. Categorizing every bespoke reference vs transform(source): 74
in-sync, 21 stale, but DOZENS are genuine Codex-condensed hand-rewrites (e.g.
research/references/data-flow-from-entry-points.md: 85 source lines deleted, 56
added) and 85 source refs are intentionally absent. A blanket auto-refresh would
clobber the hand-authored copies.
Resolution (codex duel: constructive->B+ manifest, adversarial cost/value->C):
for a P2 with a sibling DETECTION bead (age-odv), the proportionate call is to
CODIFY the contract, not build a ~240-file tracked/bespoke classification regime.
codex-sync correctly skips bespoke twins (incl --force); 'nothing to generate' is
correct, not a bug; refreshing a bespoke twin is a deliberate human edit;
accidental drift is the divergence gate's job (age-odv).
Documents the contract in AGENTS-CODEX.md + the codex-sync.sh header so the
confusion that spawned this bead can't recur. Doc/comment only — no logic change.
Closes age-0js4.
--check now verifies each parity twin EXACTLY matches generator output
(presence + registration + byte-identical SKILL.md + prompt.md + mirrored
references), not just presence. This is the single drift gate that lets the
content validators skip parity twins.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The remaining 6 of the original 14 ref-dropping pointers legitimately document
NON-Codex runtimes, so the "0 Claude mentions" twin rule was wrong for them
(scrubbing "Claude" would gut the content). Adds a shared exemption list,
scripts/lint/codex-cross-runtime-skills.txt, honored by the generator AND the
gates:
- codex-sync: for listed skills, apply only the slash->$ rewrite; preserve
runtime names/paths verbatim (Claude Code / ~/.claude stay accurate).
- validate-codex-runtime-sections: skip the no-Claude-mention scan for them.
- audit-codex-parity: skip CLAUDE_TOOL_NAMING for them.
Converts all 6 to self-contained (body + references now ship to Codex):
cass (parses Claude/Codex/Gemini logs), rch (Claude Code PreToolUse hook),
vibing-with-ntm (claude -p LAW-0 ban), agent-native (per-runtime paths),
cc-hooks (Claude Code hook system), agy-native (AGY/Gemini harness).
This completes age-8wm: all 14 pointer twins now self-contained. The 8 ordinary
ones convert clean (Codex-native); these 6 stay runtime-accurate via the
exemption. shellcheck clean; the 3 codex gates pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds --force to codex-sync (scoped regenerate of existing twins; refuses
unscoped to protect the curated set) and fixes two transform bugs found in
review: the slash->$ regex was corrupting markdown PATHS (../foo/ -> ..$foo/),
and only references/scripts were copied (missing fixtures/ etc., breaking body
links). Now mirrors ALL source content except SKILL.md; catalog entries are
add-only so curated reasons aren't clobbered.
Converted 8 pointer twins to self-contained (body transformed runtime-native +
full references/scripts/fixtures mirrored) so Codex users get the real content
(installs ship skills-codex/ only): agent-mail, beads-br, beads-bv,
beads-workflow, dcg, ntm, reverse-engineer, toil-mining.
The other 6 of the original 14 are NOT auto-convertible — their docs legitimately
reference Claude tools/runtime, which the repo's own gates reject in a Codex doc:
cass + rch (Claude tool-naming "the Read tool"/"Bash tool" in references, fails
audit-codex-parity); cc-hooks, vibing-with-ntm, agy-native, agent-native (claude
-p / "the Claude path" etc., fails validate-codex-runtime-sections). They need a
manual Claude-term scrub (or bespoke classification) — tracked on age-8wm.
regen-all --check GREEN; acceptance test 15/15; shellcheck -S warning clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Research (this session) established the runtime model: Codex installs ship
skills-codex/ ONLY (plugin.json "skills":"./skills-codex"; install-codex-plugin.sh
copies only skills-codex; install-codex.sh discards the source tarball). So a
pointer twin ("read skills/<name>/SKILL.md") dangles for real users — the twin
must be self-contained (AGENTS-CODEX.md).
codex-sync now generates a self-contained twin from source:
- SKILL.md = slim (name+description) frontmatter + source body transformed
runtime-native: /<known-skill> -> $<known-skill>, ~/.claude -> ~/.codex,
"Claude Code" -> "Codex".
- references/ + scripts/ copied byte-identical (lint scans only SKILL.md).
- Still missing-twin-only + idempotent; existing hand-tended twins untouched
(converting all ~75 is a separate reviewed step; the 14 ref-dropping pointer
twins tracked in age-8wm).
Acceptance test upgraded to assert self-containment: throwaway source skill WITH
a reference + transform cases -> twin carries body + reference, transforms
applied, content-divergence gate passes (15/15). shellcheck -S warning clean.
regen-all docs reconciled (pointer -> self-contained).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
scripts/codex-sync.sh authors the COMPLETE Codex twin for any source skill that
lacks one: a slim (name+description) frontmatter + a fixed pointer body naming
skills/<name>/SKILL.md as the source of truth, the prompt.md pointer template,
the per-skill marker, and all catalog surfaces, then fixes hashes. Because a
parity twin carries no source content beyond name+description, source body edits
never require a twin hand-edit — the divergence/parity/manifest/hash cascade that
made adding a skill cost ~5 serial codex-gate fixes is gone.
- Idempotent + append-only (no catalog re-sort → minimal diffs).
- bespoke twins are the opt-out: never generated or overwritten.
- Wired into regen-all.sh (generate step + --check drift step); stale
"twins are MANUAL" note replaced.
- tests/scripts/test-codex-sync-generator.sh: self-cleaning L2 acceptance —
throwaway source skill → generate → lint-clean, registered twin, gates pass,
zero hand-edits (10/10).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Bo