{"slug": "foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents", "title": "Foundry-protocol – A framework for orchestrating complex tasks with AI agents", "summary": "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.", "body_md": "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).\n\n**Core idea:** the protocol itself is an artifact that improves with use. Each project\nthat uses it produces lessons — what worked, what misled an agent, which acceptance\ncriterion was missing. Those lessons flow back to [`docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) in\n*this* repository, rather than staying trapped in the project where they arose. The next\nproject starts with that experience already built in, instead of repeating the same\nmistakes.\n\n```\nfoundry-protocol/\n├── CLAUDE.md                    # operating instructions for Claude\n│                                 # when acting as orchestrator/planner\n├── docs/\n│   ├── ORCHESTRATION.md         # generic protocol (roles, cycle, WO, log)\n│   ├── DECISIONS.md             # template for the decisions/ADR register\n│   ├── AUTONOMY-EVAL.md         # template + validated criteria for\n│   │                             # assessing whether an agent can coordinate alone\n│   ├── LESSONS.md               # self-improvement ledger — grows with each project\n│   ├── history/                 # where condensed per-project summaries live\n│   ├── memory/                  # template for per-project living memory\n│   │   ├── ENTRY-TEMPLATE.md    # format of one entry (same shape as the\n│   │   │                         # Claude Code personal memory)\n│   │   └── MEMORY.md            # index template\n│   ├── work-orders/TEMPLATE.md  # work order template (PREPARATION, tasks, sabotage checks, RESULT)\n│   ├── gates/TEMPLATE.md        # human validation gate template (≥ 1 PR, complete report)\n│   ├── ORCHESTRATOR-LOOP.md     # optional autonomous cycle (orchestrator does not implement; failure ⇒ new agent)\n│   ├── FORMAT-CONTRACT.md       # stable shapes that tools read without an LLM\n│   ├── RESUME.md                # resuming a WO in any session/account\n│   ├── RESTART-PROMPT.md        # template for the orchestrator restart prompt\n│   ├── DR-INDEX.md              # DR index, one line each (minimal context)\n│   ├── CONTEXT-TEMPLATE.md      # per-package CONTEXT.md (≤ 45 lines, instead of reading src/)\n│   └── foundry.conf             # BASE_BRANCH, GATE_BRANCH_PREFIX, VERIFY_CMD\n├── .claude-plugin/marketplace.json  # local marketplace (for `claude plugin install`)\n├── plugin/                      # Claude Code plugin: skills + MCP engine\n│   ├── .claude-plugin/plugin.json\n│   ├── mcp/server.mjs           # local MCP engine (see plugin/mcp/README.md)\n│   └── skills/\n│       ├── bootstrap-project/\n│       ├── close-work-order-cycle/\n│       └── write-project-memory/\n├── runtime/                      # agno/AgentOS foundation (Phase 1, experimental)\n└── scripts/\n    ├── bootstrap-project.sh     # installs the skeleton into a new or existing project\n    └── project/                 # scripts copied to <project>/scripts/\n        ├── wo.sh                # status [NNN] | resume NNN | next\n        ├── wo-watchdog.sh       # STALLED / FINISHED(review) WOs / 429 signals\n        ├── gate.sh              # status | report NN [--verify] | pr NN\n        ├── olog.sh              # curated, append-only, committed LOG\n        ├── orch-hook.py         # hook: raw record of each operation (outside git)\n        ├── check-format-contract.sh\n        ├── _conf.sh             # reads docs/foundry.conf\n        └── claude-settings.json # hook for .claude/settings.json\n```\n\nThe pieces `ORCHESTRATOR-LOOP`, `FORMAT-CONTRACT`, `RESUME`, `DR-INDEX`, per-package\n`CONTEXT.md` and the scripts come from a multi-agent project (2026-10). There they took\ndozens of WOs to `ACCEPTED` in an autonomous cycle, with rate limits and resumes across\naccounts (`LESSONS.md` #21–#25). The **human validation gates** (`docs/gates/`) are the\npiece that connects that cycle to the user's direction: each gate is at least one PR and\ncarries a complete report of completed operations (`ORCHESTRATION.md` §2.3).\n\n```\n/path/to/foundry-protocol/scripts/bootstrap-project.sh /path/to/project \"Project Name\"\n```\n\nThis creates, inside the target project, the documents of `docs/` listed above (protocol,\nWO and gate templates, `foundry.conf`, LOG, `history/`), the scripts from\n`scripts/project/` into `scripts/`, the logging hook in `.claude/settings.json` (only if it\ndoes not exist yet) and `docs/memory/{ENTRY-TEMPLATE.md,MEMORY.md,entries/,media/}`. The\nlatter is the project's living memory, which grows at every cycle (see §6 of the generated\n`ORCHESTRATION.md`). After that, the normal work is: fill in §0/§3 (state + shared context)\nof the project's `ORCHESTRATION.md` with that project's concrete facts, consult\n[`docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) before the first work order, and follow the protocol\nin §2.\n\n```\n/path/to/foundry-protocol/scripts/update-project.sh /path/to/project          # dry run: shows the plan\n/path/to/foundry-protocol/scripts/update-project.sh /path/to/project --apply  # applies it\n```\n\nBootstrap records, for each managed file (`scripts/managed-files.txt`), a baseline copy in\n`docs/.foundry/base/` and the foundry version in `docs/.foundry/version`. On update:\n\n- **UPDATE** — the project did not edit the file: it is replaced by the new version.\n- **MERGE** — both changed: a three-way merge (`git merge-file` ), applied only if it is clean.\n- **CONFLICT** — overlapping edits: the project file is left untouched and the merge is written\nto`<file>.conflict` . Resolve by hand, delete the`.conflict` file, and run`--apply` again.\n- **ADOPT / NEW / DELETED / GONE** — projects bootstrapped before this mechanism have no\nbaseline: identical files are adopted, different ones are reported as conflicts to review by hand.\n\nThe 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.\n\n`plugin/` packages the recurring procedures of the protocol as\n[Claude Skills](https://docs.claude.com/en/docs/claude-code/skills) —\n`bootstrap-project`, `close-work-order-cycle`, `write-project-memory` — so that any session\ncan invoke them directly instead of re-reading all of `ORCHESTRATION.md` each time.\n\nTo register the plugin locally, symlink `plugin/` into Claude Code's personal skills directory\n(`<claude-skills-dir>/`). It then loads in any session, in any project:\n\n```\nln -s /path/to/foundry-protocol/plugin <claude-skills-dir>/foundry-protocol\nclaude plugin validate <claude-skills-dir>/foundry-protocol   # confirm\nclaude plugin list                                       # should list foundry-protocol@skills-dir\n```\n\nBecause the symlink points into the repository, editing `plugin/` here takes effect\nimmediately — there is no sync step.\n\nTwo directions, not to be confused:\n\n1. **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\nremembering — not only when closing a phase. The project's own`docs/ORCHESTRATION.md` /`DECISIONS.md` continue to hold protocol and broad history, as before.\n2. **Generalizable lessons (rarer, typically when closing a phase):** what would serve**any** future project — a missing acceptance criterion, a prompt shape that confused an\nagent — is distilled and written back to[`foundry-protocol/docs/LESSONS.md`](https://github.com/AlphaIAt/foundry-protocol/blob/master/docs/LESSONS.md) ,\nnever the reverse. This repository's generic`ORCHESTRATION.md` is only edited when a\nlesson implies changing the protocol itself. See §6 of`ORCHESTRATION.md` and §3 of`CLAUDE.md` .\n\nThis 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.\n\nOriginal authors and maintainers: **αIAt** ([https://aiat.pt](https://aiat.pt)) and **Guilherme da Silveira**\n([gbasilveira@gmail.com](mailto:gbasilveira@gmail.com)).\n\nLicensed under MIT — see [`LICENSE`](https://github.com/AlphaIAt/foundry-protocol/blob/master/LICENSE). The code files (scripts, MCP engine, runtime)\ncarry the same attribution in their header.\n\n`runtime/` (agno/AgentOS foundation, Phase 1) is experimental and is not yet supported as\na stable part of the protocol.", "url": "https://wpnews.pro/news/foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents", "canonical_source": "https://github.com/AlphaIAt/foundry-protocol", "published_at": "2026-10-20 21:23:48+00:00", "updated_at": "2026-10-20 21:47:17.098298+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["foundry-protocol", "Claude", "Claude Code", "agno", "AgentOS"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents", "markdown": "https://wpnews.pro/news/foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents.md", "text": "https://wpnews.pro/news/foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents.txt", "jsonld": "https://wpnews.pro/news/foundry-protocol-a-framework-for-orchestrating-complex-tasks-with-ai-agents.jsonld"}}