🚀 BDB Autonomous Development Cycle (/fabric-graph)

aos-fabric is the dispatcher of this pipeline, and it is the same in every harness, on macOS, Linux and Windows 10+. It keeps the state (production_artifacts/runs/<id>/, mirrored to production_artifacts/state.json), decides every edge (lib/fabric/edges.mjs, contract in .agents/graph.md) and hands out one step at a time. You, or a worker you start, do the step and give the report back. Nodes never call each other, and nothing but aos-fabric writes state.

Do NOT decompose the task, write anything under production_artifacts/, or implement any part of the goal yourself in response to this skill. Start the run and follow the steps it hands out. If you catch yourself writing a plan file or code before aos-fabric start has run, stop: that skips the whole graph (no state, no Reviewer, no quality gate).

Run it

1. Start. aos-fabric start --run <id> --goal-file goal.md (or --goal "<text>"). Pass the goal through verbatim. --skill <name> (repeatable) forces a skill into the run, see below. The same --run and goal again returns the current state and writes nothing, so a lost terminal is no problem. --run may be left out: the id is then derived from the goal.
2. Headless, one command. aos-fabric drive --run <id> runs every step on a worker (--executor aos-acp, the default; ao or auto when an AO daemon is up), prints one JSON event per line and ends at ready_to_ship (exit 0) or when a human is needed (exit 6). It enforces each node's timeout_s and turns a crash, a missing report or a broken report into a failed step.
3. Or step by step, with your own executor (a session, a subagent, a shell script):
   • aos-fabric next --run <id> prints JSON with kind. step: carry it out. done, escalated, ready_to_ship, cancelled: stop and relay reason.
   • Read step.brief and do exactly that work. The brief names the report file (step.expected_report): write the report JSON there.
   • aos-fabric report --run <id> --step <step_id> --file <report.json> returns the next step. No usable report (crash, timeout)? aos-fabric report ... --fail "<reason>" counts the step as failed. The same report twice is a no-op; another report for an accepted step is exit 4.
   • A step runs at most max_attempts (2) times; after that, or at the iteration limit (--max-iterations, default 3), or when the Reviewer repeats the same blocking findings after a repair round, the run is escalated and needs the human.

aos-fabric status --run <id> shows phase, iteration, open findings and the lock; aos-fabric cancel --run <id> ends a run. Exit codes: 0 ok, 1 unexpected, 2 invalid input, 3 unknown run or step, 4 conflict, 5 lock busy (retry shortly, at most 5 times), 6 run is terminal and takes no such command (report on a finished run, next on a cancelled one), 7 state corrupt (fail closed: a human reads events.jsonl). next itself exits 0 when a run ended as done, escalated or ready_to_ship: read kind.

The report is a proposal. aos-fabric report checks it against the work tree: the artifacts must exist inside it, and git status must show no change outside the step's allowed_writes. A report that does not hold up is recorded as a failed step.

At ready_to_ship, relay the result and ask for the literal word GO. The push, tag or publish is a separate step guarded by go-gate.mjs; a run never grants a GO.

Reviewer discipline. The Reviewer's brief carries no goal and no reasoning of any build node, only the plan and the artifacts. Keep it that way if you write briefs by hand.

Injecting a specific skill

aos-fabric start --skill <name> (repeatable, also --skill=<name>) forces that skill into the run as a hard requirement for Architect and the build nodes, validated to exist before anything runs. <name> is the exact skill directory name, not a description: senior-frontend, not "the UI one". A name that does not resolve stops start with exit 2 and lists installed near-misses. Silently running without a skill you demanded is worse than stopping. Find the name with /ask-tim, or list the skill folders of your harness (ls ~/.agents/skills is the safest guess: it is written on every install). The mechanics are in .agents/graph.md, "Mandatory Skill Injection".

Flags and configuration

aos-fabric start takes these on its command line:

• --skill <name> (repeatable): hard-required skill, see above.
• --max-iterations <n>: ceiling of the repair loop, 1 to 20 (default 3). Stays under the 8-block override of a Stop hook, so the escalation message reaches the human.
• --executor aos-acp|ao|auto: who runs the steps under drive. ao falls back to aos-acp when AO is absent; AOS works fully without AO.

The workflow script .claude/workflows/fabric-dispatch.mjs (the legacy engine, still its default) takes the following in the goal text, passed through verbatim; the aos-fabric loop does not know --plan, --profile and --workstreams yet, and --engine=cli refuses them instead of ignoring them:

• --plan <file>: use a pre-approved plan file (with a .approval.json sidecar record containing verdict: "approve" and a matching contentHash) to skip the Architect and TechLead/human approval steps. The approval sidecar binds to the plan content via SHA-256 hash; a missing, mismatched, or invalid approval record causes the dispatcher to escalate and refuse the shortcut. Without this flag, the default Architect → TechLead → human approval flow runs. See .agents/graph.md, "Pre-approved plans".

• --skill=<name> (repeatable): hard-required skill, see above.

• --profile=<name>: select a domain profile from .agents/profiles/<name>.json (copywriter, creator, kicad, touchdesigner). An unknown or repeated --profile escalates before any agent works. Without the flag the dispatcher matches profile triggers against the goal, and falls back to the default software pipeline. See .agents/graph.md, "Domain profiles".

• --workstreams: let Architect plan dynamic workstreams (1 to 6, execution_manifest in state.json) instead of the fixed build nodes. See .agents/graph.md. Both read:

