cursor-agent-team is a single-conversation, multi-role framework that turns Cursor into a stable AI agent team for real-world development work. It gives you an opinionated way to run multiple specialized roles (architect, engineer, reviewer, etc.) inside one Cursor chat, with minimal handoff and strong context continuity.

This project is both a methodology and a framework for human–AI collaboration in Cursor: it defines how your AI team should think and work together, then ships a concrete setup (prompts + files + workflows) that you can drop into your own repo.

Standard (environment checks + clone path)

Install the cursor-agent-team framework on this machine, in order:

1) Ensure Python >= 3.8 and that you can run `python` in the terminal (on Windows, `py -3` may apply).

2) Work inside this repo’s root directory. If you have not cloned yet, run `git clone https://github.com/thiswind/cursor-agent-team.git`, then `cd cursor-agent-team`.

3) Before installing, confirm the current directory is the repo root (verify `install.py` is present).

4) From that directory run `python install.py`, or on Windows if `python` is missing: `py -3 install.py`.

Then report: absolute path to the repo root and whether the installation completed successfully.

Accelerated (Python already OK)

Install the cursor-agent-team framework: if not cloned, `git clone https://github.com/thiswind/cursor-agent-team.git`, then `cd` to the repo root (verify `install.py` exists), run `python install.py` or on Windows `py -3 install.py`.

git clone https://github.com/thiswind/cursor-agent-team.git
cd cursor-agent-team
python install.py

On Windows if only py is available, use py -3 install.py for the third line. Full flags: python install.py --help.

TRAE SOLO Installation

For TRAE SOLO (ByteDance):

git clone https://github.com/thiswind/cursor-agent-team.git
cd cursor-agent-team
python install.py --trae-solo

This will set up the TRAE SOLO adaptation with custom Agents (instead of Commands), Skills (instead of mdc Rules), and a separate project rules file. The core methodology, scripts, and ai_workspace are shared across both platforms.

Where things land

cursor-agent-team takes a pragmatic approach to "multi-agent" work in Cursor: instead of spawning many separate agents and passing state around, you keep a single LLM in one conversation and let multiple roles collaborate on the same shared context window. It behaves like a small-team workflow and Cursor configuration template, not yet another generic multi-agent framework.

It is meant for developers, researchers, and advanced users who want a reliable "AI team" workflow inside Cursor, rather than a simple Q&A assistant.

• A workflow and methodology centered around a multi-role collaboration pattern, plus a concrete Cursor implementation
• A single-conversation, multi-role template for AI collaboration
• A practical repo you can fork and tweak to run real projects (papers, reports, code, experiments)

• Not a hosted SaaS or productized platform
• Not a "cover every use case" multi-agent framework
• Not an autonomous pipeline where the AI runs on its own — a human is always in the loop
• Not a plug-and-play solution for users seeking immediate productivity gains without conceptual investment

We augment human capability; we don't replace it. Three design pillars:

1. Multi-role, not multi-agent — One LLM, one conversation. /discuss and /crew share the same context. No agent handoff, no context loss. Like a meeting room where everyone has perfect memory.

2. Human-in-the-loop by design — You are the conductor. We explore, you decide. We execute, you confirm. "Your command, our execution" — not "set and forget."

3. Empowerment, not replacement — Democratizing team access: individuals get team-level capability. Cognitive load redistribution: you think strategy, we handle execution details. Frees you from the "details quagmire" for purer thinking.

Target users: Individuals and small teams with methodological awareness—those who think about how they work with AI, not just what they want AI to do.

We believe: AI should augment human judgment, not replace it. Context continuity matters more than agent count. Plans grounded in fresh research beat plans from training data alone. And the human must remain in the loop—as conductor, not spectator.

A multi-role collaboration framework for Cursor IDE. One LLM wears different "masks" (commands) in the same conversation. Provides:

• Structured workflow: discuss → plan → execute
• Specialized roles: Each command has distinct responsibilities
• Hard constraint validation: Python scripts ensure deterministic output
• Extensible team: Create new roles via /prompt_engineer

We occupy a specific niche: single-conversation, multi-role, context-preserving collaboration.

Evaluation context: Among single-conversation, multi-role, context-heavy approaches, cursor-agent-team is a first-tier architectural reference implementation—designed for methodological exploration, not product deployment.

