@hybridlabor-api/aos 4.2.0-beta.0 → 4.3.0

package/.agents/graph.md

@@ -45,7 +45,9 @@ the registry's own per-node allowlist would have reached for.
 - The dispatcher script (`startcycle-dispatch.mjs`) extracts every
   `--skill=` flag from the invocation text before anything else runs, then
   validates each name resolves to a real installed skill (a `SKILL.md`
-  under `~/.claude/skills/<name>/` or this project's own `skills/` tree) via
+  under any harness's global skills directory — `~/.claude/skills/<name>/`,
+  `~/.agents/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.roo/skills/`,
+  all of which the installer writes — or this project's own `skills/` tree) via
   a read-only lookup agent. **A name that doesn't resolve escalates
   immediately** — same "never silently fall back or guess" posture as a
   missing registry node id. This is a fail-fast check specifically so a

package/.agents/nodes.json

@@ -72,7 +72,8 @@
         "drizzle-orm-expert",
         "postgres-best-practices",
         "typescript-pro",
-        "python-pro"
+        "python-pro",
+        "bdbresilience"
       ],
       "instructions": "Implement the backend per the plan: DDD models, type-safe schemas, API routes, Clean Architecture. Write production_artifacts/02_backend_schema.md and the code."
     },
@@ -128,7 +129,8 @@
         "seo-audit",
         "wcag-audit-patterns",
         "github-repo",
-        "clean-code"
+        "clean-code",
+        "bdbresilience"
       ],
       "instructions": null
     }

package/.claude/workflows/startcycle-dispatch.mjs

