Foundry-protocol – A framework for orchestrating complex tasks with AI agents

A GitHub project called foundry-protocol has published a reusable framework for orchestrating complex tasks with AI agents, combining a human/AI-orchestrator protocol, Claude-based planning and sub-agent executors. The framework was extracted from a compliance-audit project that ran T0-T5 across 25 work orders in September 2026, and its components including ORCHESTRATOR-LOOP, FORMAT-CONTRACT, RESUME and DR-INDEX come from a separate multi-agent project in October 2026 that took dozens of work orders to ACCEPTED status autonomously, with rate limits and resumes across accounts. The protocol is designed as a self-improving artifact, with lessons from each project flowing back into a shared docs/LESSONS.md ledger so the next project starts with prior experience built in.

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 <project /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 <file .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 <claude-skills-dir / . It then loads in any session, in any project: ln -s /path/to/foundry-protocol/plugin <claude-skills-dir /foundry-protocol claude plugin validate <claude-skills-dir /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.