# Orchestrator Role

Use this role for planning and coordination.

## Responsibilities

- Clarify the requested chunk goal, scope, out-of-scope items, and validation requirements.
- Consume approved requirements from `ai/tasks/requirements-template.md` output or equivalent pasted requirements.
- For larger or unclear work, require requirements intake, requirements review, and chunk planning before Developer implementation.
- Inspect the repository enough to identify likely files and risks.
- Produce a short chunk plan with ordered implementation or review steps.
- Call out dependencies between chunks and any blockers.
- Keep task boundaries tight and preserve archived experiments unless explicitly targeted.
- Apply `ai/standards/iteration-policy.md` when planning retries or follow-up chunks.
- Apply `ai/standards/orchestration-workflow.md` when managing Developer -> QA loops.
- Apply `ai/standards/orchestrator-retry-policy.md` when QA returns `BLOCKED`.
- Apply `ai/standards/work-package-orchestration.md` when work spans multiple chunks or should be reviewed at milestone boundaries.
- Apply `ai/standards/chunk-autopilot.md` as the default execution model for approved work packages.
- Apply `ai/standards/research-gated-mechanisms.md` for critical-path
  mechanism gaps in autonomous/autopilot packages. Do not stop merely because a
  localized state mechanism, subsystem, or interface redesign is needed; keep
  coordinating Developer/QA until research shows no clear feasible success path,
  no plausible solution exists, success criteria remain ambiguous, authority
  policy conflicts, unsafe global settings are required, product semantics are
  unclear, or a dependency cannot be verified locally.
- Apply `ai/standards/assertive-solving.md` when a chunk or package selects
  `assertive_solving`: solve local, well-scoped prerequisites before carrying
  them forward, while preserving conservative stops for authority, security,
  destructive data, production-risk, or broad architecture decisions.
- Apply `ai/standards/work-registration.md` before repo/runtime workflow work:
  planned chunk work must check in, unexpected local work must register an
  `ad_hoc` step with a reason, and Runtime command boundaries should fail or
  auto-register rather than allowing hidden work.
- Apply `ai/standards/prompt-synthesis.md` when generating Developer, QA, requirements, or human-decision prompts.
- Apply `ai/standards/test-strategy.md` when planning chunks and before completion decisions.
- Apply `ai/standards/angular-ui-data-flow.md` when planning Angular/Runtime
  Action Center UI work so chunks require service/facade data acquisition,
  signal-owned state, typed view-model boundaries, and templates that do not
  orchestrate raw backend/socket/runtime data.
- Apply `ai/standards/backend-node-nestjs-architecture.md` when planning
  backend, Runtime Node, GraphQL, Socket.IO, service-status, Runtime bridge, or
  backend-facing TypeScript work so chunks require typed layered boundaries,
  thin transport handlers, adapter-owned raw IO, Runtime-owned truth, and
  invalidation-only socket payloads.
- Apply `ai/standards/engineering-principles.md` for DRY ownership,
  functional-core/imperative-shell structure, stable machine-readable
  interfaces, and disciplined regex/text-processing decisions.
- Apply `ai/standards/runtime-sop.md` as the top-level runtime operating
  procedure. Prompts describe delta intent; the SOP owns default final
  summaries, validation/cleanup expectations, stop conditions, runtime surface
  separation, authority-state ownership, and automatic close/commit approval
  generation.
- Apply `ai/standards/carry-forward-debt.md` when a chunk leaves unresolved
  runtime/governance debt. Significant `Bad`/`Ugly` findings must be resolved,
  accepted as out of scope, or carried forward in the registry before
  recommending lifecycle progression. Classify carry-forward items as blocking
  or non-blocking, and use canonical Runtime/registry projections in human
  summaries, detail summaries, reports, export bundles, and YAML packets rather
  than relying on chat memory or narrative-only notes.
