---

Skills, agents, rules, and prompt patterns that make AI-assisted development actually work at scale.

Without structure, Claude on a large codebase produces code that works once, degrades fast, and has no tests. agentforge fixes this with 9 behavioral skills, a 7-agent team, and 5 quality rules — installable in one command.

claude plugin install github:VincentMao/agentforge

→ 5-minute walkthrough · Refactor demo · ML pipeline

---

What's Inside

	Count	What
🧠 Skills	9	Behavioral contracts: 10x-engineer, refactoring, unit-testing, debugging, and more
🤖 Agents	7	Team roles: orchestrator, architect, planner, code-reviewer, evaluator, doc-drafter
📐 Rules	5	Python quality: ruff, mypy strict, pytest 80%+ coverage, git workflow
🔀 Prompt templates	7	Orchestrator-worker, ReAct, evaluator-optimizer, reflection, and more
💡 Examples	2	Legacy refactor (before/after Python) · ML pipeline (PyTorch + Hydra)
📖 Reference docs	4 chapters	Prompt engineering · LLM engineering · Multi-agent design · Research engineering

---

The Skill Interface

Type / in Claude Code after installing the plugin — your specialist team appears instantly.

All 9 skills: 10x-engineer · planner · code-reviewer · refactoring · unit-testing · 10x-data-scientist · architecture-review · debugging · documentation

Each skill loads a behavioral contract — it changes how Claude thinks, not just what it outputs.

---

The Agent Team

Seven specialized agents that coordinate on complex tasks. Here's a real task flowing through the full team:

Agent	Role	Hands off to
orchestrator	Routes the task, never writes code	planner
planner	Breaks work into phases with TodoWrite	implementation
code-reviewer	Runs pytest + mypy + ruff, reports by severity	evaluator or back to planner
evaluator	Checks output against original requirements	doc-drafter
doc-drafter	Writes docstrings, README updates, changelog	done

---

How Rules Govern Your Codebase

The .claude/rules/ files are read by Claude at the start of every session. You write them once — Claude enforces them on every commit, every PR, every code review.

# What happens automatically on every git commit:
ruff check src/ tests/ --fix   # formatting + linting
mypy src/ --strict             # type checking
pytest tests/ --cov=src --cov-fail-under=80   # tests + coverage gate

---

The Quality Gate

Every commit passes through four automated gates, enforced by pre-commit hooks:

flowchart TD
    G(["git commit"]) --> R

    R["🔧 ruff\nlinting + formatting"]
    R -->|"✅"| M["🏷️ mypy\nstrict type checking"]
    R -->|"❌"| Fix1(["fix & retry"])

    M -->|"✅"| T["🧪 pytest\nunit + integration tests"]
    M -->|"❌"| Fix2(["add types"])

    T -->|"✅"| C["📊 coverage\nminimum 80%"]
    T -->|"❌"| Fix3(["fix tests"])

    C -->|"✅"| Done(["✨ commit accepted"])
    C -->|"❌"| Fix4(["add tests"])

    style G    fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style R    fill:#f59e0b,stroke:#d97706,color:#fff
    style M    fill:#8b5cf6,stroke:#6d28d9,color:#fff
    style T    fill:#ef4444,stroke:#991b1b,color:#fff
    style C    fill:#06b6d4,stroke:#0891b2,color:#fff
    style Done fill:#22c55e,stroke:#15803d,color:#fff

Loading

---

The Refactor Demo

Open the messy before/ code in Claude Code, type /refactoring. The skill enforces tests-first, one seam at a time — no big-bang rewrites.

refactor-before-after_video.mp4

	before/	after/
Functions	1 god function, 300+ lines	4 pure functions, each < 40 lines
Global state	data = None, model = None	None — pure functions only
Type annotations	Zero	100%, mypy --strict clean
Tests	Zero	18 tests, 100% coverage
Imports	Circular, unstructured	Explicit, typed

cd examples/legacy-refactor/before
claude   # then type: /refactoring

---

The ML Pipeline

A production-ready PyTorch + Hydra training pipeline — the same pattern used in large-scale ML systems. Swap a model, change a dataset, or run a hyperparameter sweep from the CLI with no code edits.

cd examples/data-pipeline
pip install -e ".[dev]"
make train                                        # synthetic data auto-generated

python src/train.py experiment=baseline           # named experiment override
python src/train.py model.optimizer.lr=0.0001     # single hyperparameter
python src/train.py "model.optimizer.lr=0.001,0.0001" --multirun   # sweep

---

Prompt Templates

Seven orchestration patterns — each with a concrete worked example and an explanation of when (and when not) to use it. Full templates with anti-patterns are in prompt-templates/.

---

Orchestrator-Worker — Fan Out, Then Merge

Use when a task can be broken into N independent parallel subtasks that don't need each other's output.

→ prompt-templates/orchestrator-worker.md

---

Evaluator-Optimizer — Iterate Until Quality Threshold

Use when you need output to meet a measurable bar — generate → score → improve → repeat until ≥ threshold.

→ prompt-templates/evaluator-optimizer.md

---

Parallel Agents — Same Task, N Independent Contexts

Use when you have the same task type to run across multiple independent files or contexts simultaneously. 3× faster than sequential.

→ prompt-templates/parallel-agents.md

---

Reflection — Adversarial Self-Critique Before Delivering

Use for high-stakes outputs: architecture decisions, security analysis, code reviews. One reflection loop catches what a first pass misses.

→ prompt-templates/reflection.md

---

Plan and Execute — Approval Gate Before Touching Code

Use before any task touching more than 2 files, or where wrong assumptions mean wasted hours. Plan is reviewed and approved before a single line changes.

→ prompt-templates/plan-and-execute.md

---

ReAct — Reasoning + Acting for Exploratory Tasks

Use when the next action depends on what the previous one returned. The structured Thought → Action → Observation loop prevents guessing.

→ prompt-templates/react-pattern.md

---

Chain of Thought — Show Reasoning Before the Answer

Use for algorithm design, multi-constraint optimization, or any problem where intermediate steps change the answer. Forces explicit reasoning before conclusions.

→ prompt-templates/chain-of-thought.md

---

Quick Start

# Install as Claude Code plugin — all 9 skills activated immediately
claude plugin install github:VincentMao/agentforge

# Or drop .claude/ directly into any existing Python project
cp -r /path/to/agentforge/.claude /your/project/

→ Full walkthrough: QUICKSTART.md

---

Contributing

Contributions welcome — skills, agents, prompt templates, reference chapter sections, and bug fixes.

• 📖 Read CONTRIBUTING.md for how to add a skill or agent
• 💬 Open a GitHub Discussion for questions, ideas, or showing what you built
• 🐛 File an Issue for bugs

---

Contact

Built by Vincent Xianglun Mao — research scientist, large-scale ML systems.

For collaborations, research, or questions:
📧 maoxianglun@gmail.com
🔗 LinkedIn
💬 GitHub Discussions

---

License

MIT — see LICENSE.