Agent Foundry MCP server

Agent Foundry

Skill and agent runtime for AI coding assistants.

Plan → execute → verify. Skills, agents, a local daemon. MIT, local, no cloud. 41 original skills. Two optional skills carry their own Apache-2.0 license; see LICENSES.md.

Quick start · Catalog · Architecture · Commands · Web app

---

Why Agent Foundry

Models hallucinate. They over-comment. They reach for npm install when you asked for a one-line fix. Agent Foundry steers the model back to the actual work.

Three layers:

Layer	What	Lives in
🧠 Skills	Disciplines the model applies (how to think, not what to know)	skills/core/<name>/SKILL.md
🤖 Agents	Roles the orchestrator can dispatch (critic, planner, orchestrator)	agents/af-*/AGENT.md
⚙️ Orchestrator	Local daemon that ranks, dispatches, executes, logs, judges	agent_foundry/ (Python)

Each layer is portable. A skill body is a plain markdown file with a trigger phrase. An agent is a role definition. The orchestrator is a Python package you can pip install or run from source.

---

Quick start

1. Install

Two independent lanes. Install one or both.

Skills (Node 22.14+, no Python):

macOS / Linux / Git Bash:

curl -fsSL https://raw.githubusercontent.com/youcisla/Agent-Foundry/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/youcisla/Agent-Foundry/main/scripts/install.ps1 | iex

Or run the installer from npm without a global install (any OS). The explicit package plus bin form selects the Node installer even when the Python package is also installed:

npx --yes --package @youcisla/agent-foundry agent-foundry-install
npx --yes --package @youcisla/agent-foundry agent-foundry-install --list

A global install exposes the same bin:

npm install -g @youcisla/agent-foundry
agent-foundry-install --list

The same package is mirrored on GitHub Packages: https://github.com/youcisla/Agent-Foundry/pkgs/npm/agent-foundry.

Runtime (Python 3.10-3.14, no Node):

pip install agent-foundry-runtime
agent-foundry-runtime init
agent-foundry-runtime doctor
uvx agent-foundry-runtime mcp   # MCP stdio server, no install needed

Registry name: io.github.youcisla/agent-foundry.

agent-foundry still works as a compatibility alias from either package, but two packages can install the same name. Scripts should use agent-foundry-install (Node) and agent-foundry-runtime (Python). The alias is kept until at least 2027-06-30.

Every harness gets each skill as a direct child of its real discovery root. See docs/harness-compatibility.md for the path matrix and the dos/don'ts.

Then set an API key:

export ANTHROPIC_API_KEY=sk-...   # or OPENAI_API_KEY

2. Use it

In Claude Code (or any harness that accepts slash commands):

/af "build a react component"      # plan + execute
/plan "audit this API"             # see which skills match

Without a harness:

agent-foundry-runtime plan  "kill generic AI slop"
agent-foundry-runtime run   "refactor the API design"
agent-foundry-runtime doctor

3. Or browse first

→ youcisla-agents.vercel.app has the full catalog, an interactive knowledge graph, and one-click install.

4. Or connect over MCP

agent-foundry-runtime mcp   # stdio MCP server: plan, execute, list_skills, search_skills, get_skill, verify_skills, check_action, runtime_status, execution_history, list_models

Or run the published package directly:

uvx agent-foundry-runtime mcp

Registered name: io.github.youcisla/agent-foundry.

5. Measure a skill instead of trusting it

agent-foundry-runtime eval --tasks tasks.json

Each task runs twice, with and without the skill, and reports the pass-rate lift. Task format: {"id", "prompt", "skill", "verify"} where verify is a shell command that receives the output on stdin. The layout matches SkillsBench v1.1 (benchflow/skillsbench), so published benchmarks can be reused.

---

Architecture

Your prompt  (/af build a react component)
   └─▶ Agent Foundry daemon
         └─▶ planner · rank_skills
               └─▶ executor · LiteLLM  ⇄  LLM provider (Claude, OpenAI, …)
                     └─▶ SQLite · executions.db
                           └─▶ Response to user

Published through three channels: npm (@youcisla/agent-foundry), PyPI (agent-foundry-runtime), and the official MCP registry (io.github.youcisla/agent-foundry).

Interactive versions of every diagram live on the site: /architecture, /graph (knowledge graph + orchestration), and /audit.

What's in the box

skills/         41 disciplines (31 core + 10 optional)    ─┐ feed
agents/         af-planner · af-critic · af-orchestrator  │ the
                                                          ▼ indexer
agent_foundry/  config.py ─▶ daemon.py (FastAPI) ─▶ mcp_server.py (stdio MCP)
                indexer.py ─▶ planner.py ─▶ loop.py  ⇄  executor.py
                loop.py ─▶ judge.py (af-critic) ─▶ logging_db/
scripts/        install.js ─▶ 14 harness skill roots + CLI index

The daemon is lazy-started by the CLI, so there is no systemd/launchd requirement. Everything runs locally. Your data stays in ~/.config/agent-foundry/executions.db.

The loop, end to end

 1.  user      → run_loop   : /af "kill generic AI slop"
 2.  run_loop  → planner    : rank_skills(prompt, index)
 3.  planner   → run_loop   : top match (e.g. anti-slop, 0.24)
 4.  run_loop  → run_loop   : budget guard
 5.  run_loop  → executor   : build_messages(prompt, body)
 6.  executor  → LiteLLM    : POST /v1/messages
 7.  LiteLLM   → executor   : response text
 8.  executor  → run_loop   : response + cost
 9.  (judge=true) run_loop → af-critic : score → {corr, slop, scope, verdict}
10.  run_loop  → SQLite     : log_execution(...)
11.  run_loop  → user       : LoopResponse {output, plan, judge_score?}

---

Catalog

41 skills, 3 agents. Original work; MIT except two optional skills (chrome-devtools-mcp-bridge, persistent-memory) licensed Apache-2.0 in their own frontmatter. Each skill:

• 📏 ≤150 lines / ≤8 KB (Codex cap, no exceptions)
• 🎯 Exactly one trigger phrase (Use when... so the model knows when to fire)
• 🚫 Anti-patterns + Verification checklist (teach what not to do, then confirm it was done)
• ⚡ Action verbs, not tool names (examine not Read, create not Write)

Core skills (31)

Skill	Trigger
anti-slop	Kill generic AI patterns before they ship
api-design	Use when creating a new API endpoint or reviewing API consistency
automation-pick	Decide whether to automate a task before automating
bottleneck-gating	Phase a project by measured bottleneck, not intuition
budget-guard	Set and enforce a hard spend ceiling for paid loops
constraint-then-solve	Restate the problem, catalog constraints, then solve
context-optimization	Use on any task with >2K-token outputs, big files, or repeated reads
cron-troubleshoot	Debug a missing or wrong cron job
e2e-test-strategy	Use when designing test coverage for a web app or API
engram-routing	Route prompts via O(1) N-gram lookup when trigger patterns should match fast
execution-observability	Log model, cost, latency, and outcome for every run
fallback-model-routing	Route around provider failures and report which model answered
feedback-loop	After shipping, instrument → measure → iterate
knowledge-extract	Turn a session into a skill draft
landscape-first	Research the space before building
measure-first	Use when about to optimize, refactor, or claim a system is slow
plan-before-code	Use before writing any non-trivial code change
plan-then-act	Use when a task has multiple steps and the order matters
prompt-discipline	Use on every non-trivial task: think, simplify, edit surgical, stay goal-driven
pushback-when-wrong	Use when reviewing an assertion that smells off
quality-protocol	Use before declaring a task complete
re-verify-findings	Use after any prior verification claimed a finding
read-before-build	Read source files before writing code
session-closeout	Apply at the end of any multi-step project
session-distill	Extract patterns from every session
show-your-work	Output a thinking trace after complex tasks
structured-output-contract	Enforce a JSON Schema for machine-read output
verify-first	Apply before committing to any claim
workflow-decompose	Use when designing or debugging an automation
cache-identity	Version and bound caches; publish atomically
judge-integrity	Separate judge failure from a low score

Optional skills (10)

