Factory

Run the factory pipeline for: $ARGUMENTS

What this does

Factory ships one milestone (== one roadmap phase) at a time. It scans the milestone's open issues, generates missing specs via speckit, then launches up to 5 parallel worktree writer agents — each implementing one issue on its own branch with lint+typecheck+tests as a hard gate before opening a PR. Every PR is then reviewed by a separate, fresh-context reviewer agent (writer/reviewer separation per CLAUDE.md). Reviewer findings are fixed via the writer agent resumed in-place (warm context, cheap), bounded to 2 fix cycles. The final review verdict is posted to the PR. Factory stops with PRs open for human merge — no auto-merge.

For multi-phase roadmap execution use /autopilot instead. Factory is scoped to exactly one phase/milestone per invocation.

You are the orchestrator (opus). You do not implement, review, or fix code yourself. You dispatch agents (sonnet) and aggregate their structured returns. You never read PR diffs or full review prose into your own context — only {verdict, cycles, pr_url} summaries.

Convention: phase ↔ milestone

A roadmap phase file docs/roadmap/_.md corresponds to a GitHub milestone whose title exactly equals _ (e.g., phase file 003_auth.md ↔ milestone 003_auth). This is how /issues files them and how factory resolves them. No frontmatter, no labels — title match only.

Parse Arguments

Factory requires exactly one phase/milestone per invocation. Reject calls without a target.

• /factory — e.g., /factory 003_auth. Resolves to roadmap file docs/roadmap/003_auth.md AND milestone titled 003_auth. Both must exist (phase file is the source of truth for spec paths and file lists; milestone is the source of truth for which issues are still open).
• /factory --milestone — fetch milestone ` via gh api, read its title, then resolve the matching docs/roadmap/.md. Equivalent to /factory `.
• --no-issues: skip GitHub issue creation if a spec exists but no issue is filed yet (still requires a milestone for scoping).
• --dry-run: scan and report the planned batches + review-loop budget, spawn nothing.
• --limit N: override the default 5-agent parallel cap (use carefully).

If no argument is passed, STOP and tell the user: > Factory requires a phase or milestone. Use /factory or /factory --milestone . For full-roadmap execution, use /autopilot.

Phase 0: Preflight — Fix friction before it bites

Run all checks in parallel before touching anything else. A single failure here costs 10 seconds; discovering the same failure mid-pipeline wastes 10 minutes.

0a. Directory check

git rev-parse --show-toplevel 2>/dev/null

If this fails: STOP. Tell the user: > You are not inside a git repository. cd to the project root first, then re-run /factory.

If the output does not match the current working directory, STOP: > Current directory ` is not the repo root . Run /factory from `.

0b. Git state check

git status --short
git branch --show-current

