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:
- Note the timeout
- Re-dispatch a NEW agent for the same task
- 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.