@super-repo/factory

Autonomous software factory for the super monorepo workflow. Pulls candidate features from a multi-source backlog, runs them through feat → build → ship → merge, waits for main to go green, and loops — with hard guardrails and a kill-switch.

The factory is not the /super lifecycle replacement. It calls into /super build (parallel implementer subagents) and the existing super CLI primitives, then handles the per-repo PR + auto-merge orchestration itself.

What it does

pick top backlog item
  └── write minimal PRD to tasks/<slug>.md
      └── /super build <slug>            (parallel implementer subagents)
          └── for each repo, in dependency order:
              ├── stage + commit + push (signed)
              ├── gh pr create
              ├── gh pr merge --auto --squash
              ├── poll for merge or conflict
              │   └── on conflict → dispatch `merge-resolver` subagent → retry once
              └── after last repo, poll main checks → green
loop

Design decisions (from tasks/factory.md)

• Parallel build, serial ship. Reuses /super build; PRs merge one repo at a time in dependency order.
• Auto-merge via auto-approver Action. super factory onboard scaffolds .github/workflows/factory-auto-approve.yml so PRs from the configured bot identity get approval automatically and gh pr merge --auto can close.
• Wait for main post-merge CI green between iterations. Bound by a 30-min timeout. On timeout, halt and surface the stalled PR.
• Merge-resolver subagent on conflict. The factory shells out to claude --print --agent merge-resolver ...; if the resolver fails, the loop halts.
• Container with SSH agent forwarding. Image only contains pubkey + git config; private key never on disk inside the container.
• JSON state files with atomic writes. .super/state/factory.json (current) + .super/state/<slug>.json (per feature). Readers retry once on parse error.
• Heuristic idea generation. Self-proposed candidates come from [ ] items in ROADMAP.md plus TODO: / FIXME: markers. AI-driven proposal is deferred (--ai-propose flag reserved).

Subcommands (via super factory ...)

| Command | Purpose | | --- | --- | | super factory run | Run the loop — opens PRs, auto-merges, halts on guardrail trip. --max-iterations, --build-iterations, --include-proposed, --github-label, --dry-run. | | super factory onboard [<repo>] | Show readiness checklist for stack repos and scaffold missing pieces. --write selects which files. | | super factory status | Print current factory state and recent history. | | super factory backlog | Print the merged ranked backlog. | | super factory propose | Generate heuristic backlog candidates without enqueueing. |

Per-repo factory contract

For a stack repo to participate:

• ROADMAP.md — anchor for idea generation ([ ] items become candidates).
• .factory.json — declares test/lint/build commands, forbiddenPaths globs, autoMerge boolean, mainBranch, autoApproveBot.
• .github/workflows/factory-auto-approve.yml — auto-approves PRs authored by the configured bot.
• A CI workflow that produces a status check (the auto-merge gate).
• Branch protection on main requiring CI green + 1 approval.

super factory onboard <repo> scaffolds the first three and prints next steps for CI + branch protection.

Container

Reference image and compose file under docker/. Designed for SSH agent forwarding so the private key never lives in the container:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_signing
export GH_TOKEN=$(gh auth token)
docker compose -f packages/factory/docker/compose.example.yml up

The image's /etc/gitconfig is preset for the interc0der identity with SSH commit signing on. Override with GIT_USER_NAME, GIT_USER_EMAIL, SUPER_SIGNING_PUB env vars.

State + visibility (MCP)

The factory writes to .super/state/. The MCP server (@super-repo/mcp) exposes read-only tools so other agents can introspect:

• super_factory_status — current iteration + phase
• super_factory_history — past iterations (JSONL)
• super_factory_backlog — merged ranked queue
• super_factory_propose — on-demand heuristic candidates

Kill-switch

Create .super/factory.stop to halt the loop at the start of the next iteration. The factory never auto-removes it; the user clears it when ready to resume.

Limitations (v1)

• No daemon mode. The loop is a foreground CLI command (or a single container).
• No multi-machine fan-out.
• No paid-CI integration. Polls GitHub Actions check runs only.
• Idea generation is heuristic-only; AI-driven proposal is reserved as --ai-propose.
• Merge-resolver dispatches via claude CLI shell-out; without claude in PATH, conflicts halt the loop.