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

npx agentxchain@latest --version

You should see a version number (e.g. 2.26.0). If npm resolves to a stale global install, use:

npx -p agentxchain@latest -c 'agentxchain --version'

Step 2 — Scaffold a governed repo

mkdir tutorial-governed && cd tutorial-governed
npx agentxchain init --governed --template cli-tool --dir . -y
git init && git add -A && git commit -m "initial governed scaffold"

Verify the scaffold is structurally valid:

agentxchain template validate

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 default scaffold 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.

Edit agentxchain.json and change the dev and qa role runtimes:

{
  "roles": {
    "dev": {
      "runtime": "manual-dev"
    },
    "qa": {
      "runtime": "manual-qa"
    }
  }
}

manual-qa already exists in the scaffold. Add manual-dev to the runtimes section:

{
  "runtimes": {
    "manual-dev": {
      "type": "manual"
    }
  }
}

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

You should see status: completed and all three phases closed.

Export the run and then generate the governance report:

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

This produces a structured summary of the run: turns, decisions, gate evaluations, timing, and the complete decision ledger.

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