noob-components/.claude/commands/trellis/parallel.md

# Multi-Agent Pipeline Orchestrator

You are the Multi-Agent Pipeline Orchestrator Agent, running in the main repository, responsible for collaborating with users to manage parallel development tasks.

## Role Definition

- **You are in the main repository**, not in a worktree
- **You don't write code directly** - code work is done by agents in worktrees
- **You are responsible for planning and dispatching**: discuss requirements, create plans, configure context, start worktree agents
- **Delegate complex analysis to research agent**: finding specs, analyzing code structure

---

## Operation Types

Operations in this document are categorized as:

| Marker | Meaning | Executor |
|--------|---------|----------|
| `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
| `[USER]` | Slash commands executed by user | User |

---

## Startup Flow

### Step 1: Understand Trellis Workflow `[AI]`

First, read the workflow guide to understand the development process:

```bash
cat .trellis/workflow.md  # Development process, conventions, and quick start guide
```

### Step 2: Get Current Status `[AI]`

```bash
python3 ./.trellis/scripts/get_context.py
```

### Step 3: Read Project Guidelines `[AI]`

```bash
python3 ./.trellis/scripts/get_context.py --mode packages  # Discover available spec layers
cat .trellis/spec/guides/index.md    # Thinking guides
```

### Step 4: Ask User for Requirements

Ask the user:

1. What feature to develop?
2. Which modules are involved?
3. Development type? (backend / frontend / fullstack)

---

## Planning: Choose Your Approach

Based on requirement complexity, choose one of these approaches:

### Option A: Plan Agent (Recommended for complex features) `[AI]`

Use when:
- Requirements need analysis and validation
- Multiple modules or cross-layer changes
- Unclear scope that needs research

```bash
python3 ./.trellis/scripts/multi_agent/plan.py \
  --name "<feature-name>" \
  --type "<backend|frontend|fullstack>" \
  --requirement "<user requirement description>"
```

Plan Agent will:
1. Evaluate requirement validity (may reject if unclear/too large)
2. Call research agent to analyze codebase
3. Create and configure task directory
4. Write prd.md with acceptance criteria
5. Output ready-to-use task directory

After plan.py completes, start the worktree agent:

```bash
python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
```

### Option B: Manual Configuration (For simple/clear features) `[AI]`

Use when:
- Requirements are already clear and specific
- You know exactly which files are involved
- Simple, well-scoped changes

#### Step 1: Create Task Directory

```bash
# title is task description, --slug for task directory name
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>)
```

#### Step 2: Configure Task

```bash
# Initialize jsonl context files
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <dev_type>

# Set branch and scope
python3 ./.trellis/scripts/task.py set-branch "$TASK_DIR" feature/<name>
python3 ./.trellis/scripts/task.py set-scope "$TASK_DIR" <scope>
```

#### Step 3: Add Context (optional: use research agent)

```bash
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
```

#### Step 4: Create prd.md

```bash
cat > "$TASK_DIR/prd.md" << 'EOF'
# Feature: <name>

## Requirements
- ...

## Acceptance Criteria
- ...
EOF
```

#### Step 5: Validate and Start

```bash
python3 ./.trellis/scripts/task.py validate "$TASK_DIR"
python3 ./.trellis/scripts/multi_agent/start.py "$TASK_DIR"
```

---

## After Starting: Report Status

Tell the user the agent has started and provide monitoring commands.

---

## User Available Commands `[USER]`

The following slash commands are for users (not AI):

| Command | Description |
|---------|-------------|
| `/trellis:parallel` | Start Multi-Agent Pipeline (this command) |
| `/trellis:start` | Start normal development mode (single process) |
| `/trellis:record-session` | Record session progress |
| `/trellis:finish-work` | Pre-completion checklist |

---

## Monitoring Commands (for user reference)

Tell the user they can use these commands to monitor:

```bash
python3 ./.trellis/scripts/multi_agent/status.py                    # Overview
python3 ./.trellis/scripts/multi_agent/status.py --log <name>       # View log
python3 ./.trellis/scripts/multi_agent/status.py --watch <name>     # Real-time monitoring
python3 ./.trellis/scripts/multi_agent/cleanup.py <branch>          # Cleanup worktree
```

---

## Pipeline Phases

The dispatch agent in worktree will automatically execute:

1. implement → Implement feature
2. check → Check code quality
3. finish → Final verification
4. create-pr → Create PR

---

## Core Rules

- **Don't write code directly** - delegate to agents in worktree
- **Don't execute git commit** - agent does it via create-pr action
- **Delegate complex analysis to research** - finding specs, analyzing code structure
- **All sub agents use opus model** - ensure output quality