Skip to main content

Run a governed flow without lying to yourself

Governed mode is staged and gate-driven. agentxchain run is the primary automated workflow, but review_only + local_cli is invalid: if you want CLI-driven automation, that role must be authoritative, or you must keep the role on manual, api_proxy, mcp, or remote_agent. The scaffold created by init --governed -y is manual-only by default:

Prerequisites​

  • Minimum CLI version: agentxchain 2.155.72 or newer

  • Check your installed binary: agentxchain --version

  • Upgrade with npm: npm install -g agentxchain@latest

  • Upgrade with Homebrew: brew upgrade agentxchain

  • If the binary on PATH and these docs disagree, use the safe fallback: npx --yes -p agentxchain@latest -c "agentxchain <command>"

  • pm uses manual-pm

  • dev uses manual-dev

  • qa uses manual-qa

That means the default generic scaffold is not immediately runnable with agentxchain run. If a role is still bound to the manual adapter, use step for that path or rebind the role to a non-manual runtime first.

Project templates such as cli-tool, web-app, and api-service stay mixed-mode on purpose:

  • pm uses manual-pm
  • dev uses local-dev
  • qa uses api-qa

Path 0: Demo​

If you are evaluating AgentXchain, do this before you wire a real repo:

npx --yes -p agentxchain@latest -c "agentxchain demo"

What it does:

  • Creates a temporary governed repo, initializes git, and runs a full PM -> Dev -> QA lifecycle through the real runner interface.
  • Shows mandatory challenge, phase gates, decisions, objections, and completion without API keys, config edits, or manual turn authoring.
  • Cleans up the temp workspace when it finishes.

What it requires:

  • Node.js 18.17+ (or 20.5+)
  • git
  • Network access for npx if agentxchain is not already installed

What it does not prove:

  • Your local coding CLI wiring
  • Your provider/API configuration
  • Your repo-specific workflow kit choices

After the demo, read Build Your First Governed Project in 5 Minutes for the fastest manual-first path to a real accepted turn, then Getting Started for the mixed-mode project-template path. Use Your First Governed Turn when you want the artifact-by-artifact breakdown.

Before you start​

  • Node.js 18.17+ (or 20.5+)
  • git (governed scaffold expects a repo)
  • npm install -g agentxchain (or brew tap shivamtiwari93/tap && brew install agentxchain) for repeated commands on this page
  • Optional: VS Code extension for in-editor governed status, approvals, and notifications
  • npx --yes -p agentxchain@latest -c "agentxchain demo" for the zero-install demo path
  • A working local coding CLI for the default local-dev runtime, or a config change to point local-dev.command at your installed tool
  • An API key for any api_proxy role you plan to use (review_only or proposed), such as ANTHROPIC_API_KEY for the mixed-mode api-qa runtime used by project templates
  • Scaffold intent via --template or defaults to pm → dev → qa

Choose your starting point​

1. Large existing project, never used AgentXchain​

Start with init --governed, not migrate. Treat the first pass as a bootstrap on top of a real repo, not as an automated lights-out run.

cd /path/to/existing-repo
git checkout -b agentxchain-bootstrap

agentxchain init --governed --template web-app --goal "Stabilize and improve the existing web app" --dir . -y
agentxchain template validate
agentxchain doctor

git add -A
git commit -m "bootstrap AgentXchain governed scaffold"

agentxchain step

Tip: --goal "..." should be part of the primary scaffold command, not an afterthought. If you skipped it, run agentxchain config --set project.goal "Stabilize and improve the existing web app" before the first governed turn.

:::caution Commit before running automated turns Authoritative and proposed turns require a clean git working tree. The git add -A && git commit step above is not optional — if you skip it, the first writable automated turn will refuse to assign because the framework needs a clean diff baseline. This protects against false artifact-observation failures. See Why this exists below. :::

step assigns the PM turn (the planning-phase entry role), writes the dispatch bundle, and polls for the staged result. While step is waiting, open a second terminal to write your planning docs and stage the turn result at .agentxchain/staging/<turn_id>/turn-result.json. When step detects the staged result, it auto-validates and auto-accepts. Then approve the phase transition:

agentxchain approve-transition
git add -A && git commit -m "orchestrator: accept pm turn"

agentxchain step --role dev --verbose
git add -A && git commit -m "orchestrator: accept dev turn"
agentxchain step --role qa
# default api_proxy QA returns a review artifact; ensure the QA gate files
# already contain real content before you approve completion
agentxchain approve-completion

