agent factory.
Home/Documentation/Agent tools

Tools for coding agents.

Updated Read as Markdown ↗

Give your coding agent the commands to register work, inspect a capability, run a repair and verify the result. This reference covers all 36 commands in the current Factory CLI.

Run examples from your installed Factory checkout. npm run northstar -- invokes the CLI; factoryctl is the compatibility alias. These are terminal tools. For MCP connections, see MCP & integrations.

discover the installed command set
npm run northstar -- --help
npm run northstar -- intake --help

Promote an accepted problem recommendation

owner-decision promote takes a decision ID and explicit promotion input; --dry-run checks eligibility without writing. owner-decision work reads back the resulting work. V1 supports canonical_problem subjects; capability-level recommendations cannot be promoted directly. Promotion does not launch execution.

terminal
npm run northstar -- owner-decision --help

Start from the agent skills

  • .agents/skills/onboard-project/SKILL.md connects a repository, checks prerequisites and configures a project pack.
  • .agents/skills/intake-work/SKILL.md turns the owner’s request into classified work with acceptance criteria, then submits it through intake.

A compatible agent can discover these skills or read them directly. The pack defines project sources, commands and permissions.

Example: register an onboarding experiment

The agent classifies the request and prepares the batch. Save this example as intake.json after adapting it to the project:

intake.json
{
  "items": [
    {
      "request": "Test whether skipping optional setup improves onboarding conversion from 62% to 64%.",
      "classification": "experiment",
      "priority": "P2",
      "requester": "owner",
      "acceptanceCriteria": [
        "Compare eligible new accounts using the same 24-hour activation definition.",
        "Record the result and sample size for each experiment group.",
        "Keep project creation p95 below 2 seconds."
      ]
    }
  ]
}
register and inspect the work
npm run northstar -- intake --pack packs/my-app --file intake.json
npm run northstar -- backlog list --pack packs/my-app
npm run northstar -- checkpoint --pack packs/my-app

Intake returns created or deduplicated, a stable backlogItemId and an intakeDecisionId. It accepts verify, fix, feature, experiment or decision. Registering a request does not start execution.

Example: inspect history and propose a target

read the product and its history
npm run northstar -- map show --pack packs/my-app
npm run northstar -- map history --pack packs/my-app
npm run northstar -- memory report --pack packs/my-app
npm run northstar -- capability-success status --pack packs/my-app
npm run northstar -- product-advisor fact-pack --pack packs/my-app

Use the real capability ID returned by your map in place of onboarding. Its measurement source and success contract must already be declared.

measure, record a hypothesis, then ask the Advisor
npm run northstar -- capability-success measure --pack packs/my-app --capability onboarding
npm run northstar -- capability-success expect --pack packs/my-app --capability onboarding --hypothesis "Removing optional setup raises 24-hour activation from 62% to 64%."
npm run northstar -- product-advisor run --pack packs/my-app --agent muse
npm run northstar -- product-advisor brief --pack packs/my-app

Muse Spark uses the installed Muse CLI for the advisory step. A recorded hypothesis or accepted Advisor recommendation does not grant engineering or release permission.

The repair sequence

  1. checkpoint establishes whether to continue, resume a PR or stop.
  2. triage produces a bounded task packet.
  3. confirm-cause validates the cause and failing reproducer before the edit.
  4. The worker makes the approved change; confirm-fix validates tests and records remediation.
  5. record records the actual merge and release when authorized.
  6. verify checks the released behavior independently. cures keeps the repair available for later rechecks.

run supervises worker sessions; watch starts work on the configured schedule. A worker cannot award itself independent verification through record.

Complete command reference

Snapshot: 2026-09-15, framework revision 5b3cc3a. Names, syntax, subcommands and listed flags are taken from the CLI registry. Expand a command for its syntax; use installed --help for command-specific input schemas and version changes.

36 of 36 commands

Connect a project

preflightCheck prerequisites
Checks only

Checks Node, coding CLIs and GitHub tooling before a project is connected. Reports the missing prerequisite.

syntax · replace placeholders
npm run northstar -- preflight [--pack <dir>] [--agent <provider>]
Listed options
  • --pack <dir>
  • --agent <provider>
