io.github.youcisla/agent-foundry

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, no third-party skill content.

**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:

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)

Optional skills (10)

Agents (3)

---

Commands

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:

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:

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

---

Roadmap

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.

---

Built by Youcisla · Contribute · Report an issue