Your First Governed Turn

You ran npx agentxchain demo and saw governance in action. Now do it for real on your own repo. This guide walks through every step, shows you what each artifact looks like, and tells you exactly when to act.

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

Step 1 — Scaffold

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

After this, your repo has:

my-first-governed/
├── agentxchain.json              # roles, runtimes, gates, workflow
├── .agentxchain/
│   ├── state.json                # orchestrator-owned run state
│   ├── history.jsonl             # append-only turn history
│   ├── decision-ledger.jsonl     # every decision from every turn
│   ├── dispatch/turns/           # turn dispatch bundles (written by orchestrator)
│   ├── staging/                  # turn results (written by actor, read by orchestrator)
│   ├── reviews/                  # QA review artifacts (materialized by orchestrator)
│   └── prompts/
│       ├── pm.md                 # PM role prompt
│       ├── dev.md                # Dev role prompt
│       ├── qa.md                 # QA role prompt
│       └── eng_director.md       # Engineering Director prompt
├── .planning/
│   ├── PM_SIGNOFF.md             # ← starts at "Approved: NO"
│   ├── ROADMAP.md
│   ├── SYSTEM_SPEC.md
│   ├── IMPLEMENTATION_NOTES.md
│   ├── acceptance-matrix.md
│   ├── ship-verdict.md
│   ├── RELEASE_NOTES.md
│   └── (template extras)         # e.g. command-surface.md for cli-tool
└── TALK.md                       # collaboration log (orchestrator appends here)

The cli-tool template adds project-type planning artifacts like command-surface.md, distribution-checklist.md, and platform-support.md. Other templates add different extras. See Templates for details.

Verify the scaffold is intact:

agentxchain template validate

Step 2 — Assign the PM Turn

agentxchain step

What happens:

On a fresh scaffold, step initializes the governed run automatically
The orchestrator creates a dispatch bundle at .agentxchain/dispatch/turns/<turn_id>/
The bundle contains ASSIGNMENT.json, MANIFEST.json, CONTEXT.md, and PROMPT.md
Because the planning phase entry role is pm, the first turn is assigned to PM without needing --role pm
State moves to active, and step waits for .agentxchain/staging/<turn_id>/turn-result.json

What you see:

Initialized governed run: run_e4f2...

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

What to do next: Read PROMPT.md and CONTEXT.md. ASSIGNMENT.json gives you the authoritative staging path and turn metadata. MANIFEST.json records the dispatch bundle contents.

Step 3 — Write Planning Artifacts

Open .planning/PM_SIGNOFF.md. It looks like this:

# PM Signoff — My First Governed

Approved: NO

> This scaffold starts blocked on purpose. Change this to `Approved: YES`
> only after a human reviews the planning artifacts and is ready to open
> the planning gate.

## Discovery Checklist
- [ ] Target user defined
- [ ] Core pain point defined
- [ ] Core workflow defined
- [ ] MVP scope defined
- [ ] Out-of-scope list defined
- [ ] Success metric defined

## Notes for team
(PM and human add final kickoff notes here.)

This is part of the planning gate. It starts at Approved: NO on purpose. The full planning gate requires three files to be ready:

.planning/PM_SIGNOFF.md
.planning/ROADMAP.md
.planning/SYSTEM_SPEC.md

Human approval still matters, but the gate is broader than a single file.

Fill in the checklist, add your scope, and change Approved: NO → Approved: YES:

# PM Signoff — My First Governed

Approved: YES

> This scaffold starts blocked on purpose. Change this to `Approved: YES`
> only after a human reviews the planning artifacts and is ready to open
> the planning gate.

## Discovery Checklist
- [x] Target user defined — developers who process CSV data
- [x] Core pain point defined — existing tools OOM on large files
- [x] Core workflow defined — stdin/file → streaming parse → JSON stdout
- [x] MVP scope defined — single-file CLI, streaming, error handling
- [x] Out-of-scope list defined — no GUI, no multi-file, no format detection
- [x] Success metric defined — handles 1GB+ CSV without OOM