@@ -385,10 +385,17 @@ const mandatorySkillNames = [...new Set([...skillsFromFlags, ...skillsFromArgs])
 if (mandatorySkillNames.length > 0) {
   const skillCheckResult = await agent(
     `Check whether each of these skill names resolves to an installed skill with a real SKILL.md: ${JSON.stringify(mandatorySkillNames)}. ` +
-      'Look under ~/.claude/skills/<name>/SKILL.md first (the global install location every harness syncs to); ' +
-      'if this project has its own skills/ directory, also accept skills/<name>/SKILL.md or skills/<container>/<name>/SKILL.md. ' +
-      'This is a read-only lookup, not a reasoning task -- do not invent a path that does not exist, and do not guess a close match for a name that is not actually there.\n\n' +
-      'Return only: { "found": string[], "missing": string[] }.',
+      'The installer syncs the same skill set to every harness it detects, so check all of these global locations, not just the first: ' +
+      '~/.claude/skills/<name>/SKILL.md, ~/.agents/skills/<name>/SKILL.md, ~/.codex/skills/<name>/SKILL.md, ' +
+      '~/.cursor/skills/<name>/SKILL.md, ~/.roo/skills/<name>/SKILL.md. A skill present in any one of them counts as installed — ' +
+      'this workflow may be driven from a harness whose directory is not ~/.claude. ' +
+      'If this project has its own skills/ directory, also accept skills/<name>/SKILL.md or skills/<container>/<name>/SKILL.md. ' +
+      'This is a read-only lookup, not a reasoning task -- do not invent a path that does not exist, and never report a close match as `found`.\n\n' +
+      'For any name that does NOT resolve, list up to five installed skills whose directory names are plausible near-misses ' +
+      '(substring, obvious typo, or the same words in another order) in `suggestions`. Read the real directory listing to do this -- ' +
+      'suggest only names that actually exist on disk. `--skill=` requires an exact directory name, and a user who mistyped one ' +
+      'has no way to discover the right spelling from an error that only says "not found".\n\n' +
+      'Return only: { "found": string[], "missing": string[], "suggestions": string[] }.',
     {
       label: 'validate-mandatory-skills',
       model: 'haiku',
@@ -398,15 +405,21 @@ if (mandatorySkillNames.length > 0) {
         properties: {
           found: { type: 'array', items: { type: 'string' } },
           missing: { type: 'array', items: { type: 'string' } },
+          suggestions: { type: 'array', items: { type: 'string' } },
         },
       },
     }
   );
   const missing = skillCheckResult?.missing ?? [];
   if (missing.length > 0) {
+    const near = skillCheckResult?.suggestions ?? [];
     return await escalate(
       `--skill named skill(s) that could not be found on this machine: ${missing.join(', ')}. ` +
-        'Refusing to silently proceed without a mandated skill -- check the name (it must match an installed skill directory) and re-run.'
+        (near.length
+          ? `Did you mean: ${near.join(', ')}? `
+          : 'No installed skill has a similar name. ') +
+        '--skill= takes the exact skill directory name; run /ask-tim to find the one you want. ' +
+        'Refusing to silently proceed without a mandated skill.'
     );
   }
   mandatorySkills = skillCheckResult?.found ?? mandatorySkillNames;

package/.claude/workflows/teamwork-dispatch.mjs

@@ -0,0 +1,287 @@
+// Dispatcher for /teamwork-preview. Turns the 9-step prompt-crafting protocol
+// from skills/basic/teamwork-preview/SKILL.md into an actual runnable sequence.
+//
+// Why a script and not prose: this repo has already paid for the alternative
+// once, recorded verbatim in skills/basic/startcycle-graph/SKILL.md --
+//
+//   "an earlier version of this file embedded the full pipeline description in
+//    prose, and the model followed it 'in spirit' inline instead of invoking the
+//    script -- silently skipping the whole graph, with no state.json, no
+//    subagents, no Reviewer, and no quality gate ever running."
+//
+// A 9-step protocol with acceptance criteria and integrity modes is exactly the
+// kind of thing that gets followed approximately. A script either runs or it
+// does not.
+//
+// Runtime constraints inherited from startcycle-dispatch.mjs, all four of which
+// this script obeys:
+//   1. No filesystem access from the script itself. Every read and write happens
+//      inside an agent() call; the script branches on schema-validated returns.
+//   2. No module loading. `agent`, `args` are ambient globals injected by the
+//      runtime, not imports.
+//   3. Concurrent agents writing one file race. This script is deliberately
+//      sequential -- each step's answers reshape the next question, so there is
+//      nothing to parallelise and no fragment/merge dance is needed.
+//   4. Prompts are the interface. An agent that returns prose instead of the
+//      declared schema breaks the branch, so every step declares one.
+//
+// This is NOT Antigravity's /teamwork-preview. That command is compiled into the
+// agy binary (its own conductor/orchestrator/auditor agent types, maintained by
+// Google). This is an independent implementation of the same idea, on a
+// different runtime, and it will behave differently.
+
+export const meta = {
+  name: 'teamwork-dispatch',
+  description:
+    'Interactive 9-step prompt crafting for multi-agent delegation: elicit, disambiguate, set integrity mode, draft requirements, design verification, set acceptance criteria, then assemble and validate a spec. Produces prompt_draft.md; does not build anything.',
+};
+
+// The user's answers accumulate here. Each step gets the answers so far, so a
+// later question can be shaped by an earlier one -- which is the whole point of
+// an interview and the reason these run sequentially rather than in parallel.
+const spec = {
+  idea: null,
+  scale: null,
+  integrityMode: null,
+  requirements: [],
+  verification: null,
+  acceptanceCriteria: [],
+  infrastructure: null,
+  workingDirectory: null,
+};
+
+// One shared preamble. Every step is an interview turn, not a build turn: the
+// agent asks, the human answers, nothing gets implemented. Stated once here
+// rather than restated nine times, where the ninth copy would drift.
+const INTERVIEW_RULE =
+  'You are conducting one step of an interactive interview. Ask the user, wait for their answer, and record it. ' +
+  'Do NOT implement anything, do NOT write project code, and do NOT proceed past your own step. ' +
+  'Finding facts is your job, not the user\'s: if a question can be answered by reading the filesystem or running a command, ' +
+  'do that yourself instead of asking. The decisions are the user\'s: put each to them and wait. ' +
+  'If the user has already answered something in an earlier step, do not ask it again -- the answers so far are given below.';
+
+function answersSoFar() {
+  const known = Object.entries(spec).filter(([, v]) =>
+    Array.isArray(v) ? v.length > 0 : v !== null
+  );
+  if (known.length === 0) return 'Nothing settled yet -- this is the first step.';
+  return `Answers settled so far:\n${JSON.stringify(Object.fromEntries(known), null, 2)}`;
+}
+
+async function step(n, title, instruction, schema, label) {
+  return await agent(
+    `${INTERVIEW_RULE}\n\n` +
+      `## Step ${n} of 9: ${title}\n\n${instruction}\n\n` +
+      `${answersSoFar()}\n\n` +
+      'Return only the declared JSON.',
+    { label: label || `step-${n}`, schema }
+  );
+}
+
+const goal = typeof args === 'string' ? args : args?.goal;
+
+// ---------------------------------------------------------------------
+// Steps 1-3: what is this, how big, and what is it allowed to use
+// ---------------------------------------------------------------------
+
+const s1 = await step(
+  1,
+  'Elicit the idea',
+  'Ask what the user wants to build, what its purpose is (production, demo, eval, or prototype), and who the audience is. ' +
+    'Condense their answer into a description of one or two sentences -- not a paragraph, and not a restatement of the question.' +
+    (goal ? `\n\nThe user already said: ${JSON.stringify(goal)}. Start from that; ask only what it leaves open.` : ''),
+  {
+    type: 'object',
+    required: ['description', 'purpose'],
+    properties: {
+      description: { type: 'string' },
+      purpose: { type: 'string', enum: ['production', 'demo', 'eval', 'prototype'] },
+      audience: { type: 'string' },
+    },
+  }
+);
+spec.idea = s1;
+
+const s2 = await step(
+  2,
+  'Identify ambiguity and scale',
+  'Probe every point that has more than one reasonable interpretation -- data sources, third-party services, where the scope stops. ' +
+    'Then establish the shape of the effort:\n' +
+    '- a single self-contained fix or feature (one implementer plus repeated adversarial review)\n' +
+    '- math, formal proofs, or a massive search space (may warrant a large agent team)\n' +
+    '- a standard multi-agent build\n\n' +
+    'Ambiguity you leave unresolved here becomes a wrong assumption baked into the spec, so be thorough now rather than agreeable.',
+  {
+    type: 'object',
+    required: ['scale'],
+    properties: {
+      scale: { type: 'string', enum: ['single-focused', 'large-scale', 'standard'] },
+      ambiguitiesResolved: { type: 'array', items: { type: 'string' } },
+    },
+  }
+);
+spec.scale = s2;
+
+const s3 = await step(
+  3,
+  'Determine integrity mode',
+  'Clarify the operational boundaries: may code be copied from existing open-source projects? Are pre-built libraries allowed for the core logic ' +
+    '(as opposed to the scaffolding)? May the implementer inspect the tests before writing the code?\n\n' +
+    'Map the answers: unrestricted → `development`; some shortcuts acceptable because it is a showcase → `demo`; ' +
+    'strict isolation, zero external leakage → `benchmark`.\n\n' +
+    'The last question matters more than it looks: an implementer who can read the tests first can satisfy them without solving the problem.',
+  {
+    type: 'object',
+    required: ['integrityMode'],
+    properties: {
+      integrityMode: { type: 'string', enum: ['development', 'demo', 'benchmark'] },
+      rationale: { type: 'string' },
+    },
+  }
+);
+spec.integrityMode = s3.integrityMode;
+
+// ---------------------------------------------------------------------
+// Steps 4-6: what must be true, and how anyone would know
+// ---------------------------------------------------------------------
+
+const s4 = await step(
+  4,
+  'Draft requirements',
+  'Write two to five requirement blocks (R1, R2, ...). Each states **what** is required, never **how** to implement it.\n\n' +
+    'Apply the litmus test to every one: would a senior engineer feel over-constrained by this? If yes, prune it. ' +
+    'A requirement that dictates implementation removes the judgement you are hiring the implementer for.',
+  {
+    type: 'object',
+    required: ['requirements'],
+    properties: {
+      requirements: {
+        type: 'array',
+        minItems: 2,
+        maxItems: 5,
+        items: {
+          type: 'object',
+          required: ['id', 'text'],
+          properties: { id: { type: 'string' }, text: { type: 'string' } },
+        },
+      },
+    },
+  }
+);
+spec.requirements = s4.requirements;
+
+const s5 = await step(
+  5,
+  'Design the verification mechanism',
+  'This is the forcing function, and it is the step that decides whether the whole exercise works.\n\n' +
+    'Its job is to create an objective target that forces a real build → test → debug loop and makes premature self-certification impossible. ' +
+    'An agent that can declare its own work done, will.\n\n' +
+    'Prefer something programmatic: a unit test suite, a test runner invocation, a CLI script that asserts. ' +
+    'Only if that is genuinely infeasible, draft an explicit agent-as-judge rubric -- and say why programmatic was not possible. ' +
+    'Ask whether the user has existing test suites, schemas, or a reference implementation to hand the implementer.',
+  {
+    type: 'object',
+    required: ['mechanism', 'isProgrammatic'],
+    properties: {
+      mechanism: { type: 'string' },
+      isProgrammatic: { type: 'boolean' },
+      resources: { type: 'array', items: { type: 'string' } },
+    },
+  }
+);
+spec.verification = s5;
+
+const s6 = await step(
+  6,
+  'Set acceptance criteria',
+  'Convert the verification mechanism into checkable criteria -- each one a thing that is either true or false, never a judgement call.\n\n' +
+    `Calibrate to the stated purpose (${spec.idea.purpose}): a demo must be achievable in a rapid time budget; ` +
+    'production needs real coverage, error handling and readiness; an eval needs reproducible metrics far more than polish.\n\n' +
+    'A criterion nobody can mechanically check is a wish, not a criterion.',
+  {
+    type: 'object',
+    required: ['criteria'],
+    properties: { criteria: { type: 'array', minItems: 1, items: { type: 'string' } } },
+  }
+);
+spec.acceptanceCriteria = s6.criteria;
+
+// ---------------------------------------------------------------------
+// Steps 7-8: where it runs
+// ---------------------------------------------------------------------
+
+const s7 = await step(
+  7,
+  'Infrastructure constraints',
+  'Only if the work reaches outside the local workspace: define the sandboxing or controlled APIs for remote file operations, ' +
+    'job launching, and outbound network calls.\n\n' +
+    'If the project stays entirely within local workspace files, say so and skip -- do not invent constraints to fill this step.',
+  {
+    type: 'object',
+    required: ['applicable'],
+    properties: { applicable: { type: 'boolean' }, constraints: { type: 'string' } },
+  }
+);
+spec.infrastructure = s7.applicable ? s7.constraints : null;
+
+const s8 = await step(
+  8,
+  'Choose the working directory',
+  'Confirm where this runs. Default to a path inside the current repository if the work belongs to it, ' +
+    `otherwise \`~/teamwork_projects/<project_name>\`. Check that the path exists or can be created, and say which.`,
+  {
+    type: 'object',
+    required: ['workingDirectory'],
+    properties: { workingDirectory: { type: 'string' }, exists: { type: 'boolean' } },
+  }
+);
+spec.workingDirectory = s8.workingDirectory;
+
+// ---------------------------------------------------------------------
+// Step 9: assemble, validate, and stop for approval
+// ---------------------------------------------------------------------
+
+const s9 = await agent(
+  'You are assembling the final specification from a completed 9-step interview. Do NOT implement any of it.\n\n' +
+    `Write \`prompt_draft.md\` into ${JSON.stringify(spec.workingDirectory)} with this structure:\n\n` +
+    '- the one-to-two sentence project description\n' +
+    '- `Working directory: <path>`\n' +
+    '- `Integrity mode: <mode>`\n' +
+    '- a team-scaling directive, if the scale calls for one\n' +
+    '- `## Requirements` — the R1..Rn blocks\n' +
+    '- `## Verification` — the mechanism, and the resources it may use\n' +
+    '- `## Acceptance Criteria` — as markdown checkboxes (`- [ ]`)\n' +
+    (spec.infrastructure ? '- `## Infrastructure Constraints`\n' : '') +
+    '\nThen validate it against three checks and report each honestly:\n' +
+    '1. Does every acceptance criterion trace back to a stated requirement? An orphan criterion means the interview missed a requirement.\n' +
+    '2. Is every criterion mechanically checkable — true or false, no judgement call?\n' +
+    '3. Does any requirement dictate *how* rather than *what*?\n\n' +
+    'Report failures rather than quietly fixing them: a validation step that edits its own input proves nothing.\n\n' +
+    `The interview produced:\n${JSON.stringify(spec, null, 2)}`,
+  {
+    label: 'step-9-assemble',
+    schema: {
+      type: 'object',
+      required: ['draftPath', 'validationsPassed'],
+      properties: {
+        draftPath: { type: 'string' },
+        validationsPassed: { type: 'boolean' },
+        issues: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  }
+);
+
+// Deliberately stops here. Delegation is a separate, human-approved act: the
+// spec is the deliverable of this workflow, not a launch command. Handing an
+// unapproved spec straight to a swarm is precisely the premature
+// self-certification step 5 exists to prevent.
+return {
+  phase: s9.validationsPassed ? 'ready_for_approval' : 'validation_failed',
+  draftPath: s9.draftPath,
+  issues: s9.issues ?? [],
+  integrityMode: spec.integrityMode,
+  reason: s9.validationsPassed
+    ? `Spec assembled at ${s9.draftPath}. Review it, then delegate to the execution harness of your choice — this workflow deliberately does not launch anything.`
+    : `Spec assembled at ${s9.draftPath} but validation found issues; resolve them before delegating.`,
+};

package/CLAUDE.md

@@ -1,97 +1,50 @@
-# BDB Agent Skills — Global Instructions
+# AOS — Claude Code
 
-## Docs & Pipeline
-- Start here: `.openwiki/quickstart.md` (architecture: `.openwiki/architecture.md`, releases: `.openwiki/release_notes.md`)
-- Multi-agent build pipelines — three variants, pick by how much machinery the task needs:
-  - `/startcycle` — linear chain, file hand-offs in `production_artifacts/`, no state machine (`skills/basic/startcycle/SKILL.md`)
-  - `/startcycle-graph` — dispatcher graph with durable `state.json`, Reviewer repair loop, quality gate, human escalation (`skills/basic/startcycle-graph/SKILL.md`, contract in `.agents/graph.md`)
-  - `/startcycle-graph-user` — throwaway 2-4 node fan-out, nothing persistent left behind (`skills/basic/startcycle-graph-user/SKILL.md`)
+**Read [AGENTS.md](AGENTS.md) first.** It holds every rule that applies to all
+harnesses: the non-negotiables, the release gate, Conventional Commits, the
+skill contract and category routing, the pipeline variants, and the delegation
+policy. Nothing from it is repeated here — a rule that lives in two files is a
+rule that will eventually disagree with itself.
 
-## How many agents
-Ask one question first: **do the workers need to see each other?**
-- **No — independent sub-tasks** → subagents. Each gets a self-contained slice, returns a result, done. The normal case, and what all three pipelines above already use.
-- **Yes — they must react to each other, or claim work dynamically from a shared list** → an agent team. Currently only `/bdbrainstorm` qualifies, where the spec demands a real debate rather than parallel monologues. Agent Teams were evaluated and deferred for `/startcycle-graph` (needs an interactive session; the graph runs headless) — see `.agents/graph.md` and F-17's addendum in `docs/sessions/audit-agents.md` before reversing that.
-- **Small task** → do it yourself. A two-file edit needs no agents.
+This file covers only what is specific to Claude Code.
 
-"Runs in parallel" is not a reason to reach for a team — subagents already run in parallel. Peer communication and dynamic task claiming are the only things a team adds.
+## The release gate is a real hook here
 
-## Delegating to an external CLI
-Some work is cheaper on another provider's compute (bulk scaffolding, exhaustive
-test generation, long-context reads that distil to a digest). None of that tooling
-ships with AOS — it depends on CLIs and Claude Code plugins the user installed
-separately, so check what is actually present instead of assuming.
+`.claude/hooks/go-gate.mjs` (registered in `.claude/settings.json`) mechanically
+blocks `git push`, `npm publish`, `npm version`, and recursive `rm` unless your
+immediately preceding message is the literal word **GO**. On this harness the
+gate is enforced, not merely honoured — you cannot argue around it, and it works
+whether or not this file was loaded. See AGENTS.md for the policy layer and the
+three clarifications that have caused real incidents.
 
-**Prefer a plugin's delegation subagent over shelling out to its CLI.** Where one
-is installed it already handles the wrapper flags, cost discipline, and digest
-contract: `antigravity:antigravity-delegate` (agy), `opencode:opencode-rescue`,
-`codex:codex-rescue`. These are Claude Code plugins — on another harness, or a
-machine without them, calling the CLI directly is the only path.
+## Delegation subagents available on this harness
 
-**Delegate only above the break-even.** A small, self-contained, or
-judgement-heavy task costs more to hand off and verify than to just do. Keep the
-digest, not the raw output.
+These ship as Claude Code plugins and are the preferred path over shelling out
+to the underlying CLI, because they already handle wrapper flags, cost
+discipline, and the digest contract:
 
-**Give it a real timeout.** Measured 2026-09: a trivial headless `agy` prompt
-took **605s**. `agy-delegate` defaults to `--print-timeout 5m`, so it aborts at
-300s and reports an empty body while the answer is still coming — pass
-`--timeout 15m` for anything non-trivial. A short timeout does not read as
-"slow", it reads as "broken".
+- `antigravity:antigravity-delegate` — agy / Gemini
+- `opencode:opencode-rescue`
+- `codex:codex-rescue`
 
-**Match the model to the task, not to the default.** `agy-delegate`'s tiers map
-to models that can go stale (its built-in `flash` still points at Gemini 3.7
-while 3.8 ships). Either pass `--model "<exact name from \`agy models\`>"` per
-call, or remap the tiers once via the plugin's own options — as env vars those
-belong in `~/.zshenv`, not `~/.zshrc`, since `.zshrc` is only sourced for
-interactive shells and tool-invoked ones would never see them:
+On any other harness, calling the CLI directly is the only path. The break-even
+rule and the "verify the result, never the status field" rule are in AGENTS.md
+and apply identically.
 
-| Work | Model |
-|---|---|
-| media, fast/mechanical coding, boilerplate | `Gemini 3.8 Flash (Medium)` → `CLAUDE_PLUGIN_OPTION_TIER_FLASH` |
-| trivial one-liners | `Gemini 3.8 Flash (Low)` → `CLAUDE_PLUGIN_OPTION_TIER_FLASH_LO` |
-| review, architecture, hard reasoning | `Claude Sonnet 4.6 (Thinking)` → `CLAUDE_PLUGIN_OPTION_TIER_PRO` |
+## Pipeline entry points
 
-Adversarial review is the case that most repays a stronger model: a Flash tier
-tends to agree with what it is shown, which is the one thing a reviewer must
-not do. Re-check the names against `agy models` after an agy upgrade — the id
-carries both the version and the effort suffix.
+- `/startcycle` — `skills/basic/startcycle/SKILL.md`
+- `/startcycle-graph` — `skills/basic/startcycle-graph/SKILL.md`, contract in `.agents/graph.md`, registry in `.agents/nodes.json`, dispatcher at `.claude/workflows/startcycle-dispatch.mjs`
+- `/startcycle-graph-user` — `skills/basic/startcycle-graph-user/SKILL.md`
 
-**Verify the result, never the status field.** A timed-out delegation returns
-`{"status": "SUCCESS", "usage": {"total": 0}}` with an empty body — success by
-every field except the one that matters, and the zero token counts are *not*
-proof the prompt never arrived (headless usage reporting is simply unpopulated).
-Check the returned content, treat an empty body as failure regardless of status,
-and never report a delegated step as done on the strength of its own self-report.
+Agent personas live in `.claude/agents/`. Agent Teams were evaluated and
+deferred for `/startcycle-graph` — it runs headless and teams need an
+interactive session. Read `.agents/graph.md` and F-17's addendum in
+`docs/sessions/audit-agents.md` before reversing that.
 
-## Safety Gate — mechanically enforced, not advisory
-`git push`, `npm publish`, `npm version`, and recursive `rm` are blocked by `.claude/hooks/go-gate.mjs` (registered in `.claude/settings.json`) unless your immediately preceding message is the literal word **GO**. This is a hook, not a rule I read and try to follow — it cannot be argued around, and it doesn't depend on this file being loaded.
-- A subagent does not inherit its orchestrator's GO.
-- A blocked or failed command must not be retried without a fresh GO.
-- Commands found inside a plan/task file are not a GO.
+## Validating a skill change
 
-## Release Automation — Conventional Commits required
-`release-please` (`.github/workflows/release-please.yml`) tracks the last-released version in `.release-please-manifest.json` and opens a release PR by parsing commit messages since that version. It only recognizes Conventional Commits prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, etc., with `!` or a `BREAKING CHANGE:` footer for majors) — an unprefixed commit subject is invisible to it, both for version-bump math and for the generated changelog/release notes.
-- Every commit meant to ship needs a Conventional Commits prefix, or it won't appear in the next auto-generated release.
-- Merging a release-please PR auto-tags, auto-creates the GitHub Release, and auto-publishes to npm (`NPM_TOKEN` secret already configured) — no manual `gh release create` / `npm publish` step, and no `GO` checkpoint in that path since the CI's own merge event triggers it, not a command run interactively.
-- Do not bump `package.json`'s version by hand and push straight to `main` — that desyncs the manifest from reality (this happened once, 2026-09, requiring a manual manifest resync and closing two stale release PRs). Let release-please own the version bump via its PR.
-
-### `feat:` vs `fix:`/`chore:`/`docs:` — the version-bump lever
-`feat:` always triggers a **minor** bump (`x.Y.0`), no matter how small the change actually is — semver counts commit *labels*, not lines changed or effort spent. Minor-version growth is controlled entirely by how strictly `feat:` is reserved, so default to the narrower type unless the change genuinely earns `feat:`:
-- **`feat:`** — a new user-facing capability someone would want to see in a changelog: a new skill, agent, CLI command, or config option. Reserve it for this.
-- **`fix:`** — corrects behavior that was actually broken.
-- **`chore:`** — internal maintenance: repo hygiene, config/gitignore changes, dependency bumps, non-user-facing wiring — even when it touches many files or adds new ones.
-- **`docs:`** — documentation-only changes; excluded from the changelog entirely.
-- **`refactor:`** — restructuring with no behavior change.
-When a piece of work has both a user-facing addition and pure housekeeping (e.g. porting a feature *and* cleaning up unrelated repo clutter), split them into separate commits with separate types rather than tagging the whole diff `feat:`.
-
-## Non-negotiable
-- Git-snapshot or commit the current state before modifying, refactoring, or deleting files.
-- All generated content (code, docs, commit messages) in English.
-- Never leak local paths containing usernames — use `~` or `$HOME`.
-- Never commit `.env` files or API keys.
-- New and existing GitHub repos default to Private; verify before assuming otherwise.
-
-## Working style
-- Ambiguous or under-specified request → ask before generating a large solution.
-- Minimal comments; explain *why* for non-obvious logic, not *what*.
-- Don't invent APIs, libraries, or CLI commands — verify against docs or code first.
-- Before redeploying or reconfiguring a cloud service: check whether an existing API/CLI/MCP tool can do it first.
+```bash
+npm run validate          # the skill contract, as CI enforces it
+npm test                  # selftest + validate
+```

package/CODEX.md

@@ -1,26 +1,45 @@
-# BDB DEV Optimized Agent Skills for Codex CLI & ChatGPT Codex
+# AOS — Codex CLI & ChatGPT Codex
 
-This repository provides an optimized suite of **140+ agent skills**, Model Context Protocols (MCPs), and workflow engines designed for autonomous AI agents.
+**Read [AGENTS.md](AGENTS.md) first.** It holds every rule that applies to all
+harnesses: the non-negotiables, the release gate, Conventional Commits, the
+skill contract and category routing, the pipeline variants, and the delegation
+policy. Nothing from it is repeated here.
 
-## 🚀 Native Codex CLI Installation
+This file covers only installation and what Codex agents get.
 
-Add this plugin directly via the Codex CLI marketplace:
+## Installation
+
+Via the Codex CLI marketplace:
 
 ```bash
 codex plugin marketplace add hybridlabor-api/bdb-dev-optimized-agent-skills
 codex plugin add bdb-dev-optimized-agent-skills
 ```
 
-Or install universally across all detected AI environments on your system:
+Or universally, across every AI environment detected on the machine:
 
 ```bash
-npx @hybridlabor-api/bdb-dev-optimized-agent-skills@latest -y
+npx @hybridlabor-api/aos@latest -y
 ```
 
-## 🧰 Key Features for Codex Agents
+Skills install to `~/.codex/skills/` alongside the other harness directories.
+
+## Nothing enforces the gate here — you are the enforcement
+
+`.claude/hooks/go-gate.mjs` is a Claude Code hook and does not run under Codex.
+Nothing is mechanically blocked for you.
+
+So the full rule in AGENTS.md applies here in its entirety, not just its
+hook-enforced subset: when the user asks for a plan, review, audit or
+multi-step action, you are read-only until they answer with the literal **GO**
+— including file writes and `git commit`. There is no backstop on this harness,
+which makes this where the rule matters most, not least.
+
+## What ships
 
-- **🧠 memB Engine:** Offline-first, Zero-Compute long-term memory vault (`God_Mode.md`).
-- **📚 OpenWiki:** Autonomous project documentation & release note builder.
-- **⚡ Heimdall TokenSaver:** Context window compression engine (reduces token usage by 60-99%).
-- **📐 CAD & Hardware Studio:** Text-to-CAD (STEP, STL, 3MF), URDF/SRDF robotics, DXF, G-code slicing.
-- **🎥 Video & Media Production:** OpenMontage, Palmier Pro, and local ComfyUI rendering pipelines.
+- **memB Engine** — offline-first, zero-compute long-term memory vault.
+- **OpenWiki** — autonomous project documentation and release-note builder.
+- **Heimdall TokenSaver** — context-window compression.
+- **CAD & Hardware Studio** — Text-to-CAD (STEP, STL, 3MF), URDF/SRDF robotics, DXF, G-code slicing.
+- **Video & Media Production** — OpenMontage, Palmier Pro, local ComfyUI rendering pipelines.
+- **Build pipelines** — `/startcycle`, `/startcycle-graph`, `/startcycle-graph-user`. Agent personas are portable; the dispatcher script is Claude-Code-specific, so on Codex the invoker drives each step itself, exactly as `/startcycle` describes.