installed help
npm run northstar -- preflight --help
adoptConnect an existing repository
Creates a pack

Builds a project pack from Git history, including work, release markers and recurring activity. Review the proposed release convention.

syntax · replace placeholders
npm run northstar -- adopt --repo <dir> --pack <dir> [--yes] [--force] [options]
Listed options
  • --repo <dir>
  • --name <name>
  • --mission <text>
  • --north-star <metric>
  • --release-marker <tag|release|commit|none>
  • --release-pattern <regexp>
  • --routine-min <n>
  • --family-min <n>
  • --limit <n>
  • --offline
  • --yes
  • --force
installed help
npm run northstar -- adopt --help
refreshComplete readable product context
Writes with flags

Finds missing labels and user outcomes. --fix applies mechanical corrections; --propose asks an agent for reviewable wording.

syntax · replace placeholders
npm run northstar -- refresh [--pack <dir> | --packs <dir>] [--fix] [--propose] [--json]
Listed options
  • --pack <dir>
  • --packs <dir>
  • --fix
  • --propose
  • --propose-family
  • --propose-value
  • --agent <provider>
  • --batch <n>
  • --passes <n>
  • --from <file>
  • --json
installed help
npm run northstar -- refresh --help
truthRead current problems
Runs a probe

Runs the probe declared by the pack and returns identified signals with priorities. The configured probe determines source access.

syntax · replace placeholders
npm run northstar -- truth --pack <dir>
installed help
npm run northstar -- truth --help

Intake, mapping and planning

intakeTurn a request into durable work
Writes backlog intake

Validates a full batch of classified requests, checks existing evidence and duplicates, appends the intake decision and returns stable backlog IDs.

syntax · replace placeholders
npm run northstar -- intake --pack <dir> (--json <batch> | --file <path>)
Listed options
  • --json <batch>
  • --file <path>
installed help
npm run northstar -- intake --help
backlogManage declared work
Writes by subcommand

Lists, adds, links and changes work status. Can accept legacy Advisor gaps and import Strategist proposals. Status updates append history.

syntax · replace placeholders
npm run northstar -- backlog [list|add|accept|link|set-status|import-proposal] --pack <dir> [options]

Subcommands: listaddacceptlinkset-statusimport-proposal

Listed options
  • --title <text>
  • --priority <P1|P2|P3>
  • --evidence <text>
  • --id <id>
  • --status <status>
  • --signal <identity>
  • --family <key>
  • --gap <id>
  • --proposal <n>
installed help
npm run northstar -- backlog --help
roadmapReview and update the roadmap
Writes by subcommand

Reads and validates the roadmap, previews a patch, applies it or activates a node. Preview first and preserve revision checks.

syntax · replace placeholders
npm run northstar -- roadmap [status|validate|preview|apply|activate] --pack <dir> [--file <patch>]

Subcommands: statusvalidatepreviewapplyactivate

Listed options
  • --file <patch>
installed help
npm run northstar -- roadmap --help
milestoneSet a measurable project milestone
Writes by subcommand

Records a milestone, selects the active one or records completion. Declaring a target and achieving it are separate events.

syntax · replace placeholders
npm run northstar -- milestone [list|add|set|done] "<name>" --pack <dir> [options]

Subcommands: listaddsetdone

Listed options
  • --name <name>
  • --hint <text>
  • --progress <metric>
  • --tail <text>
  • --node <id>
  • --no-node
  • --no-activate
installed help
npm run northstar -- milestone --help
issuesSchedule work
Plan changes state

Reads the work plan or assigns an issue identity to a sprint, target date and position. Supports an expected revision for writes.

syntax · replace placeholders
npm run northstar -- issues [status|plan] --pack <dir> [--identity <id> --sprint <name> --target-date <date> --position <n>]

Subcommands: statusplan

Listed options
  • --identity <id>
  • --sprint <name>
  • --target-date <date>
  • --position <n>
  • --expected-revision <n>
installed help
npm run northstar -- issues --help
relationsConnect causes and dependencies
Add changes state

Lists or adds same-cause and dependency relationships. Validates the graph and rejects dependency cycles. Confirm shared causes with evidence.