If you prefer more control, press Ctrl+C during the step poll, do your work, then run agentxchain accept-turn and agentxchain approve-transition manually.

This is the safest path for a large mature repo because it forces scope, acceptance criteria, and human review before the first implementation turn. Do not jump to agentxchain run until the runtime bindings are truthful and you have already seen one or two clean governed turns.

For authoritative implementation turns, keep the verification contract honest: verification.status: "pass" only works when every listed verification.machine_evidence command exits 0. If you need to prove error handling, wrap those checks in npm test, node --test, or a shell assertion that exits 0 when the failure occurs as expected. Do not list raw non-zero negative-case commands on a passing turn.

2. Large project that used AgentXchain earlier​

If the repo is already on the current governed format and you just want to continue:

cd /path/to/existing-governed-repo

agentxchain status
agentxchain template validate
agentxchain step --resume

Use step --resume when there is already one active retained turn and you want to continue it. Use resume instead when you want a fresh dispatch bundle now without waiting for the turn to finish:

agentxchain resume

If the repo is on an older AgentXchain protocol or legacy governed format, migrate first:

cd /path/to/older-agentxchain-repo

agentxchain migrate --yes
agentxchain status
agentxchain template validate

After migration, review the scaffold and runtime wiring honestly. If you want to restart with a planning refresh on a large repo, start with:

agentxchain step

If the migrated repo already has a retained turn you intend to continue, use agentxchain step --resume or agentxchain resume as appropriate.

3. Starting a new project with AgentXchain​

For a new repo, start by scaffolding truthfully, committing the governed files, then deciding whether you want the mixed-mode manual path or a fully automated run path:

agentxchain init --governed --template web-app --goal "Ship a governed web app MVP" --dir my-agentxchain-project -y
cd my-agentxchain-project

git init
agentxchain template validate
agentxchain doctor

git add -A
git commit -m "initial governed scaffold"

From there:

  • Keep the shipped mixed-mode scaffold and use agentxchain step first if you want a human-led planning pass.
  • Use agentxchain init --governed --template full-local-cli if you want automated PM/Dev/QA turns with human gate approvals only. The Automation Patterns page is the truthful path for that setup.
  • Rebind any manual roles to non-manual runtimes, then use agentxchain run --auto-approve --max-turns 10 if you want an automated path.

What governed mode creates​

agentxchain init --governed --dir my-agentxchain-project -y

This creates the scaffold:

CategoryFilesGit status
Configurationagentxchain.jsonCommitted
Runtime state.agentxchain/state.json, .agentxchain/history.jsonl, .agentxchain/decision-ledger.jsonlGitignored by default (durable on disk)
Turn handoff.agentxchain/dispatch/turns/<turn_id>/, .agentxchain/staging/<turn_id>/turn-result.jsonGitignored (transient)
CollaborationTALK.mdGitignored by default (durable on disk)
Planning artifacts.planning/PM_SIGNOFF.md, .planning/ROADMAP.md, .planning/SYSTEM_SPEC.md, .planning/IMPLEMENTATION_NOTES.md, .planning/acceptance-matrix.md, .planning/ship-verdict.md, .planning/RELEASE_NOTES.mdCommitted
Role prompts.agentxchain/prompts/pm.md, .agentxchain/prompts/dev.md, .agentxchain/prompts/qa.md, .agentxchain/prompts/eng_director.mdCommitted

If you already know the repo shape, initialize with a built-in template such as api-service, cli-tool, library, web-app, or the blueprint-backed enterprise-app. The template adds project-type planning artifacts and records scaffold intent in agentxchain.json. See Templates.

Prove the scaffold before you run it​

After initialization, validate that the governed scaffold contract is intact:

agentxchain template validate

