Skip to main content

Automation patterns

This page names the runtime patterns operators actually try to build, instead of forcing them to infer everything from scattered examples.

Pattern: all automated turns, human gate approvals only​

This is the beta tester's natural target setup:

  • PM, Dev, QA, and Director all run through local_cli
  • every governed role is authoritative
  • humans do not author turns manually
  • humans do approve phase/completion gates

Use the dedicated scaffold for it:

agentxchain init --governed --template full-local-cli --goal "Ship a governed product slice" --dir my-project -y

What that means in practice:

  • pm -> local-pm
  • dev -> local-dev
  • qa -> local-qa
  • eng_director -> local-director
  • planning still pauses for approve-transition
  • completion still pauses for approve-completion

This is not the same as lights-out run --auto-approve. Humans still hold the constitutional approvals. The difference is that humans approve gates instead of manually writing turn results.

Exact local CLI command shapes​

Use truthful unattended-write commands. Anything weaker is a false-positive setup.

  • Claude Code: claude --print --dangerously-skip-permissions --bare
  • Codex CLI: codex exec --dangerously-bypass-approvals-and-sandbox {prompt}

Those commands map to different prompt transports:

  • Claude Code -> prompt_transport: "stdin"
  • Codex CLI -> prompt_transport: "argv"

If you scaffold full-local-cli with --dev-command and --dev-prompt-transport, AgentXchain applies that local CLI contract across the template's default local runtimes instead of silently customizing only dev.

For complete per-CLI recipes including troubleshooting, see Local CLI Recipes.

Fast path​

agentxchain init --governed --template full-local-cli --goal "Ship a governed docs linter" --dir my-project -y
cd my-project

git init
agentxchain template validate
agentxchain doctor
agentxchain connector check
agentxchain connector validate local-pm
agentxchain connector validate local-dev

Then choose one of the two truthful operating modes.

Continuous mode: preferred​

run --continuous now auto-checkpoints accepted authoritative turns by default, so Dev and QA handoffs do not stall on manual git commits.

agentxchain run --continuous --vision .planning/VISION.md --max-runs 1
agentxchain approve-transition
agentxchain run --continuous --vision .planning/VISION.md --max-runs 1
agentxchain approve-completion

What happens:

  1. The first continuous run drives the automated PM turn, checkpoints it, and pauses only for the planning gate.
  2. approve-transition opens implementation.
  3. The second continuous run drives Dev and QA, checkpointing each accepted authoritative turn before the next writable handoff.
  4. approve-completion closes the run.

Step-by-step mode: manual checkpoint boundary​

If you prefer step, you must checkpoint after each accepted authoritative turn.

agentxchain step
agentxchain checkpoint-turn
agentxchain status
agentxchain approve-transition
agentxchain step
agentxchain checkpoint-turn
agentxchain step
agentxchain checkpoint-turn
agentxchain approve-completion

What happens:

  1. The first step dispatches the automated PM turn and auto-accepts it.
  2. checkpoint-turn records the accepted PM artifacts so the next authoritative turn starts from a clean baseline.
  3. The run pauses at the planning gate because human approval is still required.
  4. approve-transition opens implementation.
  5. The next step dispatches Dev automatically.
  6. checkpoint-turn records the accepted Dev artifacts before the next authoritative turn.
  7. The next step dispatches QA automatically.
  8. checkpoint-turn records the accepted QA artifacts, then approve completion.

That is the whole point of the pattern: automated turns, human gates.

Do not skip the checkpoint between accepted authoritative turns. The next code-writing turn will fail closed if the latest accepted writable turn is still only in the working tree.

Why authoritative turns require a clean working tree​

AgentXchain validates turn results by comparing files_changed against the diff between the dispatch baseline (the git state when the turn was assigned) and the post-turn working tree. If uncommitted files exist before dispatch, the acceptance validator cannot distinguish "files the agent changed" from "files that were already dirty." This causes false-negative rejections where the turn is correct but the validator rejects it for undeclared changes.

The clean-baseline rule exists to make artifact observation reliable:

  • Before every authoritative turn: checkpoint the latest accepted turn or commit/stash unrelated repo dirt.
  • If you hit a dirty-tree refusal naming an accepted turn: run agentxchain checkpoint-turn --turn <id>.
  • If you hit a dirty-tree refusal for unrelated files: run git status, commit or stash the listed files, then retry.
  • doctor will warn you if the working tree is dirty and the next expected role is authoritative.

Human steering during automation​

If the operator needs to redirect the next PM turn without dropping back to manual runtimes, inject the work item and then resume PM dispatch explicitly:

agentxchain inject "Revise the roadmap around the new acceptance contract" \
  --priority p0 \
  --charter "Revise the PM plan before more implementation turns" \
  --acceptance "roadmap reflects the new scope,system spec reflects the new interface"

agentxchain resume --role pm
agentxchain step --resume

The injected charter is foregrounded into the next PM dispatch bundle as the primary instruction, not buried as background context. Use this path when a human wants to steer the run between automated turns.

If the repo is blocked on a human escalation first, clear that blocker with agentxchain unblock <id> before resuming PM dispatch.

When to use this pattern​

Use full-local-cli when:

  • you want automated planning, implementation, and QA turns
  • you trust local CLI agents to write directly in the repo
  • you still want humans approving major transitions
  • you want the shortest path to a governed automation loop without manual runtime roles

Do not use it when:

  • you are still learning the artifact contract and want the manual-first generic scaffold
  • QA or PM must stay non-writing by policy
  • you need remote/provider review paths instead of local subprocesses