Tools for coding agents.
Updated Read as Markdown ↗
Skills are what a person asks: connect a project, add or investigate work, ask how the Factory is doing, or start or recover it. The command list underneath is the reference.
Give your coding agent the commands to register work, inspect a capability, run a repair and verify the result. This reference covers36 commands from the September 15 catalog snapshot, plus the everyday read commands checked below.
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.
npm run northstar -- --help
npm run northstar -- intake --helpFrom a goal to a configured Factory
Commands checked against agentic-factory main at 50329f7 on 4 October 2026. The executable is northstar; factoryctl remains an alias. There is no public Orchestro installer.
northstar init \
--dir packs/content-factory \
--slug content-factory \
--goal "Build an evidence-led content system
for danielepelleri.com: publish useful work,
improve discoverability and learn from results."init writes a validated domain manifest. It does not discover or connect adapters, grant permissions, or start a live loop. Complete project onboarding and capability reconciliation first. The following are separate operations on that configured project.
# Check the configured project
northstar readiness --pack packs/content-factory
# See what can move next
northstar checkpoint --pack packs/content-factory
# Run the selected work
northstar run --pack packs/content-factory
# Keep the configured loop watching
northstar watch --pack packs/content-factory
# Read the cloud connection
northstar cloud status --pack packs/content-factory
# Ask for the local owner view
northstar stato --pack packs/content-factoryReal commands for everyday questions
Read-only operations checked against the private core on 2026-09-26, revision 4dbd119. Replace packs/my-app and example work IDs with your project’s values. These commands require an installed checkout and configured pack; they are not public MCP endpoints.
Project status
Current work, latest durable result, blocker and source freshness.
npm run northstar -- stato --json --pack packs/my-appComplete backlog
All registered work. Filter its returned items in your client.
npm run northstar -- backlog list --pack packs/my-appWork evidence
Lifecycle and recorded receipt kinds for one work identity.
npm run northstar -- diary --signal backlog:demo-checkout --pack packs/my-appGovernor recap
Interventions, technical waits and owner escalations in the period.
npm run northstar -- governor recap --hours 24 --pack packs/my-appCloud connection
Binding, last synchronization and errors; does not run a sync.
npm run northstar -- cloud status --pack packs/my-appProduct map
Persisted topology, revision, links and freshness.
npm run northstar -- map status --pack packs/my-appSuccess evidence
Declared contracts and stored measurement/verification references.
npm run northstar -- capability-success status --pack packs/my-appAdvisor history
Recorded advisory runs, provider and published recommendation count.
npm run northstar -- product-advisor runs --pack packs/my-appThe homepage and How it works use these commands with labelled illustrative output excerpts. Live Factories reads public observations instead of simulating command output. JSON field names follow the current command output, including Italian keys in stato. Omitted fields, sample IDs and sample measurements are not production receipts. Check --help in your installed version.
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.
npm run northstar -- owner-decision --helpStart from the agent skills
.agents/skills/onboard-project/SKILL.mdconnects a repository, checks prerequisites and configures a project pack..agents/skills/intake-work/SKILL.mdturns 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:
{
"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."
]
}
]
}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-appIntake 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
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-appUse the real capability ID returned by your map in place of onboarding. Its measurement source and success contract must already be declared.
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-appMuse 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
checkpointestablishes whether to continue, resume a PR or stop.triageproduces a bounded task packet.confirm-causevalidates the cause and failing reproducer before the edit.- The worker makes the approved change;
confirm-fixvalidates tests and records remediation. recordrecords the actual merge and release when authorized.verifychecks the released behavior independently.cureskeeps 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 Node, coding CLIs and GitHub tooling before a project is connected. Reports the missing prerequisite.
npm run northstar -- preflight [--pack <dir>] [--agent <provider>]npm run northstar -- preflight --helpadoptConnect an existing repository
Builds a project pack from Git history, including work, release markers and recurring activity. Review the proposed release convention.
npm run northstar -- adopt --repo <dir> --pack <dir> [--yes] [--force] [options]npm run northstar -- adopt --helprefreshComplete readable product context
Finds missing labels and user outcomes. --fix applies mechanical corrections; --propose asks an agent for reviewable wording.
npm run northstar -- refresh [--pack <dir> | --packs <dir>] [--fix] [--propose] [--json]npm run northstar -- refresh --helptruthRead current problems
Runs the probe declared by the pack and returns identified signals with priorities. The configured probe determines source access.
npm run northstar -- truth --pack <dir>npm run northstar -- truth --helpIntake, mapping and planning
intakeTurn a request into durable work
Validates a full batch of classified requests, checks existing evidence and duplicates, appends the intake decision and returns stable backlog IDs.
npm run northstar -- intake --pack <dir> (--json <batch> | --file <path>)npm run northstar -- intake --helpbacklogManage declared work
Lists, adds, links and changes work status. Can accept legacy Advisor gaps and import Strategist proposals. Status updates append history.
npm run northstar -- backlog [list|add|accept|link|set-status|import-proposal] --pack <dir> [options]Subcommands: listaddacceptlinkset-statusimport-proposal
npm run northstar -- backlog --helproadmapReview and update the roadmap
Reads and validates the roadmap, previews a patch, applies it or activates a node. Preview first and preserve revision checks.
npm run northstar -- roadmap [status|validate|preview|apply|activate] --pack <dir> [--file <patch>]Subcommands: statusvalidatepreviewapplyactivate
npm run northstar -- roadmap --helpmilestoneSet a measurable project milestone
Records a milestone, selects the active one or records completion. Declaring a target and achieving it are separate events.
npm run northstar -- milestone [list|add|set|done] "<name>" --pack <dir> [options]Subcommands: listaddsetdone
npm run northstar -- milestone --helpissuesSchedule work
Reads the work plan or assigns an issue identity to a sprint, target date and position. Supports an expected revision for writes.
npm run northstar -- issues [status|plan] --pack <dir> [--identity <id> --sprint <name> --target-date <date> --position <n>]Subcommands: statusplan
npm run northstar -- issues --helprelationsConnect causes and dependencies
Lists or adds same-cause and dependency relationships. Validates the graph and rejects dependency cycles. Confirm shared causes with evidence.
npm run northstar -- relations [list|add] --pack <dir> [--from <identity> --to <identity> --kind <type> --note <text>]Subcommands: listadd
npm run northstar -- relations --helpmapBuild and maintain the capability map
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.
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
npm run northstar -- map --helpreprojectCorrect a derived view
Previews and applies controlled projection corrections while preserving the raw ledger. Use the frozen count, hash and cutoff safeguards.
npm run northstar -- reproject --pack <dir> (--json <request> | --file <path>) [--dry-run]npm run northstar -- reproject --helpAdvice, decisions and product metrics
strategistReview the selected work
Evaluates a bounded task packet against mission, metrics and history. Produces a recommendation and rationale, not lifecycle proof.
npm run northstar -- strategist --pack <dir> [--agent <provider>]npm run northstar -- strategist --helpauditFind reproducible work
Investigates under the pack’s declared audit perspective, records evidence and turns findings into backlog work. Each pass tracks what changed.
npm run northstar -- audit --pack <dir> [--agent <provider>]npm run northstar -- audit --helpadvisorTrack gaps against a goal
Scans threshold gaps or records a declared opportunity. Gaps become backlog work through backlog accept. This is distinct from product-advisor.
npm run northstar -- advisor [scan|add|dismiss] --pack <dir> [options]Subcommands: scanadddismiss
npm run northstar -- advisor --helpproduct-advisorReview capabilities and engineering history
Builds fact packs, candidates and bounded model reviews. Records advisory runs without changing the lifecycle, backlog or product map.
npm run northstar -- product-advisor [fact-pack|candidates|run|brief|runs|audit|review-pack] --pack <dir> [options]Subcommands: fact-packcandidatesrunbriefrunsauditreview-pack
npm run northstar -- product-advisor --helpowner-decisionKeep owner decisions and outcomes
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.
npm run northstar -- owner-decision [record|history|position|outcomes|metrics|promote|work] --pack <dir> [options]Subcommands: recordhistorypositionoutcomesmetricspromotework
npm run northstar -- owner-decision --helpcapability-successMeasure a capability’s product benefit
Reads status, runs declared measurements, records a hypothesis and compares stored before/after observations with an explicit attribution basis. Does not authorize engineering work.
npm run northstar -- capability-success [status|measure|expect|verify-benefit] --pack <dir> [options]Subcommands: statusmeasureexpectverify-benefit
npm run northstar -- capability-success --helpapproveApprove a Strategist proposal
Records the owner’s approval for a specific proposal. A coding agent must already have authority to represent that decision.
npm run northstar -- approve --pack <dir> --proposal <n>npm run northstar -- approve --helpapprovalsInspect approvals and expired claims
Lists approvals. The explicit sweep operation releases expired claims; it is not an automatic background action.
npm run northstar -- approvals [list|sweep] --pack <dir> [--max-age-minutes <n>]Subcommands: listsweep
npm run northstar -- approvals --helpupstreamReview framework drift
Compares declared upstream baselines with mirrors and records decisions on differences. Use for framework maintenance, not ordinary product repair.
npm run northstar -- upstream [check|decide|decisions] [--repo <owner/repo>] [--ref <ref>] [--dir <mirror>]Subcommands: checkdecidedecisions
npm run northstar -- upstream --helpRun, verify and watch
triageSelect one task
Returns at most one task packet with its issue boundary and required evidence. It does not start a worker.
npm run northstar -- triage --pack <dir>npm run northstar -- triage --helpcheckpointDecide whether the loop can stop
Reports executable work, an active PR to resume, a human dependency or a valid stop. Use at the start and end of a run.
npm run northstar -- checkpoint --pack <dir>npm run northstar -- checkpoint --helprunExecute bounded repair work
Starts a coding worker in a dedicated worktree and resumes according to checkpoint results. Pack permissions and per-run budgets apply.
npm run northstar -- run --pack <dir> [--agent <provider>] [--require-strategist] [limits]npm run northstar -- run --helpwatchKeep checking on a schedule
Records periodic observations and launches the configured run command when work exists. Requires the pack schedule and a running host.
npm run northstar -- watch --pack <dir>npm run northstar -- watch --helpconfirm-causeValidate the cause before editing
Checks the evidence and failing reproducer before a repair begins. Rejects unsupported cause claims without writing a receipt.
npm run northstar -- confirm-cause --pack <dir> (--json <claims> | --file <path>)npm run northstar -- confirm-cause --helpconfirm-fixRecord a tested repair
Checks the passing reproducer, test suite and bounded change. This is the command that creates a remediation receipt.
npm run northstar -- confirm-fix --pack <dir> (--json <claims> | --file <path>)npm run northstar -- confirm-fix --helprecordRecord a lifecycle event
Appends evidence of a merge, deployment, decision or resolution. It cannot create remediation or independent verification receipts.
npm run northstar -- record --pack <dir> (--json <receipt> | --file <path>)npm run northstar -- record --helpverifyIndependently check the released fix
Runs the configured verifier against the released revision outside the worker’s worktree. Can detect recurrence on a previously verified repair.
npm run northstar -- verify --pack <dir> [--signal <identity>]npm run northstar -- verify --helpcuresInspect and recheck repairs
Lists verified repair boundaries and their measuring commands. --cure reruns the check for a selected repair.
npm run northstar -- cures --pack <dir> [--cure <id>]npm run northstar -- cures --helpInspect, measure and preserve history
diaryRead lifecycle history
Reads ledger receipts for a signal identity or family. Use it to reconstruct attempted fixes, releases and verification.
npm run northstar -- diary --pack <dir> [--signal <identity> | --family <key>]npm run northstar -- diary --helpmetricsMeasure project metrics
Runs the declared metric sources and reports values and history length. --record saves an observation. Missing values remain unknown.
npm run northstar -- metrics --pack <dir> [--record]npm run northstar -- metrics --helpboardRead the owner board
Builds a view across project packs. Unreadable packs remain visible. --html writes the board to a local file.
npm run northstar -- board [--packs <dir>] [--project <name>] [--view owner] [--html <file>] [--plain]npm run northstar -- board --helpserveOpen the local board
Serves a live view of project packs on a local port. This starts the board server, not a repair worker.
npm run northstar -- serve --packs <dir> [--port <n>]npm run northstar -- serve --helpdurabilityBack up or restore Factory state
Checks whether state has a mirror, copies the complete .factory directory, or restores it from a chosen mirror. Restore replaces local Factory state.
npm run northstar -- durability [status|mirror|restore] --pack <dir> [--from <dir>]Subcommands: statusmirrorrestore
npm run northstar -- durability --helpmemoryReconcile engineering evidence
Imports bounded evidence from database, Git and diaries; links identifiers and reports reconciliation or mapping eligibility. Reads source repositories without modifying them.
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
npm run northstar -- memory --helpExit 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.