issueforge: Instructions file for Claude Code

IssueForge

A local-first GitHub IssueOps supervisor. A maintainer labels an issue, a self-hosted runner spawns an already-installed coding agent (Claude Code / Codex) in a SHA-pinned worktree, and the agent reports its own findings back to the issue with gh.

IssueForge is not a coding agent. It never plans steps, chooses tools, or calls a model, and it writes no GitHub content — no comments, no labels, no PRs; the harness does all of it. If a change requires planning, tool choice, or a model call, that is scope drift: say so instead of building it.

Commands

pnpm check                  # typecheck + lint + test — the arbiter, run before declaring done
pnpm test                   # runs `pnpm build` first, deliberately (see below)
pnpm test:unit              # vitest only, no build — fast loop
npx vitest run path/to.test.ts   # a single file
node apps/cli/src/main.ts --help  # run the CLI with no build step

pnpm test builds first because sqlite-run-store.test.ts spawns a second real process that imports packages/adapters/dist/index.js; without a build it warns and skips, silently losing the only two-process test. Everything else resolves @issueforge/* to src.

The one rule enforced mechanically

contracts  ->  core  ->  adapters  ->  apps/cli
 (no deps)    (pure)     (io only)     (wiring)

core imports only contracts — no node:fs, node:sqlite, execa, gh. No adapter imports @octokit or any GitHub API client. Nothing imports the CLI. tests/import-boundaries.test.ts fails CI on a violation. It is what stops IssueForge drifting into a coding-agent framework.

That test once guarded three deleted directories, caught its own ENOENT, and passed by checking nothing. When you add a boundary test, make it fail first.

Where new code goes

• New task (fix, verify) → a TaskDefinition value (kind, buildCard, resultSchema) in adapters/src/runner/task-runner.ts, then register it in TASKS in main.ts and in INTENT_LABELS in contracts/src/github.ts. Do not copy TaskRunner — its ordering is crash-safety logic and a second copy will rot.
• New harness → adapters/src/harness/<name>/.
• New CLI command → apps/cli/src/commands/<name>.ts exporting a doer (runX, returns data) and a renderer (renderX, returns a string), then wire it into buildProgram() in main.ts. Commands never touch stdout themselves — that split is what makes them testable. Get dependencies from createContext(); never construct adapters directly. Set process.exitCode, never call process.exit.
• New I/O → adapters; new rules about what a run may do → core/domain; new vocabulary → contracts.