Tutorial: Install to Completion

This tutorial walks you through one complete governed lifecycle — from an empty directory to approve-completion. Every command is copy-pasteable. No API keys required. No local coding CLI required. No hand-waving.

Time: ~15 minutes. Prerequisites: Node.js 18.17+, git, a terminal.

By the end you will have run a governed PM → Dev → QA cycle with real gate enforcement, real artifact checks, and a real governance report.

:::tip Already ran the demo? If you ran npx --yes -p agentxchain@latest -c "agentxchain demo", you saw governance in action with canned data. This tutorial does the same thing manually so you understand every step. :::

Step 1 — Install and verify

npm install -g agentxchain
agentxchain --version

You should see a version number (e.g. 2.44.0). If you only want the zero-install demo path instead of a real install, use:

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

Step 2 — Scaffold a governed repo

mkdir tutorial-governed && cd tutorial-governed
agentxchain init --governed --template cli-tool --goal "Build a CLI that lints decision logs" --dir . -y
git init && git add -A && git commit -m "initial governed scaffold"

Verify the scaffold is structurally valid and the environment is ready:

agentxchain template validate
agentxchain doctor

Your repo now has:

• agentxchain.json — roles, runtimes, routing, gates
• .agentxchain/state.json — orchestrator-owned run state (status: idle)
• .agentxchain/prompts/ — role-specific prompt files
• .planning/PM_SIGNOFF.md — starts at Approved: NO (intentionally blocked)
• .planning/ROADMAP.md, .planning/SYSTEM_SPEC.md — planning artifacts
• .planning/IMPLEMENTATION_NOTES.md, .planning/acceptance-matrix.md, .planning/ship-verdict.md, .planning/RELEASE_NOTES.md — later-phase gate files

Switch dev and QA to manual (fully reproducible)

The cli-tool scaffold used here is mixed-mode:

• dev uses local-dev
• qa uses api-qa

That is honest for normal usage, but it is the wrong fit for a copy-paste tutorial. For this walkthrough, change roles.dev.runtime from local-dev to manual-dev, change roles.qa.runtime from api-qa to manual-qa, and keep every turn on the same printed prompt flow.

Use agentxchain config --set to rebind both roles:

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

Both manual-dev and manual-qa already exist in the scaffold. These commands only rebind the active roles.

Commit the config change:

git add agentxchain.json && git commit -m "switch dev and qa to manual for tutorial"

Step 3 — Start the planning turn

agentxchain step

What happens: the orchestrator initializes a governed run, assigns the first turn to pm (the planning phase entry role), and waits for a result.

You'll see output like:

Initialized governed run: run_e4f2...

MANUAL TURN REQUIRED
Role: pm
Turn: turn_a1b2...
Prompt: .agentxchain/dispatch/turns/turn_a1b2.../PROMPT.md
Result: .agentxchain/staging/turn_a1b2.../turn-result.json

Note the turn ID — you'll need it for the result file.

Step 4 — Do the PM's work

As the PM, you need to fill in the planning gate files. Open each file and replace the placeholder content.

.planning/PM_SIGNOFF.md

# PM Planning Sign-Off

Approved: YES

## Scope
Build a URL shortener CLI tool with create, resolve, and list commands.

## Acceptance Criteria
1. `shorten <url>` creates a short code and prints it
2. `resolve <code>` prints the original URL or an error
3. `list` prints all stored mappings
4. All operations persist to a local JSON file

.planning/ROADMAP.md

Replace the phase table rows with real goals (keep the table structure):

# Roadmap

| Phase | Goal | Status |
|-------|------|--------|
| Planning | Define scope, acceptance criteria, and technical constraints | In progress |
| Implementation | Build the three CLI commands with JSON persistence | Pending |
| QA | Verify all acceptance criteria against the implementation | Pending |

## Deliverables
- `shorten.js` — main CLI entry point
- `store.js` — JSON persistence layer
- `shorten.test.js` — acceptance tests

.planning/SYSTEM_SPEC.md

Replace the placeholder content with a real spec:

# System Spec

## Purpose
Build a URL shortener CLI tool that lets operators create, resolve, and list short links from the terminal.

## Interface
- `shorten <url>` → stdout: `<code>`
- `resolve <code>` → stdout: `<original_url>` | stderr: `Unknown code`
- `list` → stdout: `<code> -> <url>` (one per line)

## Behavior
- Single-module Node.js CLI
- JSON file storage at `./.data/store.json`
- Short codes are deterministic per URL so repeated shorten requests reuse the same code

## Error Cases
- Invalid command prints usage and exits non-zero
- Unknown code prints `Unknown code` and exits non-zero

