---

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 18+):

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

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, get_skill

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

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

What's in the box

skills/         35 disciplines (25 core + 10 optional)    ─┐ feed
agents/         af-planner · af-critic · af-orchestrator  │ the
                                                          ▼ indexer
agent_foundry/  config.py ─▶ daemon.py (FastAPI)
                indexer.py ─▶ planner.py ─▶ loop.py  ⇄  executor.py
                loop.py ─▶ judge.py (af-critic) ─▶ logging_db.py

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

35 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 (25)

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
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
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
verify-first	Apply before committing to any claim
workflow-decompose	Use when designing or debugging an automation

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 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 index	Rebuild the skill index from disk
agent-foundry browse	Browse/search the catalog, or --read <id>
agent-foundry mcp	Start the MCP stdio server (plan/execute/list_skills/get_skill)
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 (/plan, /execute, /loop, /loop/resume, /loop/{id}, /index, /health) for programmatic use.

---

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+ (for the daemon) or Node 18+ (for the cross-platform installer)
• macOS, Linux, or Windows
• A supported harness: Claude Code, Codex, Gemini, Hermes, OpenCode, or any of the 13 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 three gates. All green right now.

# 34 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

Current:

Gate	Result
foundry-eval.py	34 passed, 0 failed ✅
validate.sh	35 skills, 0 failed ✅
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.

---

Web app

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

Page	What
Catalog	All 35 skills + 3 agents with live search
Graph	Interactive React Flow knowledge graph (555 nodes, 898 edges, 54 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, 13 harness adapters (3 tested)
📋 v0.4	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.

---