Orchestrated Mode

The pipeline

The commands, and how they wire into the workflow

You drive the whole pipeline with one command — /tl-telar:orchestrate. It invokes the gates, decomposition, parallel execution, and final review for you. The other commands set it up, recover it, or run a single stage on its own. The command-level lifecycle:

Command	Role in the orchestrated workflow	You run it
/tl-telar:setup-orchestration	One-time opt-in: detects the framework, writes .tl-telar-thresholds.json (including execution.max_parallel_wus), and creates the .tl-telar/ state skeleton.	Once per project
/tl-telar:orchestrate	The entry point. Drives the entire pipeline above — it runs the design and plan gates, decomposes into Work Units, dispatches independent WUs in parallel, and does the final review, all from one session.	Per feature
/tl-telar:review-design	The design gate as a standalone command. orchestrate runs this stage automatically; invoke it directly to gate a design doc outside a full run.	Standalone / optional
/tl-telar:review-plan	The plan gate as a standalone command — same relationship to orchestrate as review-design.	Standalone / optional
/tl-telar:resume	Recovers an interrupted run: re-reads the state files and re-runs the scheduler to reconstruct the ready frontier, then continues where it left off.	After an interruption
/tl-telar:prime · /tl-telar:self-reflect	The knowledge loop around the pipeline — prime re-injects relevant facts into a run's context; self-reflect captures learnings back into the KB after a PR.	Auto + after merge

The document chain

Each stage produces an artifact that feeds the next — the correctness guarantee that keeps generated work aligned to intent.

Review gates

Design review gate — collaborative, 6 reviewers

A pre-implementation review of a design doc. APPROVED only if all six reviewers approve: PM, Architect, Designer, Security-Design, CTO, and Mobile-Platform. It catches scope ambiguity, architecture drift, UX inconsistency, threat-model gaps, strategic misfit, and platform-convention violations before any plan is drafted. Max 3 iterations, then structured escalation.

Plan review gate — adversarial, 3 reviewers

Three fresh-instance adversarial reviewers inspect the implementation plan. PASS means it's fit to execute; FAIL means blocking defects, cited with file:line evidence and rubric rule IDs. Fresh instances each iteration prevent anchoring bias. Max 3 iterations, then human escalation.

Stack-aware, risk-tiered reviewer roster & model tiering

The per-Work-Unit code-review roster is not hardcoded. A pure resolver (scripts/tl-telar-reviewer-roster.js) selects reviewers from the Work Unit's file scope, so a web, backend, Rust, or desktop change gets the domain-correct rubric instead of a mobile one. Domain rubrics cover security (mobile / web / backend-data / Rust / desktop), accessibility, performance, backend correctness (data-integrity + reliability + API-contract), and frontend UX (interaction states + i18n). Agents are model-tiered through frontmatter (opus / sonnet / haiku), and every adversarial reviewer is pinned to Opus as the last line of defense.

The roster also scales with the Work Unit's risk_tier, because rigor is front-loaded into the plan (each WU carries mandatory data_contracts / edge_cases / test_plan, enforced by the plan gate) so implementation review can stay thin. A trivial WU gets a single Code reviewer; a standard WU gets Code + Maintainability (UI accessibility/performance are covered by deterministic CI lenses, not LLM reviewers); a critical WU gets the full roster plus an up-front design gate, strict CI, an adversarial cross-model pass, and a mandatory human checkpoint. A sensitive-path Security floor (auth, token, payment, migration, and the like) forces a Security reviewer on every tier and is never droppable. On a FAIL, retries re-review incrementally (sticky-pass — only the failing reviewer plus any prior-pass reviewer the fix touches; critical-tier Security is never sticky), and cross-model review stays always-on when configured rather than being gated by tier.

The 4-phase execution loop

Each Work Unit runs through the same loop — and, when Work Units are independent, several of these loops run concurrently (see Parallel dispatch below). Validation is run by the orchestrator itself (never delegated); reviewers are fresh each pass.

1. IMPLEMENT — make the change for this Work Unit.
2. VALIDATE — run validation commands directly; output is redirected to logs to keep the terminal quiet.
3. REVIEW — spawn fresh adversarial reviewers chosen by the stack-aware resolver from the Work Unit's file scope and sized by its risk_tier (Code always; Maintainability, domain Security, Backend-Correctness, Frontend-UX, Accessibility, or Performance as the tier and scope warrant), with a never-droppable sensitive-path Security floor. Every reviewer runs on Opus. Any FAIL blocks COMMIT; retries re-review incrementally (sticky-pass).
4. COMMIT — on PASS, emit COMMIT-READY. After 3 failed retries, escalate with the full failure history.

Parallel Work Unit dispatch

Independent Work Units run at the same time instead of one after another. A portable Node scheduler — scripts/tl-telar-wu-scheduler.js — reads the plan and live state, computes which WUs are eligible right now, and the orchestrator dispatches each eligible WU as a concurrent background Task(). On every completion the frontier is recomputed, so newly-unblocked WUs start immediately. The scheduler is pure (it only reads state and returns JSON), which is what makes runs deterministic and resumable.

Two facts every WU already declares drive the decision — no new authoring burden:

