Sub-Agent Protocols

This project is a Claude-compatible, LLM-agnostic sub-agent framework that simulates a complete SaaS product team. It is delivered as a reusable, developer-ready NPM package.

Goals

• To create a fully orchestrated, modular, spec-led development environment that reflects how a real SaaS company operates.
• To simulate roles like product, engineering, QA, and documentation via intelligent sub-agents.
• To provide a plug-and-play tool for other developers to build upon.

Getting Started

1. Clone the repository:

   git clone https://github.com/oliverpople/subagents-protocol.git
   cd subagents-protocol

2. Install the dependencies:

   npm install

3. Build the project:

   npm run build

4. Set up your environment variables: Create a .env file in the root of the project and add your LLM API keys:

   CLAUDE_API_KEY=your-claude-api-key
   OPENAI_API_KEY=your-openai-api-key

Usage

The framework is designed to be run from the command line.

Running a Workflow

To run a workflow, use the run command with the --feature flag:

npx subagents run --feature "Allow users to export filtered reports as CSV"

Available Flags

• --feature <description>: (Required) A high-level description of the feature to be built.
• --protocol <name>: (Optional) The name of the protocol to run. Defaults to fullRoundtrip.
• --resume <specId>: (Optional) The ID of a previous session to resume.
• --voice: (Optional) Enables voice narration of the agent activities.

Resuming a Workflow

To resume a previous workflow, use the --resume flag with the specId of the session you want to continue:

npx subagents run --resume SPEC-2025-0081

Available Protocols

• fullRoundtrip: Runs the entire workflow, from spec to release plan.
• productToDev: Runs the product manager, backend developer, and frontend developer.
• devToQA: Runs the backend developer, frontend developer, and QA engineer.
• specToDocs: Runs the product manager and documentation agent.

To-Do

• [x] Implement dynamic protocols to chain agents in different ways.
• [x] Build out the llmRouter to handle switching between different LLM providers.
• [x] Re-enable and debug the voice narration feature.
• [x] Add comprehensive tests for all agents and protocols.
• [ ] Replace mock agent implementations with actual LLM calls.
• [ ] Implement a more robust CLI with more commands and options.
• [ ] Add support for more LLM providers.
• [ ] Improve the context management system to handle more complex state.
• [ ] Add more specialized agents to the framework.