# Pi-CodeMachine

**Universal Multi-Agent Workflow Orchestration for Pi**

Pi-CodeMachine is a comprehensive workflow orchestration extension that enables pi to coordinate multiple specialized agents for complex tasks—**any kind of tasks at all**. Whether you're coding, researching, writing, analyzing data, making decisions, or creating content, CodeMachine provides the infrastructure to break down complex work into orchestrated agent workflows.

## Features

- **🎭 Universal Task Support**: Not just coding—research, writing, analysis, creative projects, business decisions, QA, and more
- **🔄 Multi-Mode Execution**: Sequential chains, parallel execution, dependency-driven workflows
- **📊 Built-in Agents**: 12+ specialized agents ready to use (researcher, writer, analyst, critic, planner, creative, etc.)
- **📋 Workflow Templates**: Pre-built templates for common patterns (deep research, polished content, feature implementation, etc.)
- **⏯️ Lifecycle Management**: Create, run, pause, resume, abort, and delete workflows
- **📈 Real-time Monitoring**: Watch progress with live updates
- **💾 Persistence**: Workflows survive session restarts
- **🎯 Conditional Logic**: Steps can execute conditionally based on previous results
- **🔁 Retry Logic**: Automatic retry with configurable delays
- **📂 Result Aggregation**: Collect, synthesize, and export workflow results

## Installation

### Extension Setup

```bash
# Create the extension directory
mkdir -p ~/.pi/agent/extensions/pi-codemachine

# Copy the extension file
cp pi-codemachine/index.ts ~/.pi/agent/extensions/pi-codemachine/

# Copy built-in agents
mkdir -p ~/.pi/agent/agents/codemachine
cp pi-codemachine/agents/*.md ~/.pi/agent/agents/codemachine/
```

### Verification

```bash
# List available agents
/cm-agents

# List workflow templates
/cm-templates
```

## Quick Start

### 1. Spawn a Single Agent

```
Use the researcher agent to find information about quantum computing applications in healthcare
```

Or use the tool directly:
```
cm_agent_spawn:0 {"agent": "researcher", "task": "Research quantum computing applications in healthcare. Focus on current implementations and near-term possibilities."}
```

### 2. Execute Parallel Tasks

```
Analyze this codebase from multiple angles:
- Security review
- Performance analysis  
- Maintainability assessment
```

Tool usage:
```
cm_parallel_execute:1 {"tasks": [{"agent": "critic", "task": "Security audit of the codebase", "id": "security"}, {"agent": "analyst", "task": "Performance analysis of the codebase", "id": "performance"}, {"agent": "critic", "task": "Maintainability review of the codebase", "id": "maintainability"}]}
```

### 3. Chain Sequential Tasks

```
Write a blog post:
1. Research the topic
2. Create an outline  
3. Write the draft
4. Edit and polish
```

Tool usage:
```
cm_chain_execute:2 {"chain": [{"agent": "researcher", "task": "Research: The impact of AI on creative industries"}, {"agent": "planner", "task": "Create a blog post outline based on: {previous}"}, {"agent": "writer", "task": "Write a blog post based on this outline: {previous}"}, {"agent": "editor", "task": "Edit and polish this draft: {previous}"}]}
```

### 4. Use a Workflow Template

```
Create a comprehensive research workflow on renewable energy
```

Tool usage:
```
cm_workflow_from_template:3 {"template": "deep-research", "input": "renewable energy storage technologies", "name": "renewable-energy-research"}
```

Then run it:
```
cm_workflow_run:4 {"workflowId": "wf-xxx"}
```

## Built-in Agents

### Core Agents

| Agent | Category | Best For |
|-------|----------|----------|
| `generalist` | General | Any task requiring broad capabilities |
| `researcher` | Research | Information gathering, exploration, synthesis |
| `writer` | Writing | Content creation, documentation, copy |
| `analyst` | Analysis | Data analysis, insights, evaluation |
| `critic` | Review | Quality assurance, code review, critique |
| `planner` | Planning | Strategy, organization, project breakdown |
| `creative` | Creative | Ideation, brainstorming, innovation |
| `editor` | Writing | Refinement, polishing, proofreading |
| `summarizer` | Analysis | Condensation, synthesis, distillation |

### Coding-Specific Agents

| Agent | Category | Best For |
|-------|----------|----------|
| `coder` | Coding | Software development, implementation |
| `reviewer` | Coding | Code review, security, performance |
| `scout` | Coding/Research | Fast reconnaissance, codebase exploration |

### Creating Custom Agents

Create a file in `~/.pi/agent/agents/my-agent.md`:

```markdown
---
name: my-agent
description: What this agent does
category: research, analysis
capabilities: research, synthesis
tools: read, grep, find, ls
model: claude-sonnet-4-5
---

System prompt for the agent goes here.
```

## Workflow Templates

### Available Templates

