Skip to content

majiayu000/spellbook / skills/multi-model-orchestrator

multi-model-orchestrator

Verified

Use when coordinating complex tasks across multiple AI agents with a centralized handoff document for planning, execution tracking, and feedback fusion.

references/best-practices.md

View on GitHub
# Best Practices

Part of the `multi-model-orchestrator` skill. Patterns that keep handoffs
high-signal and traceable. Load this when authoring or reviewing subtasks.

### 1. **Clear Subtask Descriptions**

Bad:
```yaml
- id: task-1
  input: "fix the code"
```

Good:
```yaml
- id: task-1
  input: |
    The authentication middleware in src/auth.ts has a race condition
    when multiple requests arrive simultaneously.

    Current behavior: requests can bypass the token refresh check
    Expected behavior: all requests wait for token refresh to complete

    Code reference: src/auth.ts:45-62
    Test: tests/auth.race-condition.test.ts
```

### 2. **Specific Acceptance Criteria**

Bad:
```yaml
acceptance: "it should work"
```

Good:
```yaml
acceptance: |
  - Token refresh completes within 100ms
  - No requests can bypass the mutex
  - All 100 concurrent requests pass the test suite
  - Performance regression < 5% vs baseline
```

### 3. **Declare Dependencies Explicitly**

```yaml
depends_on: ["task-1", "task-2"]  # Clear ordering
```

Not:
```yaml
# Implicitly assumes task-1 was done first (bad)
```

### 4. **Record Everything**

Even if a task fails, record it:

```yaml
- round: 2
  task_id: "task-2"
  status: "blocked"
  result: "Attempt failed due to missing dependency"
  issues: |
    Task-1 output was incomplete.
    Need to ask Opus to redo task-1.
  next_step: "Re-execute task-1 with clearer requirements"
```

### 5. **Keep Handoffs in Git**

```bash
# Commit your handoff
git add .claude/handoffs/my-task.yaml
git commit -m "WIP: multi-agent task execution for feature X"

# Later you can see the full evolution:
git log -p .claude/handoffs/my-task.yaml
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall