Factory documentation / Use the factory

Use the factory

Run one station or an ordered Line. Read the result and routing policy before automating.

Run one station

./factory list
./factory run secret-scan --target . --sink file
./factory run docs-drift --target . --engine pi --sink file

--target accepts a registered name or local directory. The engine is selected automatically unless overridden. Only choose Beads where the target has a configured destination.

Run a Line

./factory line project-audit --target . --sink file
./factory line web-excellence --target . --sink file

Stations run in declared order. Read the Andon policies before relying on a Line as a gate; an environment failure and a finding are different outcomes. (To audit the software factory itself, point --target at a separate clean clone rather than the running checkout, which houses the active findings store.)

Sinks & visibility

File

Default local fallback. Review the local delta outside the published Pages site.

Beads

On a configured target, medium-and-above triaged findings file automatically and dedupe by fingerprint. Missing visibility withholds high/critical from the synced tracker.

No public findings issue sink.

github-issues is rejected as a findings sink. The issue-triage station handles public input; promote links an approved public issue to a Beads item. Do not publish raw run evidence.

For ad-hoc paths, --visibility public|private declares routing policy; a registered target’s own declaration wins.

CLI at a glance

Each block below is generated from the factory’s own argument parser on every build, including nested subcommands. Wide usage lines scroll sideways inside their block. Run ./factory <command> --help for the options installed on your machine.

`integrate`

Print integration instructions and recipes for AI agents and CI/CD

usage: ./factory integrate [-h] [--agent]
                           [--section {all,github-actions,pre-commit,target,skills,agents}]

options:
  --agent                   Format specifically for AI agents (machine-actionable markdown)
  --section {all,github-actions,pre-commit,target,skills,agents}
                            Specific integration section to output

`list`

List all available agents

usage: ./factory list [-h]

`promote`

Promote a human-approved public issue to one linked bead

usage: ./factory promote [-h] --target TARGET --issue ISSUE

options:
  --target TARGET  Configured named public target
  --issue ISSUE    Approved public issue URL in the configured repo

`run`

Run an agent against a target

usage: ./factory run [-h] --target TARGET
                     [--engine {auto,pi,claude,antigravity,deepseek}]
                     [--model MODEL] [--sink SINK]
                     [--budget-minutes BUDGET_MINUTES]
                     [--visibility {public,private}]
                     agent

positional arguments:
  agent  Name of the agent to run (e.g. secret-scan)