## Acceptance Tests
- [ ] `node shorten.js shorten https://example.com` prints a short code
- [ ] `node shorten.js resolve <code>` prints `https://example.com`
- [ ] `node shorten.js list` prints `<code> -> https://example.com`
- [ ] `./.data/store.json` exists after the first shorten operation

## Constraints
- No external dependencies beyond Node.js stdlib
- Idempotent: shortening the same URL twice returns the same code

Stage the PM turn result

Create the result file at the path shown in the terminal output. Replace <turn_id> with your actual turn ID:

mkdir -p .agentxchain/staging/<turn_id>

Write .agentxchain/staging/<turn_id>/turn-result.json:

{
  "schema_version": "1.0",
  "run_id": "<your_run_id>",
  "turn_id": "<your_turn_id>",
  "role": "pm",
  "runtime_id": "manual-pm",
  "status": "completed",
  "summary": "Scoped URL shortener CLI: 3 commands, JSON persistence, 4 acceptance criteria.",
  "decisions": [
    {
      "id": "DEC-001",
      "category": "scope",
      "statement": "MVP: shorten, resolve, list commands with local JSON storage.",
      "rationale": "Minimal useful surface to prove the governed workflow."
    }
  ],
  "objections": [
    {
      "id": "OBJ-001",
      "severity": "low",
      "statement": "Defer analytics and team features until the core shorten/resolve/list flow is proven.",
      "status": "raised"
    }
  ],
  "files_changed": [],
  "artifacts_created": [],
  "verification": {
    "status": "pass",
    "commands": [],
    "evidence_summary": "Planning review — no code to verify.",
    "machine_evidence": []
  },
  "artifact": { "type": "review", "ref": null },
  "proposed_next_role": "human",
  "phase_transition_request": "implementation",
  "needs_human_reason": null,
  "cost": { "input_tokens": 0, "output_tokens": 0, "usd": 0 }
}

:::caution Use your real IDs Replace <your_run_id> and <your_turn_id> with the actual values from step output. The orchestrator rejects mismatched IDs. :::

The step process detects the staged file and accepts the turn automatically.

Commit the planning work:

git add -A && git commit -m "complete planning turn"

Step 5 — Approve the phase transition

The PM's turn result requested phase_transition_request: "implementation". The orchestrator moves the run to pending_phase_transition. Now the human approves:

agentxchain approve-transition

If this fails, the gate files are still placeholders or PM_SIGNOFF.md does not contain Approved: YES.

git add -A && git commit -m "approve planning → implementation"

Step 6 — Run the implementation turn

agentxchain step

Because you rebound dev to manual-dev, the orchestrator assigns a turn to dev and prints the same manual-turn prompt you saw in planning. If you skip the runtime edit above, this step dispatches to local-dev instead.

Do the Dev's work

Fill in .planning/IMPLEMENTATION_NOTES.md:

# Implementation Notes

## Changes
- Created `shorten.js` with `shorten`, `resolve`, and `list` commands
- Created `store.js` for JSON persistence at `./.data/store.json`
- Short codes are deterministic per URL

## Verification
- `node shorten.js shorten https://example.com` → prints a 6-char code
- `node shorten.js resolve <code>` → prints `https://example.com`
- `node shorten.js list` → prints `<code> -> https://example.com`

## Technical Decisions
- Used a deterministic stdlib-only hash for repeatable short codes
- Stored mappings in a repo-local JSON file for a self-contained tutorial fixture

Stage the dev turn result (same pattern — replace IDs):

{
  "schema_version": "1.0",
  "run_id": "<your_run_id>",
  "turn_id": "<your_turn_id>",
  "role": "dev",
  "runtime_id": "manual-dev",
  "status": "completed",
  "summary": "Implemented URL shortener: 3 commands, JSON persistence, idempotent codes.",
  "decisions": [
    {
      "id": "DEC-002",
      "category": "implementation",
      "statement": "Used crypto.randomBytes for code generation with URL-hash idempotency.",
      "rationale": "stdlib-only, collision-resistant, deterministic for repeated URLs."
    }
  ],
  "objections": [],
  "files_changed": ["shorten.js", "store.js", ".planning/IMPLEMENTATION_NOTES.md", ".data/store.json"],
  "artifacts_created": [".data/store.json"],
  "verification": {
    "status": "pass",
    "commands": ["node shorten.js shorten https://example.com"],
    "evidence_summary": "All 3 commands tested manually. Output matches spec.",
    "machine_evidence": [
      { "command": "node shorten.js shorten https://example.com", "exit_code": 0, "stdout_excerpt": "a1b2c3" }
    ]
  },
  "artifact": { "type": "workspace", "ref": null },
  "proposed_next_role": "qa",
  "phase_transition_request": "qa",
  "needs_human_reason": null,
  "cost": { "input_tokens": 0, "output_tokens": 0, "usd": 0 }
}