This proves five things: the built-in template registry is coherent, the project template resolves, the core workflow-kit files exist with their structural markers (Approved:, ## Phases, ## Purpose, ## Interface, ## Acceptance Tests, | Req # |, ## Verdict:), template-required planning artifacts are present, and acceptance hints are tracked. Use --json for machine-readable output — the workflow_kit block distinguishes scaffold-layer failures from template-layer failures. See Templates — Prove the template surface for details.

If those scaffold-owned planning files are deleted later, restore them from the repo's current template plus workflow_kit contract instead of rebuilding them by hand:

agentxchain generate planning --dry-run
agentxchain generate planning

This is scaffold proof, not gate proof. A fresh scaffold still starts with Approved: NO, a placeholder acceptance matrix row, placeholder implementation notes, placeholder release notes, and ## Verdict: PENDING; the governed runtime will only open the planning/completion gates after those become Approved: YES, a QA-owned acceptance matrix whose requirement rows all end in passing Status values, an affirmative ## Verdict: value, a non-placeholder SYSTEM_SPEC.md with real Purpose, Interface, and Acceptance Tests sections, an IMPLEMENTATION_NOTES.md with real ## Changes and ## Verification content, and a RELEASE_NOTES.md with real ## User Impact and ## Verification Summary content.

Override the local dev runtime during scaffold​

The shipped default dev runtime is:

{
  "type": "local_cli",
  "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
  "prompt_transport": "stdin"
}

If your local coding agent needs a different launch command, set it during init instead of hand-editing the scaffold afterward:

agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y

If your tool expects prompt text on the command line, include {prompt} directly in --dev-command and AgentXchain will lock the scaffold to argv delivery:

agentxchain init --governed --dir my-agentxchain-project --dev-command my-agent run {prompt} -y

Do not mix these modes casually. argv requires {prompt}. stdin and dispatch_bundle_only must not include {prompt}. Init fails closed if the prompt-delivery contract is ambiguous.

Automated path: use agentxchain run​

1. Initialize​

agentxchain init --governed --template cli-tool --dir my-agentxchain-project -y
cd my-agentxchain-project
git init && git add -A && git commit -m "initial governed scaffold"

2. Make the scaffold runnable​

The mixed-mode cli-tool scaffold defaults to manual-pm, so agentxchain run will stop immediately unless you rebind the PM role to a non-manual runtime. The smallest honest change is to point pm at an api_proxy runtime and keep dev on local-dev and qa on api-qa.

Use agentxchain config --set to add the runtime and rebind the role:

agentxchain config --set runtimes.api-pm.type api_proxy
agentxchain config --set runtimes.api-pm.provider anthropic
agentxchain config --set runtimes.api-pm.model claude-sonnet-4-6
agentxchain config --set runtimes.api-pm.auth_env ANTHROPIC_API_KEY
agentxchain config --set roles.pm.runtime api-pm

If you use another local tool instead of the scaffolded claude --print --dangerously-skip-permissions --bare command, prefer setting it during init with --dev-command and --dev-prompt-transport. Editing runtimes.local-dev afterward still works, but the point is to scaffold a truthful runtime contract up front. See Adapters for the runtime contract.

3. Run the governed flow​

agentxchain run --auto-approve --max-turns 10

Use --auto-approve for non-interactive execution and CI. Without it, gate pauses still fail closed outside a TTY.

4. Inspect the result​

agentxchain status

run keeps assigning turns, dispatching to adapters, validating staged results, and handling gates until the run reaches a terminal state:

  • completed
  • blocked
  • max_turns_reached

If you want to preview the execution plan without dispatching, use:

agentxchain run --dry-run

Manual path: keep the shipped default generic scaffold​

If you keep the default manual-only generic scaffold, use step for the planning turn and let the orchestrator stop where the human work actually happens.

1. Start the PM turn​

agentxchain step

step assigns the PM turn (the planning-phase entry role), writes the dispatch bundle to .agentxchain/dispatch/turns/<turn_id>/, and polls for a staged result at .agentxchain/staging/<turn_id>/turn-result.json. When the staged result appears, step auto-validates and auto-accepts the turn.

2. Create PM artifacts and stage the turn result​

While step is polling, open a second terminal and write your planning docs (PM_SIGNOFF.md, ROADMAP.md), then create the staged turn result. A fresh scaffold starts with PM_SIGNOFF.md set to Approved: NO; change that line to Approved: YES only after a human reviews the planning artifacts and is ready to open the planning gate. Copy the exact template from the dispatch bundle's ASSIGNMENT.json instead of inventing fields. The minimum truthful shape still looks like this:

{
  "schema_version": "1.0",
  "run_id": "run_...",
  "turn_id": "turn_...",
  "role": "pm",
  "runtime_id": "manual-pm",
  "status": "completed",
  "summary": "Defined the planning scope...",
  "decisions": [
    {
      "id": "DEC-001",
      "category": "scope",
      "statement": "...",
      "rationale": "..."
    }
  ],
  "objections": [
    {
      "id": "OBJ-001",
      "severity": "medium",
      "against_turn_id": "turn_...",
      "statement": "...",
      "status": "raised"
    }
  ],
  "files_changed": [],
  "verification": {
    "status": "skipped",
    "commands": [],
    "evidence_summary": "Review turn.",
    "machine_evidence": []
  },
  "artifact": {
    "type": "review",
    "ref": null
  },
  "proposed_next_role": "human",
  "phase_transition_request": "implementation",
  "run_completion_request": null
}

3. Approve the phase transition​

Once step detects and accepts the staged result, approve the phase transition:

agentxchain approve-transition

The phase advances from planning to implementation. If PM_SIGNOFF.md still says Approved: NO, approve-transition must fail closed.

If you pressed Ctrl+C during the step poll instead of letting it auto-accept, you can validate and accept manually:

agentxchain validate --mode turn
agentxchain accept-turn
agentxchain approve-transition

4. Continue with dev and QA​

agentxchain step --verbose
# dev turn: local_cli dispatches to your coding agent, auto-accepts on completion
agentxchain step
# qa turn: api_proxy calls the LLM API, auto-accepts on completion
# api_proxy QA does not directly rewrite .planning/* gate files
agentxchain approve-completion

QA must challenge the dev's work. Blind agreement is a protocol violation.

If QA is bound to api_proxy with review_only authority, the accepted turn produces a structured review and an orchestrator-materialized review artifact under .agentxchain/reviews/. It does not mean the QA gate files were rewritten automatically. If QA uses proposed authority instead, the model returns file proposals materialized under .agentxchain/proposed/<turn_id>/; run agentxchain proposal apply to copy them to the workspace after review.

Multi-repo cold start​

Use the coordinator when one initiative spans multiple governed repos and you need cross-repo sequencing, shared barriers, or a coordinator-owned gate. The coordinator is additive: each child repo keeps its own governed state and its own gates.

1. Scaffold two governed repos inside one workspace​

mkdir agentxchain-rollout
cd agentxchain-rollout

agentxchain init --governed --template api-service --dir repos/api -y
agentxchain init --governed --template web-app --dir repos/web -y

git -C repos/api init
git -C repos/api add -A
git -C repos/api -c user.name="test" -c user.email="[email protected]" commit -m "bootstrap api governed scaffold"

git -C repos/web init
git -C repos/web add -A
git -C repos/web -c user.name="test" -c user.email="[email protected]" commit -m "bootstrap web governed scaffold"

(cd repos/api && agentxchain template validate)
(cd repos/web && agentxchain template validate)

2. Create agentxchain-multi.json​

Create this file at the workspace root:

agentxchain-multi.json
{
  "schema_version": "0.1",
  "project": {
    "id": "agentxchain-rollout",
    "name": "AgentXchain Rollout"
  },
  "repos": {
    "api": {
      "path": "./repos/api",
      "default_branch": "main",
      "required": true
    },
    "web": {
      "path": "./repos/web",
      "default_branch": "main",
      "required": true
    }
  },
  "workstreams": {
    "planning_sync": {
      "phase": "planning",
      "repos": ["api", "web"],
      "entry_repo": "api",
      "depends_on": [],
      "completion_barrier": "all_repos_accepted"
    },
    "implementation_sync": {
      "phase": "implementation",
      "repos": ["api", "web"],
      "entry_repo": "api",
      "depends_on": ["planning_sync"],
      "completion_barrier": "all_repos_accepted"
    },
    "qa_sync": {
      "phase": "qa",
      "repos": ["api", "web"],
      "entry_repo": "api",
      "depends_on": ["implementation_sync"],
      "completion_barrier": "all_repos_accepted"
    }
  },
  "routing": {
    "planning": {
      "entry_workstream": "planning_sync"
    },
    "implementation": {
      "entry_workstream": "implementation_sync"
    },
    "qa": {
      "entry_workstream": "qa_sync"
    }
  },
  "gates": {
    "initiative_ship": {
      "requires_human_approval": true,
      "requires_repos": ["api", "web"]
    }
  }
}

Keep the coordinator phase order aligned with the child repos. The default governed scaffold uses planning -> implementation -> qa, so the coordinator should declare the same order unless you intentionally customize every child repo's routing first. multi init rejects mismatches instead of letting them fail later during dispatch.

3. Initialize and dispatch the first repo​

agentxchain multi init
agentxchain multi step --json

The first multi step dispatches the entry repo for the current workstream. With the config above, that is repos/api.

4. Complete the repo-local planning turn​

Inside the selected repo, do the normal manual planning flow from the earlier section:

  • update .planning/PM_SIGNOFF.md and .planning/ROADMAP.md
  • write the staged result to .agentxchain/staging/<turn_id>/turn-result.json
  • run repo-local acceptance and repo-local phase approval
cd repos/api
agentxchain accept-turn
agentxchain approve-transition
cd ../..

Do not skip the repo-local approve-transition. The coordinator does not erase child repo gates. A planning turn that is accepted locally but still waiting on the child repo gate is not ready for the coordinator phase gate.

5. Dispatch the downstream repo with coordinator context​

agentxchain multi step --json

This dispatches repos/web and writes cross-repo handoff artifacts into the downstream bundle:

  • COORDINATOR_CONTEXT.json
  • COORDINATOR_CONTEXT.md

The JSON artifact carries upstream acceptance projections and barrier context from the already-accepted repo.

6. Complete the second repo, then open the coordinator gate​

Repeat the same repo-local flow in repos/web:

cd repos/web
agentxchain accept-turn
agentxchain approve-transition
cd ../..

Then return to the workspace:

agentxchain multi step --json
agentxchain multi approve-gate

At that point the coordinator can request phase_transition_requested from planning to implementation. You now have one active coordinated initiative, two linked governed child repos, coordinator history under .agentxchain/multirepo/, and real cross-repo context flowing into downstream repo turns.

If the coordinator enters blocked, fix the cause first, then run agentxchain multi resume. That restores the coordinator to active or paused without mutating repo-local state. Continue with agentxchain multi step or agentxchain multi approve-gate based on the restored status.

Verify the protocol surface​

If you are evaluating AgentXchain as protocol infrastructure, do not stop at a happy-path walkthrough. Run the conformance kit:

agentxchain verify protocol --tier 3 --target .

This exercises the shipped fixture corpus across the state machine, turn-result validation, trust-hardening surfaces, and multi-repo coordinator layer. Add --format json when you want CI-readable output.

Adapter modes​

AdapterHow it worksAutomation
manualHuman reads dispatch, does work, stages resultFull human control
local_cliOrchestrator spawns local coding CLI (Claude Code by default; any tool via --dev-command)Fully automated
mcpOrchestrator calls a local MCP stdio server tool that returns a governed turn resultFully automated
api_proxyOrchestrator calls LLM API directly with retry and cost trackingFully automated

Observe run lifecycle events​

Every governed lifecycle action emits a structured event to .agentxchain/events.jsonl. Use the events command to inspect or follow them in real time:

agentxchain events --json
agentxchain events --follow --type run_started,run_completed

This is the repo-local observability surface. For external notification delivery, configure webhooks in agentxchain.json — see Notifications.

Audit, export, and report​

Do not teach yourself the wrong boundary here:

agentxchain audit --format markdown
agentxchain export --format json > governance-export.json
agentxchain report --input governance-export.json --format markdown

Use audit for the live current repo or workspace summary. Use export when you need the portable artifact. Use report --input only when you already have an export artifact and want the verified derived summary.

That still holds in coordinator workspaces. Partial artifacts are intentional, not broken: audit and report keep repo_ok_count / repo_error_count export-health visibility plus the failed repo row and error, but they do not fabricate failed-child drill-down when the nested child export is unavailable.

Common mistakes​

  • Don't treat run as zero-config on the default scaffold. pm defaults to manual-pm; rebind that role or use step.
  • Don't confuse run with step. run drives a multi-turn automated flow. step runs one governed turn and is the right tool for manual roles.
  • Don't confuse init with execution. init creates the scaffold. run and step execute it.
  • Don't edit state.json manually. The orchestrator owns it.
  • Don't skip gates. approve-transition and approve-completion are constitutional — they exist so humans stay in control.
  • Turn results must have objections. Blind agreement is a protocol violation.

Continuous-delivery intake​

Governed runs can also start from delivery signals instead of manual step invocations. The intake command family turns CI failures, alerts, and other signals into governed work items with full audit trails:

agentxchain intake record --source ci_failure --category test_regression
agentxchain intake triage <event_id>
agentxchain intake approve <intent_id>
agentxchain intake plan <intent_id>
agentxchain intake start <intent_id>     # repo-local execution

When the fix spans multiple repos, use intake handoff instead of intake start to bridge the intent into a coordinator workstream. See Continuous Delivery Intake for the full lifecycle.

Next steps​