syntax · replace placeholders
npm run northstar -- relations [list|add] --pack <dir> [--from <identity> --to <identity> --kind <type> --note <text>]

Subcommands: listadd

Listed options
  • --from <identity>
  • --to <identity>
  • --kind <type>
  • --note <text>
installed help
npm run northstar -- relations --help
mapBuild and maintain the capability map
Writes by subcommand

Scans and proposes topology, detects Git-based drift, revises or declares nodes and links, and reads current or historical capability views. Proposed and declared links remain distinct.

syntax · replace placeholders
npm run northstar -- map [scan|drift|revise|declare|propose-topology|propose-links|retract-link|status|history|show] --pack <dir> [options]

Subcommands: scandriftrevisedeclarepropose-topologypropose-linksretract-linkstatushistoryshow

Listed options
  • --patch <json>
  • --file <path>
  • --node <id>
  • --edge <from,to,kind>
  • --expected-revision <n>
  • --link <linkId>
  • --label <text>
  • --batch <n>
  • --agent <name>
  • --revision <n>
  • --revisit
  • --history
installed help
npm run northstar -- map --help
reprojectCorrect a derived view
Preview or governed write

Previews and applies controlled projection corrections while preserving the raw ledger. Use the frozen count, hash and cutoff safeguards.

syntax · replace placeholders
npm run northstar -- reproject --pack <dir> (--json <request> | --file <path>) [--dry-run]
Listed options
  • --json <request>
  • --file <path>
  • --dry-run
installed help
npm run northstar -- reproject --help

Advice, decisions and product metrics

strategistReview the selected work
Records a review

Evaluates a bounded task packet against mission, metrics and history. Produces a recommendation and rationale, not lifecycle proof.

syntax · replace placeholders
npm run northstar -- strategist --pack <dir> [--agent <provider>]
Listed options
  • --agent <provider>
installed help
npm run northstar -- strategist --help
auditFind reproducible work
Investigates and writes

Investigates under the pack’s declared audit perspective, records evidence and turns findings into backlog work. Each pass tracks what changed.

syntax · replace placeholders
npm run northstar -- audit --pack <dir> [--agent <provider>]
Listed options
  • --agent <provider>
installed help
npm run northstar -- audit --help
advisorTrack gaps against a goal
Writes gap records

Scans threshold gaps or records a declared opportunity. Gaps become backlog work through backlog accept. This is distinct from product-advisor.

syntax · replace placeholders
npm run northstar -- advisor [scan|add|dismiss] --pack <dir> [options]

Subcommands: scanadddismiss

Listed options
  • --kind <Prodotto|Funzione|Esperienza>
  • --title <text>
  • --why <text>
  • --score <1|2|3>
  • --lane <lane>
  • --short <text>
  • --gap <id>
  • --source <channel>
  • --url <url>
  • --voices <n>
  • --last-at <date>
  • --limit <n>
installed help
npm run northstar -- advisor --help
product-advisorReview capabilities and engineering history
Records advice

Builds fact packs, candidates and bounded model reviews. Records advisory runs without changing the lifecycle, backlog or product map.

syntax · replace placeholders
npm run northstar -- product-advisor [fact-pack|candidates|run|brief|runs|audit|review-pack] --pack <dir> [options]

Subcommands: fact-packcandidatesrunbriefrunsauditreview-pack

Listed options
  • --agent <stub|muse|claude|codex|grok>
  • --top <n>
  • --batch <n>
  • --json
installed help
npm run northstar -- product-advisor --help
owner-decisionKeep owner decisions and outcomes
Records decisions or explicitly promotes eligible work; no execution

Records owner judgments on Advisor recommendations. Explicit promotion checks eligibility and enters the existing governed intake; work reads back its state. Neither action launches an executor or grants release permission.

syntax · replace placeholders
npm run northstar -- owner-decision [record|history|position|outcomes|metrics|promote|work] --pack <dir> [options]

Subcommands: recordhistorypositionoutcomesmetricspromotework

Listed options
  • --run <advisorRunId>
  • --subject <id>
  • --subject-type <type>
  • --decision <verdict>
  • --decision <decisionId>
  • --rationale <text>
  • --by <actor>
  • --supersedes <decisionId>
  • --json <input>
  • --file <path>
  • --dry-run