Skill	Trigger
persistent-memory	Use when persisting context across sessions or threading memory across agents
token-compression	Compress tool outputs before they consume context
chrome-devtools-mcp-bridge	Drive Chrome DevTools from an agent
design-language	Apply Apple-grade UI polish
funnel-pr-guard	Guard conversion-critical paths from breaking
sql-migration-trio	Three-file migration pattern (up/down/schema)
agent-memory-vault	Shared structured memory that survives agent sessions
agent-team-standards	Per-project locked agent skill set with version pins
autonomous-briefing	Run a fully autonomous morning briefing
book-to-skill	Convert book chapters or long articles into a runnable skill

Agents (3)

Agent	Model	Job
af-critic	opus	Score output on correctness, slop, scope. Returns JSON.
af-planner	opus	Decompose a request into a skill/agent plan. Returns JSON.
af-orchestrator	opus	Dispatch subtasks to specialized agents and skills, then merge results.

---

Commands

Command	What it does
agent-foundry-runtime init [--force]	Write config and the first skill index
agent-foundry-runtime index	Rebuild the skill index from disk
agent-foundry-runtime plan "<prompt>"	Rank skills for a prompt
agent-foundry-runtime run "<prompt>"	Plan + execute the top-ranked skill
agent-foundry-runtime resume <session_id> "<prompt>"	Continue a loop session with a follow-up
agent-foundry-runtime session <session_id>	Inspect a stored loop session
agent-foundry-runtime execute <skill_id> "<prompt>"	Run a specific skill
agent-foundry-runtime doctor	Health-check: config, index, daemon, API key
agent-foundry-runtime status	Routing accuracy, fallback rate, average cost
agent-foundry-runtime consult "<need>"	Recommend skills for a need
agent-foundry-runtime cost-report	Token and time estimates per skill
agent-foundry-runtime feedback <id> <score>	Attach a human score to an execution
agent-foundry-runtime rejudge <id> [--model]	Re-score stored output without re-running the completion
agent-foundry-runtime calibrate [--bins N]	Compare judge scores with human feedback
agent-foundry-runtime prune --older-than-days N [--dry-run]	Delete old executions, observations, policy decisions, and perf stats
agent-foundry-runtime learn [--scope project|global]	Learn trigger weights from judged executions
agent-foundry-runtime instincts [--explain <id>] [--proposals]	List instincts, explain evidence, or write review-only proposals
agent-foundry-runtime instinct-approve <id>	Approve an instinct and persist it
agent-foundry-runtime attest	Sign a manifest of skill file hashes and frontmatter digests
agent-foundry-runtime verify [--strict]	Verify the installed manifest and signature
agent-foundry-runtime gate --kind <kind> --value <value>	Classify an action as allow, confirm, or deny
agent-foundry-runtime browse	Browse/search the catalog, or --read <id>
agent-foundry-runtime mcp	Start the MCP stdio server (plan/execute/list_skills/search_skills/get_skill/verify_skills/check_action/runtime_status/execution_history/list_models)
agent-foundry-runtime eval --tasks <file>	Paired skill eval: with vs without, reports lift
agent-foundry-runtime serve	Start the daemon (lazy-started on first command)

Every command also has an HTTP endpoint on the daemon for programmatic use: /health, /site-data, /events, /index, /plan, /engram, /execute, /loop, /loop/resume, /loop/{id}, /stats, /feedback, /learn, /instincts, and /instincts/{id}/approve.

---

Capability boundary

What the runtime does not provide, stated so you do not discover it in production:

• No hosted execution sandbox. Skills run as prompts; tool execution belongs to the host harness.
• No multi-tenant auth or per-user quota enforcement. The daemon binds localhost and trusts the local user.
• No durable queue across daemon restarts. In-flight requests are lost if the process dies.
• No cross-provider load balancing. Routing is per-call chain order with optional historical attempt allocation.
• No semantic determinism guarantee from providers. The determinism contract covers the trace digest, not model sampling.

Install lanes

Skills and runtime are separate, explicit steps:

# Skills only: Node 22.14+, no Python
npx --yes --package @youcisla/agent-foundry agent-foundry-install --harness=codex

# Runtime only: Python 3.10-3.14, no Node
pip install agent-foundry-runtime && agent-foundry-runtime init
# init warns until content is installed with agent-foundry-install

