# Best Practices

> Competitor-informed patterns adopted from research across 4 open-source multi-agent pipelines (ralph-loop 116★, claude-pipeline 104★, atelier 13★, ai-first-framework).

## 1. Symlink Distribution (from ralph-loop)

**Problem**: Copying pipeline files on install duplicates ~10K tokens of content per session.
**Solution**: `--link` flag creates symlinks instead of copies. Updates propagate instantly.

```bash
npx @mmerterden/multi-agent-pipeline install --link
```

**Trade-off**: Requires the source package to remain installed. Best for development; use copy mode for production installs.

## 2. FIX_FIRST Pattern (from claude-pipeline)

**Rule**: When a bug or test failure is discovered during development, fix it immediately before continuing with the current task. Never defer fixes to "later".

Applied in Phase 3 (Development):

- If a test fails → fix the failing test before writing new code
- If lint errors appear → fix them before the next TDD cycle
- If a build breaks → stop and fix before proceeding

## 3. Wave-Based Parallel Execution (from atelier)

**Problem**: Running all explore agents in parallel can cause coverage overlap and wasted tokens.
**Solution**: Group parallel work into waves with clear boundaries.

Applied in Phase 1 (Analysis):

- **Wave 1**: 3 explore agents scan independent areas (architecture, security, CI/docs)
- **Wave 2**: Merge results, identify gaps, launch targeted follow-ups only if needed
- Never launch more than 5 parallel agents per wave

## 4. Roz-First TDD (from atelier)

**Rule**: Tests are written STRICTLY before implementation. No exceptions.

Applied in Phase 3:

1. RED - Write the failing test
2. Verify it fails for the RIGHT reason
3. GREEN - Write minimal code to pass
4. Verify ALL tests pass
5. REFACTOR - Clean up without changing behavior

## 5. Deterministic Quality Gates (from claude-pipeline)

**Rule**: Every phase transition must pass an explicit gate. No implicit transitions.

| Gate        | Condition                                  | Blocks   |
| ----------- | ------------------------------------------ | -------- |
| Phase 1 → 2 | Analysis complete, no unanswered questions | Planning |
| Phase 3 → 4 | Build passes, lint clean, tests green      | Review   |
| Phase 4 → 6 | All blocking findings resolved             | Commit   |
| Phase 6 → 7 | Push successful, PR created                | Report   |

## 6. 3-Iteration Hard Kill (original)

**Rule**: Any retry loop (build fix, test fix, API call) is killed after 3 attempts. The agent must escalate to the user instead of spinning.

```
Attempt 1 → fix → retry
Attempt 2 → different fix → retry
Attempt 3 → STOP → ask user for guidance
```

## 7. Layer-Based Memory (from ralph-loop)

**Problem**: Loading full project context at session start wastes tokens.
**Solution**: Lazy-load reference files only when the current phase needs them.

Applied via modular loading:

- **L0 (always)**: Main command routing (~300 tokens)
- **L1 (on demand)**: Phase definitions, rules (~2K tokens each)
- **L2 (rare)**: Platform guides, knowledge base (~5K tokens each)

This reduces wake-up tokens from ~19K to ~800.

## 8. Single Source of Truth (from ai-first)

**Rule**: Every configuration, rule, or standard exists in exactly ONE authoritative location. All other instances are derived via sync.

Applied via `multi-agent-sync`:

- Claude Code commands → source of truth
- Copilot CLI skills → derived (synced)
- Pipeline repo → derived (genericized, personal data scrubbed)
- Website → derived (version + feature counts)
- Remote Control → derived (pipeline references)