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

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 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 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 — 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 todocs/memory/entries/of that project any project-specific fact/decision worth remembering — not only when closing a phase. The project's owndocs/ORCHESTRATION.md /DECISIONS.md continue to hold protocol and broad history, as before.
2. Generalizable lessons (rarer, typically when closing a phase): what would serveany future project — a missing acceptance criterion, a prompt shape that confused an agent — is distilled and written back tofoundry-protocol/docs/LESSONS.md , never the reverse. This repository's genericORCHESTRATION.md is only edited when a lesson implies changing the protocol itself. See §6 ofORCHESTRATION.md and §3 ofCLAUDE.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) and Guilherme da Silveira (gbasilveira@gmail.com).

Licensed under MIT — see 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.