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

lib/floor/config.ts

View on GitHub
/**
 * The floor's block of the burndown config: the running environment merges are checked against,
 * the standing walks, and how often to walk. Absent means no floor. See references/floor.md.
 */

import type { HealthPath } from './probe.ts';

export type EnvironmentKind = 'web' | 'ios' | 'android';

/**
 * Which driver skill the walk prompt loads for each kind when the config names none. These are
 * the project-agnostic drivers; an environment built on a particular stack sets
 * `environment.driverSkill` to the specialised one (an Expo app names `expo-ios-simulator`).
 */
export const DRIVER_SKILLS: Record<EnvironmentKind, string> = {
  web: 'playwright-harness',
  ios: 'ios-simulator',
  android: 'android-emulator-harness',
};

export type Login = {
  url: string;
  /** Environment variable NAMES. The loader refuses anything that looks like a value. */
  userEnv: string;
  passwordEnv: string;
  restrictedUserEnv?: string;
  restrictedPasswordEnv?: string;
};

export type Environment = {
  kind: EnvironmentKind;
  /** The driver skill the walker loads, when the kind's default is not the right one. */
  driverSkill?: string;
  /** The running instance the base branch deploys to. */
  baseUrl: string;
  /** Requests the in-process probe makes on every walk. Empty means `/`. */
  healthPaths: HealthPath[];
  /** How long one health request may take before it counts as no response. */
  probeTimeoutMs: number;
  /** Prints the running commit. Optional; without it items inside `graceMinutes` are `unverified`. */
  revisionCommand?: string;
  /** Prints recent logs, read when a walk fails. Optional. */
  logsCommand?: string;
  login?: Login;
  /** Paths the walker may POST to. Default none. */
  safeEndpoints: string[];
  graceMinutes: number;
  /**
   * Daily windows, in UTC `HH:MM`, when the environment is expected to be down or wrong: a nightly
   * database copy, a scheduled deploy. Inside one a walk still records what it sees but pauses
   * nothing, runs no callback, and files no incident.
   */
  quietWindows: Array<{ start: string; end: string }>;
};

export type Walk = { name: string; paths: string[]; steps: string };

/** What a programmable cadence sees when it picks the wait before the next walk. */
export type FloorState = {
  /** Items with no terminal verdict yet. */
  pending: number;
  /** The last walk found the environment wrong. */
  wrong: boolean;
  /** The line is paused, by the floor or by a person. */
  paused: boolean;
  /** The run's own work is done and the floor is finishing what is pending. */
  draining: boolean;
};

export type FloorConfig = {
  /** Minutes between walks, or a function of the floor's state that returns them. Default 10. */
  every: number | ((state: FloorState) => number);
  /** After the run's own work is done, how long to keep walking until the floor is clear. Default 60. */
  drainMinutes: number;
  environment: Environment;
  walks: Walk[];
  /** Also put merges this loop did not make (a person's, another tool's) on the floor. Default true. */
  forge: boolean;
};

/** What an adopter writes under `floor` in burn-down-github-issues.config.ts. */
export type FloorConfigInput = Partial<Omit<FloorConfig, 'environment'>> & {
  environment: Partial<Environment> & { kind: EnvironmentKind; baseUrl: string };
};

const DEFAULT_ENVIRONMENT: Omit<Environment, 'kind' | 'baseUrl'> = {
  probeTimeoutMs: 10_000,
  healthPaths: [],
  safeEndpoints: [],
  graceMinutes: 15,
  quietWindows: [],
};

/** True when `now` (UTC) falls inside any configured quiet window; windows may cross midnight. */
export function inQuietWindow(windows: Array<{ start: string; end: string }>, now = new Date()): boolean {
  const minutes = now.getUTCHours() * 60 + now.getUTCMinutes();
  const toMinutes = (hhmm: string) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3, 5));
  return windows.some(({ start, end }) => {
    const a = toMinutes(start);
    const b = toMinutes(end);
    return a <= b ? minutes >= a && minutes <= b : minutes >= a || minutes <= b;
  });
}

