Factory

The control plane for running AI-driven software development in a loop. This repo defines the workflow — preferences, loop protocol, conventions. Software gets built in separate project repos under ~/apps/, each with its own issue tracker.

The maintainer plans interactively; an AI Loop Session consumes the queue and only pings when it has a question. See CONTEXT.md for the glossary and docs/adr/ for foundational decisions.

The loop at a glance

1. Plan (you, interactive): /grilling → /to-prd → /to-issues files tracer-bullet issues to the project's issue tracker, labeled ready-for-agent. An effort too big or foggy for one session gets charted first with /wayfinder — a map of decision tickets on the same tracker, resolved one per session until a spec is in reach; the loop never sees them (PROTOCOL.md, "Wayfinder maps").
2. Run (AI, autonomous): /factory in the project repo starts a Loop Session:
   • reads the newest handoff in .scratch/handoffs/, if any
   • picks the next unblocked ready-for-agent issue — priority first, then oldest — and moves it to a started state
   • implements subagent-driven (superpowers TDD subagents; the session only orchestrates), gated by /review
   • lands it: branch per issue → PR → auto-merge when tests, typecheck, and review are green → issue completed
   • questions: push notification + block ~15 min; unanswered → question posted to the issue, needs-info, work stays on its branch, loop continues
   • at each issue boundary: context above ~40% → /handoff to .scratch/handoffs/ and stop
   • empty queue → notify and stop; the loop never invents work
3. Steer (you, from anywhere): set priorities and answer needs-info questions in the tracker.

Resuming after a handoff, a reboot, or a week away is always the same command: /factory.

PROTOCOL.md is the full Loop Session spec; the /factory skill executes it (source in skills/factory/, shipped as part of the Factory plugin).

New project

Run /factory-new <name>. It will:

1. Create the repo under ~/apps/<name> with git + a private GitHub remote
2. Pick the issue tracker — GitHub Issues by default (the repo itself is the tracker), or Linear (a project on the Side projects team)
3. Stamp Factory conventions: .factory/config.json (the stamp — tracker, merge policy, attack surface, optional notifier), AGENTS.md, docs/agents/ (issue tracker, triage labels, domain docs), triage labels on the tracker, .scratch/ in .gitignore
4. Drop you into a Planning Session to produce the first issues

Existing project

Run /factory-adopt inside the repo. It will:

1. Stamp the repo with the same conventions as above, after detecting which tracker it already uses (an existing docs/agents/issue-tracker.md, open GitHub issues, or a GitHub remote paired with a matching Linear project) — creating the remote, labels, and any project the tracker needs only where missing, and merging into an existing AGENTS.md/CLAUDE.md rather than overwriting
2. Re-triage sweep: every open issue gets a category label (Feature/Improvement/Bug) + a state label (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix), and issues destined for agents get durable agent briefs written into them — you approve in batches
3. Leave the project loop-ready: /factory works from that point on

Already stamped, out of date

Run /factory-migrate inside the repo. A repo stamped by an older Factory — the legacy v1 stamp (an adapter doc with a Factory loop operations section, no .factory/config.json), or a v2 stamp below the plugin's current version — is migrated, not re-adopted. The skill detects the stamp, builds one combined plan for every pending step, shows one diff, and takes one approval. The v1-to-v2 step reads the tracker off the old adapter doc's title for one-tap confirmation and asks only what the old stamp cannot answer: merge policy and attack surface. Preflight names this skill whenever it finds a stale stamp, and /factory offers to run it at session start. PROTOCOL.md, "Migration", is the contract.

Conventions all projects share

• Issue tracker: GitHub Issues by default, Linear supported; one tracker per repo. See docs/agents/issue-tracker.md for the tool conventions.
• Triage labels: the five canonical states, 1:1 names. See docs/agents/triage-labels.md.
• Domain docs: single-context CONTEXT.md + docs/adr/ per repo, created lazily. See docs/agents/domain.md.
• Security sweeps: a Project with an attack surface carries an OWASP Top 10 sweep issue in every milestone that touches it; declines are recorded in its CONTEXT.md. See PROTOCOL.md, "Security sweeps".
• Git: branch per issue, PR, auto-merge on green. No half-done work on main — parked issues live on their branch.
• Context discipline: Loop Sessions stay under ~40% context; superpowers subagents do the implementation; /handoff bridges sessions.
• Notifications: an optional notifierCommand in .factory/config.json is the push channel — the plugin's Claude Code Notification hook and the runtime's own ping both run it with the message in FACTORY_NOTIFY_MESSAGE. Offered during adopt/migrate, declinable. See PROTOCOL.md, "Ping and Park".

Install

What the Factory assumes on the machine:

1. Claude Code, plus the Linear MCP server connected to the Side projects workspace for any Linear-backed Project.

2. gh authenticated, git over SSH.

3. Skills: superpowers and the engineering skills (/review, /handoff, /grilling, …) installed under ~/.claude/skills. New repos get their per-repo config (AGENTS.md, docs/agents/) via /setup-matt-pocock-skills, or via /factory-new for new projects and /factory-adopt for existing ones.

   Install superpowers yourself — the Factory's manifest declares no dependency on it, on purpose. A manifest dependency names a marketplace as well as a plugin, so it breaks on a machine that installed superpowers from a different one. Any marketplace will do; Preflight checks for the skills, not their provenance.

4. The Factory plugin, installed from its marketplace:

   /plugin marketplace add pedrosousa13/factory
   /plugin install factory

   Since this is a private repo, set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 — background pulls disable git credential helpers, so a failed pull would otherwise trigger a full re-clone.

   /factory should then show up in any Claude Code session's skill list.

Use

1. Plan in the project repo: /grilling an idea into shape, slice it into ready-for-agent issues (see "The loop at a glance").
2. Run /factory in the project repo and walk away. The Loop Session works the Queue and pings only when it has a question.
3. Steer from the tracker: reorder priorities, answer needs-info questions. Re-running /factory is always the right way to resume.

PROTOCOL.md is the contract for what the Loop Session does at every step.