Skip to content

ethanplusai/codex-on-crack / plugins/codex-on-crack/skills/crack

Lead substantial Codex builds with one configured implementation worker and lead acceptance. Use when the user requests codex-on-crack, names a model to delegate work to, asks to run subagents through Claude, or requests a lead/worker split. Keep host-only work direct; honor explicit external model choices. Workers must not invoke this orchestrator.

FileKindSize
SKILL.mdskill md8.0 KB
agents/openai.yamlconfig300 B
references/build-records.mdmarkdown2.7 KB
references/checkpoint.mdmarkdown1.3 KB
references/external-lead.mdmarkdown13.9 KB
references/measurement.mdmarkdown1.8 KB
references/model-selection.mdmarkdown2.2 KB
references/parallel.mdmarkdown1.7 KB
references/policy.mdmarkdown494 B
references/replay.mdmarkdown3.2 KB
references/verification.mdmarkdown2.1 KB
references/worker-contract.mdmarkdown1.3 KB
scripts/doctor.mjsscript608 B
scripts/lead.mjsscript26.0 KB
scripts/lib/catalog.mjsscript5.6 KB
scripts/lib/changes.mjsscript13.3 KB
scripts/lib/config.mjsscript6.5 KB
scripts/lib/external-lead.mjsscript56.7 KB
scripts/lib/io.mjsscript3.8 KB
scripts/lib/lead-protocol.mjsscript25.9 KB
scripts/lib/plan.mjsscript9.2 KB
scripts/lib/readiness.mjsscript6.0 KB
scripts/lib/report.mjsscript10.7 KB
scripts/lib/roles.mjsscript8.9 KB
scripts/lib/routing.mjsscript2.7 KB
scripts/lib/toml.mjsscript785 B
scripts/lib/trial.mjsscript12.4 KB
scripts/report.mjsscript2.7 KB
scripts/select.mjsscript3.9 KB
scripts/setup.mjsscript7.0 KB
scripts/trial.mjsscript1.8 KB
scripts/validate-plan.mjsscript2.6 KB
scripts/worktree.mjsscript7.8 KB
templates/checkpoint.mdmarkdown903 B
templates/plan.jsonconfig680 B
templates/spec.mdmarkdown742 B
templates/task-brief.mdmarkdown2.5 KB
templates/task-report.mdmarkdown1.5 KB
viewer/README.mdmarkdown5.9 KB
viewer/bridge.mjsscript16.6 KB
viewer/fixtures/sample.jsonconfig8.2 KB
viewer/package.jsonmanifest187 B
viewer/public/app.mjsscript8.8 KB
viewer/public/index.htmlother1.8 KB
viewer/public/style.cssother4.4 KB
viewer/serve.mjsscript11.2 KB
viewer/src/adapter.mjsscript9.9 KB
viewer/src/emit.mjsscript992 B
viewer/src/model.mjsscript8.9 KB
viewer/src/server.mjsscript4.1 KB
viewer/src/tail.mjsscript1.9 KB
viewer/test/browser.mjsscript2.6 KB
viewer/test/server.test.mjsscript3.2 KB
viewer/test/usage.test.mjsscript9.0 KB
viewer/test/viewer.test.mjsscript5.1 KB

scripts/setup.mjs

View on GitHub
#!/usr/bin/env node
// $codex-on-crack:crack-setup: scan the catalog, preview role files, apply with a receipt, undo.
import fs from 'node:fs';
import path from 'node:path';
import { parseArgs } from 'node:util';
import { CrackError, ok, readIfExists, readInput, realInput, run } from './lib/io.mjs';
import { checkAgentsShape, locations, readConfig, installationContext } from './lib/config.mjs';
import { describeModels, effectiveCatalog } from './lib/catalog.mjs';
import {
  DEFAULT_ROLES, agentFiles, parseCrackToml, renderCrackToml, reviewWarnings, validateRoles,
} from './lib/roles.mjs';
import {
  applyChanges, policyMigration, managedPaths, managedPolicy, planChanges, policyBlock, undoReceipt,
} from './lib/changes.mjs';
import { checkRouting } from './lib/routing.mjs';
import { parseToml } from './lib/toml.mjs';

const OPTIONS = {
  home: { type: 'string' },
  'codex-home': { type: 'string' },
  profile: { type: 'string' },
  roles: { type: 'string' },
  'model-catalog': { type: 'string' },
  'migrate-legacy': { type: 'boolean', default: false },
  policy: { type: 'boolean', default: false },
  receipt: { type: 'string' },
  apply: { type: 'boolean', default: false },
};
const USAGE = 'Usage: setup.mjs <scan|plan|apply|undo> [--roles draft.toml] [--policy] [--receipt path] [--apply] [--home dir] [--codex-home dir] [--profile name]';
const AGENT_FILE = /^crack_[a-z0-9_]+\.toml$/;

function inspect(values) {
  const where = locations({ home: values.home, codexHome: values['codex-home'] });
  const { config, inputHashes, profile, warnings } = readConfig({ ...where, ...installationContext(where.codexHome, values.profile, values['model-catalog']) });
  warnings.push(...checkAgentsShape(config));
  const catalog = effectiveCatalog({ config, ...where, ...installationContext(where.codexHome, values.profile, values['model-catalog']) });
  inputHashes[catalog.file] = catalog.hash;
  return { ...where, config, inputHashes, profile, warnings, catalog, models: describeModels(catalog.entries) };
}

