Agency Agents: Open-Source AI Team Framework Guide

This guide explains what Agency Agents actually provides: reusable role-based agent configuration files, not a complete multi-agent operating platform. It covers installation, team-size choices, serial and parallel workflows, isolation, permissions, and an acceptance checklist for moving from a small experiment to a reliable process.

Agency Agents is suitable for quickly testing role-based AI work, but it is not a complete enterprise collaboration platform. Install a small set of role files into the coding tool you already use, then add your own orchestration, permissions, review gates, and reliable execution environment before running important or long-lived tasks.

This guide is for independent developers who need a few development, design, testing, or marketing agents; product and engineering teams evaluating an AI Agent team; and automation owners planning to run agent tasks continuously or in parallel.

Decision: Treat Agency Agents as a role configuration collection. Do not treat it as an autonomous company, scheduler, identity system, or sandbox.

What Does the Agency Agents Open-Source Framework Actually Provide?

The simplest description is a directory of Markdown files. Each file defines how an agent should behave in a particular role.

That definition can include:

• A professional identity.
• A preferred working style.
• A task-specific process.
• Deliverables the agent should produce.
• Quality standards.
• Typical failure patterns to avoid.
• Examples of how the role should respond.

This is more structured than a single prompt, but it is still configuration. The file does not create a new foundation model. It does not automatically provision a server. It does not create a task queue. It does not guarantee that several agents will coordinate correctly.

The official project currently presents role-based agents for tools including Claude Code, Cursor, Windsurf, Aider, Qwen Code, and GitHub Copilot. Its website and repository have shown changing counts as the project evolves, so we recommend checking the official directory before writing internal documentation or selecting a fixed set of roles. (agencyagents.dev)

The project is distributed under the MIT License, according to the repository README. That makes internal experimentation and commercial use easier, but it does not remove the need to review each role file, control credentials, or define your own approval process. Licensing the files is not the same as approving every action an agent might take in your environment. (github.com)

For the current installation instructions and role directory, use the official Agency Agents site and the official GitHub repository README.

Is Agency Agents a Multi-Agent Framework?

Not by itself.

Agency Agents supplies role definitions. A multi-agent system normally also needs a runtime that can create tasks, pass results between agents, retry failures, track state, enforce permissions, and decide when work is complete.

Those are separate layers.

Agency Agents provides:

• Role identity.
• Role-specific instructions.
• Expected working behavior.
• Suggested deliverables.
• A portable way to reuse the same specialist concept in supported tools.

Your surrounding workflow must provide:

• Task decomposition.
• Agent selection.
• Input and output contracts.
• Dependency handling.
• Retry logic.
• Branch or worktree isolation.
• Logs and traceability.
• Secret management.
• Human approval.
• Final merge or publishing rules.

This distinction answers a common search question: the project can be part of a multi-agent workflow, but it is not the complete multi-agent runtime.

The difference matters because two role files can still produce duplicated work. If a product researcher returns an unstructured essay and a product manager receives no acceptance criteria, the second agent has to repeat the research. The problem is not that the personalities are too similar. The problem is that the handoff has no contract.

A useful contract is short and explicit:

• Input: what files, facts, or decisions the agent may use.
• Action: what the agent must do.
• Output: the exact artifact it must return.
• Acceptance: how another person or agent decides whether the output is usable.
• Failure: what happens when information is missing.

For example, a planning agent should not simply “design the feature.” It should return a decision record, affected files, open questions, testable acceptance criteria, and a list of implementation risks. That output gives the execution agent something concrete to consume.

How Should Independent Developers Choose Roles?

Start with three roles, not the entire collection.

For a software project, a reasonable first set is:

1. Planning role: turns an idea into scope, constraints, and acceptance criteria.
2. Execution role: changes code or produces the requested artifact.
3. Review role: checks correctness, security, tests, and missing edge cases.

This small group is easier to understand than a large collection of specialists. It also creates a visible feedback loop. Planning defines the target. Execution produces the work. Review tests whether the result matches the target.

The main risk for an individual developer is role sprawl. Installing every available persona creates several hidden costs:

• More instructions compete for attention.
• Similar roles produce slightly different versions of the same answer.
• It becomes unclear which agent owns the decision.
• Prompts become longer and harder to debug.
• A failure can be blamed on the model, the role file, the tool, or the handoff.

Our recommendation is to add a role only when a real project exposes a repeated need. If the same security review appears in three projects, add a security role. If a role is used once and its output is never consumed, keep it out of the default workflow.

Step 1: Install Only the Roles Needed for One Project

The official README documents copying agent files into the Claude Code agent directory:

cp -r agency-agents/* ~/.claude/agents/

The official site also provides an installer command. Before running a shell installer, inspect the script, confirm the target directory, and decide whether the installation should be global or project-specific. A global installation is convenient, but it can make unrelated projects inherit roles you did not intend to use. (agencyagents.dev)

For Cursor, do not assume that copying Claude Code files creates a complete Cursor workflow. Cursor uses project rules in .cursor/rules and also supports a root-level AGENTS.md file for project instructions. Its rules system controls persistent context, scope, and activation behavior. The role content may be reusable, but the file placement and activation model still need to match the target tool. (docs.cursor.com)

Step 2: Select Roles by Deliverable, Not by Job Title

“Developer” is too broad for a reliable workflow.

A better selection question is:

• Who creates the implementation plan?
• Who writes or changes the code?
• Who runs tests?
• Who reviews security-sensitive changes?
• Who prepares the release notes?
• Who makes the final decision?

This approach prevents the common mistake of choosing five agents because their names sound useful. The correct role is the one that owns a distinct output.

Product And Content Teams Need Explicit Handoffs

Product and content teams can use the same model, but their handoffs are different.

A compact product workflow might contain:

• Research role: returns evidence, user segments, assumptions, and unresolved questions.
• Solution role: converts evidence into a proposal with trade-offs.
• Content role: turns the approved proposal into pages, emails, or launch material.
• Quality role: checks factual consistency, terminology, claims, and missing context.

The roles should not all receive the full conversation history by default. Give each role the smallest context needed to complete its task. This reduces repetition and makes accidental context leakage easier to detect.

A useful handoff could look like this:

Research output:
- User problem
- Evidence
- Confidence level
- Unverified assumptions
- Recommended next decision

Solution input:
- Research output only
- Product constraints
- Required decision date

Solution output:
- Chosen direction
- Rejected alternatives
- Acceptance criteria
- Risks

The same method works for content production. The research role should not directly publish copy. The content role should not silently change the product decision. The quality role should be able to reject an output and name the exact requirement that failed.

This is where an AI Agent team becomes useful. The value does not come from having many personalities. It comes from reducing ambiguity between stages.

Serial And Parallel Workflows Have Different Costs

Use serial work when the next task depends on the previous result. Use parallel work when tasks can be completed independently and merged later.

Serial work is usually better for:

• Requirements followed by implementation.
• Research followed by a product decision.
• Code changes followed by tests.
• Draft content followed by fact checking.
• Threat modeling followed by security remediation.

Parallel work is usually better for:

• Reviewing separate modules.
• Writing independent test cases.
• Comparing unrelated design options.
• Checking documentation and release notes at the same time.
• Running independent research tracks with separate source requirements.

Parallel execution is not automatically faster. It adds coordination work. Someone must define the task boundary, collect outputs, resolve contradictions, and decide which result is authoritative.

For software development, agents working on the same files should not share one uncontrolled working directory. Use separate branches or Git worktrees. Git officially describes worktrees as multiple working trees attached to the same repository, allowing several branches to be checked out at once. (git-scm.com)

A safe pattern is:

git worktree add ../project-plan plan/feature
git worktree add ../project-implementation work/feature
git worktree add ../project-tests test/feature

Each agent receives one worktree and one responsibility. The review agent examines committed changes or a pull request. It does not edit the implementation branch while pretending to be an independent reviewer.

The merge gate should require:

• Tests pass.
• Required files are changed.
• No secrets were committed.
• The output matches the acceptance criteria.
• A human approves high-impact changes.
• The branch history identifies which role produced each artifact.

Software Engineering Teams Need More Than Role Files

A development team should separate roles into planning, implementation, testing, security review, and documentation.

The planning role can work before implementation. A test-design role can work in parallel with implementation if it receives stable acceptance criteria. Documentation can often proceed after the interface or behavior is settled. Security review should run against the actual proposed change, not only against the original plan.

The key boundary is file ownership.

If two agents modify the same configuration file, migration, API contract, or shared component, parallel execution can create conflicts even when both outputs look reasonable. The issue is not only Git conflict resolution. One agent may make assumptions that invalidate the other agent’s tests.

For that reason, use a simple scheduling rule:

• Parallelize independent analysis.
• Parallelize separate modules.
• Serialize changes to shared interfaces.
• Run one final review after integration.

Cursor’s documentation shows that its Agent mode can explore a codebase, edit multiple files, run commands, and fix errors. It also provides modes and permissions that help teams restrict behavior. Those capabilities belong to the coding tool, not to the Agency Agents role files themselves. (docs.cursor.com)

This distinction should appear in team documentation. Otherwise, people may believe that installing a “Security Engineer” role automatically creates security controls. It does not. The role can instruct an agent to threat-model inputs, but the environment still decides whether that agent can read production credentials, execute commands, or publish changes.

Can Agency Agents Be Used For Enterprise Projects?

Yes, but only as one layer of the system.

Enterprise use requires controls that the role collection does not automatically provide:

• Identity and access management.
• Per-project permissions.
• Secret isolation.
• Command restrictions.
• Network policy.
• Execution logs.
• Data retention rules.
• Human approval for sensitive actions.
• Reproducible environments.
• Incident response procedures.

The main enterprise risk is not a bad persona description. It is excessive authority combined with weak traceability.

For example, a role may be instructed to “review deployment safety,” while the runtime still allows it to access deployment credentials. That is a policy failure. A good prompt cannot compensate for an over-permissioned execution environment.

For production work, we recommend separating:

1. Configuration: role files and project rules.
2. Runtime: the machine, container, or remote environment executing tasks.
3. Orchestration: the system that assigns and tracks work.
4. Governance: permissions, approvals, logs, and retention.
5. Acceptance: the rules that decide whether the result can be merged or published.

If one of these layers is missing, the workflow may work in a demonstration and fail under repeated use.

Remote Execution Becomes Important When Work Persists

Small experiments can run locally when the task is short, the repository is safe, and the developer can watch the process.

A repeatable remote environment becomes more valuable when:

• Several agents must run at the same time.
• Dependencies take a long time to install.
• Tasks need to continue after a laptop is closed.
• Multiple contributors need the same toolchain.
• Build and test environments must be recreated consistently.
• Logs must remain available for later review.

Do not decide to scale based only on the number of roles installed. A project with ten unused role files may need less infrastructure than a project with three roles running long builds concurrently.

The better signals are:

• Number of simultaneous tasks.
• Task duration.
• Dependency installation cost.
• Repository size.
• Need for persistent sessions.
• Required network access.
• Required isolation level.
• Frequency of human intervention.

If a team needs a persistent macOS environment for Claude Code or Cursor tasks, review ZekVPS’s remote Mac options and Mac support information. The decision should be based on workload continuity and isolation requirements, not on the number of role files in the repository.

Agency Agents Adoption Score

Our adoption score is a workflow assessment, not a benchmark of model quality.

• Role clarity: 9/10. The file-based format makes specialist behavior easy to inspect and modify.
• Portability: 8/10. The project targets several coding tools, but installation and activation details vary by tool.
• Built-in orchestration: 2/10. Role files do not replace a scheduler, queue, state store, or retry system.
• Enterprise governance: 3/10. Permissions, secrets, audit logs, and sandboxing must be added by the adopting team.
• Small-team usefulness: 8/10. A small role set can improve repeatability without requiring a large platform.
• Large-team readiness: 5/10. The roles can be a useful content layer, but the surrounding runtime and governance need deliberate design.

The score explains the correct buying and deployment decision: adopt it for role design and workflow experiments. Do not present it internally as a complete production platform.

First Acceptance Run: A Checklist For Formal Adoption

Use one real project. Avoid a toy prompt that cannot expose failure modes.

• [ ] Choose one planning role, one execution role, and one review role.
• [ ] Write the input and output contract for each role.
• [ ] Define which files, tools, and credentials each role may access.
• [ ] Run the same task through the workflow twice.
• [ ] Check whether the outputs are complementary rather than repetitive.
• [ ] Force one controlled failure, such as a missing dependency or invalid requirement.
• [ ] Confirm that the failed step can be retried without corrupting the project state.
• [ ] Review whether private context appears in a downstream output.
• [ ] Run tests or another objective verification step.
• [ ] Ask a human reviewer to approve or reject the final artifact.
• [ ] Record the reason for rejection if the result fails.
• [ ] Decide whether the workflow can be repeated by another team member.
• [ ] Keep only the roles that produced a distinct, accepted deliverable.

A three-to-five-role pilot is usually easier to evaluate than a full collection. Expand only after the first workflow has stable boundaries and a clear definition of done.

The most important acceptance question is not “Did the agent sound like an expert?” It is “Could another person verify the output without replaying the entire conversation?”

For current counts, supported tools, installation commands, and licensing, we verified the official site and repository on August 13, 2026. These details can change as the project evolves, so they should be rechecked before each production rollout. (agencyagents.dev)

If the current approach is a developer laptop with several terminals, the real weaknesses are usually limited session persistence, inconsistent dependencies, and weak separation between concurrent tasks. A local setup is fine for short experiments, but it becomes harder to observe and reproduce when agents need to run continuously. Renting a Mac from ZekVPS can be a better fit when the priority is a persistent macOS workspace for temporary development, testing, or parallel agent sessions. It is not the right choice for every workload: teams with stable, heavy, long-term usage may prefer owning hardware, while projects requiring physical devices or specialized peripherals need to verify access requirements first.

Start with one planning role, one execution role, and one review role. Once the workflow passes the checklist, move the long-running or parallel tasks into a properly isolated remote Mac environment rather than assuming the role files will provide the missing infrastructure.