Skip to content

simiancraft/simiancraft-skills / skills/burn-down-github-issues

burn-down-github-issues

Unverified

Run an unattended burndown of a GitHub issue backlog as cards on a per-operator GitHub Projects board whose lanes are an explicit state machine: appraise and size the inbox, carve what is over the ceiling, fix the ready ones in parallel git worktrees, prove each fix on a draft pull request, have an isolated second-engine reviewer judge it, land one branch at a time with freshness checks, and dead-letter per phase whatever a machine cannot finish. Use when the task is "work the backlog unattended", "triage and fix recent issues", "run the issue loop", "burn down issues", or "where is issue N on the board". Requires a per-repository burn-down-github-issues.config.ts at the target repo's root (the loop refuses to start without it), the prove-work-on-github skill, the codex and claude CLIs for the default seats, and a gh token with the project scope for the board. Skip for one-off fixes to a known issue you are already working interactively, and for backlogs whose issues are mostly product decisions rather than code.

FileKindSize
SKILL.mdskill md17.0 KB
board.tsscript6.5 KB
callbacks/README.mdmarkdown1.1 KB
callbacks/on-size-over-ceilingother843 B
card.tsscript4.3 KB
chart-machine.tsscript3.9 KB
claim-race.tsscript6.1 KB
export-machine.tsscript1.8 KB
lanes.tsscript5.2 KB
lib/admission.test.tsscript7.6 KB
lib/admission.tsscript5.5 KB
lib/board-writer.test.tsscript3.6 KB
lib/board-writer.tsscript11.8 KB
lib/carving-revisit.test.tsscript7.5 KB
lib/carving.tsscript26.9 KB
lib/floor/config.test.tsscript456 B
lib/floor/config.tsscript8.1 KB
lib/floor/floor.test.tsscript9.9 KB
lib/floor/floor.tsscript28.7 KB
lib/floor/incident.tsscript11.2 KB
lib/floor/ledger.tsscript5.6 KB
lib/floor/probe.tsscript3.6 KB
lib/lanes.tsscript4.4 KB
lib/machine.test.tsscript11.2 KB
lib/machine.tsscript52.4 KB
lib/place-callbacks.test.tsscript2.5 KB
lib/place-callbacks.tsscript3.0 KB
lib/preflight.test.tsscript4.5 KB
lib/preflight.tsscript1.2 KB
lib/pressure.test.tsscript56.9 KB
lib/refs.test.tsscript1010 B
lib/refs.tsscript1.9 KB
lib/run-scope.test.tsscript5.4 KB
lib/run-scope.tsscript1.2 KB
lib/scenarios.test.tsscript17.1 KB
lib/simulate.test.tsscript7.3 KB
lib/simulate.tsscript7.0 KB
lib/world-sweep.test.tsscript21.4 KB
loop.source.test.tsscript4.8 KB
loop.tsscript66.2 KB
prompts/diagnose.mdmarkdown2.1 KB
prompts/walk.mdmarkdown3.6 KB
references/adopting.mdmarkdown26.3 KB
references/architecture.mdmarkdown20.7 KB
references/floor.mdmarkdown14.6 KB
references/operating.mdmarkdown19.6 KB
references/state-machine.mdmarkdown31.1 KB
status.tsscript4.9 KB
watch.tsscript6.4 KB

claim-race.ts

View on GitHub
#!/usr/bin/env bun
/**
 * Prove the claim lock on the real tracker: several contenders claim one issue at the same
 * instant, and exactly one may win. From inside an adopting repository:
 *
 *   bun run <skill-dir>/claim-race.ts --issue <n> --contenders 3 --rounds 3
 *
 * Each contender is its own process with its own run id, exactly as two loops on two machines
 * would be. All are released at one wall-clock instant, each runs the real `claim()` (the comment,
 * the label, the re-read, the tie-break by comment id), reports what it got, holds a won claim
 * for a moment, and releases it. The parent judges every round: one winner, every other
 * contender `busy`, and afterwards no unreleased claim on the thread. Use an issue that carries
 * `loop/skip` and exists for this, since the thread collects claim and unclaim markers.
 *
 * This is the experiment the fake-tracker unit tests cannot run: GitHub has no compare-and-swap,
 * and the announce-then-reread protocol is only as good as the window between two runs' writes.
 */

import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { claim, trackerIo } from '../carve-github-issue/lib/claims.ts';
import { readTree } from '../carve-github-issue/lib/tree.ts';
import { invokeRootFrom, loadProjectConfig, PIPELINE_DEFAULTS, repoRootFrom } from '../fix-github-issue/lib/config.ts';
import { createContext } from '../fix-github-issue/lib/context.ts';
import { parseSeat } from '../fix-github-issue/lib/engines.ts';
import { ensureLabels } from '../fix-github-issue/lib/labels.ts';

const HERE = fileURLToPath(import.meta.url);
const args = process.argv.slice(2);
const opt = (name: string) => {
  const i = args.indexOf(`--${name}`);
  return i >= 0 ? args[i + 1] : undefined;
};
const num = (name: string, fallback: number) => {
  const raw = opt(name);
  if (raw === undefined) return fallback;
  const n = Number(raw);
  if (!Number.isInteger(n) || n <= 0) {
    console.error(`--${name} expects a positive integer, got '${raw}'`);
    process.exit(1);
  }
  return n;
};

