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/lib/readiness.mjs

View on GitHub
#!/usr/bin/env node
// Static readiness for codex-on-crack. Reads only; never makes a model call.
import fs from 'node:fs';
import path from 'node:path';
import { CrackError, readIfExists, sha256 } from './io.mjs';
import { checkAgentsShape, locations, readConfig, installationContext } from './config.mjs';
import { describeModels, effectiveCatalog } from './catalog.mjs';
import { agentFiles, parseCrackToml, reviewWarnings, validateRoles } from './roles.mjs';
import { isManagedPath, ledger, managedPaths, policyMigration } from './changes.mjs';

import { checkRouting } from './routing.mjs';

export function doctor(values) {
  const where = locations({ home: values.home, codexHome: values['codex-home'] });
  const { config, profile, warnings } = readConfig({ ...where, ...installationContext(where.codexHome, values.profile) });
  const paths = managedPaths(where.codexHome);
  const crackText = readIfExists(paths.crackToml)?.toString('utf8');
  const delegationConfigured = crackText !== undefined;
  const problems = [];
  const collect = (entry, blocking) => {
    if (blocking) problems.push(entry);
    else warnings.push(entry.hint ? `${entry.message} ${entry.hint}` : entry.message);
  };
  const attempt = (step, { blocking = true } = {}) => {
    try {
      return step();
    } catch (error) {
      if (!(error instanceof CrackError)) throw error;
      collect({ code: error.code, message: error.message, hint: error.hint }, blocking);
      return null;
    }
  };
  // Enabled subagents are a delegation prerequisite. Every other shape error
  // breaks Codex's config for direct work too, so it stays blocking either way.
  let shape = null;
  try {
    shape = checkAgentsShape(config);
  } catch (error) {
    if (!(error instanceof CrackError)) throw error;
    collect({ code: error.code, message: error.message, hint: error.hint },
      delegationConfigured || error.code !== 'subagents_disabled');
  }
  if (shape) warnings.push(...shape);
  // A model catalog is only needed to validate roles. Workflow-only use reads it
  // best-effort and never fails on it.
  const readCatalog = () => effectiveCatalog({ config, ...where, ...installationContext(where.codexHome, values.profile) });
  const catalog = delegationConfigured
    ? attempt(readCatalog)
    : (() => { try { return readCatalog(); } catch { return null; } })();
  if (!delegationConfigured && catalog === null) {
    warnings.push('No readable model catalog was found; that only matters when you configure a builder with $codex-on-crack:crack-setup.');
  }
  const models = catalog ? describeModels(catalog.entries) : [];
  const byModel = new Map(models.map((model) => [model.model, model]));
  let roles = [];
  if (!delegationConfigured) {
    // Workflow-only is a complete, supported state: the skills work without any
    // roles. Only a leftover generated file, which no crack.toml explains, is a
    // real inconsistency.
    const orphans = fs.existsSync(paths.agentsDir)
      ? fs.readdirSync(paths.agentsDir)
        .filter((name) => isManagedPath(where.codexHome, path.join(paths.agentsDir, name)))
        .sort()
      : [];
    if (orphans.length) {
      problems.push({
        code: 'orphaned_agent_files',
        message: `Role file(s) exist without crack.toml: ${orphans.join(', ')}.`,
        hint: 'Run $codex-on-crack:crack-setup to regenerate them, or remove them if you no longer want delegation.',
      });
    }
  } else if (catalog) {
    const validated = attempt(() => validateRoles(parseCrackToml(crackText), models));
    if (validated) {
      roles = validated.roles;
      warnings.push(...validated.warnings, ...reviewWarnings(roles));
    }
  }
  attempt(() => policyMigration(where.codexHome, new Map()));
  if (roles.length) warnings.push(...(attempt(() => checkRouting({ config, roles, models, codexHome: where.codexHome })) ?? []));
  const expected = attempt(() => ledger(where.codexHome)) ?? new Map();
  const files = attempt(() => agentFiles({ codexHome: where.codexHome, roles })) ?? [];
  const rungs = files.map(({ file, text, role, rung, provider }) => {
    const current = readIfExists(file);
    let state = 'in-sync';
    if (current === null) state = 'missing';
    else if (current.toString('utf8') !== text) state = expected.get(file) === sha256(current) ? 'stale' : 'edited';
    if (state !== 'in-sync') {
      problems.push({
        code: `agent_file_${state}`,
        message: `${path.basename(file)} is ${state}.`,
        hint: state === 'edited'
          ? 'Move your edits into crack.toml, delete the file, then run $codex-on-crack:crack-setup.'
          : 'Run $codex-on-crack:crack-setup to regenerate the agent files.',
      });
    }
    return {
      role: role.name,
      kind: rung.kind,
      agent: rung.agent,
      model: rung.model,
      effort: rung.effort,
      writes: role.writes,
      ...(role.tasks === undefined ? {} : { tasks: role.tasks }),
      vision: byModel.get(rung.model)?.vision ?? false,
      context_window: byModel.get(rung.model)?.contextWindow ?? null,
      provider,
      provider_source: provider ? 'router-agent' : 'inherited',
      file: state,
    };
  });
  if (!config.model) warnings.push('No root model is set in config; the orchestrator is whatever you pick in the model picker.');
  warnings.push('Project, CLI, UI, and managed-policy overrides are not resolved by this static check.');
  return {
    ok: problems.length === 0,
    status: problems.length ? 'not-ready' : delegationConfigured ? 'static-ready' : 'workflow-ready',
    delegation: {
      configured: delegationConfigured,
      ready: delegationConfigured && problems.length === 0,
      note: delegationConfigured
        ? 'Roles are configured. Delegation also needs the client to load the agent files in a fresh session.'
        : 'Workflow-only: no roles are configured. Run $codex-on-crack:crack-setup when you want a delegated builder.',
    },
    runtime_verified: false,
    inference_request_made: false,
    root_model: config.model ?? null,
    profile,
    catalog: catalog ? { source: catalog.source } : null,
    rungs,
    problems,
    warnings,
  };
}
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: 471kUpdated 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