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

View on GitHub
#!/usr/bin/env node
// Isolated worktrees for parallel writers: add, integrate (scope-checked), remove.
// Never commits, merges, pushes, or deletes a branch that holds unmerged commits.
import fs from 'node:fs';
import path from 'node:path';
import { execFileSync } from 'node:child_process';
import { parseArgs } from 'node:util';
import { CrackError, atomicWrite, ok, readIfExists, run, sha256 } from './lib/io.mjs';
import { normalizePath } from './lib/plan.mjs';

const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
const OPTIONS = {
  repo: { type: 'string' },
  task: { type: 'string' },
  base: { type: 'string' },
  allowed: { type: 'string', multiple: true },
  apply: { type: 'boolean', default: false },
  force: { type: 'boolean', default: false },
};
const USAGE = 'Usage: worktree.mjs <add|integrate|remove> --repo <root> --task <id> [--base <ref>] [--allowed <path>]... [--apply] [--force]';

function git(cwd, args, input) {
  try {
    return execFileSync('git', ['-C', cwd, ...args], {
      encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024,
    });
  } catch (error) {
    const detail = String(error.stderr ?? '').trim().split('\n').pop() || 'no detail';
    throw new CrackError('git_failed', `git ${args[0]} failed: ${detail}`, 'Inspect the repository state, then retry.');
  }
}

function context(values) {
  if (!values.repo || !values.task) throw new CrackError('usage', '--repo and --task are required.', USAGE);
  if (!TASK_ID.test(values.task)) throw new CrackError('usage', '--task must be a plan task id.', USAGE);
  let repo;
  try {
    repo = fs.realpathSync(values.repo);
  } catch {
    throw new CrackError('not_repo_root', `${values.repo} does not exist.`, 'Pass the repository root as --repo.');
  }
  const top = fs.realpathSync(git(repo, ['rev-parse', '--show-toplevel']).trim());
  if (top !== repo) throw new CrackError('not_repo_root', 'Pass the repository root as --repo.', `The root is ${top}.`);
  const dir = path.join(repo, '.crack', 'worktrees', values.task);
  return {
    repo,
    task: values.task,
    dir,
    branch: `crack/${values.task}`,
    baseFile: `${dir}.base`,
    integratedFile: `${dir}.integrated`,
  };
}

function excludeCrackDir(repo) {
  const common = git(repo, ['rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
  const file = path.join(common, 'info', 'exclude');
  const current = readIfExists(file)?.toString('utf8') ?? '';
  if (current.split('\n').includes('/.crack/')) return;
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.appendFileSync(file, `${current && !current.endsWith('\n') ? '\n' : ''}/.crack/\n`);
}

function readBase(c) {
  const base = readIfExists(c.baseFile)?.toString('utf8').trim();
  if (!base) throw new CrackError('worktree_missing', `The base commit record for ${c.task} is missing.`, 'Recreate the worktree.');
  return base;
}

// Every path the worker changed relative to the base, including new files.
function changedPaths(c, base) {
  const untracked = git(c.dir, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean);
  if (untracked.length) git(c.dir, ['add', '--intent-to-add', '--', ...untracked]);
  return git(c.dir, ['diff', '--name-only', '--no-renames', '-z', base]).split('\0').filter(Boolean);
}

function patchFor(c, base) {
  return git(c.dir, ['diff', '--binary', '--no-renames', base]);
}

function add(values) {
  const c = context(values);
  if (fs.existsSync(c.dir)) throw new CrackError('worktree_exists', `A worktree for ${c.task} already exists.`, 'Integrate or remove it first.');
  if (git(c.repo, ['status', '--porcelain']).trim()) {
    throw new CrackError('dirty_baseline', 'A new worktree would omit uncommitted dependency outputs or user work.',
      'Continue sequentially in the current workspace. Do not auto-commit or discard changes to bypass this guard.');
  }
  excludeCrackDir(c.repo);
  const base = git(c.repo, ['rev-parse', '--verify', `${values.base ?? 'HEAD'}^{commit}`]).trim();
  git(c.repo, ['worktree', 'add', '-b', c.branch, c.dir, base]);
  atomicWrite(c.baseFile, `${base}\n`, 0o644);
  const dirty = git(c.repo, ['status', '--porcelain']).trim() !== '';
  return ok({
    path: c.dir,
    branch: c.branch,
    base,
    warnings: dirty
      ? ['The main workspace has uncommitted changes. They are not in this worktree, which starts from the base commit; brief the worker accordingly.']
      : [],
  });
}

function integrate(values) {
  const c = context(values);
  if (!fs.existsSync(c.dir)) throw new CrackError('worktree_missing', `No worktree for ${c.task}.`, 'Add it first.');
  const allowed = (values.allowed ?? []).map((entry) => normalizePath(entry, '--allowed'));
  if (!allowed.length) throw new CrackError('usage', "--allowed is required: pass the task's allowed_paths.", USAGE);
  const base = readBase(c);
  const changed = changedPaths(c, base);
  const outside = changed.filter((file) => !allowed.some((scope) => file === scope || file.startsWith(`${scope}/`)));
  if (outside.length) {
    throw new CrackError('scope_violation', `The worktree changed paths outside the task's allowed_paths: ${outside.join(', ')}.`,
      'Send the task back for correction. Nothing was applied.');
  }
  if (!changed.length) return ok({ changed, applied: false, note: 'Nothing to integrate.' });
  const patch = patchFor(c, base);
  git(c.repo, ['apply', '--check', '--whitespace=nowarn'], patch);
  if (values.apply) {
    git(c.repo, ['apply', '--whitespace=nowarn'], patch);
    atomicWrite(c.integratedFile, `${sha256(patch)}\n`, 0o644);
  }
  return ok({
    changed,
    applied: values.apply,
    note: values.apply
      ? 'Applied to the main workspace without committing. Review it there, then remove the worktree.'
      : 'Preview only: the patch applies cleanly. Add --apply to apply it.',
  });
}

function remove(values) {
  const c = context(values);
  if (!fs.existsSync(c.dir)) throw new CrackError('worktree_missing', `No worktree for ${c.task}.`, 'Nothing to remove.');
  if (values.force) throw new CrackError('unsafe_cleanup', 'Forced cleanup is not supported by this helper.', 'Preserve remaining files and inspect the worktree manually.');
  const ignored = git(c.dir, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z']).split('\0').filter(Boolean);
  if (ignored.length) throw new CrackError('remaining_files', 'Ignored files remain in the worktree; cleanup refused.', 'Preserve or explicitly remove them yourself before retrying.');
  let force = false;
  const integrated = readIfExists(c.integratedFile)?.toString('utf8').trim();
  if (!force && integrated) {
    // Safe to discard only if the worktree still holds exactly what was integrated.
    const base = readBase(c);
    changedPaths(c, base);
    const patch = patchFor(c, base);
    force = integrated === sha256(patch);
    if (force) git(c.repo, ['apply', '--reverse', '--check', '--whitespace=nowarn'], patch);
  }
  git(c.repo, ['worktree', 'remove', ...(force ? ['--force'] : []), c.dir]);
  for (const file of [c.baseFile, c.integratedFile]) fs.rmSync(file, { force: true });
  let branchDeleted = true;
  try {
    git(c.repo, ['branch', '-d', c.branch]);
  } catch {
    branchDeleted = false;
  }
  return ok({
    removed: c.dir,
    branch: c.branch,
    branch_deleted: branchDeleted,
    note: branchDeleted ? 'Removed.' : `Kept branch ${c.branch}: it has commits that are not merged.`,
  });
}

const COMMANDS = { add, integrate, remove };

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