# Foundry-protocol – A framework for orchestrating complex tasks with AI agents > Source: > Published: 2026-10-20 21:23:48+00:00 A reusable framework for orchestrating complex tasks with AI agents, using the human/AI-orchestrator protocol + Claude planning + sub-agent executors. Extracted and generalized from real experience in a compliance-audit project (T0-T5, 25 work orders, 2026-09). **Core idea:** the protocol itself is an artifact that improves with use. Each project that uses it produces lessons — what worked, what misled an agent, which acceptance criterion was missing. Those lessons flow back to [`docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) in *this* repository, rather than staying trapped in the project where they arose. The next project starts with that experience already built in, instead of repeating the same mistakes. ``` foundry-protocol/ ├── CLAUDE.md # operating instructions for Claude │ # when acting as orchestrator/planner ├── docs/ │ ├── ORCHESTRATION.md # generic protocol (roles, cycle, WO, log) │ ├── DECISIONS.md # template for the decisions/ADR register │ ├── AUTONOMY-EVAL.md # template + validated criteria for │ │ # assessing whether an agent can coordinate alone │ ├── LESSONS.md # self-improvement ledger — grows with each project │ ├── history/ # where condensed per-project summaries live │ ├── memory/ # template for per-project living memory │ │ ├── ENTRY-TEMPLATE.md # format of one entry (same shape as the │ │ │ # Claude Code personal memory) │ │ └── MEMORY.md # index template │ ├── work-orders/TEMPLATE.md # work order template (PREPARATION, tasks, sabotage checks, RESULT) │ ├── gates/TEMPLATE.md # human validation gate template (≥ 1 PR, complete report) │ ├── ORCHESTRATOR-LOOP.md # optional autonomous cycle (orchestrator does not implement; failure ⇒ new agent) │ ├── FORMAT-CONTRACT.md # stable shapes that tools read without an LLM │ ├── RESUME.md # resuming a WO in any session/account │ ├── RESTART-PROMPT.md # template for the orchestrator restart prompt │ ├── DR-INDEX.md # DR index, one line each (minimal context) │ ├── CONTEXT-TEMPLATE.md # per-package CONTEXT.md (≤ 45 lines, instead of reading src/) │ └── foundry.conf # BASE_BRANCH, GATE_BRANCH_PREFIX, VERIFY_CMD ├── .claude-plugin/marketplace.json # local marketplace (for `claude plugin install`) ├── plugin/ # Claude Code plugin: skills + MCP engine │ ├── .claude-plugin/plugin.json │ ├── mcp/server.mjs # local MCP engine (see plugin/mcp/README.md) │ └── skills/ │ ├── bootstrap-project/ │ ├── close-work-order-cycle/ │ └── write-project-memory/ ├── runtime/ # agno/AgentOS foundation (Phase 1, experimental) └── scripts/ ├── bootstrap-project.sh # installs the skeleton into a new or existing project └── project/ # scripts copied to /scripts/ ├── wo.sh # status [NNN] | resume NNN | next ├── wo-watchdog.sh # STALLED / FINISHED(review) WOs / 429 signals ├── gate.sh # status | report NN [--verify] | pr NN ├── olog.sh # curated, append-only, committed LOG ├── orch-hook.py # hook: raw record of each operation (outside git) ├── check-format-contract.sh ├── _conf.sh # reads docs/foundry.conf └── claude-settings.json # hook for .claude/settings.json ``` The pieces `ORCHESTRATOR-LOOP`, `FORMAT-CONTRACT`, `RESUME`, `DR-INDEX`, per-package `CONTEXT.md` and the scripts come from a multi-agent project (2026-10). There they took dozens of WOs to `ACCEPTED` in an autonomous cycle, with rate limits and resumes across accounts (`LESSONS.md` #21–#25). The **human validation gates** (`docs/gates/`) are the piece that connects that cycle to the user's direction: each gate is at least one PR and carries a complete report of completed operations (`ORCHESTRATION.md` §2.3). ``` /path/to/foundry-protocol/scripts/bootstrap-project.sh /path/to/project "Project Name" ``` This creates, inside the target project, the documents of `docs/` listed above (protocol, WO and gate templates, `foundry.conf`, LOG, `history/`), the scripts from `scripts/project/` into `scripts/`, the logging hook in `.claude/settings.json` (only if it does not exist yet) and `docs/memory/{ENTRY-TEMPLATE.md,MEMORY.md,entries/,media/}`. The latter is the project's living memory, which grows at every cycle (see §6 of the generated `ORCHESTRATION.md`). After that, the normal work is: fill in §0/§3 (state + shared context) of the project's `ORCHESTRATION.md` with that project's concrete facts, consult [`docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) before the first work order, and follow the protocol in §2. ``` /path/to/foundry-protocol/scripts/update-project.sh /path/to/project # dry run: shows the plan /path/to/foundry-protocol/scripts/update-project.sh /path/to/project --apply # applies it ``` Bootstrap records, for each managed file (`scripts/managed-files.txt`), a baseline copy in `docs/.foundry/base/` and the foundry version in `docs/.foundry/version`. On update: - **UPDATE** — the project did not edit the file: it is replaced by the new version. - **MERGE** — both changed: a three-way merge (`git merge-file` ), applied only if it is clean. - **CONFLICT** — overlapping edits: the project file is left untouched and the merge is written to`.conflict` . Resolve by hand, delete the`.conflict` file, and run`--apply` again. - **ADOPT / NEW / DELETED / GONE** — projects bootstrapped before this mechanism have no baseline: identical files are adopted, different ones are reported as conflicts to review by hand. The project name, base branch and relative link to foundry-protocol are rendered the same way the bootstrap fills them in, so they are not reverted. `plugin/` packages the recurring procedures of the protocol as [Claude Skills](https://docs.claude.com/en/docs/claude-code/skills) — `bootstrap-project`, `close-work-order-cycle`, `write-project-memory` — so that any session can invoke them directly instead of re-reading all of `ORCHESTRATION.md` each time. To register the plugin locally, symlink `plugin/` into Claude Code's personal skills directory (`/`). It then loads in any session, in any project: ``` ln -s /path/to/foundry-protocol/plugin /foundry-protocol claude plugin validate /foundry-protocol # confirm claude plugin list # should list foundry-protocol@skills-dir ``` Because the symlink points into the repository, editing `plugin/` here takes effect immediately — there is no sync step. Two directions, not to be confused: 1. **Project memory (at every relevant cycle):** the Claude in planning role writes to`docs/memory/entries/`*of that project* any project-specific fact/decision worth remembering — not only when closing a phase. The project's own`docs/ORCHESTRATION.md` /`DECISIONS.md` continue to hold protocol and broad history, as before. 2. **Generalizable lessons (rarer, typically when closing a phase):** what would serve**any** future project — a missing acceptance criterion, a prompt shape that confused an agent — is distilled and written back to[`foundry-protocol/docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) , never the reverse. This repository's generic`ORCHESTRATION.md` is only edited when a lesson implies changing the protocol itself. See §6 of`ORCHESTRATION.md` and §3 of`CLAUDE.md` . This is what makes the agent "more competent with experience": it is not a model being retrained; it is the protocol + the lessons ledger accumulating explicit, readable, versioned judgment — applied by any future session that reads this repository before starting. Original authors and maintainers: **αIAt** ([https://aiat.pt](https://aiat.pt)) and **Guilherme da Silveira** ([gbasilveira@gmail.com](mailto:gbasilveira@gmail.com)). Licensed under MIT — see [`LICENSE`](https://github.com/AlphaIAt/foundry-protocol/blob/master/LICENSE). The code files (scripts, MCP engine, runtime) carry the same attribution in their header. `runtime/` (agno/AgentOS foundation, Phase 1) is experimental and is not yet supported as a stable part of the protocol.