simiancraft/simiancraft-skills / skills/carve-github-issue
carve-github-issue
VerifiedBreak one GitHub issue that is too large to work into sub-issues, unattended, and keep the carving honest as the children close. A carver names the pieces along the highest natural seam (domain, tier, route, area, file, unit, material), matches each against the backlog so nothing is authored twice, and a second engine confirms the cut covers the parent before anything is created. The parent becomes a trunk that is finished by closing its children; every child close re-checks the trunk, and a trunk with nothing left goes back to the appraiser. Use when the task is "this issue is too big, split it", "carve #N into sub-issues", "is this carving still good", or when burn-down-github-issues sizes an issue over its ceiling. Requires a per-repository config (its own, or the burndown's), the codex and claude CLIs for the default seats, and GitHub sub-issues on the repository. Skip for fixing anything; this skill writes only to the tracker.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| carve.ts | script | 10.6 KB |
| lib/callbacks.ts | script | 1.4 KB |
| lib/carve.test.ts | script | 19.0 KB |
| lib/carve.ts | script | 25.6 KB |
| lib/claims.test.ts | script | 12.9 KB |
| lib/claims.ts | script | 13.8 KB |
| lib/fake-tracker.ts | script | 9.4 KB |
| lib/knife.test.ts | script | 52.3 KB |
| lib/knife.ts | script | 52.9 KB |
| lib/record.ts | script | 12.7 KB |
| lib/tree.ts | script | 23.3 KB |
| lib/validate.test.ts | script | 12.8 KB |
| prompts/carve.md | markdown | 8.1 KB |
| prompts/confirm-carve.md | markdown | 4.1 KB |
| prompts/revisit.md | markdown | 4.9 KB |
| references/adopting.md | markdown | 6.3 KB |
| references/callbacks.md | markdown | 1.7 KB |
| references/lifecycle.md | markdown | 29.7 KB |
| references/seams.md | markdown | 9.1 KB |
| references/the-record.md | markdown | 6.6 KB |
carve.ts
View on GitHub/**
* carve-github-issue: express one oversized issue as sub-issues, or re-check a carving.
*
* The knife. Given an issue sized over the ceiling, a carver names the parts along the highest
* natural seam, matches each against the backlog so nothing is authored twice, and a second engine
* confirms the cut covers the parent before anything is created. Given a trunk that was carved
* already, it asks whether the carving is still good. Everything it decides lands on the tracker:
* sub-issues, edges, labels, and a carving record on the trunk's thread. This file is the command;
* the library it drives is in `lib/`, and the burndown calls `carveIssue` directly.
*
* This file is shared: it ships with the skill and is not copied into a repository. Everything
* true of a repository lives in a config file at that repository's root. Run it from inside the
* target repository:
*
* bun run <skill-dir>/carve.ts --issue <n> # carve, or revisit, one issue
* bun run <skill-dir>/carve.ts --issue <n> --dry-run # with fixture seats: log every write, land nothing
* bun run <skill-dir>/carve.ts --issue <n> --ceiling 3 # a one-off ceiling
* bun run <skill-dir>/carve.ts --issue <n> --carver codex:gpt-5.6-sol --confirmer claude:claude-opus-5
*
* Exit codes: 0 for every confirmed verdict, a resumed generation, or an issue left alone; 1 when
* the knife failed; 3 when another run holds the issue.
*/
import { existsSync, readFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { enrichBlockers } from '../fix-github-issue/lib/blockers.ts';
import { resolveCallbacksDir } from '../appraise-github-issues/lib/appraise.ts';
import { invokeRootFrom, loadProjectConfig, PIPELINE_DEFAULTS, type PipelineKnobs, repoRootFrom } from '../fix-github-issue/lib/config.ts';
import { createContext } from '../fix-github-issue/lib/context.ts';
import { assertDistinctEngines, isFixture, parseSeat, seatLabel } from '../fix-github-issue/lib/engines.ts';
import { ensureLabels } from '../fix-github-issue/lib/labels.ts';
import type { Issue } from '../fix-github-issue/lib/pipeline.ts';
import { log, sh, step, teeConsole } from '../fix-github-issue/lib/shell.ts';
import { ISSUE_LIST_FIELDS } from '../appraise-github-issues/lib/appraise.ts';
import { CARVE_DEFAULTS, type CarveKnobs, JOURNAL_STEPS, type JournalStep } from './lib/carve.ts';
import { carveIssue } from './lib/knife.ts';
import { installStopHandler } from '../fix-github-issue/lib/stop.ts';
import { guardCli } from '../fix-github-issue/lib/cli.ts';
import type { Board } from '../burn-down-github-issues/board.ts';
import { type BoardWriter, waitForBoard, createBoardWriter } from '../burn-down-github-issues/lib/board-writer.ts';
const HERE = dirname(fileURLToPath(import.meta.url));
const PROMPTS = join(HERE, 'prompts');
const args = process.argv.slice(2);
/** Every flag this command reads is named here and in USAGE; a source test holds the three together. */
export const CLI = { flags: ['dry-run'], options: ['issue', 'ceiling', 'carver', 'confirmer', 'fail-after'] } as const;
export const USAGE = `carve-github-issue: carve one oversized issue into sub-issues, or revisit one already carved.
Run it from inside the target repository.
bun run <skill-dir>/carve.ts --issue <n> [flags]
--issue <n> the issue to carve or revisit (required)
--dry-run with fixture seats: log every write, land nothing
--ceiling <n> a one-off ceiling, in points (default: the config's)
--carver, --confirmer <seat>
engine[:model] for that seat
--fail-after <step> testing only: exit hard after that journal step
--help, -h print this and exit`;
// Before anything else: an argument this command does not know must never fall through to a real run.
guardCli(args, CLI, USAGE);
const flag = (name: string) => args.includes(`--${name}`);
const opt = (name: string) => {
const i = args.indexOf(`--${name}`);
if (i < 0) return undefined;
const value = args[i + 1];
if (value === undefined || value.startsWith('--')) {
console.error(`--${name} needs a value`);
process.exit(1);
}
return value;
};
const positive = (name: string): number | undefined => {
const raw = opt(name);
if (raw === undefined) return undefined;
const parsed = Number(raw);
if (!Number.isInteger(parsed) || parsed <= 0) {
console.error(`--${name} expects a positive integer, got '${raw}'`);
process.exit(1);
}
return parsed;
};
const DRY_RUN = flag('dry-run');
const ISSUE_NUMBER = positive('issue');
if (ISSUE_NUMBER === undefined) {
console.error('usage: bun run carve.ts --issue <n> [--dry-run] [--ceiling <n>] [--carver <seat>] [--confirmer <seat>]');
process.exit(2);
}
const FAIL_AFTER = (() => {
const raw = opt('fail-after');
if (raw === undefined) return undefined;
if (process.env.CARVE_DEV !== '1') {
console.error('--fail-after is a development flag; set CARVE_DEV=1 to use it');
process.exit(1);
}
if (!JOURNAL_STEPS.includes(raw as JournalStep)) {
console.error(`--fail-after expects one of ${JOURNAL_STEPS.join(', ')}, got '${raw}'`);
process.exit(1);
}
return raw as JournalStep;
})();
const REPO_ROOT = repoRootFrom(process.cwd());
const INVOKE_ROOT = invokeRootFrom(process.cwd(), REPO_ROOT);
/** Its own config when the repository has one, the burndown's otherwise. */
const CONFIG_FILE = ['carve-github-issue.config.ts', 'burn-down-github-issues.config.ts'].find((name) => existsSync(join(INVOKE_ROOT, name)));
type Knobs = PipelineKnobs & { maxPoints: number; callbacksDir: string; carve: typeof CARVE_DEFAULTS };
const CONFIG = await loadProjectConfig<Knobs>({
invokeRoot: INVOKE_ROOT,
repoRoot: REPO_ROOT,
fileName: CONFIG_FILE ?? 'carve-github-issue.config.ts',
defaults: { ...PIPELINE_DEFAULTS, maxPoints: 2, callbacksDir: '<worktreeRoot>/appraisal-callbacks', carve: CARVE_DEFAULTS },
positiveIntegers: ['maxPoints', 'maxReviewRounds', 'checksTimeoutMinutes', 'smokeTimeoutMinutes', 'maxWorkerAttempts', 'carve.maxDepth', 'carve.maxChildren', 'carve.maxCarveRounds', 'carve.maxCarveAttempts', 'carve.maxGenerations', 'carve.maxRevisitsPerGeneration'],
blocks: ['carve'],
help: [
'The knife is shared across repositories; everything true of a repository lives in that file.',
'Copy the template from references/adopting.md in this skill (or adopt burn-down-github-issues, whose config this command also reads).',
],
});
const SEATS = (() => {
try {
const carverSpec = opt('carver') ?? process.env.LOOP_CARVER ?? CONFIG.seats.carver ?? CONFIG.seats.worker;
const confirmerSpec = opt('confirmer') ?? process.env.LOOP_CARVE_CONFIRMER ?? CONFIG.seats.carveConfirmer ?? CONFIG.seats.confirmer ?? CONFIG.seats.reviewer;
const seats = {
carver: parseSeat(carverSpec, '--carver'),
confirmer: parseSeat(confirmerSpec, '--confirmer'),
worker: parseSeat(CONFIG.seats.worker, 'seats.worker'),
reviewer: parseSeat(CONFIG.seats.reviewer, 'seats.reviewer'),
};
assertDistinctEngines(seats.carver, seats.confirmer, 'carver and confirmer');
return seats;
} catch (error) {
console.error((error as Error).message);
process.exit(1);
}
})();
const ctx = createContext({
project: CONFIG.project,
knobs: {
autoMerge: 'never',
maxReviewRounds: CONFIG.maxReviewRounds,
checksTimeoutMinutes: CONFIG.checksTimeoutMinutes,
agentTimeoutMinutes: CONFIG.agentTimeoutMinutes,
smokeTimeoutMinutes: CONFIG.smokeTimeoutMinutes,
pointScale: CONFIG.pointScale,
maxWorkerAttempts: CONFIG.maxWorkerAttempts,
},
seats: { worker: SEATS.worker, reviewer: SEATS.reviewer },
repoRoot: REPO_ROOT,
invokeRoot: INVOKE_ROOT,
promptsDirs: [PROMPTS, join(HERE, '..', 'appraise-github-issues', 'prompts')],
dryRun: DRY_RUN,
});
const KNOBS: CarveKnobs = {
ceiling: positive('ceiling') ?? CONFIG.maxPoints,
...CONFIG.carve,
callbacksDir: resolveCallbacksDir(ctx, CONFIG.callbacksDir),
seats: { carver: SEATS.carver, confirmer: SEATS.confirmer },
failAfter: FAIL_AFTER,
};
teeConsole(join(ctx.runDir, 'carve.log'));
step(`${ctx.project.name} carve-github-issue`);
log(`run pid ${process.pid} started ${new Date().toISOString()}`);
log(`issue #${ISSUE_NUMBER} | ceiling ${KNOBS.ceiling} | scale ${ctx.knobs.pointScale.join(', ')} | depth up to ${KNOBS.maxDepth} | up to ${KNOBS.maxChildren} children | ${KNOBS.maxCarveRounds} rounds | config ${CONFIG_FILE}`);
log(`carver ${seatLabel(SEATS.carver)} | confirmer ${seatLabel(SEATS.confirmer)} | callbacks ${KNOBS.callbacksDir}`);
if (DRY_RUN) log('DRY RUN: no lock, no claim, no journal file; only fixture seats run; only this log is written');
// Not refused here: finishing an announced generation runs no seat, so a dry run can rehearse a
// resume without one. The knife stops at the first seat it would actually have to run and says so.
if (DRY_RUN && !(isFixture(SEATS.carver) && isFixture(SEATS.confirmer))) {
log('DRY RUN: no fixture seats, so anything that needs the carver or the confirmer stops there; an announced generation is still rehearsed to its end');
}
let writer: BoardWriter | undefined;
installStopHandler(log, () => waitForBoard(writer));
if (!DRY_RUN) ensureLabels(ctx);
// The knife moves its own cards (C2, C3, C4) when it knows where the board is. A carve started by
// hand, or by a producer's size callback, is otherwise invisible for its whole run: the card sits
// wherever the driver that dispatched it last left it. The pointer is the one card.ts reads.
if (!DRY_RUN) {
const pointer = join(resolve(REPO_ROOT, CONFIG.project.worktreeRoot, 'runs'), 'board.json');
try {
if (existsSync(pointer)) {
writer = createBoardWriter(JSON.parse(readFileSync(pointer, 'utf8')) as Board, CONFIG.project.repo, log);
ctx.onLane = (event) => {
writer?.onLane(event);
};
log(`board: moving #${ISSUE_NUMBER}'s card on ${pointer}`);
}
} catch (error) {
// A board is a projection. An unreadable one costs the operator a moving card, never the carve.
log(`board: ${pointer} could not be read (${(error as Error).message.split('\n')[0]}); carving without it`);
}
}
const issue: Issue = JSON.parse(sh(ctx, ['gh', 'issue', 'view', String(ISSUE_NUMBER), '--json', ISSUE_LIST_FIELDS]));
enrichBlockers(ctx, [issue]);
const result = await carveIssue(ctx, issue, KNOBS);
log(`${result.outcome}: ${result.reason}${result.generation !== undefined ? ` (generation ${result.generation})` : ''}${result.children?.length ? ` children ${result.children.map((n) => `#${n}`).join(', ')}` : ''}`);
step(result.outcome);
await writer?.settled();
process.exit(result.outcome === 'failed' ? 1 : result.outcome === 'busy' ? 3 : 0);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |