the-agency-cli 1.2.0

The Virtual IT Team in Your Pocket. A framework of 28 AI Personas for enterprise software development.

The Agency

The Virtual IT Team in Your Pocket 🏢

"The Agency" is an open-source framework that models a complete Enterprise Software Development Organization using specialized AI Personas (Skills).

⚖️ Why The Agency? (vs. CrewAI, AutoGen, LangGraph)

Unlike traditional agent orchestration frameworks that require you to write hundreds of lines of complex Python code to define state variables, execution graphs, and LLM API hooks, The Agency is purely contextual.

• Zero Code Orchestration: The Agency provides the missing Domain Knowledge, Organizational Chart, and Standard Operating Procedures (SOPs) as modular logic files. You don't need to write connection code.
• Bring Your Own Editor: Instead of running a headless python script, you inject The Agency's Personas directly into the powerful AI tools you already use every day (Cursor, Roo Code, Copilot Workspaces, Gemini CLI, Aider).
• Practical Software Engineering: Other frameworks give you a generic sandbox. The Agency gives you a heavily researched, production-proven IT department ranging from a project_manager and cmo_analyst to a chief_information_security_officer and sre_cloud_architect.

You don't need another orchestration engine. You just need a better team.

Simply inject these personas into your favorite AI tool and watch the Virtual IT Team design, develop, secure, test, and market your application.

🛡️ Core Value: Prompt Poisoning Defense

As an open-source framework driven purely by contextual markdown, The Agency recognizes that "Prompt Injection" and "Data Poisoning" are the largest unmitigated threats to autonomous agent ecosystems.

We maintain a strict Chain of Trust for all external contributions. Because malicious actors could attempt to submit Pull Requests containing jailbreaks or data exfiltration commands hidden inside a Persona's System Prompt (SKILL.md), this repository treats prompt security as a first-class citizen. All incoming PRs are strictly audited, ensuring that an enterprise using The Agency is never compromised by a poisoned virtual employee.

---

👥 The Organization Chart

The Virtual IT Team comprises specialized "Skills", mapped precisely to a modern tech enterprise:

• Management: project_manager, historian, workspace_manager
• Architecture: solution_architect, cmo_analyst (Digital Twin Owner), sre_cloud_architect
• Development: backend_developer, frontend_developer, coder
• Design: ux_ui_designer
• Data Engineering: relational_dba, graph_database_architect, data_scientist
• Quality Assurance: chief_test_officer, qa_automation_engineer, test_engineer, e2e_journey_tester, test_data_manager, ui_qa_engineer
• Security: chief_information_security_officer, application_security_engineer, security_operations_analyst
• Deployment: ssdlc_manager
• Management & Marketing: head_of_marketing, product_marketing_manager, content_copywriter, technical_writer
• Support & AI Ops: customer_support_triage, prompt_engineer, makefile_orchestrator
• Meta-Skills (The Creators): skill_creator (Organizational Architect), tool_smith (Internal Tooling)

(Read each SKILL.md inside the skills/ folder to review the specific heuristics and constraints of that role).

---

🚀 How to Use "The Agency"

Because The Agency defines logic and processes rather than hard-coded python scripts, you can use it conceptually within any environment.

1. The Global Agency CLI (Recommended)

The most powerful way to use "The Agency" is to install it globally on your system path. This allows you to spawn any persona directly into whichever project directory you are currently working in.

Because "The Agency" is written in Python, the recommended way to install it globally without breaking your system packages is via pipx.

# Install the CLI globally in an isolated environment
pipx install the-agency-cli

# Navigate to any of your completely separate projects
cd /my/super/secret/startup/

# Launch the interactive CLI right there
agency

The CLI will guide you through:

• Initialize & Configure: Automatically scans for AI assistants like Cursor (.cursorrules), Gemini (.gemini), Roo Code (.clinerules), and Claude (CLAUDE.md). It installs the Agency skills into your .agency/ folder and injects specialized system logic into your AI tool's project memory so they know how to use the skills!
• Browse Skills: View the organizational chart and understand what every department does.
• Run Skill: Choose a specific skill, paste a task, and the agent will immediately context-switch into your codebase to start working.

2. In Premium Agentic Tools (Cursor, Roo Code, Copilot Workspaces)

Point your AI assistant at the specific SKILL.md you want it to embody. For example, tell Cursor: "Embody the role defined in skills/frontend_developer/SKILL.md and complete this task."

3. Pure Makefiles & Terminal Piping

If you prefer raw execution, you can completely ignore .agency.py and run sequential generation using the Makefile pattern.

See the example Makefile in the root directory for a proof-of-concept pipeline.

# Example: Generate an application schema using a local 8B model
make build-schema 

4. Supercharging Skills with Tools

While skills have "Brains", they need "Hands" to affect the local machine. By installing common CLI tools globally on your terminal (e.g., semgrep, docker, playwright), you empower the agents to use those tools automatically via run_command capabilities.

Read the Recommended Tools Architecture to see which open-source CLIs pair best with which Virtual Employee. If a tool you need doesn't exist, spawn the tool_smith meta-skill to write a custom wrapper!

---

📦 Integrating into an Existing Project

If you are not starting from scratch, you can easily drop "The Agency" into a mature, existing repository.

1. Call the agency command and select "Initialize" The agency init command does two massive things:

• It automatically configures whatever native AI tool you use (Cursor, Cline, Gemini, Aider) with the Agency's context and instructions.
• It copies the entire skills/ directory into your .agency/ folder.

2. Initialize the "Digital Twin" (The Most Important Step) AI agents hallucinate when they don't know your existing architecture. Before asking the Agency to write new code for your existing app, you must map your current state. From the agency initialization menu, select "Map Digital Twin":

• The historian reads your files to summarize the project's purpose.
• The solution_architect maps the src/ hierarchy to build a system architecture.
• The cmo_analyst aggregates this into a master "Digital Twin" state document at docs/cmo_state.md.

3. Resume Normal Operations Once properly mapped and configured, your native AI editor (like Cursor or Gemini) naturally understands your new virtual employees and the structure of your application. Ask your IDE directly: "Tell the backend_developer to build a new auth route according to the architecture."

---

🏗️ The Project Lifecycle

If you elect to use the full agency, follow the routing lifecycle governed by the project_manager:

1. Discovery: cmo_analyst checks the system's "Digital Twin" constraints (docs/).
2. Design Blueprint: ux_ui_designer maps the wireframes; prompt_engineer maps the LLM context flow.
3. Architecture: solution_architect defines the data models and component structure.
4. Security Check: ciso reviews the architecture for vulnerabilities. (Must pass before coding).
5. Implementation: Specialized backend_developer and frontend_developer write the code.
6. Testing: chief_test_officer coordinates unit, integration, and E2E tests.
7. Deployment: sre_cloud_architect dictates topology, and ssdlc_manager routes it to production.
8. Launch: The Marketing division generates go-to-market copy while the technical_writer builds the public APIs.

---

📜 Legacy Assets

Older, hard-coded Python SDK variants of this agentic framework have been archived in the legacy/ folder for historical reference. The future of The Agency is agnostic, prompt-driven markdown injected into powerful local or cloud execution layers.

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Want to add a new role to the IT Team?

1. Copy an existing SKILL.md inside skills/.
2. Define their Core Responsibilities and Workflow Integration in the markdown.
3. Submit a Pull Request.

🐛 Issues and Support

If you encounter any bugs, have feature requests, or need help integrating The Agency into your workflow, please open an issue on GitHub.

📄 License

Distributed under the MIT License. See LICENSE for more information.