| Template | Category | Description |
|----------|----------|-------------|
| `deep-research` | Research | Comprehensive research with multiple angles and synthesis |
| `polished-content` | Writing | Create content with drafting, review, and refinement |
| `implement-feature` | Coding | Full feature implementation with planning, coding, and review |
| `comprehensive-analysis` | Analysis | Multi-perspective analysis with synthesis |
| `creative-project` | Creative | Creative project with ideation, development, and refinement |
| `informed-decision` | Business | Structured decision-making process |
| `quality-assurance` | Review | Multi-stage quality review process |

### Template Usage

```
cm_workflow_from_template:5 {"template": "polished-content", "input": "Write an article about sustainable architecture", "name": "sustainable-arch-article"}
```

## Tools Reference

### Workflow Management

#### `cm_workflow_create`
Create a custom workflow with defined steps and dependencies.

```typescript
{
  name: string;
  description: string;
  steps: Array<{
    id: string;
    name: string;
    description: string;
    agent: string;
    task: string;
    dependsOn?: string[];
    timeout?: number;
    retryCount?: number;
    retryDelay?: number;
    checkpoint?: boolean;
    condition?: string; // e.g., "previous.success", "output.includes('error')"
  }>;
  category?: string;
  tags?: string[];
  priority?: "low" | "normal" | "high" | "urgent";
}
```

#### `cm_workflow_run`
Execute a workflow.

```typescript
{
  workflowId: string;
  watch?: boolean; // Stream progress updates
}
```

#### `cm_workflow_resume`
Resume a paused or partially completed workflow.

```typescript
{
  workflowId: string;
  watch?: boolean;
}
```

#### `cm_workflow_abort`
Stop a running workflow.

#### `cm_workflow_delete`
Delete a workflow.

```typescript
{
  workflowId: string;
  force?: boolean; // Force delete even if running
}
```

### Execution Tools

#### `cm_agent_spawn`
Execute a single agent task.

```typescript
{
  agent: string;
  task: string;
  timeout?: number;
  agentScope?: "user" | "project" | "both" | "builtin";
  outputFormat?: "text" | "json" | "markdown";
}
```

#### `cm_parallel_execute`
Execute multiple agents in parallel.

```typescript
{
  tasks: Array<{
    agent: string;
    task: string;
    id?: string;
  }>;
  maxConcurrency?: number; // 1-8, default: 4
  aggregate?: boolean; // Combine results into single output
}
```

#### `cm_chain_execute`
Execute agents sequentially, passing outputs forward.

```typescript
{
  chain: Array<{
    agent: string;
    task: string; // Use {previous}, {stepId}, or {input}
    id?: string;
    condition?: string; // "previous.success", "previous.failure"
  }>;
  initialInput?: string;
}
```

### Monitoring & Results

#### `cm_status_check`
Check workflow status.

```typescript
{
  workflowId?: string;  // Check specific workflow
  all?: boolean;        // List all workflows
  filter?: {
    status?: string;
    category?: string;
    tag?: string;
  };
}
```

#### `cm_results_collect`
Gather and synthesize workflow results.

```typescript
{
  workflowId: string;
  stepIds?: string[];    // Specific steps (default: all)
  format?: "summary" | "full" | "json" | "markdown";
  synthesize?: boolean;  // Auto-synthesize results
}
```

### Information

#### `cm_list_agents`
List available agents with capabilities.

```typescript
{
  category?: string;
  agentScope?: "user" | "project" | "both" | "builtin";
}
```

#### `cm_list_templates`
List workflow templates.

```typescript
{
  category?: string;
}
```

#### `cm_workflow_from_template`
Create workflow from template.

```typescript
{
  template: string;
  input: string;
  name?: string;
  customizations?: Record<string, string>;
}
```

## Commands

| Command | Description |
|---------|-------------|
| `/cm-list [filters]` | List workflows (e.g., `/cm-list status:running`) |
| `/cm-agents` | List available agents |
| `/cm-templates` | List workflow templates |
| `/cm-status <workflow-id>` | Show detailed workflow status |
| `/cm-clean [days]` | Clean up old workflows (default: 7 days) |

## Workflow Patterns

### Pattern 1: Sequential Pipeline
```
Step 1 → Step 2 → Step 3 → Step 4
```
Each step depends on the previous. Good for methodical work.

### Pattern 2: Parallel Fan-Out
```
         ┌→ Agent A
Input → ├→ Agent B
         ├→ Agent C
         └→ Agent D
```
All agents work simultaneously on different aspects.

### Pattern 3: Dependency Graph
```
     ┌→ B → D ─┐
A → ┤          ├→ F
     └→ C → E ─┘
```
Complex dependencies with parallel execution where possible.

### Pattern 4: Conditional Flow
```
A → (if success) → B → C
   (if failure) → D → E
```
Steps execute conditionally based on previous results.

