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
#!/usr/bin/env bun
/**
 * The board: one GitHub Projects (v2) board per operator per repository, the durable state a
 * burndown is resumed from. From inside an adopting repository:
 *
 *   bun run <skill-dir>/board.ts               # find the board, create it if absent, verify, print it
 *   bun run <skill-dir>/board.ts --dry-run     # find and report; create nothing
 *   bun run <skill-dir>/board.ts --operator x  # name the board after operator x instead of the gh login
 *
 * The board is titled `<project>_burndown_<operator>`: the config's project name, lower-cased,
 * then the GitHub login the token belongs to. It is owned by the repository's owner (the org or
 * user in `project.repo`) and linked to the repository, so it appears on the repository's
 * Projects tab. Scoping it to the operator is the point: two people burning down the same
 * repository each keep their own board, and one person coming back picks up their own.
 *
 * Idempotent. An open board with that title is reused, never duplicated; a closed one with that
 * title is named and left alone. The board found or created is verified by a second read before
 * anything is printed, and `<worktreeRoot>/runs/board.json` records where it is. The board is
 * the state; the file is only a pointer.
 *
 * Needs the `project` token scope (`gh auth refresh -h github.com -s project`); `read:project`
 * lists but cannot create, and the script says which one it is missing rather than failing in
 * GraphQL.
 */

import { mkdirSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { invokeRootFrom, loadProjectConfig, PIPELINE_DEFAULTS, repoRootFrom } from '../fix-github-issue/lib/config.ts';

const args = process.argv.slice(2);
const flag = (name: string) => args.includes(`--${name}`);
const opt = (name: string) => {
  const i = args.indexOf(`--${name}`);
  return i >= 0 ? args[i + 1] : undefined;
};

const DRY_RUN = flag('dry-run');

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: ['board.ts reads the same config the loop does; see references/adopting.md'],
});
const PROJECT = CONFIG.project;
const RUN_DIR = resolve(REPO_ROOT, PROJECT.worktreeRoot, 'runs');
const POINTER = join(RUN_DIR, 'board.json');

export type Board = {
  owner: string;
  number: number;
  id: string;
  title: string;
  url: string;
};

function gh(cmd: string[]): { ok: boolean; out: string; err: string } {
  const proc = Bun.spawnSync(['gh', ...cmd], { cwd: REPO_ROOT, stderr: 'pipe', stdout: 'pipe' });
  return { ok: proc.exitCode === 0, out: proc.stdout.toString().trim(), err: proc.stderr.toString().trim() };
}

function must(cmd: string[]): string {
  const result = gh(cmd);
  if (!result.ok) {
    console.error(`gh ${cmd.join(' ')}\n${result.err}`);
    process.exit(1);
  }
  return result.out;
}

/** The scopes the token carries, from the header GitHub returns on every REST call. */
function tokenScopes(): string[] {
  const head = must(['api', '-i', 'user']);
  const line = head.split('\n').find((l) => l.toLowerCase().startsWith('x-oauth-scopes:'));
  return (line ?? '').slice('x-oauth-scopes:'.length).split(',').map((s) => s.trim()).filter(Boolean);
}

/** `<project>_burndown_<operator>`; the project name lower-cased and reduced to [a-z0-9-]. */
export function boardTitle(projectName: string, operator: string): string {
  const slug = projectName.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
  return `${slug}_burndown_${operator}`;
}

type Listed = { number: number; id: string; title: string; url: string; closed: boolean };

function listBoards(owner: string): Listed[] {
  const json = must(['project', 'list', '--owner', owner, '--closed', '--format', 'json', '--limit', '200']);
  const parsed = JSON.parse(json) as { projects: Listed[] };
  return parsed.projects;
}

function viewBoard(owner: string, number: number): Listed {
  const json = must(['project', 'view', String(number), '--owner', owner, '--format', 'json']);
  return JSON.parse(json) as Listed;
}

const owner = PROJECT.repo.split('/')[0];
const operator = opt('operator') ?? must(['api', 'user', '-q', '.login']);
const title = boardTitle(PROJECT.name, operator);
const scopes = tokenScopes();
const canWrite = scopes.includes('project');

console.log(`board ${title}  owner ${owner}  repo ${PROJECT.repo}  scopes ${scopes.join(', ') || '(none reported)'}`);

const boards = listBoards(owner);
const open = boards.find((b) => b.title === title && !b.closed);
const closed = boards.filter((b) => b.title === title && b.closed);
for (const b of closed) console.log(`  a closed board carries this title: #${b.number} ${b.url}; it is left alone`);

let found: Listed;
if (open) {
  console.log(`  exists: #${open.number} ${open.url}`);
  found = open;
} else if (DRY_RUN) {
  console.log(`  DRY RUN  would create project '${title}' under ${owner} and link it to ${PROJECT.repo}`);
  if (!canWrite) console.log(`  the token lacks the 'project' scope; run: gh auth refresh -h github.com -s project`);
  process.exit(0);
} else {
  if (!canWrite) {
    console.error(`no board '${title}' under ${owner}, and the token cannot create one: it has [${scopes.join(', ')}] and needs 'project'.\nrun: gh auth refresh -h github.com -s project`);
    process.exit(1);
  }
  const json = must(['project', 'create', '--owner', owner, '--title', title, '--format', 'json']);
  const created = JSON.parse(json) as Listed;
  console.log(`  created: #${created.number} ${created.url}`);
  const link = gh(['project', 'link', String(created.number), '--owner', owner, '--repo', PROJECT.repo]);
  if (link.ok) console.log(`  linked to ${PROJECT.repo}`);
  else console.log(`  not linked to ${PROJECT.repo}: ${link.err}`);
  found = created;
}

// Verify by a second, independent read: what the list or the create said is not what is trusted.
const seen = viewBoard(owner, found.number);
if (seen.title !== title || seen.closed) {
  console.error(`verification failed: #${found.number} reads back as '${seen.title}' closed=${seen.closed}`);
  process.exit(1);
}
const board: Board = { owner, number: seen.number, id: seen.id, title: seen.title, url: seen.url };
console.log(`  verified: #${board.number} '${board.title}' ${board.id} ${board.url}`);

if (!DRY_RUN) {
  mkdirSync(RUN_DIR, { recursive: true });
  writeFileSync(POINTER, `${JSON.stringify(board, null, 2)}\n`);
  console.log(`  pointer: ${POINTER}`);
}
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