Agent Foundry

---

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

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 from npm (cross-platform, Node 22.14+):

npm install -g @youcisla/agent-foundry
agent-foundry            # auto-detect harness and install

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

Or from PyPI (Python 3.10-3.14, includes the MCP runtime):

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

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

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 plan  "kill generic AI slop"
agent-foundry run   "refactor the API design"
agent-foundry 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 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 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.py
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. All original work under MIT. 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 init [--force]	Write config and the first skill index
agent-foundry index	Rebuild the skill index from disk
agent-foundry plan "<prompt>"	Rank skills for a prompt
agent-foundry run "<prompt>"	Plan + execute the top-ranked skill
agent-foundry resume <session_id> "<prompt>"	Continue a loop session with a follow-up
agent-foundry session <session_id>	Inspect a stored loop session
agent-foundry execute <skill_id> "<prompt>"	Run a specific skill
agent-foundry doctor	Health-check: config, index, daemon, API key
agent-foundry status	Routing accuracy, fallback rate, average cost
agent-foundry consult "<need>"	Recommend skills for a need
agent-foundry cost-report	Token and time estimates per skill
agent-foundry feedback <id> <score>	Attach a human score to an execution
agent-foundry rejudge <id> [--model]	Re-score stored output without re-running the completion
agent-foundry calibrate [--bins N]	Compare judge scores with human feedback
agent-foundry prune --older-than-days N [--dry-run]	Delete old executions, observations, policy decisions, and perf stats
agent-foundry learn [--scope project|global]	Learn trigger weights from judged executions
agent-foundry instincts [--explain <id>] [--proposals]	List instincts, explain evidence, or write review-only proposals
agent-foundry instinct-approve <id>	Approve an instinct and persist it
agent-foundry attest	Sign a manifest of skill file hashes and frontmatter digests
agent-foundry verify [--strict]	Verify the installed manifest and signature
agent-foundry gate --kind <kind> --value <value>	Classify an action as allow, confirm, or deny
agent-foundry browse	Browse/search the catalog, or --read <id>
agent-foundry 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 eval --tasks <file>	Paired skill eval: with vs without, reports lift
agent-foundry 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 profiles

The shell installer takes a profile:

AF_PROFILE=minimal ./install.sh    # Skills only (no daemon)
AF_PROFILE=core    ./install.sh    # Skills + daemon (default)
AF_PROFILE=full    ./install.sh    # Skills + daemon + hooks

Run 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, profiles, and platforms.

---

Requirements

• Python 3.10-3.14 (for the daemon) or Node 22.14+ (for the cross-platform installer)
• 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)
• ~50 MB disk for the catalog and generated index

---

Quality gates

Every commit runs four gates. All green right now.

# 44 assets pass static quality checks (trigger phrase, body size, anti-patterns)
python scripts/foundry-eval.py

# All skills have correct frontmatter (name, description, version, author)
./scripts/validate.sh

# No external-reference names in tracked files (provenance gate)
bash scripts/nox.sh

# Catalog counts and MCP server version match the filesystem
python scripts/check-catalog.py

Current:

Gate	Result
foundry-eval.py	44 passed, 0 failed
validate.sh	41 skills, 0 failed
check-catalog.py	31 core + 10 optional = 41 skills
nox.sh	0 external references

The nox.sh gate is the strongest guarantee: it scans every tracked file for project-handle names so that the catalog stays original work.

---

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 React Flow knowledge graph (1,163 nodes, 2,761 edges, 94 communities)
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. 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.

---