---
name: parallel
description: "Dispatch parallel agents per item in a user-provided punch list. Defaults to one worker per low-risk task; reserves full-crew fanout (multi-worker teams + mandatory Codex pairing) for production-mode work, high-risk task types (security, payments, schema migrations), or explicit !max / --full-power. Routes command-shaped items (features, bugfixes, refactors) to their owning commands."
argument-hint: "task1; task2; task3 (or numbered/bulleted list); append !max to force full crew"
---

# /parallel

Run a parallel ad-hoc dispatcher over a punch list of independent tasks.

## Default sizing

**One worker per low-risk task.** Docs, quick chores, single-trace debug, single-explorer research, single-builder dev — all run with one agent and no Codex pairing by default. Most punch lists are heterogeneous-but-low-risk, and a full crew on each item burns tokens without buying review depth that the task needs.

**Full-crew fanout fires when any of these is true:**
- The task type is high-risk: `security`, or `dev` / `complex` tasks that touch auth, payments, PII, schema migrations
- The active manifest is in production mode (`phase_plan.codify: active` or later phases active, OR `project.mode: production`)
- The user invoked `!max` (or `--full-power`)

Full-crew means multi-worker teams + mandatory Codex pairing (see Step 4 of the skill for the per-task templates). Otherwise it stays light.

## When to use

- You have 3-20 independent tasks to do in parallel
- The tasks are heterogeneous (mix of dev, research, docs, debug, quick fixes)
- None of the tasks individually warrants a full `/feature` or `/bugfix` workflow
- For production-mode or high-risk work where you want Codex-paired second opinions — opt in with `!max` if you need it regardless of phase

## When NOT to use

- A single task — use the appropriate skill or command directly
- A coherent feature spec — use `/feature`
- A single bug to fix — use `/bugfix`
- A refactor — use `/refactor`
- Everything in the list is command-shaped — invoke those commands instead

## Process

REQUIRED SUB-SKILL: Use **support-parallel** to:
1. Run Codex consent (one-time per run, per `protocols/codex.md`) — skipped by default in light mode, mandatory in full-crew mode
2. Detect run mode: light (default) vs full-crew (production manifest, high-risk task types, or `!max`)
3. Parse the task list (numbered, bulleted, or semicolon-separated argument)
4. Classify each task by type (dev / research / debug / docs / review / security / quick / complex / command-shaped) AND risk tier
5. Route command-shaped items to their owning commands (do NOT dispatch parallel runs for them)
6. Assemble a team per task — light (one worker, optional Codex per task type) unless full-crew trigger fires
7. Dispatch all per-task teams in parallel (background subagents)
8. Aggregate per-task verdicts with consensus check (full-crew only has the Claude+Codex divergence axis)
9. Surface a run-summary with conflicts highlighted

## Arguments

Either:
- Pass the list directly: `/parallel update README; explore caching options; add test for parser`
- Or pass a numbered/bulleted list in the next prompt after invoking `/parallel` bare

## Output

`.forge/parallel/{run-id}/` containing:
- `codex.yaml` — Codex consent choice
- `tasks.yaml` — task classifications
- `task-{n}/{role}.md` — per-agent output
- `task-{n}/verdict.md` — per-task consensus verdict
- `run-summary.md` — consolidated report

## Caps

- Hard cap: 20 tasks per run
- Soft cap: 10 tasks (warn, offer to batch)
- Per-task team: 1 agent (light, the default) up to 5 agents (full-crew, on trigger)
- Total agents per run: ~3-15 typical for light mode, ~12-60 for full-crew

## Examples

### Standard (lightweight default)

```
/parallel
1. Update README with new install steps
2. Explore options for adding a /status command
3. Add unit test for parser edge cases
4. Bump dep "yaml" to ^2.3
5. Investigate why CI is flaky on test 17
```

Expected behavior (no production manifest, no `!max`):
- Task 1 (docs): 1 × `doc-writer` (no Codex)
- Task 2 (research): 1 × explorer (no Codex)
- Task 3 (dev, low-risk): 1 × `builder` (no Codex)
- Task 4 (quick): 1 inline agent (no Codex)
- Task 5 (debug): 1 dispatch of `support-debug` (the skill owns its own chain)
- Total: ~5 agents in parallel

Same list with a production-mode manifest active OR a high-risk task in the mix (e.g. "audit auth handler for OWASP") escalates to the full-crew templates in Step 4.

### Force full power (`!max` override)

```
/parallel !max
1. Update README with new install steps
2. Add helper function for date parsing
3. Investigate why CI is flaky on test 17
```

Expected behavior (full-crew enforced regardless of manifest state):
- All tasks dispatch with full-crew templates
- Mandatory Codex pairing throughout
- No "light mode" shortcut even for quick / docs items
- Total: ~8 agents

Use `!max` (short form) or `--full-power` (canonical form) when prototype code is about to graduate to production, or when you want maximum review depth regardless of run-mode detection. Both forms are equivalent.

## Manifest

This command does NOT create a `.forge/work/{type}/{name}/` manifest — `/parallel` runs are not phase-gated. State lives in `.forge/parallel/{run-id}/` only.

If an active feature/bugfix manifest exists, the parallel run-id is appended to its current phase as `parallel-runs: [...]` for audit.

## Cleanup

`.forge/parallel/{run-id}/` directories accumulate one per run. The retention spec is **30 days**, after which entries are eligible for prune.

**Manual prune (works today):**

```bash
# Dry run (lists what would be removed)
find .forge/parallel -maxdepth 1 -mindepth 1 -type d -mtime +30 -print

# Actually prune
find .forge/parallel -maxdepth 1 -mindepth 1 -type d -mtime +30 -exec rm -rf {} +
```

**Future CLI hook (spec, not yet implemented):** `forge parallel clean [--older-than 30d] [--dry-run]` should walk `.forge/parallel/`, list run directories whose mtime is older than the cutoff, and (without `--dry-run`) `rm -rf` them. Default cutoff is `30d`. The subcommand belongs alongside `forge wiki *` in `src/cli.ts`. This is documented here rather than implemented inline to keep this change scoped — a follow-up work item can wire it up when there is demand. Until then, the `find` recipe above is the supported pattern.

## See also

- `skills/support-parallel/SKILL.md` — full process documentation
- `/feature`, `/bugfix`, `/refactor` — for command-shaped work that this skill refuses to swallow