options:
  --target TARGET           Target project name (from targets/) or path
  --engine {auto,pi,claude,antigravity,deepseek}
                            Engine to execute agent with
  --model MODEL             Model for the pi engine (default deepseek/deepseek-flash)
  --sink SINK               Override sink (file, beads, command; comma-separated for several)
  --budget-minutes BUDGET_MINUTES
                            Override station budget deadline in minutes
  --visibility {public,private}
                            Explicit target visibility for a raw --target path (a named target's manifest wins); missing still withholds high/critical from a synced tracker

`line`

Execute an ordered Factory Line composed of multiple stations

usage: ./factory line [-h] --target TARGET
                      [--engine {auto,pi,claude,antigravity,deepseek}]
                      [--model MODEL] [--sink SINK]
                      [--budget-minutes BUDGET_MINUTES]
                      [--visibility {public,private}]
                      line

positional arguments:
  line  Name of the line to run (e.g. project-audit)

options:
  --target TARGET           Target project name (from targets/) or path
  --engine {auto,pi,claude,antigravity,deepseek}
                            Engine to execute agents with
  --model MODEL             Model for the pi engine (default deepseek/deepseek-flash)
  --sink SINK               Override sink (file, beads, command; comma-separated for several)
  --budget-minutes BUDGET_MINUTES
                            Override station budget deadline in minutes for all stations in the line
  --visibility {public,private}
                            Explicit target visibility for a raw --target path (a named target's manifest wins); missing still withholds high/critical from a synced tracker

`hillclimb`

Run Class C goal-directed performance hill-climber with ledger

usage: ./factory hillclimb [-h] --target TARGET [--metric METRIC]
                           [--goal GOAL] [--iterations ITERATIONS] [--apply]
                           [--engine {auto,pi,claude,antigravity,deepseek}]
                           [--sink SINK] [--visibility {public,private}]

options:
  --target TARGET           Target project name or path
  --metric METRIC           Metric to optimize (perf_hazard_score, total_gzip_bytes, custom_bench_ms)
  --goal GOAL               Target numeric goal value
  --iterations ITERATIONS   Number of hill-climb iterations
  --apply                   Apply candidate edits in worktree, re-measure, keep wins, revert losses
  --engine {auto,pi,claude,antigravity,deepseek}
                            Engine to execute agent with
  --sink SINK               Override sink (file, beads, command; comma-separated for several)
  --visibility {public,private}
                            Explicit target visibility for a raw --target path (a named target's manifest wins); missing still withholds high/critical from a synced tracker

`hook`

Manage deterministic git pre-commit hooks (Rule 8 compliant)

usage: ./factory hook [-h] {install} ...

subcommands:
  install  Install sub-second secret-scan pre-commit hook

usage: ./factory hook install [-h] [--target TARGET] [--all]

options:
  --target TARGET  Target project name or path
  --all            Install across all configured targets in targets/

`skills`

Manage interactive CLI skills symlinks

usage: ./factory skills [-h] {install} ...

subcommands:
  install  Symlink all 22 factory skills into ~/.gemini and ~/.claude

usage: ./factory skills install [-h]

`schedule`

Manage launchd (macOS) and systemd (Linux) scheduled runs

usage: ./factory schedule [-h] [--list] [--generate] [--install] [--uninstall]
                          [--trigger] [--target TARGET] [--agent AGENT]
                          [--all]
                          [--platform {auto,launchd,systemd,darwin,linux,all}]
                          {list,generate,install,uninstall,trigger} ...

subcommands:
  list       List all scheduled agents and launchd/systemd status
  generate   Generate schedule units into schedules/
  install    Install and load scheduled agent
  uninstall  Unload/disable and remove scheduled agent
  trigger    Trigger immediate run of scheduled agent

options:
  --list                    List all scheduled agents and status
  --generate                Generate schedule unit files into schedules/
  --install                 Install and enable scheduled agent
  --uninstall               Disable and remove scheduled agent
  --trigger                 Trigger immediate run of scheduled service
  --target TARGET           Target name
  --agent AGENT             Agent name
  --all                     Operate on all explicitly scheduled target-agent pairs
  --platform {auto,launchd,systemd,darwin,linux,all}
                            Scheduler platform

usage: ./factory schedule list [-h]
                               [--platform {auto,launchd,systemd,darwin,linux}]

options:
  --platform {auto,launchd,systemd,darwin,linux}

usage: ./factory schedule generate [-h] [--target TARGET] [--agent AGENT]
                                   [--platform {auto,launchd,systemd,darwin,linux,all}]

options:
  --target TARGET           Target name
  --agent AGENT             Agent name
  --platform {auto,launchd,systemd,darwin,linux,all}

usage: ./factory schedule install [-h] [--target TARGET] [--agent AGENT]
                                  [--all]
                                  [--platform {auto,launchd,systemd,darwin,linux}]

options:
  --target TARGET           Target name
  --agent AGENT             Agent name
  --all                     Install all explicitly scheduled target-agent pairs
  --platform {auto,launchd,systemd,darwin,linux}

usage: ./factory schedule uninstall [-h] [--target TARGET] [--agent AGENT]
                                    [--all]
                                    [--platform {auto,launchd,systemd,darwin,linux}]

options:
  --target TARGET           Target name
  --agent AGENT             Agent name
  --all                     Uninstall all scheduled target-agent pairs
  --platform {auto,launchd,systemd,darwin,linux}

usage: ./factory schedule trigger [-h] --target TARGET --agent AGENT
                                  [--platform {auto,launchd,systemd,darwin,linux}]

options:
  --target TARGET           Target name
  --agent AGENT             Agent name
  --platform {auto,launchd,systemd,darwin,linux}