[alexanderludwig]

What this is

A local "factory" that takes one GitHub issue (or task file) to a branch ready for a PR. It's pstack 0.15.25 run as is, plus a thin layer of AntSeed glue. Everything sits under .factory/.

The base is codex/sandbox-stack (#1145), so this diff shows only the factory. #1145 keeps only the sandbox and the verify-antseed skill (with prove.sh).

This PR is the main "make the repo agent-ready" change. It has the architecture knowledge, which any agent reads (factory or not), and the factory glue.

Architecture knowledge

File	Purpose
root CLAUDE.md → ## Design principles	Credibly neutral: use existing standards and keep them intact, extend through plugins and policies, keep hosts thin (desktop and gateway changes go through the CLI, not the core), keep money stable and logic swappable.
root CLAUDE.md → ## Invariants	5 rules for the whole repo, each with what enforces it. Rules for one area live in that area's guide.
11 area guides: packages/{node,buyer-core,protocol,api-adapter,router-core,web-sdk,contracts}, plugins, apps/{cli,desktop}, apps/cli/src/gateway	Short and not standalone: one paragraph on what the area is and why, a rules table with what enforces each rule, and an Ask-first line. Nothing from the root is repeated.

Factory glue (.factory/)

File	Purpose
start.sh	Makes the worktree, the task file, the orch store and the session settings (model pin to the AntSeed buyer, no push, Bash sandbox, deny rules), then launches claude with pstack and the plugin. FACTORY_RESUME=<id> reopens a session.
RUN.md	The session's first message: the task, the exit condition, where AntSeed's files are, and how pstack's Cursor names map to Claude Code.
orchestrator.md	Our dispatcher. It replaces poteto-mode's Playbooks section: it routes the task to a pstack playbook (an architecture change goes to figure-it-out), adds overlays for area rules, high blast radius and user-visible changes, adds AntSeed steps to named playbook steps, and handles verification and done: one swarm at the code-ready head and a single verifier per later head (Autopilot-full step 4). Findings are sorted with interrogate's buckets: one that is no worse than main is never Act on. Plans name the smallest change (principle-laziness-protocol), a second writer to shared state needs a reason, and repeated fix rounds on one premise trigger principle-attack-the-premise and a scope gate. It also sets how subagents are briefed: Orchestrate's brief template, standing orders in orch/preferences.md (seeded by start.sh), short reports, a lead that keeps only summaries and checkpoints with Pause safely.
root CLAUDE.md rewrite	About 75 lines, down from about 270: working rules, principles, invariants, an area map, the payment flow, commands. The old local-testing recipe is replaced by pnpm sandbox.
add-migration skill	Lists the third migration domain, verification.
pstack-models.md	pstack's model table per role: opus writes code, astra verifies, review panels mix opus, fable, astra and sol.
sandbox-run.sh	Runs one --chain local sandbox scenario outside Claude Code's Bash sandbox (sandbox.excludedCommands), because forge panics inside it. Refuses --live, --real-funds and mainnet.
plugin/agents/*	astra and sol (model pins) plus read-only reviewer versions.
git-hooks/pre-push, check-push-gap.sh	Block pushes from the session, and prove the known routes are refused.

Process

The playbook steps are pstack's, referenced and never copied. The dispatcher (orchestrator.md) is ours. See .factory/README.md → "The process: pstack's steps, our dispatcher".

Tried on

• Stale catalog fields survive peer cache refresh #1251: draft PR [security-critical] refactor(node): Always set the catalog maps on discovered peers #1284.
• Data not resetting on AI VPN #1050 (phantom active channels): in progress.

Not a user-facing change

This is dev tooling and agent docs only, so there's no CHANGELOG entry.

Known limits

See .factory/README.md → Known limits. localhost stays reachable, the no-push env is a speed bump, and the model pin is set once per session.