/**
 * Minutes until the next walk. A cadence function that throws or returns something other than a
 * positive number falls back to `fallback`, so a typo in the config slows the floor down rather
 * than stopping it.
 */
export function nextWalkMinutes(every: FloorConfig['every'], state: FloorState, fallback = 10): number {
  let value: unknown = every;
  if (typeof every === 'function') {
    try {
      value = every(state);
    } catch {
      return fallback;
    }
  }
  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
}

/** A variable name, not a value: upper-case identifier characters only. */
const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;

/** Walk paths match as prefixes or bare suffixes (`matchesPath`); a glob would silently never match. */
export function walkPathFaults(walks: Array<{ name: string; paths: unknown[] }>): string[] {
  const faults: string[] = [];
  for (const walk of walks) {
    for (const path of walk.paths) {
      if (typeof path !== 'string' || /[*?[\]{}]/.test(path)) {
        faults.push(`floor.walks '${walk.name}': path '${String(path)}' is not a prefix or suffix; use one such as 'src/search/' or '.schema.ts', not a glob`);
      }
    }
  }
  return faults;
}

/** The floor block with its defaults applied, and the list of what is wrong with it. */
export function resolveFloor(input: FloorConfigInput): { floor: FloorConfig; faults: string[] } {
  const environment = { ...DEFAULT_ENVIRONMENT, ...(input.environment ?? {}) } as Environment;
  const floor: FloorConfig = { every: input.every ?? 10, drainMinutes: input.drainMinutes ?? 60, environment, walks: input.walks ?? [], forge: input.forge ?? true };
  const faults: string[] = [];
  const positive = (value: unknown) => Number.isInteger(value) && (value as number) > 0;
  if (typeof floor.every !== 'function' && !positive(floor.every)) faults.push('floor.every must be minutes as a positive integer, or a function of the floor state that returns them');
  if (!positive(floor.drainMinutes)) faults.push('floor.drainMinutes must be a positive integer');
  if (typeof floor.forge !== 'boolean') faults.push('floor.forge must be true or false');
  if (!(environment.kind in DRIVER_SKILLS)) faults.push(`floor.environment.kind must be one of ${Object.keys(DRIVER_SKILLS).join(', ')}`);
  if (typeof environment.baseUrl !== 'string' || !/^https?:\/\//.test(environment.baseUrl)) faults.push('floor.environment.baseUrl must be an http(s) URL');
  if (!Array.isArray(environment.healthPaths)) faults.push('floor.environment.healthPaths must be an array');
  if (!Array.isArray(environment.safeEndpoints)) faults.push('floor.environment.safeEndpoints must be an array');
  const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
  if (!Array.isArray(environment.quietWindows) || environment.quietWindows.some((w) => !HHMM.test(w?.start) || !HHMM.test(w?.end))) {
    faults.push('floor.environment.quietWindows must be an array of { start: "HH:MM", end: "HH:MM" } in UTC');
  }
  if (!positive(environment.graceMinutes)) faults.push('floor.environment.graceMinutes must be a positive integer');
  if (!positive(environment.probeTimeoutMs)) faults.push('floor.environment.probeTimeoutMs must be a positive integer');
  if (environment.driverSkill !== undefined && (typeof environment.driverSkill !== 'string' || environment.driverSkill.trim() === '')) {
    faults.push('floor.environment.driverSkill must be a skill name');
  }
  const login = environment.login;
  if (login) {
    for (const key of ['userEnv', 'passwordEnv', 'restrictedUserEnv', 'restrictedPasswordEnv'] as const) {
      const value = login[key];
      if (value !== undefined && !ENV_NAME.test(value)) faults.push(`floor.environment.login.${key} must be an environment variable NAME such as FLOOR_USER, never a value`);
    }
    if (typeof login.url !== 'string' || !login.url) faults.push('floor.environment.login.url must be a URL');
  }
  if (!Array.isArray(floor.walks) || floor.walks.some((w) => !w?.name || !Array.isArray(w.paths) || !w.steps)) {
    faults.push('floor.walks must be an array of { name, paths, steps }');
  } else {
    faults.push(...walkPathFaults(floor.walks));
  }
  return { floor, faults };
}
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