If there are uncommitted changes on main or the default branch, warn (don't block): > Working tree has uncommitted changes on main. These will not appear in worktrees. Commit or stash before continuing if they're needed by agents.

0c. gh auth + scope check

gh auth status 2>&1

Parse the output:

• If not logged in → STOP: "Run gh auth login first, then re-run /factory."
• If logged in but project scope missing → warn unless --no-issues is set:

> gh is authenticated but missing the project scope. GitHub issue creation will be skipped. > To enable it: gh auth refresh -s project > Or re-run with --no-issues to suppress this warning.

Record HAS_PROJECT_SCOPE=false and continue (issue creation will be skipped).

• If logged in with project scope → HAS_PROJECT_SCOPE=true.

0d. Roadmap exists check

ls docs/roadmap/*.md 2>/dev/null

If no files → STOP: > No roadmap files found in docs/roadmap/. Create a roadmap first with /roadmap.

0e. Build command discovery

Read CLAUDE.md (project-level, then global) for lint, typecheck, and test commands. Also check:

• package.json scripts for lint, typecheck/type-check, test
• Makefile for lint, test, check targets
• pyproject.toml / Cargo.toml for test commands

Record the resolved commands as:

LINT_CMD=
TYPECHECK_CMD=
TEST_CMD=

If any command can't be resolved, note it — agents will be told to discover it from the codebase.

0f. Report preflight results

## Preflight

✓ Repo root: /path/to/project
✓ Branch: main (clean)
✓ gh auth: logged in as @username
⚠ gh project scope: missing (issue creation skipped — run `gh auth refresh -s project` to enable)
✓ Roadmap: 4 phase file(s) found
✓ Build commands: lint=`pnpm lint`, typecheck=`pnpm typecheck`, test=`pnpm test`

---

Phase 1: Milestone Scan — What needs to be done

1a. Resolve phase + milestone

From the parsed argument, you have a phase name (e.g., 003_auth).

1. Confirm the phase file exists: docs/roadmap/.md. If not → STOP: "Phase file docs/roadmap/.md not found. Run /roadmap or check the phase name."
2. Resolve the milestone by title:

``bash gh api "repos/{owner}/{repo}/milestones?state=open" --jq ".[] | select(.title == \"\")" ` If not found → **STOP**: "No open milestone titled . Run /issues ` first to create the milestone and issues."

1b. Pull open issues for the milestone

gh issue list --milestone "" --state open --json number,title,body,url,labels

Closed issues are considered done — they are excluded from this run. No PR-status check needed; closed = shipped.

1c. Resolve spec path per issue

For each open issue, grep the issue body for a spec path. Convention from /issues: the body contains a line like Spec: docs/specs/003_auth/login.md or a markdown link [spec](docs/specs/...).

• If the spec path is present and the file exists → state = spec-ready
• If the spec path is present but the file is missing → state = unstarted (will spec-gen in Phase 2)
• If no spec path is in the body → fall back to scanning the phase roadmap file for a task whose name matches the issue title; if found, use its spec path. If still nothing → state = unstarted with the issue title used as the feature slug

1d. File-overlap analysis (NEW — borrowed from /autopilot)

For each in-scope feature, extract the files-touched list from its spec (look for ## Files, ## Files Touched, or the roadmap task entry). Build a file→features map.

Two features whose file sets intersect must not run in the same batch. Group features into the minimum number of batches such that:

• Each batch has ≤5 features (or --limit N)
• No two features in the same batch share any file in their touched-files list
• Within a batch, no feature depends on another feature in the same batch (dependencies from spec/roadmap)

Use a simple greedy bin-packer: sort features by files-touched count descending; place each into the first batch where it doesn't collide; create a new batch if no fit.

If a feature's spec has no files list → place it alone in its own batch (treat unknown as "may collide with anything"). Note this in the report so the user can fix the spec.

1e. Report scan + plan

## Milestone Scan —  (milestone #)

Open issues: 12
In scope (open, not yet PR'd): 10
Already has PR: 2 (skipped — see #45, #46)

### Batches (file-overlap-aware, ≤5 per batch)

Batch 1 (3 features, no file collisions):
  • #12 auth-login        → docs/specs/003_auth/login.md       [spec-ready]
  • #13 auth-register     → docs/specs/003_auth/register.md    [spec-ready]
  • #15 password-reset    → docs/specs/003_auth/reset.md       [unstarted — will gen spec]

Batch 2 (2 features, would collide with batch 1 on src/auth/middleware.ts):
  • #14 auth-middleware   → docs/specs/003_auth/middleware.md  [spec-ready]
  • #16 session-store     → docs/specs/003_auth/session.md     [spec-ready]

Estimated review-loop budget: ~1.3× writer cost (best case 1.0×, worst 1.8× with 2 fix cycles).

Scope for this run: open issues with no existing PR. Skip issues that already have an open PR (search by `` in PR title).

If --dry-run is set: print the plan and stop here. > Dry run complete. N features would be processed in M batches. Remove --dry-run to execute.

---

Phase 2: Spec Generation — Fill gaps before building

For each unstarted task (spec does not exist), generate the spec using speckit. This phase runs sequentially — spec generation is interactive and context-dependent; parallelizing it corrupts the context.

For each unstarted feature, spawn a foreground subagent (not background — you need its output before continuing):

You are a spec generator for the feature: 

## Project context

## Task from roadmap

## Your job
1. Read the roadmap task above to understand scope, files, and dependencies.
2. Read any related specs that already exist (listed as dependencies in the task).
3. Run `/speckit-spec ` to generate the spec interactively.
   - The spec should be written to: 
4. Then run `/speckit-plan ` to generate the implementation plan.
5. Then run `/speckit-tasks ` to generate the task breakdown.
6. Return: the spec path created, any blockers encountered, and a one-line summary.

## Friction guards
- You are in: . Verify with `pwd` before running any command.
- If speckit asks for a design reference and none exists in `docs/design/`, note it as a blocker and continue with "Design reference: TBD" rather than halting.
- If speckit prompts are interactive, answer based on the roadmap task context.

After each spec subagent completes:

• Record: feature name, spec path created, blockers
• If spec creation failed: mark feature as blocked, note the reason, continue to next feature

Design reference check (UI features only)

Before spec generation for any task whose roadmap entry mentions "UI", "page", "component", "screen", or "view":

1. Check docs/design/ for a matching design file
2. Check Paper MCP (get_basic_info) if available — look for a matching artboard
3. If neither exists: warn and continue with a placeholder rather than blocking:

> ⚠ No design reference found for `. Spec will note "Design ref: TBD". Run /verify-design ` before implementation to catch mismatches early.

---

Phase 3: GitHub Issues — Put work on the board (optional)

Skip this phase if:

• --no-issues flag is set
• HAS_PROJECT_SCOPE=false (from preflight 0c)

For each feature with a newly created or existing spec:

3a. Discover the project board

gh project list --owner  --format json 2>&1

If no projects found: skip issue creation, warn: > No GitHub Projects found for this repo. Skipping issue creation. Use --no-issues to suppress this warning.

If multiple projects found: pick the one whose name contains "backlog", "roadmap", or matches the repo name. If ambiguous, use AskUserQuestion to let the user select.

3b. Create issues

For each in-scope feature, check if an issue already exists:

gh issue list --search " in:title" --json number,title,url

If an issue already exists: skip creation, record its URL.

If no issue exists, create one:

gh issue create \
  --title ": " \
  --body "$(cat 

## Spec

 (generated by /factory)

## Acceptance criteria

## Dependencies

---
*Created by /factory*
EOF
)" \
  --label "ready"

Then add to project board in "Ready" status:

gh project item-add  --owner  --url 

If gh project item-add fails with a scope error: record the failure, continue. Issues are created even if board placement fails.

Record: feature → issue URL.

---

Phase 4: Stop Hook — Gate PRs behind quality checks

Before launching any implementation agent, register a quality gate in the project's .claude/settings.json.

Read the current .claude/settings.json (create it if absent). Add a Stop hook that runs lint, typecheck, and tests:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": " &&  && ",
            "description": "factory quality gate — lint + typecheck + tests must pass before stopping"
          }
        ]
      }
    ]
  }
}

If settings.json already has Stop hooks, append to the hooks array — never overwrite existing hooks.

Save the previous Stop hook state (or absence) so Phase 6 can restore it after the run.

Note to implementation agents: The Stop hook will run automatically when you finish. If it fails, you must fix the failures before you can stop. Do not bypass with --no-verify. This is intentional — it means broken code cannot be committed.

---

Phase 5: Parallel Implementation — ≤5 agents, each in its own worktree

Collect all features with status unstarted (spec now exists) or spec-only. Cap at 5 at a time.

If more than 5 features are in scope, process them in batches of 5. Complete each batch (all agents done or failed) before starting the next.

5a. Dispatch batch

Spawn all agents in the batch in a single message using the Agent tool with:

• isolation: "worktree" — each agent gets its own git worktree and branch
• run_in_background: true — all run concurrently
• model: "sonnet" — cost-efficient for implementation work

Each agent receives this prompt:

## Factory Agent — Feature: 

## Preflight (run these FIRST before anything else)

1. Verify directory: `pwd && git rev-parse --show-toplevel`
   - Both must print the same path: 
   - If they differ, `cd ` before continuing.
2. Verify you're on the right branch: `git branch --show-current`
   - Should be a new worktree branch, not `main`.

## Project Context

## Build & Test Commands

- Lint: 
- Typecheck: 
- Test: 

## Test Strategy

## Your Feature

- **Name:** 
- **Spec:**  — READ THIS FIRST
- **Plan:** 
- **Tasks:** 
- **Files to touch:** 
- **Dependencies:** 
- **Verification:** 
- **GitHub issue:** 
- **Design reference:**  first">

## Instructions

### Step 1 — Read everything before writing anything
Read the spec, plan, and tasks files fully. Also read:
- Any specs listed as dependencies above
- Existing source files you'll be modifying (understand what's there before changing it)
- 1-2 existing test files to understand test patterns

**UI features only:** If a design reference is provided, run `/verify-design ` before writing any component code. List mismatches from the report before proceeding. If design ref is "TBD", note it in the PR and proceed with best-effort alignment.

### Step 2 — Implement following the spec and task breakdown
Follow the task order from tasks.md (if it exists). Write tests alongside implementation:
- Unit tests for logic
- Integration tests for API/DB boundaries
- E2E only if the spec explicitly requires it

### Step 3 — Quality gate (REQUIRED before creating any PR)

Run each command in sequence and **paste the last 30 lines of output**:

2>&1 | tail -30 2>&1 | tail -30 2>&1 | tail -30

**If any command fails:** fix the issue, re-run the failing command, paste the new output. Repeat until all three pass. Do NOT create a PR while any check is failing.

If you cannot fix a failure after 3 attempts, document the failure clearly and stop — do not create a PR.

### Step 4 — Commit and push

Commit with conventional commit messages, split by logical concern. Push the worktree branch.

**Do NOT run code review yourself.** Review happens in a separate fresh-context agent after the PR is open (writer/reviewer separation per CLAUDE.md). You may be resumed later with specific findings to fix — at that point, fix exactly what's listed and re-run the quality gate. Do not interpret, debate, or expand scope.

### Step 5 — Open PR

Create a PR targeting `ma

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [0xrafasec](https://github.com/0xrafasec)
- **Source:** [0xrafasec/ai-workflow](https://github.com/0xrafasec/ai-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.