## Notes for team
CLI tool that converts CSV files to JSON with streaming support for large files.
Acceptance criteria: reads from stdin/file, outputs valid JSON, handles >1GB, exits non-zero on errors.

Also update .planning/ROADMAP.md with your delivery phases, and .planning/SYSTEM_SPEC.md with the technical contract.

Step 4 — Stage the PM Turn Result

The orchestrator needs a structured result at .agentxchain/staging/<turn_id>/turn-result.json. The exact path is written in ASSIGNMENT.json, and the full schema is embedded in PROMPT.md. Fill it in like this:

{
  "schema_version": "1.0",
  "run_id": "run_...",
  "turn_id": "turn_...",
  "role": "pm",
  "runtime_id": "manual-pm",
  "status": "completed",
  "summary": "Scoped CSV-to-JSON CLI: streaming, error handling, 4 acceptance criteria",
  "decisions": [
    {
      "id": "DEC-001",
      "category": "scope",
      "statement": "Streaming architecture — no full-file buffering",
      "rationale": "1GB+ files must work without OOM"
    },
    {
      "id": "DEC-002",
      "category": "scope",
      "statement": "Exit codes: 0 success, 1 malformed CSV, 2 I/O error",
      "rationale": "Predictable exit codes for shell pipelines"
    }
  ],
  "objections": [
    {
      "id": "OBJ-001",
      "severity": "medium",
      "against_turn_id": "self",
      "statement": "No character encoding spec — assumes UTF-8 only",
      "status": "raised"
    }
  ],
  "files_changed": [],
  "artifacts_created": [],
  "verification": {
    "status": "skipped",
    "commands": [],
    "evidence_summary": "Planning review turn — no code changes.",
    "machine_evidence": []
  },
  "artifact": { "type": "review", "ref": null },
  "needs_human_reason": null,
  "cost": { "input_tokens": 0, "output_tokens": 0, "usd": 0 },
  "proposed_next_role": "human",
  "phase_transition_request": "implementation",
  "run_completion_request": null
}

Key points:

objections is required. Every role must challenge — blind agreement is a protocol violation.
decisions accumulate in the decision ledger (.agentxchain/decision-ledger.jsonl). They are append-only. Neither you nor any agent can delete them.
phase_transition_request: "implementation" tells the orchestrator the PM wants to advance past planning.
proposed_next_role: "human" is normal here because the run pauses for human approval before the phase can advance.

Step 5 — Let `step` Accept the Turn, Then Open the Gate

Once the staged result file exists, the same agentxchain step process detects it, validates it, and accepts the turn automatically. If validation passes, you see output like:

Staged result detected.

Turn Accepted
Turn:     turn_a1b2c3d4e5f6...
Role:     pm
Status:   completed
Reason:   pending_phase_transition
Action:   agentxchain approve-transition
Detail:   planning_signoff

Now approve the pending planning transition:

agentxchain approve-transition

This is where the gate matters. The orchestrator checks the planning gate contract. If PM_SIGNOFF.md is still unapproved, or ROADMAP.md / SYSTEM_SPEC.md are still placeholders, the gate stays closed.

When the gate passes, the CLI prints the actual phase transition:

Approving Phase Transition
From:  planning
To:    implementation
Gate:  planning_signoff

✓ Phase advanced: planning → implementation
Next: agentxchain step

Commit the orchestrator state:

git add -A && git commit -m "pm turn accepted, phase: implementation"

Step 6 — Dev Turn

agentxchain step --verbose

In the cli-tool template, dev is bound to local_cli by default, so the implementation turn is the next entry-role turn. The orchestrator spawns your local coding agent with the full dispatch context. The agent implements the work, runs tests, and stages its own turn result.

If dev is bound to manual, you write the code yourself and stage the result like the PM turn.

After the dev turn completes, step validates and accepts that turn too. The decision ledger now has the PM's 2 decisions plus the dev's decisions — all append-only, all traceable.