function legacyRole(codexHome) {
  const file = path.join(codexHome, 'agents', 'astra_flash_builder.toml');
  const data = readIfExists(file);
  if (data === null) return null;
  try {
    const doc = parseToml(data.toString('utf8'), 'astra_flash_builder.toml');
    return { file, model: typeof doc.model === 'string' ? doc.model : null };
  } catch {
    return { file, model: null };
  }
}

function scan(values) {
  const state = inspect(values);
  const { crackToml } = managedPaths(state.codexHome);
  return ok({
    root_model: state.config.model ?? null,
    profile: state.profile,
    catalog: { source: state.catalog.source },
    eligible: state.models.filter((m) => m.eligible)
      .map(({ model, displayName, vision, contextWindow, efforts, defaultEffort }) => ({ model, displayName, vision, contextWindow, efforts, defaultEffort })),
    ineligible: state.models.filter((m) => !m.eligible)
      .map(({ model, displayName, reason, why }) => ({ model, displayName, reason, why })),
    default_roles: DEFAULT_ROLES,
    existing: {
      crack_toml: fs.existsSync(crackToml) ? crackToml : null,
      astra_flash_builder: legacyRole(state.codexHome),
    },
    warnings: state.warnings,
  });
}

function desired(state, values) {
  const paths = managedPaths(state.codexHome);
  const source = values.roles ? path.resolve(values.roles) : paths.crackToml;
  const data = values.roles ? readInput(source) : readIfExists(source);
  if (data === null) {
    throw new CrackError('roles_missing', values.roles ? `No roles draft at ${source}.` : 'No crack.toml yet.',
      'Pass --roles <draft.toml> to configure delegation, as $codex-on-crack:crack-setup does. '
      + 'Direct work and the workflow skills need no roles at all.');
  }
  const { roles, warnings } = validateRoles(parseCrackToml(data.toString('utf8'), path.basename(source)), state.models);
  warnings.push(...checkRouting({ ...state, roles }));
  const files = agentFiles({ codexHome: state.codexHome, roles });
  const requested = new Map([[paths.crackToml, renderCrackToml(roles, { profile: state.profile, catalog: state.catalog.file })]]);
  for (const { file, text } of files) requested.set(file, text);
  // Retire agent files for roles or rungs that no longer exist (ours and unedited only).
  const names = fs.existsSync(paths.agentsDir) ? fs.readdirSync(paths.agentsDir).sort() : [];
  for (const name of names) {
    const file = path.join(paths.agentsDir, name);
    if (AGENT_FILE.test(name) && !requested.has(file)) requested.set(file, null);
  }
  policyMigration(state.codexHome, requested, { policy: values.policy, migrateLegacy: values['migrate-legacy'] });
  return {
    requested,
    roles: roles.map(({ name, writes, rungs }) => ({
      name,
      writes,
      rungs: rungs.map(({ kind, agent, model, effort }) => ({ kind, agent, model, effort })),
    })),
    providers: files.map(({ rung, provider }) => ({
      agent: rung.agent,
      model: rung.model,
      provider,
      provider_source: provider ? 'router-agent' : 'inherited',
    })),
    warnings: [...state.warnings, ...warnings, ...reviewWarnings(roles)],
  };
}

const listChanges = (changes) => changes.map(({ action, path: file }) => ({ action, path: file }));

function preview(values) {
  const state = inspect(values);
  const plan = desired(state, values);
  const changes = planChanges(state.codexHome, plan.requested);
  return ok({
    changes: listChanges(changes),
    roles: plan.roles,
    providers: plan.providers,
    warnings: plan.warnings,
    note: 'Preview only. Nothing was written, and config.toml is never written.',
  });
}

function apply(values) {
  const state = inspect(values);
  const plan = desired(state, values);
  const changes = planChanges(state.codexHome, plan.requested);
  const receipt = applyChanges(state.codexHome, changes, state.inputHashes);
  return ok({
    receipt,
    changes: listChanges(changes),
    roles: plan.roles,
    providers: plan.providers,
    warnings: plan.warnings,
    next: receipt
      ? 'Fully quit and reopen Codex so it loads the new agent files. The first real task on each new model is its runtime check.'
      : 'Already up to date; nothing changed.',
  });
}

function undo(values) {
  if (!values.receipt) throw new CrackError('usage', '--receipt is required for undo.', USAGE);
  const { codexHome } = locations({ home: values.home, codexHome: values['codex-home'] });
  const result = undoReceipt(codexHome, realInput(values.receipt), { apply: values.apply });
  return ok({ ...result, note: values.apply ? 'Restored. Fully quit and reopen Codex.' : 'Preview only. Add --apply to restore.' });
}

const COMMANDS = { scan, plan: preview, apply, undo };

run((argv) => {
  let parsed;
  try {
    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
  } catch (error) {
    throw new CrackError('usage', error.message, USAGE);
  }
  const command = COMMANDS[parsed.positionals[0]];
  if (!command || parsed.positionals.length !== 1) throw new CrackError('usage', 'Unknown or missing command.', USAGE);
  return command(parsed.values);
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall