# Use Pipeline Agents — Not Manual Work

**Always use the project's custom agents and skills for porting work. Never do their jobs manually or with generic agents.**

## Agent Dispatch Table

| Task | Agent / Skill | Never Do Instead |
|------|--------------|------------------|
| Check if port exists | `aminet-researcher` agent | Don't use general-purpose agent for Aminet searches |
| Check if a library is available on 68k | `aminet-researcher` agent, scope `dev/lib/` + `dev/c/` | Don't conclude "missing" from checking only the Docker image or a GitHub org — many classic libs (FreeType, SDL_ttf, SDL_mixer, etc.) live on Aminet only |
| Analyze source | `source-analyzer` agent or `/analyze-source` | Don't manually grep for POSIX calls |
| Transform source | `code-transformer` agent or `/transform-source` | Don't manually rewrite POSIX calls |
| Build for Amiga | `build-manager` agent or `/build-amiga` | Don't run compiler commands directly |
| Test via vamos | `test-runner` agent or `/test-amiga` | Don't run vamos manually |
| Full pipeline | `/port-project` | Don't run stages by hand |
| Audit dependencies | `dependency-auditor` agent | Don't manually check library deps |
| Amiga code review | `/review-amiga` | Don't skip the review step |
| Performance tuning | `perf-optimizer` agent | Don't hand-optimize 68k code |
| Publish to Aminet | `aminet-publisher` agent | Don't publish manually |
| Design test suites | `test-designer` agent | Don't manually write test-fsemu-cases.txt |
| Debug crashes | `debug-agent` agent or `/debug-amiga` | Don't manually debug Enforcer hits |
| Check memory safety | `memory-checker` agent | Don't skip memory audit — AmigaOS has no memory protection |
| Hardware validation | `hardware-expert` agent | Don't guess at hardware architecture facts |
| Add missing shim fn | `/extend-shim` | Don't manually add shim functions |
| Website operations | `site-manager` agent | Don't manually rsync or debug PHP |
| Publish to amiport site | `amiport-publisher` agent | Don't manually set package status or skip test gates |
| Visual test authoring | `visual-test-expert` agent | Don't manually write SCRAPE/SCREEN_READ tests |
| Regression detection | `regression-checker` agent | Don't manually rebuild all ports after shim changes |
| Catalog management | `catalog-engineer` agent | Don't manually score candidates or plan batches |
| SDL1/SDL2 game port or audit | `sdl-game-helper` agent | Don't try to perf-tune a game port with just `perf-optimizer` -- game bottlenecks live in render loops, frame limiters, and libstdc++ ABI traps that the general perf agent doesn't catch |

## How to Dispatch

Use the `Agent` tool with `subagent_type` set to the agent name from `.claude/agents/`:

```
subagent_type: "aminet-researcher"      # Stage 0: research
subagent_type: "dependency-auditor"     # Stage 0b: dep audit (conditional)
subagent_type: "source-analyzer"        # Stage 1: analyze
subagent_type: "code-transformer"       # Stage 3: transform
subagent_type: "hardware-expert"        # Stage 3b: hardware review (Cat 3+)
subagent_type: "build-manager"          # Stage 4: build
subagent_type: "test-designer"          # Stage 5b: test suite generation
subagent_type: "test-runner"            # Stage 5: vamos testing
subagent_type: "memory-checker"         # Stage 6b: memory safety (mandatory)
subagent_type: "perf-optimizer"         # Stage 6c: performance (mandatory)
subagent_type: "profiler"               # Stage 6d: empirical runtime measurement (optional)
subagent_type: "debug-agent"            # On crash: autonomous fix loop
# port-coordinator: DEPRECATED — cannot dispatch subagents from within an agent.
# For complex multi-file ports, orchestrate from main session dispatching each
# specialized agent directly (source-analyzer, code-transformer, build-manager, etc.)
subagent_type: "aminet-publisher"       # Publishing (never automatic)
subagent_type: "site-manager"           # Website deployment and testing
subagent_type: "visual-test-expert"    # Visual test authoring and debugging (ADR-024/025)
subagent_type: "amiport-publisher"      # Test-gated publishing to amiport site
subagent_type: "port-worker"            # Parallel batch: self-contained stages 0-4 in worktree
subagent_type: "regression-checker"     # After shim/lib changes: rebuild + test affected ports
subagent_type: "catalog-engineer"       # Catalog management: scoring, enumeration, batch planning
subagent_type: "sdl-game-helper"        # SDL1/SDL2 game ports: libSDL2 fast-path, bebbo-gcc 13.3 libstdc++ traps, FS-UAE CPU/FPU matrix
```

## Never Bypass a Running Agent

**If an agent is dispatched and running in the background, WAIT for it.** Do not:
- Write the output yourself because the agent is "taking too long"
- Dispatch a second agent to replace it without cancelling the first
- Do the agent's job inline while it runs in parallel

If an agent has not returned after 15 minutes, it may be stuck. In that case:
1. Note the timeout
2. Re-dispatch a NEW agent for the same task
3. Do NOT write the output manually

**Why:** Manual bypasses produce inferior output (test-designer agents analyze source for flags, exit codes, error paths — manual tests miss edge cases). The whole point of the pipeline is agent-quality output at every stage.

## Entry Point

For a **single port**, start with `/port-project` — it orchestrates the full pipeline (Stage 0 through Stage 7) and dispatches the right agents at each step.

For **multiple ports in parallel**, use `/batch-port-parallel` — it dispatches `port-worker` agents in isolated worktrees, then runs FS-UAE testing and reviews serially from the main session.