What the decision ledger looks like after two turns:

{"id":"DEC-001","category":"scope","statement":"Streaming architecture...","turn_id":"turn_a1b2...","role":"pm"}
{"id":"DEC-002","category":"scope","statement":"Exit codes: 0, 1, 2...","turn_id":"turn_a1b2...","role":"pm"}
{"id":"DEC-003","category":"implementation","statement":"Use Node.js Transform streams...","turn_id":"turn_f7e8...","role":"dev"}
{"id":"DEC-004","category":"implementation","statement":"Resolved OBJ-001: added --encoding flag...","turn_id":"turn_f7e8...","role":"dev"}

The implementation_complete gate auto-evaluates — it checks that IMPLEMENTATION_NOTES.md has real content and verification passed. If it does, the phase advances to qa automatically.

Step 7 — QA Turn

agentxchain step

At this point the run is in the qa phase, so agentxchain step assigns the QA turn by default. In the cli-tool template, QA is bound to api_proxy, so the orchestrator sends the full context to an LLM and materializes the review under .agentxchain/reviews/. This requires ANTHROPIC_API_KEY to be set. If you want to stay fully manual, rebind QA to a manual runtime first.

QA must raise at least one objection. This is not bureaucracy — it's how governed delivery catches issues that PM and dev both missed:

{
  "objections": [
    {
      "id": "OBJ-002",
      "severity": "low",
      "against_turn_id": "turn_f7e8...",
      "statement": "No test for CSV with embedded newlines in quoted fields",
      "status": "raised"
    }
  ]
}

After the QA turn is accepted by step:

agentxchain approve-completion

The qa_ship_verdict gate checks .planning/acceptance-matrix.md, .planning/ship-verdict.md, and .planning/RELEASE_NOTES.md, then waits for human approval. If the verdict is SHIP, the run completes.

What You Have Now

After one full PM → Dev → QA cycle:

Artifact	What it proves
`.agentxchain/decision-ledger.jsonl`	Every decision from every role, append-only
`.agentxchain/history.jsonl`	Full turn history with timestamps
`.agentxchain/reviews/`	QA review artifacts (if `api_proxy`)
`.planning/PM_SIGNOFF.md`	Human approved the planning scope
`.planning/IMPLEMENTATION_NOTES.md`	Dev documented what changed and how to verify
`.planning/ship-verdict.md`	QA approved the ship decision
`TALK.md`	Cross-role collaboration log

The decision ledger is the governance proof. Any auditor, any future agent, any operator can read it and understand: what was decided, by whom, when, and why. No decisions can be deleted or edited after acceptance.

Common Gate Failures

Failure	Cause	Fix
`planning_signoff` failed	`PM_SIGNOFF.md` is still unapproved, or `ROADMAP.md` / `SYSTEM_SPEC.md` are still placeholders	Complete all three planning files, then rerun `agentxchain approve-transition`
`implementation_complete` failed	`IMPLEMENTATION_NOTES.md` is still placeholder	Fill in real `## Changes` and `## Verification` sections
`qa_ship_verdict` failed	`ship-verdict.md` still says `PENDING`, `RELEASE_NOTES.md` is missing, or acceptance evidence is incomplete	Set `## Verdict: SHIP` (or `NO SHIP` to block), finish `RELEASE_NOTES.md`, and make sure the acceptance matrix is real

Next Steps

Quickstart — Automated Path — run the full lifecycle without manual turns
CLI Reference — full command surface
Adapters — configure automated agents (local CLI, API proxy, MCP)
Templates — project-type scaffolds
Protocol v6 — the constitutional spec

Step 1 — Scaffold​

Step 2 — Assign the PM Turn​

Step 3 — Write Planning Artifacts​

Step 4 — Stage the PM Turn Result​

Step 5 — Let step Accept the Turn, Then Open the Gate​

Step 6 — Dev Turn​

Step 7 — QA Turn​

What You Have Now​

Common Gate Failures​

Next Steps​