---
name: support-parallel
description: "Use when the user prompts a punch list of independent tasks (numbered or bulleted, ≥3 items) OR explicitly invokes /parallel. Classifies each task by type, assembles the right specialist team per task, dispatches all in parallel, aggregates results. Default is lightweight: one worker per low-risk task, no Codex pairing. Full-crew fanout (multi-worker teams + mandatory Codex) fires when the active manifest is in production mode, a task is high-risk (security, payments, schema), or the user invokes !max / --full-power. REFUSES command-shaped work — routes feature/bugfix/refactor items to their owning commands instead."
---

# Parallel

## Overview

Users don't always invoke `/feature` or `/bugfix`. The daily reality is a paste-in punch list: "do these 10 things: 1. update README; 2. explore option X; 3. add a test for Y; 4. ...". Doing those in series in one context window is slow, conflict-prone, and miscalibrates review depth — most items are low-risk and want one builder; a few are high-risk and want a full crew.

This skill assembles a **team per item**, sized to match the risk of that item and the run-mode of the parallel run as a whole. The default is light: one worker per task, no Codex pairing. The full crew (multi-worker teams + mandatory Codex pairing) fires only when there's a reason — production-mode manifest, high-risk task type, or explicit `!max`. The skill REFUSES to swallow command-shaped work; items that look like features/bugfixes/refactors get routed to their owning commands.

**Core principle:** default lightweight; opt into full crew. A 10-item list of low-risk chores in a prototype repo should fire ~10 agents, not 40. The full-crew capability is preserved for the cases that need it.

**Announce at start:** "I'm using support-parallel to dispatch N teams in parallel — M routed to commands, K running light, L running full-crew." If `!max` / `--full-power` detected: "...running in `!max` mode — full-crew enforced for every task."

## When to Use

Fire when **any** of:
- User types `/parallel` explicitly
- User prompt contains a numbered list (`1. xxx 2. xxx 3. xxx`) with ≥3 items
- User prompt contains a bulleted list (`- xxx / - xxx / - xxx`) with ≥3 items AND items look like work-tasks (not casual mentions)

Confirm with user before dispatching if auto-detected (one-line: "Detected a 5-item task list; dispatching teams — say 'no' to cancel").

Do NOT use for:
- A single task (use the appropriate command or skill directly)
- A list where every item is command-shaped (route to commands instead, don't even invoke this skill)
- Ad-hoc questions or conversation (this is for *do these things*, not *tell me about*)

## Process

### Step 0: Codex consent (per `protocols/codex.md`)

Codex consent is **conditional on run mode** (resolved in Step 1):
- **Light mode (default):** skip the consent flow entirely. Light tasks don't pair with Codex. Record `mode: skip` in `.forge/parallel/{run-id}/codex.yaml` for the audit trail.
- **Full-crew mode:** run the Codex consent flow ONCE for the whole parallel run. The choice (Verify / Takeover / Skip / Never) propagates to every per-task dispatch. Record in `.forge/parallel/{run-id}/codex.yaml`.

If individual high-risk tasks inside an otherwise-light run trigger per-task Codex pairing (per Step 1's high-risk-task escalation), the consent prompt fires at that point — not as a run-wide gate.

### Step 1: Resolve run mode (light vs full-crew)

This skill defaults to **light mode** (one worker per task, no Codex pairing). Full-crew mode fires only on an explicit signal. Resolve in this order — first match wins:

**1. Magic-keyword override** (`!max` / `--full-power`): forces **full-crew** unconditionally, regardless of manifest or task content. This is the explicit opt-in.

- Full-crew team templates for every task type (see Step 4 full-crew tables)
- Mandatory Codex consent (Verify mode) — no opt-out for the run
- No "light mode" shortcut even on quick / docs tasks
- Acknowledgement: "Running in `!max` mode — full-crew enforced for every task."

Use when:
- You're working in a prototype phase but the punch list touches code that WILL go to production
- You want maximum review coverage regardless of detection state
- You're auditing or hardening prototype code before promoting it
- You explicitly want the cost (more agents, more tokens) for the safety

**Detection rules for the override:**
- Match either form (whichever the user types):
  - **Short form:** `!max` (literal, case-insensitive — `!MAX`, `!Max` also accepted)
  - **Canonical form:** `--full-power` (literal, case-insensitive)
- Must be a whole word: bounded by whitespace, line start, or line end
- Do NOT match accidental variants: `max` alone (no bang), `!maximum`, `full power` (no dashes), `--fullpower`, `-full-power`
- Strict matching prevents false triggers from casual English
- Strip the keyword from each task's text before classification (it's a run-level flag, not part of any task)

**2. Active-manifest production mode**: full-crew for the whole run when the active work manifest indicates production. Glob `.forge/work/*/*/manifest.yaml` and pick the most recently modified; look at `phase_plan.{phase}` and `phases.{phase}.status`:

| Run mode | Triggered when |
|---|---|
| **full-crew (production)** | Both `phase_plan.codify: active` AND `phase_plan.production-build: active` (the codify-driven production flow, not just any feature manifest); OR `project.mode: production` in `.claude/CLAUDE.md`. |
| **light (default)** | Otherwise: no manifest, lightweight `/feature` (codify skipped — the new default per P2-2), manifest in prototype/iterate phases, `project.mode: prototype` or `greenfield`, or run-mode signal absent. |

The codify+production-build conjunction matters because the lightweight `/feature` default writes `production-build: active` with `codify: skipped` on every new manifest. Triggering full-crew on production-build alone would defeat the lightweight default for the most common workflow.

**3. Per-task high-risk escalation**: even in light mode, individual tasks classified as high-risk (Step 3) escalate to a full-crew team **for that task only**. The rest of the run stays light. High-risk = task type `security` OR a `dev`/`complex` task whose text mentions any of these keywords (deduplicated, case-insensitive substring match): auth, authentication, authorization, login, OAuth, SAML, JWT, session, password, credential, secret, secret rotation, payment, billing, refund, charge, PII, SSN, migration (any kind), schema migration, alter table, drop column, encryption key, RBAC, IAM, KMS, permission. The classifier's `risk:` field (Step 3 below) decides this.

**4. No-signal case**: if none of the above fires, run light. There is no "ambiguous → ask" prompt — light is the safe default and the user can re-run with `!max` if they wanted more.

Run mode determines team sizing in Step 4.

### Step 2: Parse the task list

Extract items from the prompt. Number them 1..N. For each item, record:
- raw text
- detected verbs (build, fix, explore, document, audit, refactor, deploy, ...)
- detected scope (file path, subsystem, "everywhere", ...)

If N > 20 (hard cap), refuse and ask user to batch. If N > 10 (soft cap), warn and offer to batch.

### Step 3: Classify each task — type and risk

For each task, record two fields:

**`type:`** apply this classifier in order — first match wins:

| Pattern | Classification |
|---|---|
| "add a (new) feature", "implement Y end-to-end", "build Z product" | **command-shaped: /feature** |
| "fix bug N", "investigate failure X" (single bug, multi-step) | **command-shaped: /bugfix** |
| "refactor module M", "restructure X" | **command-shaped: /refactor** |
| "start new project", "scaffold from scratch" | **command-shaped: /greenfield** |
| "hotfix production", "rollback X" | **command-shaped: /hotfix** |
| "audit security", "review for vulns", "check OWASP" | **security** (dispatch `quality-security-audit` skill) |
| "review this code/PR" (with diff scope) | **review** (dispatch `quality-code-review` skill) |
| "explore Y", "compare X vs Y", "find best approach for Z", "research Q" | **research** |
| "fix bug" (single-line, obvious) OR "find why X fails" (one trace) | **debug** |
| "write README", "document Y", "add comments to Z" | **docs** |
| "build feature slice" / "add function" / "implement X" (small, scoped) | **dev** |
| "fix typo", "bump dep", "rename variable" | **quick** |
| ≥4 subsystems touched OR ≥3 verbs combined | **complex** |
| Anything else | **ambiguous** (ask user) |

Command-shaped items get **routed out** — they do NOT get a team. Surface them to the user with: "Item X looks like a `/feature` — running it as a forge command instead. The remaining items continue as teams." User can override.

**`risk:`** apply after type:

| Risk tier | Triggered when |
|---|---|
| **high** | `type: security`; OR `type: dev / complex / review / debug` AND task text mentions any of: auth, authentication, login, OAuth, JWT, session, password, credential, payment, billing, refund, charge, PII, SSN, schema migration, alter table, drop column, encryption key, secret rotation |
| **low** | All other tasks (docs, quick, low-risk dev, single-trace debug, single-explorer research) |

High-risk tasks escalate to a full-crew team **for that task only**, regardless of run mode. Low-risk tasks follow the run-mode default (light by default, full-crew if the run is in full-crew mode per Step 1).

Record both fields in `.forge/parallel/{run-id}/tasks.yaml` for audit:

```yaml
- n: 3
  text: "Audit auth handler for OWASP top 10"
  type: security
  risk: high
  team: full-crew  # escalated even in light run-mode
```

### Step 4: Assemble team per task

A task's team is picked by **(run mode, task type)** — except that high-risk tasks (Step 3) always escalate to the full-crew row regardless of run mode.

#### Light mode (default — one worker, no Codex)

| Task type | Team |
|---|---|
| dev | 1 × `prototype-builder` (if a `pocs/*` host exists) OR `builder` — no Codex |
| research | 1 explorer (`architect` OR `tracer` OR `doc-writer`, picked by scope) — no Codex |
| debug | dispatch `support-debug` skill (owns its own chain) — no extra Codex |
| docs | 1 × `doc-writer` — no Codex |
| review | dispatch `quality-code-review` (it picks risk-tier; low-risk review work is the Low tier) |
| security | **escalates to full-crew** (security tasks are always high-risk) |
| quick | 1 agent inline (no dispatch, no Codex) |
| complex | warn user "complex task in light mode; consider `/feature` or rerun with `!max`" — if they continue, escalate this single task to the full-crew row |

#### Full-crew mode (production manifest, high-risk task, or `!max`)

| Task type | Team |
|---|---|
| dev | `builder` + dispatch `quality-code-review` skill + Codex (per consent) |
| research | 2-3 explorers from `architect`, `tracer`, `doc-writer`, `spec-reviewer` (pick by scope) + Codex |
| debug | dispatch `support-debug` skill + `gotcha-hunter` after tracer locks scope + Codex |
| docs | `doc-writer` + Codex verify |
| review | dispatch `quality-code-review` (full chain) + Codex adversarial |
| security | dispatch `quality-security-audit` + `security-reviewer` + Codex adversarial |
| quick | 1 agent + Codex verify (full-crew is no-shortcuts even for one-liners that touch shipped code) |
| complex | full crew: `architect` + `tracer` + `builder` + dispatch `quality-code-review` + `spec-reviewer` + `security-reviewer` (if risk triggers) + `e2e-runner` (if E2E plan exists) + Codex adversarial |

**Mixed-risk run:** if the run mode is light but one item is high-risk (e.g. a 5-item list where item 3 is "audit auth handler"), only item 3 escalates to its full-crew row. Items 1, 2, 4, 5 stay light. The skill's Codex consent prompt fires when the first high-risk task appears — its consent choice applies to all escalated tasks in the run.

### Step 5: Dispatch all teams in parallel

For each non-routed task:
1. Compose the prompt: include the task text, the detected type + risk, run mode, the team composition.
2. Fire each agent in the team as a background subagent (`run_in_background: true`).
3. For tasks whose team includes "dispatch X skill", spawn ONE agent that invokes that skill (the skill handles its own internal multi-agent chain).
4. Tag each agent with `parallel/{run-id}/{task-n}/{role}` for telemetry.

Batched dispatch ceiling: 20-25 agents per `<function_calls>` block. For 10 tasks × 4 agents = 40 agents, plan 2 dispatch rounds.

### Step 6: Accumulate

Background notifications arrive asynchronously:
- Save each agent's result to `.forge/parallel/{run-id}/task-{n}/{role}.md`
- Maintain a per-task status line: `Task 3 of 10: 2 of 3 agents complete (1 pending)`
- DO NOT narrate every individual agent completion to the user — batch updates every ≥3 returns

### Step 7: Per-task verdict

When all agents for a task return, synthesize:
- If Claude builder + Codex sibling agree → mark task `complete-consensus`
- If they disagree → mark `complete-divergent`, surface the disagreement
- If only one returned (other failed/timeout) → mark `complete-single-source`, flag for user attention
- If both failed → mark `failed`, recommend retry or single-task fallback

Per-task output goes to `.forge/parallel/{run-id}/task-{n}/verdict.md`.

### Step 8: Run summary

After all tasks finish (or hit batch limit), produce one consolidated report:

```
Parallel Run {run-id} — {N} tasks, {M} routed to commands

| # | Task | Type | Team size | Status | Conflicts |
|---|------|------|-----------|--------|-----------|
| 1 | update README | docs | 1 | consensus | — |
| 2 | explore option X | research | 3 | consensus | — |
| 3 | implement Y | dev | 2 | divergent | Claude says ship, Codex says blocking |
| ... | ... | ... | ... | ... | ... |

Routed to commands:
- Item 4 (add payment feature) → /feature
- Item 7 (fix critical bug) → /bugfix

Followups:
- Resolve divergence on task 3 (recommend manual review)
- Run /feature for item 4 when ready
```

Write the summary to `.forge/parallel/{run-id}/run-summary.md` and surface to user.

### Step 9: Stop

This skill does ONE run per invocation. If the user wants to iterate on findings, they invoke the appropriate command or this skill again with a new list.

## I/O Contract

| Field | Value |
|---|---|
| Requires | A user-provided task list (parsed in Step 2); optionally an active manifest for phase detection |
| Produces | `.forge/parallel/{run-id}/codex.yaml`, `.forge/parallel/{run-id}/tasks.yaml` (classification), `.forge/parallel/{run-id}/task-{n}/{role}.md` per agent, `.forge/parallel/{run-id}/task-{n}/verdict.md` per task, `.forge/parallel/{run-id}/run-summary.md` |
| Updates manifest | If a feature/bugfix manifest is active, append `phases.{phase}.parallel-runs: [{run-id}]`. Otherwise no manifest update — parallel runs are not phase-gated. |
| Feeds into | `/feature`, `/bugfix`, `/refactor` (for routed items); `support-gotcha` (for recurring patterns surfaced across tasks) |

## Agent Dispatch

This skill is itself a dispatcher. It does NOT have a single subagent type — it picks per task per phase from the table in Step 4.

| Helper skill it dispatches | When |
|---|---|
| `quality-code-review` | Every dev/review task in full-crew mode (skill owns its own agent chain) |
| `support-debug` | Every debug task (skill owns tracer + gotcha-hunter chain) |
| `quality-security-audit` | Every security task |
| `deliver-onboarding` | Every docs task that's onboarding-scoped |

Raw agents it dispatches directly:
- `prototype-builder` (prototype dev)
- `builder` (production dev, when not going through quality-code-review)
- `architect`, `tracer`, `doc-writer`, `spec-reviewer`, `security-reviewer` (research/explore)
- `e2e-runner` (complex tasks with E2E plan)
- Codex sibling (via `codex:codex-rescue` subagent type or protocol invocation)

## Integration

| Step | Skill / Command | Why |
|---|---|---|
| Pre-dispatch consent | `protocols/codex.md` | Codex pairing requires consent ONCE per run |
| Task routing-out | `/feature`, `/bugfix`, `/refactor`, `/greenfield`, `/hotfix` | Command-shaped items must use commands, not teams |
| Per-task dev | `quality-code-review` skill | Production dev tasks get the full review chain |
| Per-task debug | `support-debug` skill | Debug tasks get tracer + gotcha-hunter |
| Per-task security | `quality-security-audit` skill | Security tasks get the OWASP-aware audit chain |
| Post-run gotcha | `support-gotcha` | Patterns surfaced across multiple teams deserve a recorded lesson |

## Cleanup

`.forge/parallel/{run-id}/` directories accumulate one per run. Retention spec: **30 days**, then eligible for prune.

**Manual prune (works today):**

```bash
# Dry run — list 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 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`. Deferred to a follow-up work item; the `find` recipe is the supported pattern until it lands.

**Consolidation before prune (optional):** before pruning, `support-dream` can summarize the per-run findings into an aiwiki entry so the lessons survive. Today this is opt-in — run `support-dream` manually with `scope: .forge/parallel/` before invoking the prune command if you want a retrospective.

## Red Flags

| Red Flag | What it means |
|---|---|
| Every task gets the same team | Classifier is failing; user-pasted heterogeneous tasks don't all become "dev" |
| Routed-to-command items >50% | User typed a feature description, not a punch list — recommend dropping this skill entirely and using `/feature` |
| Codex consent skipped silently in full-crew mode | Means no second-opinion across the whole run — for full-crew this is a regression |
| 0 conflicts across all tasks (full-crew) | Either every task was trivial OR Claude+Codex are echoing each other; sample-check |
| Light mode running a high-risk task without escalating | Step 3's `risk:` classifier is failing — the task should have triggered per-task full-crew |
| Complex tasks in light mode | User pasted /feature-shaped work into a punch list; warn before proceeding |
| `.forge/parallel/` never pruned | Cleanup section above documents the 30-day prune; run periodically |
| Soft cap warning ignored repeatedly | User has misframed work — recommend splitting into milestones |

## Anti-Patterns

**Swallowing command-shaped work.** If the user types "add a payment feature, then audit security, then ship", DO NOT dispatch a parallel run — that's three workflows pretending to be three tasks. Route them: `/feature` → `quality-security-audit` → `/feature` deploy phase. `/parallel` is for items that DON'T fit a workflow.

**Heavyweight default.** Spawning a full crew on every task wastes tokens. Most punch lists are heterogeneous-but-low-risk — read run mode AND per-task risk before sizing.

**Skipping Codex on high-risk or production tasks.** "Quick" is not an excuse when the task touches auth, payments, schema, or shipped production code. An adversarial second opinion finds wiring mistakes, mismatched limits, and authorization holes that a single reviewer misses — that's the whole reason high-risk tasks escalate.

**Ignoring divergent verdicts.** Claude+Codex disagreement (in full-crew mode) is a SIGNAL, not noise. Surface it. Let the user adjudicate.

**Letting `.forge/parallel/` grow forever.** Each run leaves a directory; the 30-day prune in the Cleanup section handles it. Document a maintenance cadence in the project's onboarding doc.

**Auto-dispatching without confirmation when auto-detected.** Numbered lists in user prose aren't always task lists (could be a survey of options, a sequence diagram, etc.). Confirm before firing N agents.

## References

- `references/dispatch-pattern.md` — bash recipes, prompt templates, sizing guidance
- `references/synthesis-template.md` — per-task verdict + run-summary structures
- `agents/critic.md` — voice calibration for research/review cells
- `protocols/codex.md` — Codex consent flow
- This skill is for daily ad-hoc punch lists — paste-in lists of independent tasks that benefit from per-task specialist teams running in parallel, with command-shaped items routed out to their owning commands.