Shared multi-agent pipeline setup for Cursor. Provides standard agents, rules, and pipeline tooling that teams copy into their projects. Claude Code support is documented alongside Cursor conventions.
- Cursor with models enabled for the agents in the pipeline. Some models (e.g.
gpt-5.1-codex-max) are hidden by default and must be toggled on inCursor Settings > Models. See Models | Cursor Docs for the full list and visibility defaults. - Python 3.10+, Node.js 20+, and git for tutorials and the sandbox project. See TESTING.md for details.
Can you explain what agents, rules, and pipelines are? If not, start with Foundation.
Can you set up a pipeline and build a feature end-to-end? If not, go to Practitioner.
Ready to design multi-agent systems and lead others? See Expert.
The .cursor-foundation/, .cursor-practitioner/, and .cursor-expert/ directories are the canonical source bundles in this repo. Use them for training and for copying into your project.
Each .cursor-<tier>/ directory follows this structure (not all tiers include every subdirectory):
| Path | Purpose |
|---|---|
agents/*.md |
One file per agent defining its model, role, inputs, outputs, and behavioral instructions. Cursor discovers these as subagent_type targets. |
rules/*.mdc |
Always-on or file-triggered behavioral guardrails injected into agent context automatically. YAML frontmatter sets description, alwaysApply, and optional globs. |
skills/*/SKILL.md |
On-demand capabilities agents pull in when relevant (unlike rules, not auto-injected). Each skill is a subdirectory with a SKILL.md. Foundation has none. |
pipeline/ |
Runtime tooling: schema.py (validates artifact JSON), check.py (stage-gate invariants), README.md (artifact format docs). |
templates/ |
Scaffolds for new agents, rules, and artifacts. Copy and fill in. Foundation has none. |
walkthrough/ |
Pre-built example artifacts showing a complete pipeline run. Read-only reference material that ships with the repo. Foundation has none. |
tutorials/ |
Learner output directory (outputs/), solution keys (solutions/), and verify.py grader. Exercise instructions live in docs/. |
AGENTS.md |
Agent registry: index table of all agents in the tier, pipeline execution order, and subagent type mappings. |
README.md |
Tier landing page: competency question, learning objectives, glossary (Foundation), pipeline flow, and tutorial links. |
| Foundation | Practitioner | Expert | |
|---|---|---|---|
| Core Question | Can you understand and use AI effectively? | Can you build and deploy AI features? | Can you architect AI systems and lead others? |
| Analogy | Understanding the rules and controls | Being able to drive anywhere safely | Teaching others to drive and designing better roads |
| Expectation | Understand the concept and patterns | Experiment with multi-agent frameworks | Design and deploy multi-agent systems with monitoring |
| Portfolio | 3 documented AI use cases | 1 deployed AI use case | 1 client architecture, 1 presentation, 1 mentorship |
| Assessment | Conversation with Practitioner or Expert | Technical demo + walk-through with Expert | Peer review + mentorship vouching |
| Contains | 3 agents 1 rule 6 exercises | 8 agents 4 rules 2 skills full pipeline 11 exercises | ~15 tiered agents routing rule cost tracking 8 exercises |
This repo builds on official Cursor and Claude Code documentation:
Cursor Learn -- concept guides for working with agents:
- Agents | Customizing Agents | Working with Agents
- Developing Features | Finding and Fixing Bugs | Reviewing and Testing Code | Putting It Together
Cursor Docs -- technical reference:
- Custom Agents -- agent
.mdfiles, AGENTS.md,subagent_type - Rules --
.mdcrule files, frontmatter, activation - Agent Skills --
SKILL.mdformat, discovery, on-demand activation
See the Claude Code section below for equivalent concepts in that system.
Copy .cursor-<tier>/ into your project as .cursor/. Most teams should start with Practitioner.
cp -r .cursor-practitioner/* your-project/.cursor/Each tier includes a tutorials/ directory with exercises. Foundation exercises are quiz-based and conceptual. Practitioner exercises are hands-on and require delegating to subagents. Expert exercises involve tiered routing, cost analysis, and architecture design. See TESTING.md for the full test plan.
- Copy
.cursor-practitioner/(or expert) over your.cursor/ - Keep
jg-files as read-only upstream references - Put customizations in
team-ormy-prefixed files so they survive upgrades - Diff before overwriting if you've modified any
jg-files
| Prefix | Meaning |
|---|---|
jg-* |
Shared bundle — do not modify in your project |
<team>-* |
Team or project conventions |
| Unmarked | Individual developer additions |
Pipeline concepts (artifacts, agent roles, stage gates) are IDE-agnostic. The wiring differs:
| Cursor | Claude Code |
|---|---|
.cursor/rules/*.mdc |
CLAUDE.md at repo root |
.cursor/agents/*.md |
Referenced docs in CLAUDE.md |
.cursor/skills/*/SKILL.md |
.claude/commands/*.md |
subagent_type dispatch |
Sequential prompting through stages |
Walkthrough content and pipeline artifacts work in both environments.
- Agents that can write code: worker, debugger
- Agents that can run commands: tester, git
- Agents that cannot: merge PRs, force push, skip hooks, push to main
readonly: trueon planner, reviewer, subplanner- Always review agent-generated PRs before merging
.pipeline/ is runtime state — do not commit. Walkthrough artifacts in tier directories live under walkthrough/, not .pipeline/, so they ship with the repo.
Each pipeline run invokes multiple AI models. See Expert tier for detailed cost analysis and tiered model strategies.
If your project previously used .cursor-jg/ references, replace all paths with .cursor/. The old path convention is retired.
VERSION file at repo root (semver). Bumped on any change to agents, rules, skills, or pipeline.
Tier directories are canonical in this repo. Update the affected tier directories directly and keep shared files synchronized across tiers when applicable.
Sync checklist:
- Agents shared across tiers: planner, worker, git (Foundation, Practitioner, Expert)
- Agents in Practitioner + Expert: subplanner, tester, reviewer, debugger, benchmarker
- Rules shared: planner-first (all), commit-conventions, issue-workflow, pr-review (Practitioner, Expert)
- Skills shared: pipeline-artifact-io, benchmark-ops (Practitioner, Expert)
- Pipeline: README.md, schema.py, check.py (Practitioner, Expert — Expert extends)