Source: https://www.orchestro.org/docs/tools
Updated: 2026-09-15

# Tools for coding agents.

Updated September 15, 2026[Read as Markdown ↗](https://www.orchestro.org/docs/tools.md)

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](https://www.orchestro.org/docs/mcp).

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.

Find a command

36 of 36 commands

### Connect a project

`preflight`Check 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
```

`adopt`Connect 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
```

`refresh`Complete 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
```

`truth`Read 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

`intake`Turn 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
```

`backlog`Manage 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:** `list``add``accept``link``set-status``import-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
```

`roadmap`Review 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:** `status``validate``preview``apply``activate`

**Listed options**

*   `--file <patch>`

installed help

```
npm run northstar -- roadmap --help
```

`milestone`Set 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:** `list``add``set``done`

**Listed options**

*   `--name <name>`
*   `--hint <text>`
*   `--progress <metric>`
*   `--tail <text>`
*   `--node <id>`
*   `--no-node`
*   `--no-activate`

installed help

```
npm run northstar -- milestone --help
```

`issues`Schedule 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:** `status``plan`

**Listed options**

*   `--identity <id>`
*   `--sprint <name>`
*   `--target-date <date>`
*   `--position <n>`
*   `--expected-revision <n>`

installed help

```
npm run northstar -- issues --help
```

`relations`Connect 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:** `list``add`

**Listed options**

*   `--from <identity>`
*   `--to <identity>`
*   `--kind <type>`
*   `--note <text>`

installed help

```
npm run northstar -- relations --help
```

`map`Build 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:** `scan``drift``revise``declare``propose-topology``propose-links``retract-link``status``history``show`

**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
```

`reproject`Correct 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

`strategist`Review 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
```

`audit`Find 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
```

`advisor`Track 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:** `scan``add``dismiss`

**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-advisor`Review 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-pack``candidates``run``brief``runs``audit``review-pack`

**Listed options**

*   `--agent <stub|muse|claude|codex|grok>`
*   `--top <n>`
*   `--batch <n>`
*   `--json`

installed help

```
npm run northstar -- product-advisor --help
```

`owner-decision`Keep 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:** `record``history``position``outcomes``metrics``promote``work`

**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-success`Measure 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:** `status``measure``expect``verify-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
```

`approve`Approve 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
```

`approvals`Inspect 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:** `list``sweep`

**Listed options**

*   `--max-age-minutes <n>`

installed help

```
npm run northstar -- approvals --help
```

`upstream`Review 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:** `check``decide``decisions`

**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

`triage`Select 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
```

`checkpoint`Decide 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
```

`run`Execute 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
```

`watch`Keep 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-cause`Validate 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-fix`Record 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
```

`record`Record 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
```

`verify`Independently 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
```

`cures`Inspect 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

`diary`Read 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
```

`metrics`Measure 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
```

`board`Read 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
```

`serve`Open 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
```

`durability`Back 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:** `status``mirror``restore`

**Listed options**

*   `--from <dir>`

installed help

```
npm run northstar -- durability --help
```

`memory`Reconcile 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-db``import-git``import-diary``link``report``delta`

**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.