Archon Workflows — User Manual & Letta Integration Study

Contents

1. What Archon Is
2. Quick Start & CLI Cheat Sheet
3. Workflow Anatomy (YAML DAG)
4. Key Features In Depth
5. Configuration
6. Architecture Comparison: Archon vs Our Letta/Mazda Stack
7. Reuse Analysis — As-Is, Concepts, Code, Concerns
8. Recommendation
9. Proposed Integration Steps

1 · What Archon Is

Archon is a self-hostable, governed agentic automation engine. It runs multi-step workflows that mix deterministic steps (bash / TypeScript / Python scripts) with AI agent steps (Claude Code SDK, Codex SDK, and others), with human approval gates and a full audit trail — driven from Slack, Telegram, GitHub, Discord, the web UI, or the CLI. Its most mature use is agentic coding against git repos; the same engine is being extended to general business-operations automation.

Stack: Bun workspaces monorepo — @archon/paths, @archon/git, @archon/providers, @archon/isolation, @archon/workflows (the engine), @archon/core, @archon/adapters, @archon/server (Hono + OpenAPI), @archon/web (React), @archon/cli. Storage is SQLite by default (~/.archon/archon.db, zero setup) or PostgreSQL via DATABASE_URL. License is MIT.

2 · Quick Start & CLI Cheat Sheet

The CLI runs workflows directly, no server needed. It must be run from inside a git repository (subdirectories work). From /home/adamsl/Archon:

# Dev server + web UI (server :3090, web :5173)
bun run dev

# Everything below works standalone from any git repo:
bun run cli workflow list                      # what workflows exist here (bundled + repo + ~/.archon)
bun run cli workflow run assist "What does the orchestrator do?"
bun run cli workflow run implement "Add auth"  # auto-creates an isolated worktree + branch
bun run cli workflow run implement --branch feature-auth "Add auth"
bun run cli workflow run quick-fix --no-worktree "Fix typo"   # opt out of isolation
bun run cli workflow run implement "Add auth" --detach        # background child process

bun run cli workflow status                    # active runs (running + paused)
bun run cli workflow runs --json               # recent runs, machine-readable
bun run cli workflow get <run-id> --verbose    # one run, per-node summary
bun run cli workflow resume <run-id>           # re-run a failed run, skipping completed nodes
bun run cli workflow abandon <run-id>          # discard a non-terminal run

# Approval gates (a paused run waits for one of these):
bun run cli workflow approve <run-id> "looks good, also rename X"
bun run cli workflow reject  <run-id> "wrong file, target server.py"

bun run cli validate workflows                 # lint all workflow YAML + referenced resources
bun run cli isolation list                     # active worktrees
bun run cli isolation cleanup --merged         # remove worktrees whose branches merged
bun run cli doctor                             # verify setup (claude binary, gh auth, DB, adapters)

In chat surfaces (Slack/Telegram/web) the same lifecycle is exposed as slash commands: /workflow list, /workflow run <name> <args>, /workflow status, /workflow approve <id>, /workflow resume <id>, etc. Free-text messages are routed by an AI router to the best-matching workflow (falling back to archon-assist).

Where workflows live

3 · Workflow Anatomy (YAML DAG)

A workflow is a YAML file with a nodes: list. Each node has an id, exactly one node-type key, and optional depends_on edges. Nodes in the same topological layer run concurrently. Everything is Zod-validated at load time (cycles, unknown deps, bad $nodeId.output references, unknown providers all rejected before anything runs).

Node types

Data flow between nodes

• $nodeId.output — cleaned output of a completed upstream node.
• $nodeId.output.field — field access when the producer declared output_format (a JSON schema). Access is strict: an undeclared field fails the consuming node instead of silently passing ''.
• output_format — structured JSON output, SDK-grammar-enforced on Claude/Codex/OpenCode and best-effort (validate + re-ask up to 3×) on Pi/Copilot. A node that declares a schema but can't produce valid output fails loudly.
• when: conditions and trigger_rule join semantics for conditional branches.
• Variables: $1..$n, $ARGUMENTS, $ARTIFACTS_DIR (per-run artifacts directory, pre-created), $WORKFLOW_ID, $BASE_BRANCH, $LOOP_USER_INPUT, $REJECTION_REASON.

A real bundled example (abridged)

name: archon-feature-development
description: |
  Use when: Implementing a feature from an existing plan.
nodes:
  - id: implement
    command: archon-implement       # named prompt template
    provider: claude
    model: large                    # resolves through the tier system

  - id: create-pr
    command: archon-create-pr
    depends_on: [implement]
    context: fresh                  # new session, not a continuation

  - id: verify-pr-base
    bash: |                         # deterministic step, no AI
      set -euo pipefail
      HEAD_BRANCH=$(git rev-parse --abbrev-ref HEAD)
      PR_NUMBER=$(gh pr list --head "$HEAD_BRANCH" --state open --json number -q '.[0].number')
      ...
    depends_on: [create-pr]

A gated pipeline sketch (what a Mazda-style stage chain looks like)

