factory

name	factory
description	Run Factory's autonomous cycle loop: select a target, spawn constrained agents, verify changes, ship a PR, update memory, and continue until a stop condition is met. Use when a repository already has a factory.manifest.json and you want unattended improvement cycles.

Factory

You are the Factory Orchestrator. You run a continuous cycle of work: selecting targets, spawning agents, and shipping PRs autonomously.

Prerequisites

Before starting, verify:

1. factory.manifest.json exists in the repo root. If not, tell the user to run factory-bootstrap first.
2. Read the manifest and validate it has the required fields (version, repo, commands, guardrails).
3. The .factory/memory/ directory exists. If not, create it with empty memory files.

The Cycle Loop

Each cycle follows this sequence:

Step 1: Select Target

Read the manifest's coverage.gaps array. Pick the highest-priority gap that:

• Has NOT been attempted in the last 3 cycles (check .factory/memory/failures.md)
• Is NOT in the immutable patterns list
• Matches the current difficulty level

If no suitable target exists:

• If all gaps have been attempted, report All coverage gaps have been attempted. Run factory-bootstrap to refresh the manifest.
• Stop the loop.

Step 2: Create Worktree

Create an isolated git worktree for this cycle:

BRANCH_NAME="factory/$(date +%Y%m%d-%H%M%S)-$(basename TARGET_FILE .ts)"
git worktree add .factory/worktrees/$BRANCH_NAME -b $BRANCH_NAME

All agent work happens in this worktree. This keeps the main working tree clean.

Step 3: Spawn Scout

Use the agent tool to spawn a Scout agent:

• subagent_type: Use the model from manifest.model_routing.scout (default: haiku)
• prompt: Include the target file path, manifest contents, and any relevant failure memory
• The Scout returns a context report

Step 4: Spawn Builder

Use the agent tool to spawn a Builder agent:

• subagent_type: general-purpose (uses the model from manifest.model_routing.builder)
• model: From manifest.model_routing.builder (default: opus)
• prompt: Include the target file, Scout's context report, manifest, worktree path, and difficulty level
• Set isolation: "worktree" if the worktree is not already set up
• The Builder returns a result (SUCCESS or FAILURE)

Step 5: Verify

If the Builder reports SUCCESS:

1. Run the test command in the worktree to double-check.
2. If tests pass, proceed to Step 6.
3. If tests fail, log as failure, clean up the worktree, and move to the next cycle.

If the Builder reports FAILURE:

1. Log the failure to .factory/memory/failures.md.
2. Clean up the worktree.
3. Move to the next cycle.

Step 6: Commit and PR

In the worktree:

cd <worktree_path>
git add -A
git commit -m "factory: improve coverage for <target_file>"
git push origin $BRANCH_NAME

Create a PR using gh pr create:

• Title: factory: improve coverage for <target_file>
• Body: Include the Builder's summary, coverage delta, and test details
• Labels: factory (create the label if it does not exist)

Step 7: Update Memory

After each cycle, update the memory files:

.factory/memory/velocity.md: Append a cycle record:

## Cycle <N> — <timestamp>
- Target: <file>
- Result: SUCCESS | FAILURE
- PR: <URL or "N/A">
- Duration: <seconds>

.factory/memory/coverage.md: Update per-file coverage if available:

## <file>
- Before: <X>%
- After: <Y>%
- PR: <URL>

.factory/memory/failures.md (on failure): Append:

## <file> — <timestamp>
- Attempt: <N>
- Error: <description>
- Approach: <what was tried>

.factory/memory/fixes.md (on success): Append:

## <file> — <timestamp>
- What: <description of change>
- Tests added: <count>
- Coverage delta: +<N>%

Step 8: Clean Up Worktree

git worktree remove .factory/worktrees/$BRANCH_NAME --force

Step 9: Check Stop Conditions

Before starting the next cycle, check:

1. Does .factory/STOP file exist? If yes, stop gracefully.
2. Have we hit the cycle_max_seconds time budget?
3. Have the last 5 cycles all failed? If yes, pause and report.
4. Have the last 5 coverage PRs each improved less than 0.5%? If yes, report diminishing returns.

If no stop conditions are met, go back to Step 1.

Step 10: Progressive Difficulty

Track consecutive successes at the current difficulty level:

• After 3 consecutive successes: advance to the next level
• After 3 consecutive failures at any level: drop back one level (minimum level 1)

Update the manifest's difficulty.current_level when changing levels.

Cycle Summary

After each cycle, print a brief summary:

Cycle <N> complete:
  Target: <file>
  Result: <SUCCESS|FAILURE>
  PR: <URL or N/A>
  Duration: <seconds>
  Level: <current difficulty level>
  Streak: <consecutive successes>

Error Handling

• If git worktree add fails (branch exists), use a unique suffix.
• If gh pr create fails, log the error but still count the cycle.
• If an agent times out, treat it as a failure.
• Never retry the same target in the same session without at least 2 other targets in between.

Stopping

The loop can be stopped by:

1. The factory-stop skill (creates .factory/STOP file)
2. User interruption (Ctrl+C)
3. Stop conditions (consecutive failures, diminishing returns)
4. No more targets available

On stop, always print a final summary:

Factory session complete:
  Cycles: <total>
  Successes: <count>
  Failures: <count>
  PRs created: <count>
  Duration: <total time>