---
id: hatch3r-agent-orchestration
type: rule
description: Mandatory agent delegation, skill loading, and subagent usage directives for ALL tasks in ALL contexts
scope: always
tags: [orchestration, floor:protocol]
precedence: high
quality_charter: agents/shared/quality-charter.md
cache_friendly: true
---
# Agent Orchestration

This rule governs when and how to delegate work to hatch3r agents, load skills, and spawn subagents. These directives are mandatory — not suggestions. For extended reference on pipeline context schemas, resilience/failure handling, and observability, see `hatch3r-agent-orchestration-detail`.

## Orchestration Differentiation

Hatch3r's orchestration uses a **phase-gated pipeline** (Research, Implement, Review, Quality) with **structured handoffs** via `PipelineContext` and a **mandatory review gate** before the quality phase. This is not free-form agent chat.

## Universal Applicability

This rule applies to EVERY context without exception: board-pickup (epic, sub-issue, standalone, batch), workflow command (full/quick), plain chat, issue references, and natural language requests. The full sub-agent pipeline is mandatory — never implement code inline without sub-agents.

**"Inline implementation" defined.** Inline implementation means calling any code-writing tool — `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform equivalent — from the orchestrator turn itself, rather than from inside a spawned `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) sub-agent. The only carve-out is `hatch3r-quick-change` for Tier 1 single-line trivial edits per its declared scope.

## Universal Sub-Agent Pipeline

Every task MUST follow this four-phase pipeline: **Phase 1 — Research** (`hatch3r-researcher`), **Phase 2 — Implement** (`hatch3r-implementer`), **Phase 3 — Review Loop** (`hatch3r-reviewer` + `hatch3r-fixer`), **Phase 4 — Final Quality** (parallel specialists). See Mandatory Delegation Directives below.

## Agent Roster

| Agent | Purpose | Invoke When |
|-------|---------|-------------|
| `hatch3r-researcher` | Context gathering (15 modes) | Always — before implementation (skip trivial edits) |
| `hatch3r-implementer` | Single-task implementation | Always — one per task |
| `hatch3r-reviewer` | Code review | Always — Phase 3 review loop |
| `hatch3r-fixer` | Fix reviewer findings | Phase 3 — Critical/Warning findings |
| `hatch3r-test-writer` | Tests | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
| `hatch3r-security-auditor` | Security review | Always — Phase 4 (every code change; skip per Phase Skip Criteria) |
| `hatch3r-docs-writer` | Documentation | Phase 4 — evaluate when APIs/architecture/UX affected |
| `hatch3r-lint-fixer` | Lint/type fixes | Conditional — lint errors present |
| `hatch3r-a11y-auditor` | WCAG AA checks | Conditional — UI/accessibility changes |
| `hatch3r-perf-profiler` | Performance profiling | Conditional — performance-sensitive changes |
| `hatch3r-dependency-auditor` | CVE/supply chain | Conditional — dependencies change |
| `hatch3r-ci-watcher` | CI failure diagnosis | Conditional — CI fails |
| `hatch3r-architect` | Architecture design | Conditional — architectural decisions needed |
| `hatch3r-devops` | CI/CD and deployment | Conditional — infrastructure tasks |

## Deep Context Integration

Score task complexity per the `hatch3r-deep-context` rule before Phase 1. Apply the resulting tier:

- **Tier 2 hard gate (B1).** Before Phase 2, run `hatch3r-researcher` with `requirements-elicitation:quick` mode to detect ambiguity and ask the user via the platform-native question tool (per `agents/shared/user-question-protocol.md`). Orchestrator awaits answers and integrates them into the Phase 1 brief; do not begin Phase 2 with unresolved questions. Tier 1 is exempt only when scope is single-file, single-concern, and acceptance is testable from the user message alone.
- **Tier 3 (Deep):** Present Pre-Implementation Summary and ASK for confirmation. Do NOT proceed until all unresolved questions are answered.

## Mandatory Delegation Directives

### Context Gathering (Before Implementation)

Spawn `hatch3r-researcher` before implementing any task. Skip only for trivial single-line edits. Select modes by task type, then add tier-appropriate modes per Deep Context Integration:

- **`type:bug`**: `symptom-trace`, `root-cause`, `codebase-impact` + tier modes
- **`type:feature`**: `codebase-impact`, `feature-design`, `architecture` + tier modes
- **`type:refactor`**: `current-state`, `refactoring-strategy`, `migration-path` + tier modes
- **`type:qa`**: `codebase-impact` + tier modes

Use depth `quick` for low-risk, `standard` for medium-risk, `deep` for high-risk. Tier 3 always uses `deep` depth.

### Research Completeness Checklist

Before Phase 1 to Phase 2 handoff, verify:

- [ ] **All affected files identified** — files to be created, modified, or deleted are listed.
- [ ] **Blast radius assessed** — downstream consumers and integration points documented.
- [ ] **Existing tests located** — test files covering affected code identified (or absence noted).
- [ ] **Dependencies mapped** — internal and external dependencies enumerated.

If any item is unconfirmed, re-run researcher with additional modes or surface to user.

### Implementation Delegation

Spawn `hatch3r-implementer` via Task tool for ALL code changes. Never implement inline.

- **Single issue**: One implementer. Orchestrator owns git/PR/board.
- **Plain chat task**: One implementer. Create synthetic issue context first.
- **Epics**: One implementer per sub-issue, level-by-level respecting dependency order.
- **Batch**: Group by dependency level, one implementer per issue, shared branch + combined PR.

**Implementer prompt enrichment (Tier 2+):** Include `similar-implementation` findings as "Reference Conventions", resolved `requirements-elicitation` answers as "Resolved Requirements", and blast radius data (Tier 3 only).

### Per-Turn Pipeline-State Header

Whenever a tracked task is active at Tier 2 or Tier 3 (deep-context score >= 3), the orchestrator MUST emit a single-line pipeline-state header at the very start of every assistant turn that touches the task. Format:

```
[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
```

Examples:

- `[hatch3r-pipeline: phase 1 | last: n/a | next: hatch3r-researcher]`
- `[hatch3r-pipeline: phase 2 | last: hatch3r-researcher → SUCCESS | next: hatch3r-implementer]`
- `[hatch3r-pipeline: phase 3 | last: hatch3r-reviewer → PARTIAL | next: hatch3r-fixer]`
- `[hatch3r-pipeline: phase 3 | last: hatch3r-implementer → SUCCESS | next: user-confirmation]`

A missing header on a tracked Tier >= 2 task is a self-detectable drift signal — the user may halt the turn and request re-grounding. The header also functions as a per-reply cache prime: rendering it forces the orchestrator to re-resolve which phase it is in before choosing tools. Tier 1 tasks, read-only answers, and chat-only iterations do NOT require the header.

### End-of-Turn Delegation Attestation

When the turn is on a tracked task at Tier >= 2 AND caused at least one file mutation, the orchestrator MUST emit a closing block immediately before the Iteration Summary. The block enumerates every file mutated this turn, the spawning sub-agent invocation, and the `delegation_proof_id` returned by that sub-agent.

Format:

```
[hatch3r-delegation-attestation]
files_mutated_this_turn:
  - <relative path>: via <agent-name> (proof: <delegation_proof_id>)
mutating_subagent_invocations: <integer>
inline_edits_by_orchestrator: none | <carve-out: hatch3r-quick-change Tier-1 + queued re-delegation>
```

Rules:

- Each `files_mutated_this_turn` row MUST cite the spawning sub-agent invocation and quote the `delegation_proof_id` returned by that sub-agent verbatim. Unattributable rows are self-declared P8 B2 violations and the orchestrator MUST queue re-delegation in the next turn.
- `inline_edits_by_orchestrator: none` is the only acceptable value outside the `hatch3r-quick-change` Tier-1 carve-out declared in the "Inline implementation" definition above.
- Tier 1 read-only and chat-only turns are exempt — same scope as the Per-Turn Pipeline-State Header.
- Missing block on a Tier >= 2 mutating turn is a self-detectable drift signal — the user may halt the turn and re-ground per the same protocol as the missing-header signal.
- The block is consumed by reviewers and the next orchestrator turn; it sits beside the Iteration Summary, not inside it, preserving the existing 5-field iteration-summary contract verbatim.

### Mandatory Delegation Directive (No Inline Implementation)

Restating with maximum clarity for sub-agent prompt inclusion: the orchestrator MUST NOT call `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `replace_string_in_file`, `multi_replace_string_in_file`, `create_file`, `str_replace_based_edit_tool`, `apply_patch`, or any platform-equivalent code-writing tool from its own turn. The only path for code mutation is the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3). Carve-out: `hatch3r-quick-change` Tier 1 trivial items per its declared scope. No other carve-out exists. Violations are bypass mode (see issue #73) — surface them by halting the turn and re-delegating.

### Mid-Implementation Research Gap Checkpoint

At the midpoint of Phase 2 (after initial files are modified but before completion), the implementer MUST evaluate whether research gaps exist. This prevents discovering missing context too late in the pipeline.

**Checkpoint triggers:**
1. Implementation requires modifying a file not listed in `researchFindings.affectedFiles`.
2. An undocumented dependency or integration point is discovered.
3. The implementer's confidence drops below "medium" for any sub-task.
4. A test file expected from research does not exist or covers different behavior.

**Actions when gaps are detected:**
- Log the gap in `PipelineContext.researchGaps`.
- If the gap is blocking (cannot proceed without the missing context): pause implementation, surface the gap to the orchestrator, and request a targeted re-run of `hatch3r-researcher` with the specific modes needed.
- If the gap is non-blocking (can proceed with assumptions): document the assumption, continue implementation, and flag for reviewer attention in Phase 3.

### Per-Task Mini-Review

For multi-sub-task implementations, the implementer performs a lightweight mini-review after each sub-task: verify correctness, check interface contracts, validate no regressions, gate progression. Mini-reviews are internal (no separate reviewer agent).

### Post-Implementation Quality Pipeline

**Phase 3 — Review Loop:**

1. Spawn `hatch3r-reviewer` with diff and acceptance criteria. Reviewer includes blast radius summary.
2. Critical/Warning findings: spawn `hatch3r-fixer` with full reviewer output.
3. Re-review after fixes. Repeat until 0 Critical + 0 Warning, or max 4 iterations (matches `DEFAULT_MAX_REVIEW_ITERATIONS` in `src/pipeline/reviewLoop.ts`; raised from 3 to 4 in Cycle 7.5 W2B2 finding H26 so the oscillation detector becomes reachable in default config). The rule default and the code constant are kept in sync by `src/__tests__/pipeline/reviewLoop.test.ts` (CI-enforced).
4. **Confirmation pass** after clean review: lightweight re-review for fix-driven regressions and acceptance criteria completeness. The confirmation pass checks only: (a) no new test failures compared to Phase 2 baseline, (b) no type errors introduced, (c) acceptance criteria from the issue are still met. It does not re-run the full review checklist.
5. Max iterations reached: surface to user with a structured summary: iteration count, remaining Critical findings (with file:line), remaining Warning findings, and a recommendation (fix manually vs. accept risk). Never present raw reviewer output without summarization.
6. **Review gate confidence signal:** When the review loop exits with a clean verdict, record the iteration count in `PipelineContext.reviewResult.iterations`. Clean-on-first-pass (iteration 1) signals higher confidence than clean-after-multiple-iterations (iteration 2-3). Phase 4 specialists and the orchestrator should factor this into their risk assessment.

**Phase 4 — Final Quality** (after review loop is clean):

Launch Phase 4 specialists in parallel, bounded by `max_phase4_parallel` (default `3`, override via `HATCH3R_MAX_PHASE4_PARALLEL` env var; valid range 1-16, values outside the range fall back to default with a logged warning). The bound exists to cap per-orchestrator concurrent context cost — it does not soften the P8 B2 directive that fan-out scales with task decomposition. When the number of applicable specialists exceeds `max_phase4_parallel`, batch them by severity-descending priority: `CRITICAL → HIGH → MEDIUM → LOW` (severity is the worst-case finding class the specialist is expected to surface, per the `hatch3r-test-writer` / `hatch3r-security-auditor` always-on baseline → CRITICAL, conditional UI/security/perf → HIGH, docs/lint → MEDIUM, low-impact specialists → LOW). Within the same severity bucket, dispatch order is the trigger-table order in the table above. Each batch runs to completion (all specialists return SUCCESS/PARTIAL/FAILED) before the next batch starts; the validation pass below runs once after the final batch.

- **Always** (except when Phase Skip Criteria applies — see below)**:** `hatch3r-test-writer`, `hatch3r-security-auditor`
- **Evaluate:** `hatch3r-docs-writer` (when APIs/architecture/UX affected)
- **Conditional:** `hatch3r-lint-fixer`, `hatch3r-a11y-auditor`, `hatch3r-perf-profiler`, `hatch3r-dependency-auditor`, `hatch3r-architect`, `hatch3r-devops`

**Specialist Prompt Enrichment:** When spawning Phase 4 specialists, include:
- The `filesChanged` list from Phase 2 so specialists focus on affected code.
- The review verdict summary from Phase 3 so specialists do not re-flag already-reviewed issues.
- The `researchFindings.blastRadius` so specialists can assess downstream impact of their changes.

**Phase 4 Specialist Trigger Table:**

| Specialist | Mode | Trigger Conditions |
|-----------|------|--------------------|
| `hatch3r-test-writer` | Always | Any code change; may skip per Phase Skip Criteria |
| `hatch3r-security-auditor` | Always | Any code change; may skip per Phase Skip Criteria |
| `hatch3r-docs-writer` | Evaluate | Public API, architecture, or UX changes |
| `hatch3r-lint-fixer` | Conditional | Lint/type errors present |
| `hatch3r-a11y-auditor` | Conditional | UI/accessibility changes |
| `hatch3r-perf-profiler` | Conditional | Performance-sensitive changes |
| `hatch3r-dependency-auditor` | Conditional | Dependency files modified (package.json, go.mod, Cargo.toml, requirements.txt, Gemfile, pom.xml, pubspec.yaml, mix.exs, composer.json, and their lockfiles) |
| `hatch3r-architect` | Conditional | Architectural decisions, new modules/services |
| `hatch3r-devops` | Conditional | CI/CD or infrastructure changes |

**Project-Type-Aware Specialist Selection:**

When `PipelineContext.projectType` is available (populated from repo analysis), use the detected languages and frameworks to enrich specialist prompts with language-specific hints. For example:
- **TypeScript/JavaScript:** Include strict mode checks for lint-fixer, framework-specific test patterns for test-writer.
- **Python:** Include ruff/mypy hints for lint-fixer, pytest patterns for test-writer, SSTI/SQLi checks for security-auditor.
- **Go:** Include golangci-lint for lint-fixer, govulncheck for security-auditor, table-driven test patterns for test-writer.
- **Rust:** Include clippy lints for lint-fixer, cargo-audit for security-auditor.

See `src/pipeline/pipelineContext.ts` for the full `LANGUAGE_SPECIALIST_CONFIGS` mapping.

### Phase 4 Validation Pass

After all Phase 4 specialists complete, run a validation pass to catch regressions:

1. Run test suite and type checker. Compare against Phase 3 baseline cached in `PipelineContext`.
2. No new failures: proceed to completion.
3. New failures: identify causing specialist, spawn `hatch3r-fixer`, re-validate (max 2 iterations).
4. Persistent regressions: surface to user. Do not silently accept.
5. If any specialist produced code fixes (not just findings), spawn a lightweight `hatch3r-reviewer` re-review scoped to files modified by Phase 4 specialists. This prevents specialist fixes from bypassing the Phase 3 review gate. Max 1 re-review iteration; Critical findings trigger a single fixer pass.

### Specialist Success Criteria

| Specialist | Success Criterion |
|-----------|-------------------|
| `hatch3r-test-writer` | All new/modified code paths have tests; no untested branches in changed files. |
| `hatch3r-security-auditor` | No HIGH/CRITICAL findings unresolved; MEDIUM findings documented with plan. |
| `hatch3r-docs-writer` | Affected APIs, architecture, and UX changes reflected in docs. |
| `hatch3r-lint-fixer` | Zero lint/type errors in changed files. |
| `hatch3r-a11y-auditor` | WCAG AA compliance; no new a11y violations. |
| `hatch3r-perf-profiler` | No performance regressions; new hot paths benchmarked. |
| `hatch3r-dependency-auditor` | No known CVEs; license compatibility verified. |
| `hatch3r-architect` | ADRs documented; design aligns with patterns or divergence justified. |
| `hatch3r-devops` | CI/CD passes end-to-end; deployment config validated. |

## Skill Loading Directives

Load the matching skill before implementation:

| Task Type | Skill |
|-----------|-------|
| `type:bug` | `hatch3r-bug-fix` |
| `type:feature` | `hatch3r-feature` |
| `type:refactor` + `area:ui` | `hatch3r-visual-refactor` |
| `type:refactor` + behavior change | `hatch3r-logical-refactor` |
| `type:refactor` (other) | `hatch3r-refactor` |
| `type:qa` | `hatch3r-qa-validation` |

Skill-referenced agent delegations are mandatory.

## Subagent Spawning Protocol

1. Use `subagent_type: "generalPurpose"` for all delegations.
2. Include: agent protocol, applicable `scope: always` rules, tooling hierarchy, relevant learnings.
3. Launch independent subagents in parallel — maximum parallelism.
4. Await and review results. Surface BLOCKED or PARTIAL to user.

## Parallel Safety

This section documents when spawning multiple sub-agents concurrently is safe and when it must remain sequential.

### Design Rationale

The pipeline's default is **linear per task** — Phase 1 → Phase 2 → Phase 3 → Phase 4, serially. `PipelineContext` captures a single logical handoff token that flows through sub-agents in sequence. LLM-driven orchestrators reason better with sequential, linearly-ordered context. Within Phase 4, parallel specialists are safe because they operate on read-only artifacts. Extending parallelism to Phases 1-3 requires explicit conditions.

### Parallel-Safe Operations

1. **Phase 4 Specialists** — test-writer, security-auditor, docs-writer, lint-fixer, etc. Read-only input from Phase 3 completion; independent outputs; no shared state mutation.
2. **Intra-Phase-1 Researcher Modes** — multiple modes on the SAME task (symptom-trace + root-cause + codebase-impact) when the task is self-contained. Operate on read-only codebase; produce independent findings.
3. **Per-Module Phase 2 Fan-Out (Disjoint `affectedFiles`)** — multi-module tasks with non-overlapping file sets; each implementer commits independently; merged post-Phase-2.
4. **Tier 2/3 Elicitation Researchers** — parallel researchers on the same task to surface different perspectives; outputs tagged with confidence + perspective; orchestrator aggregates.

### NOT Parallel-Safe

1. **Cross-Phase Execution** — Phase 1 must complete before Phase 2 (Phase 2 depends on researchFindings). Phase 2 must complete before Phase 3 (review needs diff). Phase 3 must complete before Phase 4 (quality checks assume review-clean state).
2. **Phase 3 Review Loop Iterations** — reviewer → fixer → re-reviewer must be serial.
3. **Overlapping-File Implementers** — two Phase 2 implementers touching the same file must execute serially or use a merge-conflict detection gate.
4. **Shared `PipelineContext` Field Writers** — if multiple agents mutate `state` / `featureFlags` / `metadata`, serialize them. Parallel agents must only READ context.
5. **Phase 4 Validation Re-Review** — the confirmation pass after Phase 4 specialists must run serially; it checks fix-driven regressions.

### Three Conditions to Parallelize

ALL three must hold:

1. **Read-only or disjoint writes** — agents read-only from context OR write to disjoint files/fields (no conflict zone).
2. **Deterministic aggregation** — outputs merge without orchestrator intervention (tests: pass if all pass; findings: union).
3. **Overhead < savings** — coordination cost (merge, conflict detection) is less than latency savings (max-of-agents vs sum-of-agents).

**Default:** When in doubt, serialize. For typical hatch3r tasks (1–5 sub-tasks) the DAG-scheduling overhead often outweighs concurrency gain.

### Cost-Dominance Principle

Token cost of sub-agent invocation never justifies serialization of independent work. The three safety conditions (read-only or disjoint writes, deterministic aggregation, no shared mutable state) govern WHEN parallelism is safe; cost does not govern WHETHER to parallelize. When in doubt, fan out. Serialization is only valid on true dependency edges.

### Scaling Heuristic

Sub-agent count tracks task decomposition: N independent modules → N parallel Phase-2 implementers; M specialist gates → M parallel Phase-4 specialists; K independent research questions → K parallel researcher modes. Orchestrators emit `sub_agents_spawned: {count, rationale}` in their structured output.

## Cross-Phase Error Propagation

When a phase produces a non-SUCCESS status, the orchestrator must propagate error context to downstream phases rather than silently dropping it:

1. **Phase 1 PARTIAL** (incomplete research): Include the `researchGaps` list in the implementer prompt so the implementer knows which areas lack verified context. Set implementer confidence expectations accordingly.
2. **Phase 2 PARTIAL** (incomplete implementation): Include the `reason` field and list of unimplemented acceptance criteria in the reviewer prompt. The reviewer must distinguish between "not done yet" and "done incorrectly."
3. **Phase 3 UNRESOLVED** (review loop exhausted): Include the unresolved findings list in the Phase 4 specialist prompts. Specialists must not introduce changes that conflict with known unresolved issues.
4. **Phase 4 specialist FAILED**: Include the failure reason when surfacing to the user. Never report "Phase 4 failed" without specifying which specialist failed and why.

## Correlation ID

Generate a UUID v4 per top-level task before Phase 1. Include in every subagent prompt as `correlation_id`. All subagents include it in logs, outputs, and status reports. Epic sub-issues get individual IDs; batch tasks share one ID with a sub-task index.

## Severity Scale

| Severity | Definition | Pipeline Action |
|----------|-----------|-----------------|
| **CRITICAL** | Blocks merge. Security vulnerabilities, data loss, broken core functionality. | Must resolve before Phase 3 exit. |
| **HIGH** | Should fix before merge. Significant bugs, performance regressions. | Fix or escalate to user. |
| **MEDIUM** | Fix in same sprint. Code quality, minor bugs. | Document with remediation plan. |
| **LOW** | Track for future. Style nits, minor improvements. | Log only. No merge gate. |
| **INFO** | Informational. Observations, suggestions. | Awareness only. |

All subagents MUST map findings to this scale.

## Status Codes

| Status | Meaning |
|--------|---------|
| **SUCCESS** | Fully completed, all criteria met. |
| **PARTIAL** | Partially completed; include `reason` field. |
| **FAILED** | No usable output; include `reason` field. |
| **SKIPPED** | Intentionally not executed. |
| **TIMEOUT** | Time budget exceeded; forward partial output. |

## Phase Skip Criteria

Consistent criteria for when each pipeline phase can be safely skipped. All commands that use the pipeline MUST reference these criteria — do not invent command-specific skip rules.

| Phase | Can Skip When | Mandatory Minimum (even when skipped) |
|-------|--------------|--------------------------------------|
| **Phase 1 (Research)** | Trivial single-line edit (typo, comment, single-value config); Tier 1 single-file change with no cross-module impact; Research already cached in PipelineContext | Affected files identified (even via quick scan); existing tests noted |
| **Phase 2 (Implement)** | Never — implementation is always required for code changes | All changes via hatch3r-implementer (never inline except trivial items in quick-change) |
| **Phase 3 (Review)** | All items trivial (quick-change only); documentation-only change with no code | Quality checks (lint/typecheck/test) must pass; acceptance criteria verified |
| **Phase 4 (Quality)** | Review loop unresolved AND user chose manual resolution; documentation-only; all trivial + quality checks pass (quick-change only) | test-writer + security-auditor always required for code changes; quality checks must pass |

See `src/pipeline/pipelineContext.ts` for the programmatic `PHASE_SKIP_CRITERIA` constant.

## Root-Cause Depth Requirements

When a pipeline phase reports a failure or unexpected result, the orchestrator must perform root-cause classification before deciding the next action:

| Symptom | Shallow Fix (avoid) | Root-Cause Fix (required) |
|---------|---------------------|---------------------------|
| Test failure after Phase 2 | Disable or skip the failing test | Identify why the implementation breaks the test -- fix the code or update the test with justification |
| Lint errors after Phase 4 | Add `eslint-disable` comments | Fix the underlying code pattern that triggers the lint rule |
| Type errors after fixer changes | Cast with `as any` | Trace the type mismatch to its source and fix the type definition or usage |
| Review loop not converging | Surface to user after 3 iterations without analysis | Classify whether findings are oscillating (fixer A breaks what fixer B fixed) and surface the conflict pattern |

The orchestrator must reject superficial fixes from any subagent. If a fixer's output contains suppression patterns (disable comments, `any` casts, test skips without linked issues), classify as PARTIAL and re-run with an adjusted prompt that requests a root-cause fix.

## Task Context Protocols

**Single-task plain chat:** Classify task type, create synthetic issue context, run full pipeline. For issue references, fetch details via platform CLI.

**Multi-task plain chat:** Parse into discrete tasks, classify each, build dependency graph, parallelize researchers and implementers per dependency level, run review loop after all implementations, then Phase 4 specialists. When parallel implementers modify the same file: accept disjoint region edits, merge overlapping regions using the larger-scope change as base, and halt on semantic conflicts (contradictory interface/contract changes) for user resolution.

**Auto-mode guardrails:** In unattended execution, verify scope containment, no unapproved destructive operations, and output schema compliance after each phase. Halt on violation. See `hatch3r-agent-orchestration-detail` for full guardrail specifications.

## Rule Application

All `scope: always` rules apply to every task including subagent work. Include rule directives in subagent prompts.

### Tiered Rule Inclusion

**Tier 1 -- Always include (every subagent):**
- `hatch3r-security-patterns` -- security invariants
- `hatch3r-code-standards` -- code quality

**Tier 2 -- Include by phase:**
- `hatch3r-testing` -- test-writer, implementer, reviewer
- `hatch3r-accessibility-standards` -- a11y-auditor, reviewer (UI)
- `hatch3r-git-conventions` -- orchestrator git ops
- `hatch3r-ci-cd` -- ci-watcher, devops
- `hatch3r-dependency-management` -- dependency-auditor

**Tier 3 -- On-demand:**
- `hatch3r-api-design`, `hatch3r-secrets-management`, `hatch3r-data-classification`, `hatch3r-performance-budgets`, `hatch3r-browser-verification`, `hatch3r-component-conventions`, `hatch3r-i18n`, `hatch3r-theming`, `hatch3r-migrations`, `hatch3r-feature-flags`, `hatch3r-observability-logging`, `hatch3r-observability-metrics`, `hatch3r-observability-tracing`

For limited context windows, Tier 1 is mandatory. Tier 2/3 included selectively by agent role and task scope.