Commit:

git add -A && git commit -m "complete implementation turn"

The implementation gate auto-advances to qa after a passing accepted turn. There is no human approval step between implementation and QA in the default governed scaffold.

Step 7 — Run the QA turn

agentxchain step

The orchestrator assigns a turn to qa. Fill in the QA gate files:

.planning/acceptance-matrix.md

# Acceptance Matrix

| Req # | Criterion | Evidence | Status |
|-------|-----------|----------|--------|
| 1 | `shorten <url>` creates a short code | Manual test: `node shorten.js shorten https://example.com` → `a1b2c3` | PASS |
| 2 | `resolve <code>` prints original URL | Manual test: `node shorten.js resolve a1b2c3` → `https://example.com` | PASS |
| 3 | `list` prints all mappings | Manual test: `node shorten.js list` → `a1b2c3 -> https://example.com` | PASS |
| 4 | Persists to local JSON | Verified `./.data/store.json` exists after shorten | PASS |

.planning/ship-verdict.md

# Ship Verdict

## Verdict: YES

All 4 acceptance criteria pass. No blocking objections. Implementation matches spec.

.planning/RELEASE_NOTES.md

# Release Notes — v0.1.0

## User Impact

Operators can now create, resolve, and list short links from a governed CLI workflow.

## Verification Summary

Manual QA verified shorten, resolve, list, and persistence against the acceptance matrix.

Stage the QA turn result:

{
  "schema_version": "1.0",
  "run_id": "<your_run_id>",
  "turn_id": "<your_turn_id>",
  "role": "qa",
  "runtime_id": "manual-qa",
  "status": "completed",
  "summary": "All 4 acceptance criteria pass. Ship verdict: YES.",
  "decisions": [
    {
      "id": "DEC-003",
      "category": "quality",
      "statement": "All acceptance criteria verified against the implementation.",
      "rationale": "Manual testing confirms shorten, resolve, list, and persistence."
    }
  ],
  "objections": [
    {
      "id": "OBJ-003",
      "severity": "low",
      "statement": "Manual QA is enough for this walkthrough, but the next iteration should replace the manual checks with automated regression coverage.",
      "status": "raised"
    }
  ],
  "files_changed": [],
  "artifacts_created": [],
  "verification": {
    "status": "pass",
    "commands": [],
    "evidence_summary": "Review-only turn. Verified against acceptance matrix.",
    "machine_evidence": []
  },
  "artifact": { "type": "review", "ref": null },
  "proposed_next_role": "human",
  "run_completion_request": true,
  "needs_human_reason": null,
  "cost": { "input_tokens": 0, "output_tokens": 0, "usd": 0 }
}

Notice run_completion_request: true — this tells the orchestrator the QA reviewer thinks the run is ready to ship.

Commit:

git add -A && git commit -m "complete QA turn"

Step 8 — Complete the governed run

The run is now in pending_run_completion. The human gives final 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.

Step 9 — Verify

Check the final state:

agentxchain status
agentxchain audit --format markdown

You should see status: completed and all three phases closed. audit is the live current repo/workspace summary surface.

If you need a portable artifact for handoff, export the run and then generate the governance report from that artifact:

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. report --input reads an existing export artifact; it does not inspect live repo state directly. This produces a structured summary of the run: turns, decisions, gate evaluations, timing, and the complete decision ledger.

That same boundary applies in coordinator workspaces. Partial artifacts are still valid evidence surfaces: 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 the nested child export is unavailable.

What you just did

You completed a full governed lifecycle:

1. Scaffolded a governed repo with roles, routing, and gates
2. Planned — PM filled gate files, the orchestrator checked them at phase exit
3. Implemented — Dev wrote code, and the implementation gate auto-advanced to QA after passing verification
4. Reviewed — QA verified acceptance criteria and requested completion
5. Approved — Human gave sovereign approval to ship

Every transition was gated. Every decision was recorded. Every artifact was checked. This is the same protocol that runs with AI agents — you just played all three roles manually.

What to do next

• Getting Started — the fastest path with real AI runtimes
• Your First Governed Turn — artifact-level detail for every file in the scaffold
• Templates — try enterprise-app for custom roles and 5-phase workflows
• Multi-Session Continuity — how to pause and resume governed runs across sessions
• Adapters — rebind runtimes to use AI agents instead of manual turns