• deps — the WUs that must be COMPLETE first (the dependency DAG).
• file_scope — the paths this WU may modify. Two WUs may run together only if their file_scope arrays are disjoint — so two agents can never touch the same file at once. (With worktree isolation enabled, overlapping scopes may run concurrently in isolated checkouts instead.)

A diamond plan makes it concrete: once WU-A completes, WU-B and WU-C (disjoint scopes) run in parallel; WU-D waits for both, then integrates.

The scheduler classifies every non-complete WU each round and returns a JSON frontier — ready (dispatch now), running, and blocked with a reason: deps (a dependency isn't complete), file_conflict (its scope overlaps a running WU), or concurrency_cap (the ceiling is full). The ready set is always internally disjoint and acquired all-or-nothing, so the pipeline is deadlock-free by construction. If the plan itself is ambiguous — two dependency-unordered WUs declaring the same path — the scheduler surfaces a plan_warnings entry and the orchestrator stops rather than guessing an order.

You don't invoke the scheduler yourself — /tl-telar:orchestrate drives it. To see the frontier for a plan directly:

# Prints the JSON frontier {ready, blocked, running, occupied_files, plan_warnings}
node scripts/tl-telar-wu-scheduler.js \
  .tl-telar/plans/active-plan.md \
  .tl-telar/context/execution-state.md

# Tune concurrency for the current project
# .tl-telar-thresholds.json → { "execution": { "max_parallel_wus": 3 } }

Single-WU plans are just the degenerate case — ready holds one WU per round, and the loop behaves exactly as it did before.

Claude Code native features (opt-in, capability-gated)

Telar can opt into newer Claude Code native capabilities, configured under cc_features in .tl-telar/external-tools.yaml. Every one follows the same rule: enabled is intent, not capability. A feature activates only when it is enabled and a runtime probe confirms the capability is really present — otherwise the orchestrator falls back to the current behavior (fail-closed), logs one line, and never hard-fails. Defaults are true because absence degrades safely, so older Claude Code runs unchanged. The gating is one tested code path — scripts/tl-telar-cc-features.sh — not prose. See the Configuration reference for the keys.

Worktree isolation — concurrent overlapping Work Units

By default two WUs may run together only if their file_scope arrays are disjoint. With cc_features.worktree_isolation active, each WU runs in its own git worktree, so WUs with overlapping file_scope run concurrently too — the scheduler is called with --isolate to admit them, and each WU's branch is merged back with git merge --squash (staged, uncommitted — your commit stays yours). A real merge conflict routes through the same retry/escalate loop. When the capability isn't confirmed, the scheduler keeps the disjoint constraint (slower, never wrong).

Dynamic Workflows — deterministic review gates

With cc_features.dynamic_workflows active and the Workflow tool available, the plan-review gate runs its 3 adversarial reviewers via a deterministic Workflow script (parallel() fan-out + schema-validated verdicts) instead of prose Task() dispatch — no dropped reviewer, no malformed-verdict drift. Both paths emit the identical aggregated verdict, so the rest of the pipeline is oblivious to which ran; on older Claude Code the gate transparently uses the prose path.

Knowledge base

Telar keeps a typed JSONL knowledge base under .tl-telar/knowledge/ that compounds over time:

• Capture — /tl-telar:self-reflect harvests learnings from PR comments, the current conversation, and config audits, with a user-approval gate on every candidate.
• Prime — /tl-telar:prime re-injects the relevant facts into a new task's context, in five fixed categories: MUST FOLLOW, GOTCHAS, PATTERNS, DECISIONS, API BEHAVIORS.
• Curate — the knowledge curator dedups facts, promotes confidence on repeated provenance, and sweeps stale entries.

State persistence & recovery

A 3-file state model under .tl-telar/ (plan, project-context, execution-state) lets the orchestrator survive compaction and cross-session restarts. A SessionStart hook re-primes context automatically; /tl-telar:resume restores an in-progress run after confirming the resume position.

Recovery is scheduler-driven: execution-state.md records every active WU with its own phase and retry count (up to max_parallel_wus at once), and each snapshot doubles as the resume journal. On resume the orchestrator re-runs the scheduler against that snapshot to reconstruct the ready frontier from scratch — completed WUs are skipped, and any WU left IN-PROGRESS by a crashed session is reclaimed (reset to PENDING or escalated), so a crash frees its files instead of wedging the run.

External AI delegation (Phase β/γ — disabled by default)

Optional adapters can delegate implementation or review to external models (Codex, Gemini) with a budget circuit breaker ($1/task, $10/session) and fail-closed behavior. Cross-model review enforces that the model which wrote a diff never reviews it. Enable per-adapter in .tl-telar/external-tools.yaml; check status with /tl-telar:external-tools-health.

Authoring inputs for orchestrate

/tl-telar:orchestrate accepts three input modes:

Mode	Invocation	When
Free-text	/tl-telar:orchestrate <description>	No plan yet — the orchestrator drafts one
Epic file	/tl-telar:orchestrate --epic <path>	A prepared single-feature epic
Plan file	/tl-telar:orchestrate --plan-file <path>	You already keep a WU-decomposable plan

Get started with orchestration

# 1. One-time opt-in
/tl-telar:setup-orchestration

# 2. Run the full pipeline
/tl-telar:orchestrate Add a login screen with email + password

# 3. Resume after an interruption
/tl-telar:resume

# 4. Capture learnings after a PR
/tl-telar:self-reflect