installed help
npm run northstar -- owner-decision --help
capability-successMeasure a capability’s product benefit
Measures and records

Reads status, runs declared measurements, records a hypothesis and compares stored before/after observations with an explicit attribution basis. Does not authorize engineering work.

syntax · replace placeholders
npm run northstar -- capability-success [status|measure|expect|verify-benefit] --pack <dir> [options]

Subcommands: statusmeasureexpectverify-benefit

Listed options
  • --capability <id>
  • --hypothesis <text>
  • --by <actor>
  • --baseline <measurementRef>
  • --expectation <ref>
  • --after <measurementRef>
  • --before <measurementRef>
  • --release <ref>
  • --attribution-kind <none|controlled_experiment|explicit_owner_attribution>
  • --attribution-ref <ref>
installed help
npm run northstar -- capability-success --help
approveApprove a Strategist proposal
Owner authority required

Records the owner’s approval for a specific proposal. A coding agent must already have authority to represent that decision.

syntax · replace placeholders
npm run northstar -- approve --pack <dir> --proposal <n>
Listed options
  • --proposal <n>
installed help
npm run northstar -- approve --help
approvalsInspect approvals and expired claims
Sweep changes state

Lists approvals. The explicit sweep operation releases expired claims; it is not an automatic background action.

syntax · replace placeholders
npm run northstar -- approvals [list|sweep] --pack <dir> [--max-age-minutes <n>]

Subcommands: listsweep

Listed options
  • --max-age-minutes <n>
installed help
npm run northstar -- approvals --help
upstreamReview framework drift
Decision writes

Compares declared upstream baselines with mirrors and records decisions on differences. Use for framework maintenance, not ordinary product repair.

syntax · replace placeholders
npm run northstar -- upstream [check|decide|decisions] [--repo <owner/repo>] [--ref <ref>] [--dir <mirror>]

Subcommands: checkdecidedecisions

Listed options
  • --repo <owner/repo>
  • --ref <ref>
  • --dir <mirror>
  • --json <decision> | --file <path>
  • --priority <P1|P2|P3>
  • --promotion-title <text>
installed help
npm run northstar -- upstream --help

Run, verify and watch

triageSelect one task
Reads state

Returns at most one task packet with its issue boundary and required evidence. It does not start a worker.

syntax · replace placeholders
npm run northstar -- triage --pack <dir>
installed help
npm run northstar -- triage --help
checkpointDecide whether the loop can stop
Reads state

Reports executable work, an active PR to resume, a human dependency or a valid stop. Use at the start and end of a run.

syntax · replace placeholders
npm run northstar -- checkpoint --pack <dir>
installed help
npm run northstar -- checkpoint --help
runExecute bounded repair work
Executes work

Starts a coding worker in a dedicated worktree and resumes according to checkpoint results. Pack permissions and per-run budgets apply.

syntax · replace placeholders
npm run northstar -- run --pack <dir> [--agent <provider>] [--require-strategist] [limits]
Listed options
  • --agent <provider>
  • --agent-args <text>
  • --require-strategist
  • --strategist-agent <provider>
  • --resume-worktree <dir>
  • --max-hours <n>
  • --max-invocations <n>
  • --max-consecutive-failures <n>
  • --max-consecutive-no-progress <n>
  • --max-consecutive-execution-only <n>
  • --worker-timeout-minutes <n>
installed help
npm run northstar -- run --help
watchKeep checking on a schedule
Schedules work

Records periodic observations and launches the configured run command when work exists. Requires the pack schedule and a running host.

syntax · replace placeholders
npm run northstar -- watch --pack <dir>
installed help
npm run northstar -- watch --help
confirm-causeValidate the cause before editing
Validates and records

Checks the evidence and failing reproducer before a repair begins. Rejects unsupported cause claims without writing a receipt.

syntax · replace placeholders
npm run northstar -- confirm-cause --pack <dir> (--json <claims> | --file <path>)
Listed options
  • --json <claims>
  • --file <path>
installed help
npm run northstar -- confirm-cause --help
confirm-fixRecord a tested repair
Validates and records

Checks the passing reproducer, test suite and bounded change. This is the command that creates a remediation receipt.