const ISSUE = num('issue', 0);
if (ISSUE === 0) {
  console.error('--issue <n> is required');
  process.exit(1);
}
const CONTEND = args.includes('--contend');
const START = Number(opt('start') ?? 0);

const REPO_ROOT = repoRootFrom(process.cwd());
const INVOKE_ROOT = invokeRootFrom(process.cwd(), REPO_ROOT);
const CONFIG = await loadProjectConfig({
  invokeRoot: INVOKE_ROOT,
  repoRoot: REPO_ROOT,
  fileName: 'burn-down-github-issues.config.ts',
  defaults: PIPELINE_DEFAULTS,
  positiveIntegers: [],
  help: ['claim-race.ts reads the same config the loop does'],
});

const seat = parseSeat('codex', 'seat');
const ctx = createContext({
  project: CONFIG.project,
  knobs: PIPELINE_DEFAULTS,
  seats: { worker: seat, reviewer: seat },
  repoRoot: REPO_ROOT,
  invokeRoot: INVOKE_ROOT,
  promptsDirs: [],
  dryRun: false,
  log: CONTEND ? () => {} : (m) => console.log(m),
  step: () => {},
});

type Report = { runId: string; result: 'won' | 'busy'; commentId: number | null; claimedAt: number; error?: string };

// The parent creates the loop's labels once, before any contender starts, so a repository that has
// never seen the loop races on the claim and not on a missing label, and the creation is not timed.
if (!CONTEND) ensureLabels(ctx);

if (CONTEND) {
  // A contender: wait for the shared instant, claim, report on stdout as one JSON line, release.
  const wait = START - Date.now();
  if (wait > 0) await Bun.sleep(wait);
  const io = trackerIo(ctx);
  let report: Report;
  try {
    const handle = await claim(ctx, io, ISSUE, 'working');
    const claimedAt = Date.now();
    if (handle === 'busy') {
      report = { runId: ctx.runId, result: 'busy', commentId: null, claimedAt };
    } else {
      report = { runId: ctx.runId, result: 'won', commentId: handle.commentId, claimedAt };
      await Bun.sleep(3000);
      handle.release();
    }
  } catch (error) {
    report = { runId: ctx.runId, result: 'busy', commentId: null, claimedAt: Date.now(), error: (error as Error).message };
  }
  console.log(JSON.stringify(report));
  process.exit(0);
}

const CONTENDERS = num('contenders', 2);
const ROUNDS = num('rounds', 1);
let failures = 0;

console.log(`claim race on #${ISSUE}: ${CONTENDERS} contender(s), ${ROUNDS} round(s), repo ${CONFIG.project.repo}`);
for (let round = 1; round <= ROUNDS; round++) {
  const start = Date.now() + 4000;
  const children = Array.from({ length: CONTENDERS }, () =>
    Bun.spawn(['bun', 'run', HERE, '--issue', String(ISSUE), '--contend', '--start', String(start)], {
      cwd: process.cwd(),
      stdout: 'pipe',
      stderr: 'pipe',
    }),
  );
  const outputs = await Promise.all(children.map(async (child) => ({ out: await new Response(child.stdout).text(), err: await new Response(child.stderr).text(), code: await child.exited })));
  const reports: Report[] = [];
  for (const { out, err, code } of outputs) {
    const line = out.trim().split('\n').filter(Boolean).pop();
    try {
      reports.push(JSON.parse(line ?? '') as Report);
    } catch {
      reports.push({ runId: '?', result: 'busy', commentId: null, claimedAt: 0, error: `no report (exit ${code}): ${err.trim().split('\n').pop() ?? ''}` });
    }
  }
  const winners = reports.filter((r) => r.result === 'won');
  const errors = reports.filter((r) => r.error);
  const io = trackerIo(ctx);
  const tree = readTree(ctx, ISSUE, io);
  const unreleased = tree.claims.filter((c) => !c.released && Date.parse(c.expires) > Date.now());
  const ok = winners.length === 1 && errors.length === 0 && unreleased.length === 0;
  if (!ok) failures++;
  console.log(`round ${round}: ${ok ? 'PASS' : 'FAIL'}  winners ${winners.length}/${CONTENDERS}  errors ${errors.length}  unreleased claims after ${unreleased.length}`);
  for (const r of reports.sort((a, b) => a.claimedAt - b.claimedAt)) {
    const offset = r.claimedAt ? `+${r.claimedAt - start}ms` : '';
    console.log(`  ${r.result.padEnd(4)} ${r.runId} ${offset}${r.commentId ? ` comment ${r.commentId}` : ''}${r.error ? `  ${r.error}` : ''}`);
  }
}
console.log(failures === 0 ? `all ${ROUNDS} round(s) passed` : `${failures} round(s) FAILED`);
process.exit(failures === 0 ? 0 : 1);
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: 472kUpdated 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