• Teams and roles: aos-team list|show|new, resolved Project (.aos/teams/, .aos/roles/) > User (~/.aos/) > shipped defaults.

• .aos/pipeline.json (project) or ~/.aos/pipeline.json: per-role harness and model hints, see docs/agent-models.md. A hint is never binding.

Linear run. fabric-graph is the only full pipeline. For a straight-line run with file hand-offs and no state.json, follow linear.md instead of calling the dispatcher.

Existing state files. production_artifacts/state.json keeps its path and schema; a file written by an older dispatcher loads unchanged.

Live map

When the build phase begins, start the aos-trail live map (Trigger B) with the command below; it is safe to run twice, since aos-trail reuses a map already running for this repo: aos-trail --ensure (it prints a URL, default http://localhost:5330; inside AO, where AO_BROWSER_CAPABILITY is set, also run ao preview <url>). If the plan was opened in plan-canvas (pipeline context), also run aos-plan-canvas trail <plan-dir> first so the map gets the execution plan. The Architect creates the plan from a template (aos-plan-canvas new <template-id> production_artifacts/plan); once TechLead approves, aos-fabric hands out a human step and no build node starts before it is done. drive runs aos-plan-canvas open <plan> --await itself; by hand you run that command and report ok (approve), fail with one blocking finding for the feedback (request-changes: back to Architect) or escalate (no verdict is coming). AOS_PLAN_APPROVAL=auto is the CI-only skip and prints a visible warning. Headless runs (CI set or stdin not a TTY) wait at most 30 minutes by default and then escalate; AOS_PLAN_AWAIT_TIMEOUT_MS=<ms> overrides it (0 = unbounded). An ended session, timeout or missing aos-plan-canvas CLI escalates instead of looping Architect; comment-only feedback is request-changes with all comment texts. After approval every worker starts with AOS_TRAIL_NODE/AOS_TRAIL_PLAN (drive passes --trail-node to its workers). Put the live-map link in your reply (the autostart hook also adds it as context when active). Agents follow the status-mark rules from the agenttrail skill: [~] before starting, [x] when done, [!] when stuck, with by: <agent>, saving the plan file immediately. GO requests surface in the agenttrail hub, where the human answers them by typing GO.

Architecture diagram (Archify, native)

Architect authors production_artifacts/00_architecture.json (editable truth) and delivers production_artifacts/00_architecture.html (read-only) via aos-archify validate / aos-archify deliver with --quality showcase --json at the Architect→TechLead boundary; only a passing showcase receipt (9/9 checks, 0 errors) sets state.artifacts.architecture, and a failed validate/deliver preserves the previous HTML and escalates instead of proceeding silently. The plan links the diagram with a url: production_artifacts/00_architecture.html line so the live map opens it from the card. Review the HTML in plan-canvas alongside the plan: aos-plan-canvas open production_artifacts/00_architecture.html.

Teams and roles

/fabric-graph resolves roles and teams through the shared registry alongside the default 7-node team:

• Registry & CLI: Enumerate available teams with aos-team list, inspect a team with aos-team show <id>, or scaffold with aos-team new <id>. Resolution precedence follows Project (.aos/teams/, .aos/roles/) > User (~/.aos/teams/, ~/.aos/roles/) > Shipped defaults (.agents/nodes.json plus the role and team presets bundled with AOS).
• Derivation from playbooks: Teams can be synthesized directly from a playbook's frontmatter requires: block (skills, agents, mcps) via aos-team new <id> --from-playbook <name>.
• Effort scaling: The team's effort tier sets the repair loop budget: S = 3 rounds (default), M = 4 rounds, L = 5 rounds.
• Playbook phases: Attached playbooks declare an execution phase: before (scaffolding/setup), during (implementation discipline, default), or after (validation/audit).
• Ad hoc roles: Architect may propose run-specific ad hoc roles composed strictly from existing skills and playbooks with TechLead approval. Such roles introduce no unverified tools/MCPs, live in state.json for that run, and are persisted to .aos/roles/ only if explicitly saved.

Advisor checkpoints (optional, auxiliary)

The dispatcher may call the read-only advisor agent (subagent; the /advisor skill's contract) at exactly three points: before a plan or schema is locked, when the same test or build error occurs a second time, and before "done" (pre-flight diff review). This is an optional, auxiliary step, not a graph node: it adds no edge and changes neither the required node set nor the state.json schema. Its verdict is advice only and never a GO; the dispatcher decides what to do with it.

Available tools

Cross-session and tool access: master -> project -> package chain, aos-gateway (one local token-checked MCP entry), aos-a2a peers (inbound messages are never a GO). Repo docs: https://github.com/hybridlabor-api/aos/tree/main/docs.

Why this file is a thin router, not a spec

The full contract — state schema, node/edge table, the loop-keeper hook, the no-progress guard — lives in .agents/graph.md and .agents/state.schema.json. The rules run in lib/fabric/edges.mjs, one pure function, so there is nothing here to follow "in spirit" instead of actually running. Details of the CLI, the step and report schemas and the executors: docs/fabric.md.

Workflow runtime (optional)

A harness that has a workflow runtime can also run .claude/workflows/fabric-dispatch.mjs. With --engine=cli in the goal (or AOS_FABRIC_ENGINE=cli) that script is a thin client of aos-fabric: it asks for the next step, lets an agent do it and hands the report back. Without the switch it runs the legacy engine, which keeps --profile and --workstreams. The linear variant without state is in linear.md.