Agent Foundry

Skill and agent runtime for AI coding assistants.

Plan → execute → verify. Skills, agents, a local daemon. MIT, local, no cloud. 31 original skills, 0 external references.

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

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.

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/         31 disciplines (25 core + 6 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

31 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 (6)

| 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) |

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 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 serve | Start the daemon (lazy-started on first command) |

Every command also has an HTTP endpoint on the daemon (/plan, /execute, /loop, /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 | 31 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 31 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.

Built by Youcisla · Contribute · Report an issue