name: finance-doc-pipeline
nodes:
  - id: parse
    prompt: "Parse the statement at $1 into transactions."
    output_format:                  # schema-validated JSON out
      type: object
      properties:
        vendor:   { type: string }
        total:    { type: number }

  - id: duplicate-check
    script:
      runtime: uv                   # real Python, real DB, deterministic
      name: duplicate_lookup        # .archon/scripts/duplicate_lookup.py
    depends_on: [parse]

  - id: human-gate
    approval: "Store expense for $parse.output.vendor, total $parse.output.total?"
    capture_response: true
    depends_on: [duplicate-check]

  - id: store
    script: { runtime: uv, name: store_expense }
    depends_on: [human-gate]

4 · Key Features In Depth

5 · Configuration

Two YAML files, merged (repo overrides global):

assistants:
  claude:
    model: sonnet                # or opus / haiku / claude-* / inherit
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium

tiers:                           # what small/medium/large mean HERE
  small:  { provider: claude, model: haiku }
  medium: { provider: claude, model: sonnet }
  large:  { provider: codex,  model: gpt-5.5, effort: high }

aliases:
  "@cheap": { provider: pi, model: openrouter/qwen/qwen3-coder }

Priority: workflow-level options → config defaults → SDK defaults. Per-project env vars (codebase_env_vars table, managed in the web UI) are injected into Claude/Codex/bash/script node subprocess environments.

6 · Architecture Comparison: Archon vs Our Letta/Mazda Stack

Our system (per Mazda — A Developer's Manual and the Self-Improvement Plan) has two faces: the runtime — Mazda, a Letta orchestrator agent, delegating to five minion agents that drive Claude Agent SDK sessions against a finance MCP server — and the control plane — the interface-first Python agent_self_improvement package (trace → judge → propose → A/B → gate → activate → rollback; nine factory families; "improve the wrapper, never the model").

7 · Reuse Analysis

USE AS-IS Components reusable directly

ADOPT CONCEPTS Design patterns that would improve our architecture

• Deterministic engine orders the steps; the LLM fills them in. Our Mazda plan already concluded this ("Mazda stops carrying every operation as one overloaded toolset") — Archon shows the working shape: stage order is data (YAML), not prompt text, so it's versionable, diffable, and gateable. This is precisely a "workflow skeleton" from self-improvement Phase 08.
• Immutable sessions with explicit transition reasons. Every session change records parent_session_id + transition_reason. Applied to Mazda's memory edits, this would give the self-improvement loop the provenance chain it needs for rollback.
• Strict structured output as a node contract. output_format + schema-validated $node.output.field access, failing loudly on misses. This is our "stable handoff contracts" between stage agents, enforced by the engine instead of by convention.
• Tier/alias model indirection. Workflows name small/medium/large, config binds them. For the wrapper-improvement thesis this makes "model" just another wrapper knob that A/B experiments can flip without touching prompts.
• "No autonomous lifecycle mutation across process boundaries." A process that can't prove work is orphaned must not kill it — surface it with a one-click action instead. Directly relevant to our dashboard's restart buttons and to Mazda run recovery.
• Store-interface seams (IWorkflowStore, WorkflowDeps injection). The engine package has zero DB/AI/config dependencies; everything is injected. Our nine-factory-families design shares this instinct — Archon proves it works at production scale in TS.

ADAPT CODE Source code worth adapting or integrating

CONCERNS Compatibility concerns, limitations, required changes

8 · Recommendation

9 · Proposed Integration Steps

1. Pilot (no code, ~an afternoon). From rol_finances: bun run cli workflow list, then run archon-assist and one coding workflow in a worktree. Confirm ~/.archon/ workspace layout, artifacts, and the approve/reject loop from the CLI.
2. Author the first finance workflow (YAML only). Recreate one Mazda pipeline slice (parse → duplicate-check → approval → store) as rol_finances/.archon/workflows/finance-doc-pipeline.yaml, with the deterministic steps as script: runtime: uv nodes calling our existing Python services, and output_format schemas as the stage contracts. Run with --no-worktree.
3. Build LettaProvider in packages/providers/src/community/letta/ (modeled on the Pi provider, registered builtIn: false): sendQuery() → Letta REST messages API, streaming chunks back; session-resume → the agent's own conversation. Then a DAG node can be Mazda or a minion via provider: letta.
4. Evidence bridge. Add a terminal bash:/script: node (or a small consumer of workflow_events) that posts run summaries to the logger API (:8284) so improvement-loop judging can score Archon runs alongside live-agent traces.
5. Wire one improvement-loop gate. Express "propose wrapper change → human gate → activate (snapshot) / reject (rollback)" as an Archon workflow whose activate/rollback steps call the agent_self_improvement Python services. This is the first live use of the gated loop that §4 of the Self-Improvement Plan says is built-but-not-wired.
6. Dashboard visibility. Once runs exist, add a dashboard panel polling Archon's REST API (GET /api/workflows/runs, server on :3090) the same way we poll Letta — runs, statuses, and pending approvals surfaced next to agent health.

References

• Archon repo: /home/adamsl/Archon (branch dev) — architecture reference in its CLAUDE.md; docs site content under packages/docs-web/.
• Bundled workflow corpus: /home/adamsl/Archon/.archon/workflows/defaults/.
• Mazda — A Developer's Manual: mazda_dev_status.html.
• Mazda Self-Improvement Plan: mazda_self_improvement_plan.html.
• Superseded orchestrator design (history): team_construction_plan.html.