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/plan.mjs

View on GitHub
// Plan schema 2: structure, roles, file scopes, and waves. Runs nothing.
import fs from 'node:fs';
import path from 'node:path';
import { CrackError } from './io.mjs';

export const STATES = new Set(['planned', 'ready', 'running', 'review', 'changes_requested', 'escalated', 'accepted', 'blocked']);
export const RUNGS = new Set(['primary', 'fallback', 'orchestrator']);
const PLACEHOLDER = /\b(TBD|TODO|REPLACE_ME)\b|<[^>]+>/;
const ID = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;

function planError(message) {
  return new CrackError('plan_invalid', message, 'Fix the plan, then validate it again.');
}

function text(value, label) {
  if (typeof value !== 'string' || !value.trim()) throw planError(`${label} must be a nonempty string.`);
  if (PLACEHOLDER.test(value)) throw planError(`${label} still contains a template placeholder.`);
  return value;
}

export function normalizePath(value, label) {
  const raw = text(value, label);
  const parts = raw.split('/').filter((part) => part && part !== '.');
  if (raw.startsWith('/') || !parts.length || parts.some((part) => part === '..' || part === '.git')) {
    throw planError(`${label} must be a repository-relative path without '..' or '.git'.`);
  }
  if (/[*?[\]\\:\n\r]/.test(raw)) throw planError(`${label} must be a literal path, not a glob.`);
  return parts.join('/');
}

function documentRef(value, label, root) {
  const relative = normalizePath(value, label);
  const failure = planError(`${label} must reference an existing document inside the repo root.`);
  let real;
  try {
    real = fs.realpathSync(path.join(root, relative));
  } catch {
    throw failure;
  }
  const inside = path.relative(fs.realpathSync(root), real);
  if (inside.startsWith('..') || path.isAbsolute(inside) || !fs.statSync(real).isFile()) throw failure;
}

function objects(value, label) {
  if (!Array.isArray(value) || !value.length || !value.every((item) => item !== null && typeof item === 'object' && !Array.isArray(item))) {
    throw planError(`${label} must be a nonempty list of objects.`);
  }
  return value;
}

function checks(value, label) {
  objects(value, label).forEach((item, index) => {
    text(item.command, `${label}[${index}].command`);
    text(item.expected, `${label}[${index}].expected`);
  });
}

function graph(items, label) {
  const indexed = new Map();
  for (const item of items) {
    const name = text(item.id, `${label}.id`);
    if (!ID.test(name) || indexed.has(name)) throw planError(`Invalid or duplicate ${label} ID: ${name}`);
    indexed.set(name, item);
  }
  for (const [name, item] of indexed) {
    const deps = item.depends_on;
    if (!Array.isArray(deps) || !deps.every((dep) => typeof dep === 'string')) throw planError(`${label} ${name} needs a depends_on list.`);
    if (new Set(deps).size !== deps.length || deps.some((dep) => !indexed.has(dep) || dep === name)) {
      throw planError(`${label} ${name} has duplicate, missing, or self dependencies.`);
    }
  }
  const done = new Set();
  const active = new Set();
  const visit = (name) => {
    if (active.has(name)) throw planError(`Dependency cycle in ${label}: ${name}`);
    if (done.has(name)) return;
    active.add(name);
    for (const dep of indexed.get(name).depends_on) visit(dep);
    active.delete(name);
    done.add(name);
  };
  for (const name of indexed.keys()) visit(name);
  return indexed;
}

export function pathsOverlap(a, b) {
  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
}

export function rolesForPlan(doc) {
  if (doc?.roles === null || typeof doc?.roles !== 'object' || Array.isArray(doc.roles)) {
    throw new CrackError('invalid_roles', 'crack.toml has no [roles] tables.', 'Run $codex-on-crack:crack-setup.');
  }
  return new Map(Object.entries(doc.roles).map(([name, role]) => [name, { writes: role?.writes === true }]));
}

function ancestorsOf(phases, name, seen = new Set()) {
  for (const dep of phases.get(name).depends_on) {
    if (!seen.has(dep)) {
      seen.add(dep);
      ancestorsOf(phases, dep, seen);
    }
  }
  return seen;
}

