Skip to main content

Getting Started

This is the shortest honest path from "I saw the demo" to "I completed a real governed run in my own repo."

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

The key distinction: the default generic scaffold is manual-only (manual-pm, manual-dev, manual-qa), but the project template used on this page is mixed-mode. See the Runtime Matrix for all five runtimes, three authority levels, and which combinations are valid. If you want all governed turns automated while keeping human approvals at the gates, use the dedicated Automation Patterns page and the full-local-cli template instead of patching this walkthrough into something it is not.

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

That means:

  • agentxchain init --governed -y on the plain generic template needs no API keys and no local coding CLI before the first turn
  • npx --yes -p agentxchain@latest -c "agentxchain demo" needs no API keys
  • your first real repo can start with a manual planning turn immediately
  • the cli-tool QA leg on this page needs ANTHROPIC_API_KEY unless you change roles.qa.runtime to manual-qa first

If you want the shortest no-key path to a real accepted turn first, read Build Your First Governed Project in 5 Minutes. If you want artifact-by-artifact detail, read Your First Governed Turn. This page stays focused on the fastest real command sequence.

1. Run the demo first​

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

The demo proves the governed lifecycle without requiring any setup. Do not skip it if you are evaluating the product.

2. Scaffold a real repo​

npm install -g agentxchain
# or: brew tap shivamtiwari93/tap && brew install agentxchain
agentxchain --version
# Optional: install the VS Code extension from the Marketplace
# https://marketplace.visualstudio.com/items?itemName=agentXchaindev.agentxchain

mkdir my-first-governed && cd my-first-governed
agentxchain init --governed --template cli-tool --goal "Build a CLI that lints decision logs" --dir . -y
git init
agentxchain template validate
agentxchain doctor
agentxchain connector check
agentxchain connector validate local-dev   # prove the runtime produces valid governed turn results
git add -A
git commit -m "initial governed scaffold"

If you skipped --goal during scaffold, run agentxchain config --set project.goal "Build a CLI that lints decision logs" before the first governed turn. Do not re-run init --governed in place just to add the goal.

doctor checks config, binaries, env vars, and repo state. connector check is the live transport probe: it actively checks configured non-manual runtimes before the first turn and prints Probing ... progress lines while it works. For known CLIs (Claude Code, Codex), it also validates that the command flags match the role's authority intent — e.g., it warns if an authoritative role's command is missing --dangerously-skip-permissions or uses --full-auto instead of --dangerously-bypass-approvals-and-sandbox. connector validate <runtime_id> goes further: it sends a synthetic turn dispatch to the specified runtime in a scratch workspace and validates the response against the governed turn-result schema. This proves the runtime can produce valid governed output before you commit to a real run. If any of these commands fail, fix the issue before execution starts — it is cheaper to catch contract mismatches now than mid-run.

:::caution Clean working tree required for authoritative turns Authoritative and proposed turns require a clean git baseline — the framework compares files_changed in the turn result against the diff from the dispatch baseline. If you have uncommitted changes in actor-owned files when you try to assign a turn, the assignment will fail. Always commit scaffold and config changes before running your first automated turn. This is why the scaffold instructions above end with git add -A && git commit. :::

At this point the repo is scaffolded, but the planning gate is intentionally closed. PM_SIGNOFF.md starts at Approved: NO.

3. Start the planning turn​

Run the planning-phase entry turn:

agentxchain step

The CLI writes a dispatch bundle, prints the manual operator instructions, and waits for .agentxchain/staging/<turn_id>/turn-result.json.

Use the printed guidance directly:

  • open .agentxchain/dispatch/turns/<turn_id>/PROMPT.md
  • update .planning/PM_SIGNOFF.md, .planning/ROADMAP.md, and .planning/SYSTEM_SPEC.md
  • write the staged result JSON shown in the terminal

The current manual instructions now include:

  • phase-aware gate file hints
  • a minimal turn-result.json example with the real run_id and turn_id
  • the suggested next role

If you want the full artifact anatomy, stop here and read Your First Governed Turn.

4. Open the planning gate​

Once step detects and accepts the PM turn, advance the phase:

agentxchain approve-transition
git add -A
git commit -m "accept pm turn and open implementation"

If the command fails, the gate files are still placeholders or PM_SIGNOFF.md is not set to Approved: YES.

5. Run the implementation turn​

The default dev runtime is local_cli, scaffolded as:

claude --print --dangerously-skip-permissions --bare

Start the implementation leg:

agentxchain step --role dev --verbose
git add -A
git commit -m "accept dev turn"

This command only works if your local coding CLI wiring is truthful. If you use another tool, set it during init with --dev-command and --dev-prompt-transport, or update runtimes.local-dev before you expect the turn to run.

6. Run the QA leg honestly​

The shipped scaffold uses api-qa for qa, so the default path needs an Anthropic key:

export ANTHROPIC_API_KEY=...
agentxchain step --role qa

Before you run QA, make sure these files contain real content:

  • .planning/acceptance-matrix.md
  • .planning/ship-verdict.md
  • .planning/RELEASE_NOTES.md

If you do not want API-backed QA yet, use the built-in manual fallback before you run the turn:

agentxchain config --set roles.qa.runtime manual-qa

Do not hand-edit agentxchain.json for this scalar change. Use the governed config mutation path so the update is validated before the next turn. Do not pretend the cli-tool walkthrough is fully no-key end to end.

7. Complete the run​

If QA accepts and requests completion, finish with the explicit human approval:

agentxchain approve-completion
git add -A
git commit -m "approve governed completion"

That final approval is constitutional. It exists so humans remain sovereign over what actually ships.

8. Verify and share evidence truthfully​

If you want the live current repo summary right now, use audit:

agentxchain audit --format markdown

If you need a portable artifact for handoff, CI, or offline review, export first and then render it with report:

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

Do not collapse those commands into one vague "report the run" story. audit reads the live current repo or workspace. report --input reads an existing export artifact. In coordinator workspaces, partial artifacts are still valid: audit and report keep repo_ok_count / repo_error_count, preserve the failed repo row plus error, and do not fabricate failed-child drill-down when a nested export is missing.

Custom phases​

The default scaffold uses three phases: planning → implementation → qa. This is intentional — most governed runs fit this model.

If your workflow needs additional phases (e.g., design, security_review, staging), add them to the routing section of agentxchain.json after scaffolding:

{
  "routing": {
    "planning": { "entry_role": "pm", "exit_gate": "planning_signoff" },
    "design": { "entry_role": "architect", "exit_gate": "design_review" },
    "implementation": { "entry_role": "dev", "exit_gate": "implementation_complete" },
    "qa": { "entry_role": "qa", "exit_gate": "qa_ship_verdict" }
  }
}

Phase order is derived from the declaration order in routing. Transitions can only target the immediate next declared phase — no skipping. You must also add matching gate entries in gates for any custom phase. See Adapters for the full custom-phase contract.

Add workflow artifacts for custom phases​

Changing routing gives you phase order. Changing gates tells the orchestrator which files block a transition. Neither one tells AgentXchain what to scaffold or structurally validate for a new phase.

If you want a custom phase to own real workflow docs, declare workflow_kit explicitly in agentxchain.json. You can either reference a built-in phase template or spell out the artifact contract yourself:

{
  "workflow_kit": {
    "phases": {
      "architecture": {
        "template": "architecture-review"
      },
      "security_review": {
        "template": "security-review"
      },
      "design": {
        "artifacts": [
          {
            "path": ".planning/DESIGN_DOC.md",
            "semantics": "section_check",
            "semantics_config": {
              "required_sections": ["## Architecture", "## Interfaces", "## Trade-offs"]
            },
            "required": true
          }
        ]
      }
    }
  }
}

Important boundaries:

  • Built-in phase templates are additive shortcuts, not hidden magic. The shipped ids are planning-default, implementation-default, qa-default, architecture-review, and security-review.
  • workflow_kit.phases.<phase>.artifacts still works exactly as before. If you declare both template and artifacts, AgentXchain expands the built-in template first and then appends your explicit artifacts.
  • If workflow_kit is absent, the built-in workflow artifact contract stays limited to planning, implementation, and qa.
  • Custom phases without explicit workflow_kit entries can still gate on requires_files, but they do not get scaffolded files or structural checks from template validate.
  • workflow_kit: {} is an explicit opt-out. That disables per-phase workflow artifacts instead of silently falling back to the default scaffold contract.
  • Built-in phase templates do not guess owned_by. If you need role-bound ownership on a custom artifact, declare the artifact explicitly or use a blueprint-backed template like enterprise-app.

Use the CLI discovery surface before you hardcode template ids from memory:

agentxchain template list
agentxchain template list --phase-templates
agentxchain template list --phase-templates --json

That gives you the real shipped governed-template list plus the workflow-kit phase-template artifact contracts. The Templates page explains the same surface in depth.

After adding workflow_kit to an existing repo, re-run init in place so missing declared files are scaffolded:

agentxchain init --governed --dir . -y
agentxchain template validate

That proves scaffold/config agreement only. It does not mean the phase gate is ready to pass. The files still need real content that satisfies their runtime semantics.

Enterprise and custom-role teams​

The default scaffold uses pm, dev, and qa. If your workflow needs additional governed roles like architect or security_reviewer with dedicated phases and artifact contracts, use the enterprise-app template:

agentxchain init --governed --template enterprise-app --dir my-enterprise -y

This scaffolds a 5-phase workflow (planning → architecture → implementation → security_review → qa) with 6 roles, custom gate artifacts, and structurally validated docs for each phase. See Templates — Blueprint-backed templates for the full walkthrough.