syntax · replace placeholders
npm run northstar -- confirm-fix --pack <dir> (--json <claims> | --file <path>)
Listed options
  • --json <claims>
  • --file <path>
installed help
npm run northstar -- confirm-fix --help
recordRecord a lifecycle event
Writes a receipt

Appends evidence of a merge, deployment, decision or resolution. It cannot create remediation or independent verification receipts.

syntax · replace placeholders
npm run northstar -- record --pack <dir> (--json <receipt> | --file <path>)
Listed options
  • --json <receipt>
  • --file <path>
installed help
npm run northstar -- record --help
verifyIndependently check the released fix
Runs checks and records

Runs the configured verifier against the released revision outside the worker’s worktree. Can detect recurrence on a previously verified repair.

syntax · replace placeholders
npm run northstar -- verify --pack <dir> [--signal <identity>]
Listed options
  • --signal <identity>
installed help
npm run northstar -- verify --help
curesInspect and recheck repairs
Rechecks with a flag

Lists verified repair boundaries and their measuring commands. --cure reruns the check for a selected repair.

syntax · replace placeholders
npm run northstar -- cures --pack <dir> [--cure <id>]
Listed options
  • --cure <id>
installed help
npm run northstar -- cures --help

Inspect, measure and preserve history

diaryRead lifecycle history
Reads state

Reads ledger receipts for a signal identity or family. Use it to reconstruct attempted fixes, releases and verification.

syntax · replace placeholders
npm run northstar -- diary --pack <dir> [--signal <identity> | --family <key>]
Listed options
  • --signal <identity>
  • --family <key>
installed help
npm run northstar -- diary --help
metricsMeasure project metrics
Measures; optional record

Runs the declared metric sources and reports values and history length. --record saves an observation. Missing values remain unknown.

syntax · replace placeholders
npm run northstar -- metrics --pack <dir> [--record]
Listed options
  • --record
installed help
npm run northstar -- metrics --help
boardRead the owner board
Reads; optional export

Builds a view across project packs. Unreadable packs remain visible. --html writes the board to a local file.

syntax · replace placeholders
npm run northstar -- board [--packs <dir>] [--project <name>] [--view owner] [--html <file>] [--plain]
Listed options
  • --packs <dir>
  • --project <name>
  • --view owner
  • --html <file>
  • --plain
installed help
npm run northstar -- board --help
serveOpen the local board
Starts local server

Serves a live view of project packs on a local port. This starts the board server, not a repair worker.

syntax · replace placeholders
npm run northstar -- serve --packs <dir> [--port <n>]
Listed options
  • --packs <dir>
  • --port <n>
installed help
npm run northstar -- serve --help
durabilityBack up or restore Factory state
Restore replaces state

Checks whether state has a mirror, copies the complete .factory directory, or restores it from a chosen mirror. Restore replaces local Factory state.

syntax · replace placeholders
npm run northstar -- durability [status|mirror|restore] --pack <dir> [--from <dir>]

Subcommands: statusmirrorrestore

Listed options
  • --from <dir>
installed help
npm run northstar -- durability --help
memoryReconcile engineering evidence
Writes imported evidence

Imports bounded evidence from database, Git and diaries; links identifiers and reports reconciliation or mapping eligibility. Reads source repositories without modifying them.

syntax · replace placeholders
npm run northstar -- memory [import-db|import-git|import-diary|link|report|delta] --pack <dir> [--repo <dir> --repo-slug <owner/name>|--offline] [--docs <dir>]

Subcommands: import-dbimport-gitimport-diarylinkreportdelta

Listed options
  • --repo <dir>
  • --repo-slug <owner/name>
  • --docs <dir>
  • --offline
installed help
npm run northstar -- memory --help

Exit codes and authority

Read the command’s result, not only its process status. For example, checkpoint exit 2 means work must continue or an active PR must resume. verify exit 2 means a check failed or a repair recurred. run exit 0 can represent a declared human dependency, not a completed repair.

Commands that approve decisions, apply roadmap changes, restore state or execute work require the corresponding owner authority and pack permissions. Use actual evidence files for receipts; do not invent release or verification claims.

Something unclear?Talk to the builder