cursor-agent-team can be viewed as a lightweight harness implementation for Cursor/TRAE SOLO scenarios, with a strong focus on methodology and the combination of soft and hard constraints.

cursor-agent-team extends beyond traditional harness engineering in several key areas:

1. Multi-role single-conversation as first-class citizen

   • Traditional harnesses often default to "multi-agent + state transfer"; we use "one model + multiple masks" with prompt-swap instead of state handoff
   • This minimizes context cost: traditional MAS state-transfer requires 50–200KB compressed state with 10–20% context retention, while our prompt-swap uses only 1–3KB rule text with full history preserved

2. Aspect-Oriented Design for collaboration

   • Uses "Aspect-Oriented Design" to describe how cross-cutting concerns (Gleaning, Persona, TTS) are woven into the workflow at defined join points
   • This creates a more systematic approach to collaboration than traditional skill architectures, which lack workflow models or join points

3. Depth of human-AI collaboration methodology

   • Emphasizes Intelligence Augmentation, Human-AI teaming, and Cognitive load redistribution, drawing on research from the National Academies and cognitive load theory
   • Targets users with methodological awareness—those who think about how they work with AI, not just what they want AI to do

In summary, cursor-agent-team is a "workflow-level / IDE-level harness" rather than a "platform-level / enterprise-level harness framework"—a conscious design choice to prioritize methodological depth over general platform features.

cursor-agent-team is designed for developers, researchers, and advanced Cursor users who:

• Want a stable "AI team" inside a single Cursor conversation
• Care about methodology and workflow, not just ad-hoc prompts
• Are willing to spend a bit of time setting things up once, in exchange for a reusable workflow

To use cursor-agent-team in Cursor:

Tell Cursor Agent:

Install cursor-agent-team from https://github.com/thiswind/cursor-agent-team.git as a submodule and run the install script (python cursor-agent-team/install.py).

Then type /discuss to start and briefly describe what you want to achieve (e.g., "help me design and write a technical report on X").

For manual installation, see Installation.

Research-first planning — Plans should not come from LLM training data alone. Training data has a knowledge cutoff; plans synthesized from it can be outdated or wrong. We design /discuss to search for latest academic and industry research before synthesizing plans (retrieval-augmented planning). Fresh context, then synthesis—a methodological stance, not just a feature.

/discuss → [Explore & Plan] → /crew → [Execute] → Done
                ↓
         /prompt_engineer → [Create New Role] → Use New Command

1. Plan: Use /discuss to explore ideas and generate execution plans
2. Execute: Use /crew to execute the plans
3. Expand: Use /prompt_engineer to create new roles when needed

Cursor IDE — Tell Cursor Agent to install, or run manually:

git submodule add -f https://github.com/thiswind/cursor-agent-team.git cursor-agent-team
python cursor-agent-team/install.py

Update: git submodule update --remote cursor-agent-team && python cursor-agent-team/install.py

Note: The workspace at cursor-agent-team/ai_workspace/ is shared between all supported platforms (Cursor and TRAE SOLO).

• Single conversation, multi-role: all roles share one context; no complex state routing or orchestration layer
• Human-in-the-loop by design: the workflow assumes you are present; major decisions require your confirmation
• Hard constraints in code, soft skills in the LLM: topic tree validation, preflight checks, and other rules live in scripts; the LLM focuses on reasoning and generation
• Cursor-first experience: commands and flows are designed around Cursor; no extra backend services required
• Proven in a real research project: the cursor-agent-team paper was written using this framework inside Cursor

Dedicated persistent workspace for agents. Agents can write scripts, take notes, save intermediate results from searches and research. Enables staged refinement for higher output quality than direct generation. See ai_workspace/README.md.

Script-driven persona integration with Persona Sandboxing: the persona expresses at the Output Layer; the Work Layer (code, analysis, reasoning) runs in a clean context. Based on persona-spec.

• Inspiration Capital: Scatter card collection for sparking creativity
• Text-to-Speech (macOS): Voice feedback via say
• Social Media: Integration with Moltbook
• Spec-Kit Translator: Converts plans to spec-kit format

Hybrid architecture: LLM soft constraints (prompt rules) + script hard constraints (Python). Critical operations use deterministic scripts to validate outputs before committing.

