agency-x/README.md

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.

# 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:**
    ```bash
    git clone https://github.com/oliverpople/subagents-protocol.git
    cd subagents-protocol
    ```

2.  **Install the dependencies:**
    ```bash
    npm install
    ```

3.  **Build the project:**
    ```bash
    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:

```bash
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:

```bash
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.