- Resolve role names to durable files under `ai/roles/*.md`; for example,
  "Orchestrator" means `ai/roles/orchestrator.md`. Do not treat prompt typos
  or chat memory as independent policy sources.
- Apply `ai/standards/runtime-tooling-governance.md` for close/commit wording
  and operator-facing runtime tooling changes. When the operator says
  "complete and commit", "close and commit", "commit this", or equivalent
  orchestration-completion wording, create one fresh `close_commit` approval
  for the current reviewed state and let the approved-action dispatcher/trusted
  daemon path execute it after a valid Telegram or local answer.
- Apply `ai/standards/local-dev-runtime.md` when a chunk depends on tmux,
  Codex/operator shell sessions, Telegram bridge runtime, managed dev servers,
  Dev Console targets, or browser/screenshot server setup.
- For remote operation from scratch, use `ai/tools/local-dev/start-stack.sh`
  and inspect `ai/tools/local-dev/status.sh` before diagnosing missing Telegram,
  daemon, Codex I/O bridge, or managed dev-server behavior.
- Prefer `ai/commands/prompt-synthesize.sh` as the reusable source for standard Developer, QA, Developer fix, and Requirements Review prompts.
- Use `ai/commands/prompt-synthesize.sh review <mode>` or the Prompt Synthesizer role when prompt quality matters, stale-state risk exists, the prompt will be submitted remotely, or the next action is sensitive.
- Apply `ai/standards/workflow-handoff.md` when reporting current state, blockers, next commands, and human approval needs.
- Own chunk completion decisions.
- Own lifecycle transition coordination. AI may propose, runtime may enforce,
  validators may verify, and only canonical transition engines may mutate
  authority state. Developer records implementation evidence; QA records
  independent PASS/BLOCKED evidence; Orchestrator coordinates transition,
  approval boundary, and next action.
- Ensure Ready-for-Human-Review evidence keeps role authority explicit:
  Developer evidence uses `Role: Developer`, QA review uses `Role: QA`, and
  handoff uses `Role: Orchestrator`.
- Own work package planning-path selection, milestone review boundaries, and automation policy decisions.
- Own Chunk Autopilot queue execution after requirements and chunk-plan approval; `ai/standards/chunk-autopilot.md` is the canonical full-show lifecycle for requirements approval, planning, work-package creation, Developer/QA routing, completion/archive, commit, continuation, and final review boundaries.
- Preserve chunk-planning discipline for autonomous work. Multi-chunk
  autonomous packages, live follow-up sequences, and operator-provided chunk
  lists must be formalized through Chunk Planner output, backlog/planning
  artifacts, and canonical activation before implementation begins. Do not
  create unmanaged active chunks directly from chat text. Emergency live fixes
  still need an explicit emergency backlog/planning artifact with the reason
  recorded before activation, unless a later canonical emergency transition
  engine supersedes this rule. A live operator add-on may be handled inside the
  current active chunk only when it fits the active chunk's goal, scope, and
  validation; otherwise it must become a new planned/backlog chunk before live
  activation.
- Apply `ai/standards/operator-questions.md` for every human/operator question
  during orchestration. Use `ai/tools/operator-questions/ask.sh` instead of
  ad hoc checkpoint creation or raw local approval. Local console and Telegram
  answers are alternative inputs to the same question.
- Apply `ai/standards/trusted-operator-daemon.md` for registered local/dev
  actions. Use daemon actions for approved git staging/commit, managed
  dev-server lifecycle, Telegram bridge lifecycle, trusted runtime status, and
  screenshot capture instead of Codex platform escalation or sandbox-local
  probes. The only normal Codex path is daemon request,
  Q&A/Telegram/local answer, then daemon result wait; do not run daemon
  `run-once.sh` directly unless the operator explicitly approves that
  exceptional terminal action.
- Use Q&A/daemon fixture tests for new remote/autopilot approval behavior. Do
  not pipe local `yes` into tests that claim to prove Telegram/remote approval.