┌─────────────────────────────────────────────────┐
│                    LLM Layer                     │
│   (Soft Constraints: Prompt rules)              │
└────────────────────┬────────────────────────────┘
                     │ Calls
                     ▼
┌─────────────────────────────────────────────────┐
│                  Script Layer                    │
│   (Hard Constraints: Python scripts)             │
│   - validate_topic_tree.py  - preflight_check.py │
│   - cleanup_ai_workspace.py                     │
└─────────────────────────────────────────────────┘

Architecture highlights: Multi-role + single conversation; Plan-and-Execute; Dedicated agent workspace (context engineering, cognitive artifacts); Hybrid constraints (soft + hard); Phase markers (workflow verification); Command-as-role.

We started from a different point than the Skills wave. Our design addresses problems that traditional rules-based and skill-based architectures cannot solve.

We define collaboration workflow; we don't just add capabilities. Command + Rules + Scripts work together: Command defines phases (join points), Rules define aspects, Scripts provide deterministic validation.

Cross-cutting concerns (Gleaning, Wandering, Persona Output, TTS) are woven into the workflow at defined join points—not embedded in core logic. Commands define Phase/Step as join points; Rules define aspects that invoke scripts at those points. Traditional Skill architectures have no workflow model or join points; they cannot achieve this weaving.

Specification (Command + mdc) drives when and why to call; scripts execute how with deterministic validation. This aligns with "Blueprint First, Model Second" (workflow logic in spec, LLM for bounded tasks) and Formal-LLM (hard constraints via script validation). The spec-script loop—LLM reads spec, runs script, script validates—runs in a single conversation.

Cursor provides Commands (workflow definition), Rules (aspect definition), and Agent (script execution) in one session. This tight integration enables spec-driven execution and AOP-style weaving.

This binding is intentional. We start with Cursor because:

• Its Rules, integrated terminal, and workspace model align naturally with our command–rules–scripts–workspace architecture
• It aggregates state-of-the-art models behind a single subscription
• Its IDE experience (interface, file tree, workspace semantics) matches our needs

We prioritize depth on Cursor rather than breadth of platform support. A watered-down, platform-agnostic version would lose the tight spec-script loop that makes our methodology work.

Future ports will be considered only where we can preserve the same methodological guarantees (minimal handoff, HITL, workspace semantics). This is a conscious design choice, not a limitation or oversight.

A TRAE SOLO (ByteDance) adaptation is available. See TRAE_SOLO_README.md for installation and usage instructions.

TRAE SOLO uses custom Agents (instead of Commands), Skills (instead of mdc Rules), and a separate project rules file. The core methodology, scripts, and ai_workspace are shared across both platforms.

See cursor-agent-team/_scripts/README.md for script details.

We don't transfer state; we swap masks. The "Writer" knows what the "Planner" discussed because they share the same memory stream.

This repository is the reference implementation of:

Hu, K. (2026). cursor-agent-team: A Multi-Role, Single-Conversation Framework for Human-AI Collaboration. Zenodo. https://doi.org/10.5281/zenodo.18605311

The paper itself was written using this framework inside Cursor as a dogfooding case study.

Grounded in peer-reviewed research:

• Intelligence Augmentation: Licklider (1960) — human-computer symbiosis
• Lost in the Middle: Liu et al. (2023) — context degradation in long sequences
• Aspect-Oriented Programming: Kiczales et al. (1997) — cross-cutting concerns separation
• Retrieval-Augmented Planning: RaDA, RPG — fresh information before synthesis

See DIRECTION.md for potential future directions.

We focus on methodology depth over feature breadth. No timeline commitments — the project evolves based on real needs.

Current version: v0.14.0. See CHANGELOG.md.

If you use cursor-agent-team in your research, please cite:

Hu, K. (2026). cursor-agent-team: A Multi-Role, Single-Conversation Framework for Human-AI Collaboration. Zenodo. https://doi.org/10.5281/zenodo.18605311

Or in BibTeX:

@article{hu2026cursor,
  author    = {Hu, Kuang},
  title     = {cursor-agent-team: A Multi-Role, Single-Conversation Framework for Human-AI Collaboration},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18605311},
  url       = {https://doi.org/10.5281/zenodo.18605311}
}

GNU General Public License v3.0 (GPL-3.0). See LICENSE.

thiswind — @thiswind