Run the runtime from source (any OS):

git clone https://github.com/youcisla/Agent-Foundry.git ~/.agent-foundry
cd ~/.agent-foundry && pip install -e .

See INSTALL.md for the full matrix of harnesses, install lanes, and platforms.

---

Requirements

• Node 22.14+ for the skill installer (skills-only installs need no Python)
• Python 3.10-3.14 for the CLI, daemon, and MCP runtime (no Node required)
• macOS, Linux, or Windows
• A supported harness: Claude Code, Codex, Cursor, Gemini/Antigravity, OpenCode, Hermes, Zed, or any of the 14 adapters
• An API key (Anthropic, OpenAI, or any provider LiteLLM supports)

---

Quality gates

One entry point, explicit named gates, no bash required for the default scopes:

python scripts/check.py --fast      # inner loop
python scripts/check.py --all       # pre-merge and CI
python scripts/check.py --release   # built artifacts and SBOM

scripts/check.py runs each gate with a timeout, prints a machine-readable summary with --json, and never counts a skipped gate as a pass for release. See docs/testing.md for the gate scopes and the offline routing evaluation.

Metrics

Counts and measured values below are generated from live sources; do not edit them by hand.

Metric	Value	Source
Version	0.6.0	package.json
Skills	41 (31 core + 10 optional)	skills/ (filesystem)
Agents	3	agents/ (filesystem)
Adapters	14	scripts/install.js
Commands	25	agent_foundry/cli.py (Click tree)
Http Endpoints	15	agent_foundry/daemon.py (routes)
Routing Top1	85.8%	evals/routing/baseline.json
Routing Top3	99.1%	evals/routing/baseline.json
Gates	20 named gates	scripts/check.py

31 core + 10 optional = 41 skills

Provenance (generated_at, revision) lives in web/metrics.js.

---

Skill evidence

Each skill has a generated sidecar record in data/skills/<id>.json. A tier is published evidence, never an assertion:

Tier	Name	Requirement
L0	Metadata	valid frontmatter
L1	Static contract	the content lint passes
L2	Routing evidence	at least two labelled routing cases with a top-1 hit and documented neighbors
L3	Behavioural evidence	paired offline eval with at least three deterministic-verifier tasks and a stored artifact
L4	Field evidence	opt-in human feedback with a reviewer sign-off

python scripts/gen-skill-evidence.py regenerates every record from the live corpus and lint. --check fails when a body edit makes a record stale (the body hash changes, so the tier must be re-reviewed before it can be claimed again). Routing evidence is selection evidence only; records never present it as task efficacy, and L3 records appear only when paired-eval artifacts exist under data/evals/.

Releasing

Maintainers publish through .github/workflows/release.yml. See docs/releasing.md for the dry run, trusted-publisher prerequisites, tag rules, and recovery steps. The local scripts/publish.sh is an emergency fallback only.

---

Web app

Browse the catalog, the knowledge graph, and the audit at youcisla-agents.vercel.app:

Page	What
Catalog	All 41 skills + 3 agents with live search
Graph	Interactive knowledge graph canvas; no fixed counts are claimed here
Audit	God nodes, surprising connections, interactive React Flow diagrams

The site regenerates from live repo state on every commit via scripts/gen-site-data.py → Vercel build → deploy.

---

Roadmap

Status	Item
✅ v0.1	Python package + FastAPI daemon + Claude Code plugin
✅ v0.2	Foundational audit, frozen Config, multi-page web app, knowledge graph, interactive React Flow diagrams
✅ v0.3	npm package, Engram O(1) routing, af-orchestrator agent, harness adapters
✅ v0.4	PyPI + MCP registry, loop sessions, deterministic site data, per-skill adapter installs
📋 next	af verify signed-manifest integrity

See docs/launch-plan.md for the full design spec.

---

License

MIT, except the two optional skills that declare Apache-2.0 in their own frontmatter. All skills, agents, and authored artifacts are original work by the Agent Foundry Contributors. See AUTHORSHIP.md for the attribution policy, LICENSES.md for the per-artifact license ledger, and SECURITY.md for the private vulnerability reporting and supply-chain policy.

---

Built by Youcisla · Contribute · Report an issue