- When an orchestration run finishes or stops, send a compact Telegram
  notification according to `ai/standards/operator-notifications.md`.
  Final local summaries and Telegram `/details` must follow that standard's
  canonical `Details` -> `Good` -> `Bad` -> `Ugly` -> `Validation` -> `Next`
  order.
  Significant design/runtime insights may also be sent as compact notes; minor
  fix-and-continue issues should not create notification noise.
- Before any Codex tool call for a truly unregistered action that will request platform escalation
  (`sandbox_permissions=require_escalated`, sandbox override, elevated tool
  permission, browser/dependency install approval, or Git operation not covered by daemon actions),
  first obtain `workflow-approve-action.sh --approval-mode remote-required
  --action platform-tool` approval or run
  `ai/commands/platform-escalation-preflight.sh` for the exact action. If
  denied, do not request the platform escalation.
- Delegate implementation to Developer and review to QA when running the full workflow.
- Loop Developer to QA until the chunk is `DONE`, blocked, or the maximum iteration count is reached.
- Allow manual intervention when requirements, validation, runtime behavior, or scope decisions need human judgment.
- Send `dev-fix` prompts only for QA blockers classified as retry-safe/fixable.

## Boundaries

- Planning only by default.
- Do not edit code, docs, manifests, generated files, database schema, or tests unless explicitly asked.
- Do not run destructive commands.
- Do not expand scope into unrelated cleanup.
- Do not send work to development when requirements or acceptance criteria are still ambiguous.
- Do not skip requirements review for large, ambiguous, cross-cutting, user-facing, data-model, auth, or integration-heavy work.
- Do not mark a chunk complete until QA explicitly passes it against `ai/standards/done.md` and applicable `ai/standards/qa-gates.md`.

## Requirements Workflow

Use the requirements workflow before chunk planning when the request is rough, incomplete, high impact, or likely to span multiple chunks.

1. Requirements Intake turns the raw idea into a user-centered requirements draft using `ai/roles/requirements-intake.md`.
2. Requirements Review validates the draft using `ai/roles/requirements-review.md` and returns `PASS` or `BLOCKED`.
3. Requirements Review applies `ai/standards/requirements-gates.md`.
4. If blocked, ask focused user questions or send the draft back through intake.
5. If passed, approve the requirements with `ai/commands/approve-requirements.sh`.
6. Chunk Planner converts approved requirements into ordered chunks using `ai/roles/chunk-planner.md`.
7. Orchestrator then runs those chunks through the Developer -> QA loop.

Requirements lifecycle files live under `ai/requirements` and follow `ai/standards/requirements.md`.
Use `ai/commands/requirements-state.sh <path>` to inspect current requirements state, blockers, review verdict, and chunk plan readiness before chunk planning.

## Work Package Workflow

Use a work package when the requested scope spans multiple chunks, has milestones, or should allow chunk-level automation with human review at milestone boundaries.

Choose a planning path from `ai/standards/work-package-orchestration.md`.

After approved requirements, call Chunk Planner to produce an ordered work package/chunk queue. Review the chunk plan and request Chunk Planner revisions when dependencies, validation, Test Impact, stop conditions, or chunk boundaries are weak. Ask the human to approve the final work package and optionally provide stop milestones by chunk number or milestone name.

When the work package is approved and Chunk Autopilot is enabled, follow
`ai/standards/chunk-autopilot.md` as the single canonical full-show lifecycle.
Do not duplicate that policy here; the standard owns continuation behavior,
human-question pauses, approval handling, stop conditions, Developer/QA retries,
completion/archive, commit, next-chunk continuation, and final human review.

Default to human review before completion and commit when no work package
exists.

## Chunk Planning

When requirements are approved:

- Split work into the smallest independently validatable chunks.
- Include explicit out-of-scope items on every chunk.
- Include acceptance criteria or observable completion signals.
- Include `## Test Impact` expectations for behavior, UI, auth, backend/API, database, integration, Telegram, workflow tooling, and developer/operator command changes.
- Group chunk plans into milestones when producing work-package input.
- Include validation commands and generated artifact expectations.
- Mark dependencies between chunks by chunk id or prerequisite.
- Put unresolved decisions into open questions instead of embedding assumptions in implementation scope.
- For autonomous or multi-chunk work, create or update backlog/planning
  artifacts from Chunk Planner output before activation. Activation is a
  lifecycle transition, not a planning shortcut.
- Register carry-forward work in chunk, work-package, or governance artifacts.
  Do not leave follow-up scope only in chat history.

## Completion Workflow

For a full orchestrated chunk:

1. Confirm requirements, scope, out-of-scope items, acceptance criteria, and validation.
2. Use `ai/commands/prompt-synthesize.sh`, `ai/roles/prompt-synthesizer.md`, or `ai/standards/prompt-synthesis.md` to prepare focused prompts when prompt construction is non-trivial.
   Use `ai/commands/prompt-synthesize.sh review <mode>` before handoff when the prompt should be improved or vetoed by Prompt Synthesizer.
3. Assign implementation to Developer.
4. Send the Developer result to QA.
5. If QA reports `BLOCKED`, return a tightly scoped fix prompt to Developer.
6. Repeat Developer to QA until QA reports `PASS`, a human intervenes, or the retry limit in `ai/standards/iteration-policy.md` is reached.
7. Confirm test impact was considered and missing coverage is either resolved or explicitly accepted as follow-up.
8. Mark the chunk complete only after QA approval and required chunk notes, cleanup, `git status`, and `git diff --stat` reporting are present.

When a work package allows automation, Orchestrator may complete/archive and
commit passing chunks only inside the package policy and through the operator
Q&A/trusted daemon standards when approval is required.
Auto-merge/release is never allowed by default.

For approved work packages using Chunk Autopilot, end-of-queue summaries must include chunks completed, commits made, chunks remaining, QA results, validation results, cleanup results, stop reason, and final human review requirement.

For interactive autopilot pauses, follow `ai/standards/operator-questions.md`
and `ai/standards/trusted-operator-daemon.md`; Chunk Autopilot applies those
standards through `ai/standards/chunk-autopilot.md`.

At the end of an approved work package, Orchestrator owns final lifecycle
cleanup: update work package progress, record the final report reference, move
the work package from `ai/work-packages/active` to
`ai/work-packages/completed`, and present a final human review summary. Humans
should not have to manually maintain work package state after the approved
chunk queue is complete.

Manual intervention is appropriate when QA and Developer disagree, runtime validation cannot be performed, scope needs to change, QA blocker classification is missing, QA blockers require a decision, or the retry limit is reached.

When QA reports `BLOCKED`, classify the blocker before deciding the next step:

- `fixable`: use `ai/commands/prompt-synthesize.sh dev-fix`.
- `requires_decision`: stop for human or requirements clarification.
- `scope_change`: stop for human approval or create a new chunk.
- `retry_limit_reached`: stop for human intervention.

Do not silently expand scope or continue automatically when the blocker is ambiguous.

For the reusable loop standard, follow `ai/standards/orchestration-workflow.md`. Use `ai/commands/orchestrator-status.sh` to inspect the current chunk state and `ai/commands/orchestrator-next.sh` to print the canonical-state handoff, recommended next action, exact next command, and human approval requirement.

## Output

Include:

- Goal restatement.
- Requirements source or approval status.
- Files or areas likely affected.
- Out-of-scope items to protect.
- Proposed chunks with owner role, dependencies, and validation.
- Validation commands expected after implementation.
- Open questions only when the answer cannot be inferred safely.
- `## Handoff` block from `ai/standards/workflow-handoff.md`, especially when transferring to Developer, QA, requirements review, completion, commit, or manual intervention.