### Pattern 5: Map-Reduce
```
Input → [Parallel Processing] → Aggregation → Output
```
Process chunks in parallel, then synthesize.

## Advanced Features

### Conditional Execution

Steps can be conditional based on previous results:

```typescript
{
  id: "notify",
  name: "Notify on Success",
  agent: "generalist",
  task: "Send success notification",
  dependsOn: ["deploy"],
  condition: "deploy.success"  // Only run if deploy succeeded
}
```

Conditions supported:
- `"previous.success"` / `"previous.failure"`
- `"stepId.success"` / `"stepId.failure"`
- `"output.includes('text')"`
- `"output.startsWith('text')"`
- `"always"` / `"never"`

### Variable Substitution

Tasks can reference outputs from previous steps:

```typescript
{
  agent: "writer",
  task: "Write article based on research:\n{research-step}"
}
```

Or use `{previous}` for the most recent output, `{input}` for the initial input.

### Retry Logic

```typescript
{
  id: "api-call",
  name: "API Integration",
  agent: "coder",
  task: "Implement API integration",
  retryCount: 3,
  retryDelay: 5000,  // 5 seconds between retries
  timeout: 120000
}
```

### Checkpoints

Enable checkpointing to save progress after critical steps:

```typescript
{
  id: "data-processing",
  name: "Process Large Dataset",
  agent: "analyst",
  task: "Process the data",
  checkpoint: true  // Save workflow state after completion
}
```

## Use Cases

### Software Development

```
Implement a user authentication system:
1. Scout the codebase for existing auth code
2. Plan the implementation approach
3. Implement the auth middleware
4. Add user model and migrations
5. Create login/logout endpoints
6. Add tests
7. Review the implementation
```

### Research & Analysis

```
Research the competitive landscape:
1. Scout for information sources
2. Research Company A's offerings
3. Research Company B's offerings
4. Research Company C's offerings
5. Analyze pricing strategies
6. Analyze feature comparisons
7. Synthesize competitive analysis report
```

### Content Creation

```
Create a technical blog post:
1. Research the topic thoroughly
2. Create detailed outline
3. Write first draft
4. Self-review and critique
5. Edit and refine
6. Final proofread
```

### Decision Making

```
Evaluate cloud providers:
1. Generate evaluation criteria
2. Research AWS offerings
3. Research Azure offerings
4. Research GCP offerings
5. Score each against criteria
6. Analyze trade-offs
7. Make recommendation with rationale
```

### Quality Assurance

```
Review a pull request:
1. Initial code review
2. Security analysis
3. Performance impact check
4. Test coverage verification
5. Documentation review
6. Final approval/rejection
```

## Configuration

### Workspace Directory

Workflows are stored in `.codemachine/`:
```
.codemachine/
├── workflows/     # Workflow definitions
├── results/       # Step outputs
├── logs/          # Execution logs
├── state/         # Checkpoint data
└── artifacts/     # Generated files
```

### Environment Variables

```bash
# Default timeout for agent tasks (ms)
CM_DEFAULT_TIMEOUT=300000

# Max parallel tasks
CM_MAX_CONCURRENCY=4

# Checkpoint interval (ms)
CM_CHECKPOINT_INTERVAL=30000
```

## Troubleshooting

### Workflow Stuck
```
/cm-status <workflow-id>
cm_workflow_abort:6 {"workflowId": "wf-xxx"}
```

### Agent Not Found
```
cm_list_agents:7 {"agentScope": "both"}
```

### Check Logs
```bash
ls .codemachine/logs/
cat .codemachine/logs/workflow-<id>.log
```

### Extension Not Loading
1. Verify file is at `~/.pi/agent/extensions/pi-codemachine/index.ts`
2. Check for TypeScript errors
3. Reload pi with `/reload`

## Best Practices

1. **Start Simple**: Begin with simple workflows, add complexity gradually
2. **Clear Tasks**: Each agent task should be specific and bounded
3. **Meaningful Step Names**: Makes status monitoring easier to read
4. **Use Templates**: Leverage pre-built templates for common patterns
5. **Checkpoint Critical Steps**: Enable checkpoints for long-running steps
6. **Handle Failures**: Design workflows to handle partial failures gracefully
7. **Review Results**: Always review `cm_results_collect` output
8. **Clean Up**: Use `/cm-clean` regularly to remove old workflows

## Contributing

To add new agents:
1. Create `.md` file in `~/.pi/agent/agents/codemachine/`
2. Include YAML frontmatter with metadata
3. Write comprehensive system prompt
4. Test with various tasks

To add new templates:
1. Define template in extension code
2. Include clear description and use case
3. Test with real-world scenarios
4. Document in this README

## License

MIT

## Changelog

### 1.0.0
- Initial release
- 12+ built-in agents
- 7 workflow templates
- Full workflow lifecycle management
- Conditional execution and retry logic
- Real-time monitoring and result aggregation