// Waves: dependency levels (task dependencies plus every task in a prerequisite
// phase), each split into sub-waves so that concurrent writers never share a
// path and never exceed the writer cap. Readers ride in a level's first sub-wave.
function computeWaves(tasks, phases, info, capacity) {
  const prerequisites = new Map([...tasks.values()].map((task) => {
    const earlier = ancestorsOf(phases, task.phase);
    const fromPhases = [...tasks.values()].filter((other) => earlier.has(other.phase)).map((other) => other.id);
    return [task.id, new Set([...task.depends_on, ...fromPhases])];
  }));
  const levels = new Map();
  const levelOf = (id) => {
    if (!levels.has(id)) {
      const deps = [...prerequisites.get(id)];
      levels.set(id, deps.length ? 1 + Math.max(...deps.map(levelOf)) : 0);
    }
    return levels.get(id);
  };
  const byLevel = [];
  for (const id of tasks.keys()) (byLevel[levelOf(id)] ??= []).push(id);
  const waves = [];
  for (const ids of byLevel) {
    if (!ids) continue;
    const readers = ids.filter((id) => !info.get(id).writes);
    const groups = [];
    for (const id of ids.filter((candidate) => info.get(candidate).writes)) {
      const fits = groups.find((group) => group.length < capacity && group.every((other) => !info.get(id).scope
        .some((a) => info.get(other).scope.some((b) => pathsOverlap(a, b)))));
      if (fits) fits.push(id);
      else groups.push([id]);
    }
    if (!groups.length) groups.push([]);
    groups.forEach((group, index) => {
      waves.push({
        wave: waves.length + 1,
        tasks: index === 0 ? [...readers, ...group] : group,
        writers: group,
        worktrees: group.length > 1,
      });
    });
  }
  return waves;
}

export function validatePlan(plan, root, roles) {
  if (plan === null || typeof plan !== 'object' || plan.schema_version !== 2) throw planError('Expected schema_version 2.');
  text(plan.project, 'project');
  documentRef(plan.spec, 'spec', root);
  const capacity = plan.max_parallel_writers ?? 1;
  if (!Number.isInteger(capacity) || capacity < 1 || capacity > 8) {
    throw planError('max_parallel_writers must be an integer from 1 to 8.');
  }
  const phases = graph(objects(plan.phases, 'phases'), 'phase');
  const tasks = graph(objects(plan.tasks, 'tasks'), 'task');
  for (const phase of phases.values()) {
    text(phase.goal, 'phase.goal');
    checks(phase.integration_checks, 'phase.integration_checks');
  }
  const info = new Map();
  for (const task of tasks.values()) {
    const id = task.id;
    if (!phases.has(task.phase)) throw planError(`Task ${id} refers to a missing phase.`);
    const role = text(task.role, `Task ${id} role`);
    const writes = role === 'orchestrator' ? true : roles.get(role)?.writes;
    if (writes === undefined) {
      throw new CrackError('plan_invalid',
        `Task ${id} role "${role}" is not in crack.toml (and is not "orchestrator").`,
        roles.size
          ? 'Fix the role name or crack.toml, then validate again.'
          : 'No roles are configured. Keep this task with role "orchestrator" for direct work, or run $codex-on-crack:crack-setup to configure a delegated role.');
    }
    if (task.risk !== 'normal' && task.risk !== 'sensitive') throw planError(`Task ${id} needs risk normal or sensitive.`);
    if (task.risk === 'sensitive' && role !== 'orchestrator') {
      throw planError(`Sensitive task ${id} must stay with the orchestrator; split safe supporting work into another task.`);
    }
    if (!STATES.has(task.state)) throw planError(`Task ${id} has an invalid state.`);
    if (!RUNGS.has(task.rung ?? 'primary')) throw planError(`Task ${id} rung must be primary, fallback, or orchestrator.`);
    const cycles = task.review_cycles ?? 0;
    if (!Number.isInteger(cycles) || cycles < 0) throw planError(`Task ${id} review_cycles must be a non-negative integer.`);
    documentRef(task.brief, `Task ${id} brief`, root);
    const listed = task.allowed_paths ?? [];
    if (!Array.isArray(listed)) throw planError(`Task ${id} allowed_paths must be a list.`);
    const scope = listed.map((entry) => normalizePath(entry, `Task ${id} allowed path`));
    if (writes && !scope.length) throw planError(`Task ${id} writes, so it needs allowed_paths.`);
    if (!writes && scope.length) throw planError(`Task ${id} uses read-only role "${role}" but lists allowed_paths.`);
    if (!Array.isArray(task.acceptance) || !task.acceptance.length) throw planError(`Task ${id} requires acceptance criteria.`);
    task.acceptance.forEach((criterion) => text(criterion, `Task ${id} acceptance`));
    checks(task.checks, `Task ${id} checks`);
    info.set(id, { writes, scope });
  }
  for (const task of tasks.values()) {
    for (const dep of task.depends_on) {
      const depPhase = tasks.get(dep).phase;
      if (depPhase !== task.phase && !ancestorsOf(phases, task.phase).has(depPhase)) {
        throw planError(`Task ${task.id} depends on a task in a phase that is not declared as its prerequisite.`);
      }
    }
  }
  return {
    status: 'structure-valid',
    phases: phases.size,
    tasks: tasks.size,
    max_parallel_writers: capacity,
    waves: computeWaves(tasks, phases, info, capacity),
    note: 'No commands were run. Readiness, workspaces, permissions, semantic correctness, and acceptance are not verified.',
  };
}
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