# @super-repo/factory

> Autonomous software factory for the `super` monorepo workflow — pulls work from a backlog and ships it across a stack with hard guardrails.

[![NPM](https://nodei.co/npm/@super-repo/factory.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/@super-repo/factory)

[![npm version](https://img.shields.io/npm/v/@super-repo/factory.svg)](https://www.npmjs.com/package/@super-repo/factory)
[![npm downloads](https://img.shields.io/npm/dm/@super-repo/factory.svg)](https://www.npmjs.com/package/@super-repo/factory)
[![license](https://img.shields.io/npm/l/@super-repo/factory.svg)](./LICENSE)

Autonomous bots like Renovate or Dependabot solve one slice — keeping deps fresh. CLI agents like aider solve a different slice — turning a single human prompt into a single PR. There's no shared piece for "take a backlog, ship it across a multi-repo stack, gate every step on CI, and never let one runaway iteration corrupt the project." Factory is that piece.

The loop pulls candidate features from a multi-source backlog (curated, GitHub issues, heuristic `[ ]` items in `ROADMAP.md`), runs each through `feat → build → ship → merge`, waits for `main` to go green, and loops — with hard guardrails (forbidden-paths, diff caps, cost cap, kill-switch) and full state on disk so a halted run can resume cleanly.

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.

## Getting started

```sh
pnpm add -D @super-repo/factory
```

```ts
// super.config.ts — the 4-6 fields a typical operator touches
export default {
  stack: [
    { name: '@super-repo/cli', path: 'packages/libs/cli' },
    { name: '@super-repo/mcp', path: 'packages/libs/mcp' },
  ],
  factory: {
    models: {
      grill: 'claude-opus-4-7',           // PRD enrichment — smarter pays back
      build: 'claude-sonnet-4-6',         // implementer subagents
      mergeResolver: 'claude-sonnet-4-6', // conflict resolution
    },
  },
};
```

```sh
# one-shot run, with cost ceiling
npx super factory run --max-iterations=1 --max-cost=2

# inspect what halted (or what's currently in flight)
npx super factory status
```

For everything else — full schema, guardrail reference, resilience features, CI/cron recipes — see [Docs](#docs).

## Features

- **Autonomous loop** — pick → PRD → build → ship → wait-for-green → loop. Runs unattended for hours.
- **Multi-source backlog** — curated tasks, GitHub issues with a label, heuristic `[ ]` items from `ROADMAP.md` + `TODO:` / `FIXME:`. Ranked + deduplicated against shipped slugs.
- **Parallel build, serial ship** — `/super build` fans out one implementer subagent per stack repo concurrently; PRs then merge one at a time in dependency order.
- **Hard guardrails** — `forbiddenPaths` per repo, `--max-diff-files` / `--max-diff-lines`, `--max-cost <USD>`, kill-switch file (`.super/factory.stop`). Every guardrail halts cleanly and reports a `HaltReason`.
- **Resilience pack** — lockfile, retry-with-backoff, stale-PR detection, branch-protection check, per-slug failure quarantine, heartbeats during long polls, CI flake tolerance, resume mode, halt webhooks.
- **SSH-signed commits** — container image preset for SSH commit signing with agent forwarding so the private key never lives on disk inside the container.
- **Per-scope model selection** — `grill`, `propose`, `build`, `mergeResolver` each take their own Claude model. Smarter for PRD enrichment, sonnet for everything else.
- **Hand-readable state** — `.super/state/factory.json` and per-slug files written atomically. Safe to inspect or hand-edit between runs.

## CLI

| command                                    | what it does                                                                                          |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `super factory run`                        | Run the loop — opens PRs, auto-merges, halts on guardrail trip. Flags: `--max-iterations`, `--build-iterations`, `--max-cost`, `--include-proposed`, `--github-label`, `--resume`, `--dry-run`. |
| `super factory onboard [<repo>]`           | Show readiness checklist for stack repos and scaffold missing pieces (`.factory.json`, auto-approve workflow, ROADMAP template). `--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.                                             |
| `super factory cleanup --older-than-days N`| Archive shipped PRDs older than N days into `tasks/archive/`.                                         |

Full per-flag reference and runtime overrides: [docs/configuration.md](./docs/configuration.md).

## Comparison

| feature                                       | @super-repo/factory | renovate / dependabot | aider / swe-agent  | hand-rolled CI bots |
| --------------------------------------------- | :-----------------: | :-------------------: | :----------------: | :-----------------: |
| **Autonomous, multi-iteration loop**          | ✓                   | scheduled, single-pass| ✗ (single PR)      | depends             |
| **Multi-repo stack as a unit**                | ✓                   | ✗                     | ✗                  | hand-rolled         |
| **Backlog from multiple sources**             | ✓                   | dep updates only      | per-prompt         | hand-rolled         |
| **Hard per-iteration guardrails**             | first-class         | n/a                   | bolt-on            | hand-rolled         |
| **Forbidden-paths / diff caps / cost cap**    | ✓                   | ✗                     | ✗                  | hand-rolled         |
| **Kill-switch + resume mode**                 | ✓                   | n/a                   | ✗                  | rare                |
| **SSH-signed commits**                        | ✓ (preset)          | n/a                   | optional           | hand-rolled         |
| **State on disk, MCP-introspectable**         | ✓                   | ✗                     | ✗                  | rare                |

The value-prop is **autonomous loop with hard guardrails** vs ad-hoc bot scripts: Renovate is a great dep-updater but doesn't ship features; aider is a great per-prompt agent but doesn't loop; CI bots can do anything but you wear the orchestration code. Factory is the orchestration code, with the guardrails and resilience built in so the bot doesn't need a human babysitter.

## Cron & CI

Factory is invoked by cron, GitHub Actions schedules, or a long-lived container — not as a per-commit hook. A typical Actions schedule runs every 2 hours with a per-run cost ceiling:

```sh
npx factory run --max-iterations=2 --max-cost=3 --webhook-url="$SLACK_WEBHOOK"
```

See [docs/integrations.md](./docs/integrations.md) for cron, GitHub Actions, container, MCP visibility, and webhook recipes.

## Docs

Deep references and worked examples live alongside this package in [./docs/](./docs/):

- **[configuration.md](./docs/configuration.md)** — full `.factory.json` schema, `super.config.ts#factory`, `RunLoopOptions` programmatic API, model selection, discovery walk.
- **[guardrails.md](./docs/guardrails.md)** — every `HaltReason`, kill-switch wiring, `forbiddenPaths`, diff caps, cost cap, branch-protection check, per-slug quarantine.
- **[resilience.md](./docs/resilience.md)** — lockfile, retry-with-backoff, backlog dedup, stale-PR detection, heartbeats, CI flake tolerance, resume mode, atomic state writes, halt notifications.
- **[integrations.md](./docs/integrations.md)** — cron, GitHub Actions, container deployment with SSH agent forwarding, MCP visibility, AI auth, webhook receivers.
- **[recipes.md](./docs/recipes.md)** — onboard a repo, dry-run loop, continuous local/CI operation, container, resume after halt, Slack notifications, programmatic embedding.
- **[architecture.md](./docs/architecture.md)** — loop pipeline, subagent orchestration (build / merge-resolver / self-grill), `ai-*/*` branching model, per-repo factory contract, state-file layout, design decisions, v1 limitations.

## References

- [`@super-repo/cli`](../cli) — host CLI exposing the `super factory ...` subcommands.
- [`@super-repo/mcp`](../mcp) — MCP server with read-only `super_factory_status`, `super_factory_history`, `super_factory_backlog`, `super_factory_propose` tools for cross-agent introspection.
- [`@super-repo/super-skill`](../super-skill) — defines the `/super build` skill that the factory dispatches per iteration.
- [Project README](../../../README.md)

## License

MIT — Super-Repo contributors. See [LICENSE](./LICENSE).