{
  "markdown": "![cc-orchestrador-subagents](banner.png)\n\n# cc-orchestrador-subagents\n\nClaude Code plugin to conduct a multi-agent development workflow from an existing PRD/spec, with Codex, Antigravity/AGY and audit artifacts.\n\n**[Leia em Português](README.pt-BR.md)** — Portuguese version available.\n\n## Overview\n\nThe `cc-orchestrador-subagents` organizes development as a **persistent multi-agent engineering system** for Claude CLI/Claude Code. Claude is the Main Orchestrator over durable state, verified memory, searchable history, worktrees, deterministic validation, telemetry, and curated learning. It does not do demand discovery or planning — it works exclusively on projects that already have a **PRD or pre-established specs**.\n\nThe user provides the specification via file mention (`@docs/prd.md`) or by sending the PRD/spec file. That document is the **source of truth**: the orchestrator ingests it, classifies tasks, builds waves, generates contracts, delegates, monitors, integrates and reviews.\n\nCodex and Antigravity/AGY enter as specialized sub-agents:\n\n| Role | Executor | Responsibility |\n|---|---|---|\n| Harness Orchestrator | Claude CLI / Claude Code | Ingests the PRD/spec and coordinates workflow, contracts, waves, validations, logs and user decisions. |\n| Back-end implementation, database, tests and adjustments | Codex (direct `codex-companion.mjs` dispatch; fallback `codex:codex-rescue`) | Executes non-front-end tasks with `--model <gpt-5.6-terra|gpt-5.6-sol|gpt-5.6-luna> --effort <low|medium|high> --write`, both derived from the task (role: implement/review/fix — never a fixed default). |\n| Front-end implementation and UX | Antigravity/AGY (`cc-antigravity-plugin:antigravity-coder`) | Executes `FRONTEND_ONLY` tasks and front-end slices of `FULLSTACK`, including Vite/React setup, routing, and UI implementation. |\n| Back-end post-implementation review | Codex (direct `codex-companion.mjs` dispatch, no `--write`; fallback `codex:codex-rescue`) | Reviews **back-end only** with `--effort high` or falls back to orchestrator's internal read-only review when quota is exhausted. |\n| Front-end post-implementation review | Antigravity/AGY (`cc-antigravity-plugin:antigravity-agent`, `--read-only --format json --model pro-high --effort high`) | Reviews **front-end only** read-only or falls back to orchestrator's internal review when AGY is unavailable. |\n\n### Configurable Agent Stack\n\nThe table above describes the **default** stack. Which agent actually implements/reviews each role is a per-project choice, persisted in `.orchestrator/project-config.md` and resolved on first run (or any time via `/orchestrator project-config`):\n\n```bash\nnode \"${CLAUDE_PLUGIN_ROOT}/skills/orchestrator-multi-agent-development/scripts/project-config.mjs\" show --root \".\"\n```\n\nFour roles — `backendExecutor`, `frontendExecutor`, `backendReviewer`, `frontendReviewer` — each accept `codex`, `agy`, or `claude-code`. Setting a role to `claude-code` routes that role to a Claude Code sub-agent (via the `Agent` tool) instead of an external CLI, with review running read-only into `review/review-final.md`/`review/review-frontend.md`. **Setting all four roles to `claude-code` runs the entire workflow without Codex or AGY installed** — no external CLI is required by preflight in that case. Preflight only requires the `codex`/`agy` CLI and plugin when at least one role is configured to use it.\n\nPreflight also detects two optional MCP servers — the Codebase Memory MCP (`codebase-memory-mcp`, code graph queries used for architecture/impact analysis) and Context7 (up-to-date library docs in sub-agent prompts). Either one missing is a `warnings` entry, never a blocker; see `skills/orchestrator-multi-agent-development/references/mcp-context.md`.\n\nThat aggregate check only proves a server is registered *somewhere* on the machine — not that Codex or AGY specifically have it. Run `node scripts/preflight.mjs --check-agent-mcp` to also query `codex mcp list --json`/`agy mcp list` live and get `checks.optional.mcpPerAgent.<agent>.<server>`, with an `install` field carrying the exact `mcp add` command to register it for that agent. Nothing installs automatically: the orchestrator only runs it after the user approves via `AskUserQuestion`, same pattern as the Open Design installer.\n\n### Complete Workflow\n\n- **Phase 0 - Preflight, project configuration and assisted install:** validates dependencies, Node.js 22.13+, `node:sqlite`/FTS5, `Bash(node:*)`, resolves the Project_Config (roles above), detects the two optional MCPs, and offers to install any missing dependency actually required by the resolved roles.\n- **Phase 1 - Memory + specification:** audits `.orchestrator/project-memory.md`, projects FTS5 history, and reads the PRD/spec as the source of truth; only proven facts supplement context.\n- **Phase 2 - Task classification:** records category, dependencies, complexity, contracts, `expectedFiles`/`validationPlan`, `allowedPaths`, executor, and routing features.\n- **Phase 3 - Waves, routing, and isolation:** applies heuristic floors, consults comparable history when sufficient, validates routing, and separates isolated worktrees from scope-overlap serialization.\n- **Phase 4 - API/UI contracts:** creates and deterministically validates contracts, wire format, casing, examples, states, and permissions for every front-back exchange.\n- **Phase 5 - Parallel delegation:** creates eligible worktrees, acquires leases, and dispatches tasks; both Codex and AGY receive an explainable selected model (Codex: one of three fixed role slugs; AGY: capability alias/tier).\n- **Phase 6 - Lifecycle Manager:** polls adapters, persists results before consuming them, renews heartbeat/lease on observable activity, and handles stall/grace/interrupt/retry/cancel without assuming outcomes.\n- **Phase 7 - Integration:** serially integrates worktrees and uses deterministic scripts for diff, scope, API/UI, wire format, and validation results before category-specific corrections.\n- **Phase 8 - Back-end post-implementation review:** delegates final read-only review to Codex with `--effort high`, **back-end only**, and saves `review/review-final.md`. If Codex runs out of quota, the Orchestrator itself does internal review. Skipped when there is no back-end.\n- **Phase 9 - Front-end post-implementation review:** delegates final read-only review to AGY with `--read-only --format json --model pro-high --effort high`, **front-end only**, and saves `review/review-frontend.md`. If AGY is unavailable, the Orchestrator does internal review. **Skipped when there is no front-end task.**\n- **Phase 9.5 - Browser E2E:** required whenever the run has front-end. Drives critical flows in a real browser and verifies CORS, tenant/host resolution, response casing, UI state and the final user-visible effect. A same-origin topology waives the gate explicitly, with a recorded reason — never by silent derivation.\n- **Phase 10 - Final reports:** creates `report/workflow-log.md`, `report/subagents-context.md` and `report/implementation-report.md`, consolidating timeline, contracts, validations, sub-agents, AGY Conversation IDs and delivery status.\n- **Phase 11 - Durable delivery:** prepares and persists the summary/instructions without announcing success before final gates.\n- **Phase 12 - Learning and closure:** creates `learning/learning-report.md` and candidate lessons without automatic promotion, projects history/telemetry, requires `audit.complete`, closes/verifies the run, and only then publishes delivery.\n\nCoordination artifacts and final reports live under `.orchestrator/runs/<name>/` (runs created before this version stay at `.orchestration/<name>/`, still read but never migrated).\n\n### Main Operational Rules\n\n- **Usage premise:** the orchestrator only works with a ready PRD/spec. It does not do discovery, planning, or reinterpret the demand.\n- **Codex reviews back-end only;** AGY (`pro-high`) reviews front-end only.\n- **AGY Fan-out:** `--parallel` and `--subagent-model` activate native Gemini sub-agents within the AGY task. Requires `cc-antigravity-plugin >= 4.0.0`.\n- **AGY Model:** the user override and heuristic floor are authoritative; comparable history may only escalate with a minimum sample and `agyModelEvidence`. Review always uses `pro-high`.\n- **Verified memory:** only `FILE`, `CONTRACT`, passing `TEST`, durable `RUN_EVENT`, and explicit `USER` sources enter Project Memory; conflicts and stale facts are excluded.\n- **Code for mechanics:** three or more reads/greps, loops, and repeated comparisons use `scripts/intelligence`, producing bounded JSON and an evidence ID.\n- **Physical isolation:** non-overlapping scopes can use one worktree per task; overlap or unknown scope serializes the wave.\n- **Privacy-first telemetry:** only allowlisted metadata is persisted/exported; prompts, content, diffs, source, raw output, and secrets are rejected.\n- **Controlled learning:** Phase 12 creates candidates; independent validation precedes Recipes, and Curator supports pin/archive/backup/rollback without auto-delete.\n- **Codex Prompts:** do not fix `--model`; use only `--effort medium` for implementation/handoff/adjustments and `--effort high` for back-end review.\n- **Mandatory contracts:** any front-back exchange requires contract before parallelizing.\n- **Wire format:** every contract must explicitly state JSON casing, field names, complete examples and real serialization validation.\n- **Routing by category:** `FRONTEND_ONLY` goes to Antigravity/AGY, including front-end setup; Codex only assumes front-end as a registered operational fallback.\n- **Codex Quota:** lack of quota on implementation blocks and requests user decision; lack of quota on back-end review triggers orchestrator's internal read-only review.\n- **Codex Sandbox:** external network blocked for packages/restore, missing package in local cache or write outside allowed working directory becomes `BLOCKED` with evidence.\n- **AGY Limit on Windows:** AGY prompts above 28,000 chars are divided into subtasks by deliverables before delegation to avoid `ENAMETOOLONG`.\n\n## Installation\n\nLocal:\n\n```text\n/plugin marketplace add \"C:\\Users\\allan\\Desktop\\Projetos Pessoais\\cc-plugins-allan\\cc-orchestrador-subagents\"\n/plugin install cc-orchestrador-subagents@cc-orchestrador-subagents\n```\n\nGitHub:\n\n```text\n/plugin marketplace add AllanHarlen/cc-orchestrador-subagents\n/plugin install cc-orchestrador-subagents@cc-orchestrador-subagents\n```\n\nValidate:\n\n```text\n/orchestrator preflight\n```\n\nSee \"Official Dependencies\" below for the optional Codex/AGY CLIs and plugins required only by the roles you configure.\n\n## Official Dependencies\n\nThe minimum runtime is **Node.js 22.13.0**, where `node:sqlite` is available without the experimental CLI flag, plus SQLite FTS5. Preflight blocks execution without this capability **regardless of agent stack configuration**, because `knowledge.db`, `history.db`, Recipes, and adaptive routing depend on it.\n\nThe Codex and Antigravity/AGY dependencies below are only required when the corresponding Project_Config role (`backendExecutor`, `frontendExecutor`, `backendReviewer`, `frontendReviewer`) is actually set to `codex`/`agy` — see \"Configurable Agent Stack\" above. A project with every role set to `claude-code` needs neither.\n\n`/orchestrator project-config` offers to install both the CLI **and** the Claude Code plugin below through the assisted Dependency_Installer — one confirmation per dependency, no manual step required. The CLI and its plugin are checked (and installed) independently: having one does not imply the other is present. The manual steps below remain valid if you prefer to install by hand.\n\nThis plugin depends on the official Codex plugin for Claude Code: https://github.com/openai/codex-plugin-cc.\n\n```text\n/plugin marketplace add openai/codex-plugin-cc\n/plugin install codex@openai-codex\n/reload-plugins\n/codex:setup\n```\n\nThe marketplace/dependency used in manifests is `openai-codex`. The orchestrator dispatches to it directly via `codex-companion.mjs` (path resolved from `checks.plugins[\"openai-codex\"].companionPath`, published by `scripts/preflight.mjs`); the `codex:codex-rescue` sub-agent is a documented fallback for when that path cannot be resolved.\n\nFor front-end, the orchestrator requires `cc-antigravity-plugin >= 4.0.0` and AGY `>= 1.1.8` (`1.1.16` recommended), with these files present in the installed plugin:\n\n- `agents/antigravity-coder.md` (implementation)\n- `agents/antigravity-agent.md` (read-only review)\n- `commands/antigravity.md`\n- `scripts/antigravity-bridge.js`\n\n## How to provide the specification\n\nThe orchestrator does not invent the demand. Provide the PRD/spec in one of these ways:\n\n```text\n# File mention\n/orchestrator @docs/prd-reservations.md\n\n# Spec pasted directly into the argument\n/orchestrator \"Implement the reservations flow per: <paste the complete specification here>\"\n\n# With AGY model override\n/orchestrator --model pro-low @docs/prd-reservations.md\n\n# Portuguese alias\n/orquestrador @docs/prd-reservations.md\n```\n\nIf no PRD/spec is provided, the orchestrator asks for the specification before continuing.\n\n## Persistent State and Resume\n\nEvery run has a durable state machine in `.orchestrator/runs/<name>/` (or `.orchestration/<name>/` for a run created before this version):\n\n- `state.json` is the current materialized snapshot;\n- `events.jsonl` is the append-only write-ahead history used to rebuild the snapshot after a crash.\n\nResume the latest active run, or select one by `runId`/slug:\n\n```text\n/orchestrator resume\n/orchestrator resume reservations-20260817-001\n```\n\nOn resume, any task left as `RUNNING` becomes `UNKNOWN` first. The orchestrator then reconciles executor status, Git, produced files, and validation evidence. Local changes alone never imply success, and an unknown task is never blindly re-executed.\n\nThe deterministic state CLI is also available for inspection and integrity checks:\n\n```bash\nnode scripts/orchestration-state.mjs status\nnode scripts/orchestration-state.mjs resume <runId>\nnode scripts/orchestration-state.mjs verify --dir .orchestrator/runs/<name>\n```\n\nA run can become `DONE` only with a non-empty task set, evidence plans, resolved scope, completed Phase 12, required artifacts, and completion gates backed by evidence. Terminal runs are immutable. Cancellation interrupts and reconciles executors before closure.\n\n`browserE2E` is required whenever the run has front-end — including a front-end-only run against an existing separate API, which is exactly the case Phase 9.5 exists for. It is also the only gate that accepts an applicability waiver: a same-origin topology must be recorded as an explicit `N/A` with a reason, never derived away from the mix of task categories.\n\n## Memory, History, Intelligence, and Learning\n\nStable context and accumulated project experience live outside the run directory:\n\n```text\n.orchestrator/\n  project-memory.md\n  knowledge.db\n  history.db\n  telemetry.jsonl\n  learned/\n  backups/\n```\n\nMain commands:\n\n```bash\nnode scripts/orchestrator-knowledge.mjs init\nnode scripts/intelligence/inspect-project.mjs --root . --persist-knowledge\nnode scripts/orchestrator-knowledge.mjs history-search \"NU1301\"\nnode scripts/orchestration-lifecycle.mjs help\nnode scripts/orchestration-worktree.mjs help\nnode scripts/orchestration-router.mjs report\nnode scripts/orchestration-telemetry.mjs report --detailed\nnode scripts/orchestration-learning.mjs curator-status\n```\n\nThe slash command also exposes `/orchestrator knowledge status`, `knowledge search`, `knowledge pin`, `knowledge archive`, `knowledge curate`, `knowledge rollback`, `telemetry report`, and `telemetry compact`. Curator/retention operations are dry-run without `--apply`; OTLP is opt-in and metadata-only.\n\n### Full command surface\n\n| Sub-command | What it does |\n|---|---|\n| `help` | prints the synopsis, sub-commands and flags |\n| `preflight` | validates dependencies and exits |\n| `project-config` (alias `config`) | shows/changes the project agent stack and revalidates |\n| `status [runId]` | run state, read-only (without `runId`, the most recent) |\n| `resume [runId]` | resumes the run without assuming the result of an interrupted task |\n| `knowledge <sub>` | `status`, `search`, `pin`, `archive`, `activate`, `curate`, `rollback`, `render`, `audit`, `backups`, `history-project` |\n| `telemetry <sub>` | `report`, `compact`, `otlp-preview`, `otlp-export` |\n\n`/orquestrador` is the Portuguese alias and accepts exactly the same surface. The previous spelling `/orchestrador` was renamed.\n\nFlags are `--model`, `--parallel`, `--subagent-model`, `--effort` and `--timeout`. The former `--agy-` prefixed names (`--agy-model`, `--agy-parallel`, `--agy-subagent-model`, `--agy-effort`, `--agy-timeout`) remain accepted as silent legacy aliases with identical behavior.\n\nThe boundary is intentional: the LLM makes novel decisions; deterministic scripts validate mechanics; history/Recipes recover proven decisions; Project Memory supplies stable context; Codex/AGY implement.\n\n### What to Commit\n\nEvery new run lives under `.orchestrator/runs/<name>/`, alongside `project-config.md`, `worktrees/`, `history.db` and `knowledge.db` — one hidden root for everything this plugin writes to your project. (Runs created before this version stay at `.orchestration/<name>/`, read but never migrated; older docs and scripts you may still have around can reference that path.)\n\n**Default: gitignore all of it.** `.orchestration/` and `.orchestrator/` are excluded from the target project's Git history by default (same convention `cc-pensador` already uses for `.pensador/`):\n\n```gitignore\n.orchestration/\n.orchestrator/\n```\n\nThis is a deliberate reversal of the previous default, which committed `events.jsonl`, the run's Markdown/handoff artifacts, `project-memory.md`, `learned/` and `knowledge.db`. Versioning that state has a sharp edge: deleting those directories from disk does not remove them from Git — `git status` just shows them as deleted-but-tracked, and the next ordinary commit that rewrites `state.json`/`events.jsonl` at those paths (which any run does) resurrects the old content. If you want the old behavior back (cross-machine `resume`/audit trail via Git), use the narrower opt-in block below instead, and accept the risk it reintroduces — a versioned or `git clean -fdx`'d worktree breaks a running wave, and SQLite in WAL mode conflicts on every concurrent commit:\n\n```gitignore\n.orchestrator/worktrees/\n.orchestrator/backups/\n.orchestrator/history.db\n.orchestrator/telemetry.jsonl\n*.db-wal\n*.db-shm\n```\n\nFlipping the default does not retroactively untrack history a project already committed — that needs a dedicated `git rm --cached -r .orchestration .orchestrator` commit; the orchestrator does not automate it. The full per-path table (for the opt-in case) is in `references/persistent-state.md`.\n\n## Codex: Model and Effort\n\nThe workflow no longer fixes Codex models like `gpt-5.4` or `gpt-5.5`.\n\nUse:\n\n- direct `codex-companion.mjs` dispatch with `--effort medium --write` for implementation, handoff and adjustments;\n- direct `codex-companion.mjs` dispatch with `--effort high`, **no `--write`**, for back-end post-implementation review — omitting the flag is what makes the review read-only, not a prompt instruction;\n- `codex:codex-rescue` is the fallback sub-agent when `companionPath` cannot be resolved.\n\nThe model defaults to what is available in the user's account. Codex never reviews front-end.\n\n## Codex: Sandbox Limits\n\nWhen Codex is in a sandboxed environment, treat as operational blocker:\n\n- external network failure for packages, restore or registries, like `NU1301` accessing `https://api.nuget.org/v3/index.json`;\n- required package missing from local cache;\n- `UnauthorizedAccessException` or equivalent error when trying to create/edit files outside allowed working directory.\n\nIn these cases the sub-agent must stop, record evidence and return `Status: BLOCKED`, without insisting on long retries or trying to bypass the sandbox.\n\n## Front-end Routing\n\nThe agent is chosen by task category, not by work appearance. If the task is `FRONTEND_ONLY`, use `cc-antigravity-plugin:antigravity-coder` even when it is Vite/React setup, React routing, or other front-end infrastructure. `antigravity-agent` remains read-only and is reserved for the Phase 9 review — `validate-routing.mjs` fails the wave when an implementation task points at it.\n\nCodex should only receive front-end as a registered operational fallback after `QUOTA_EXAUSTED`, `AUTH_REQUIRED`, `AGY_MISSING`, `TIMEOUT`, AGY tool/write failure or explicit decision.\n\n## AGY: Front-end Delegation\n\nFront-end tasks are routed to Antigravity/AGY by category. Implementation uses `--mode accept-edits --format stream-json --model <agyModel>`; the bridge resolves aliases from the runtime model catalog and never edits user settings.\n\nDefault policy (implementation):\n\n- `flash-medium` for most tasks;\n- `pro-low` for complex tasks, multi-route, multi-file, with delicate API/UI contract or high regression risk;\n- `pro-high` only in critical cases;\n- manual override available via `/orchestrator --model <model> <demand>`.\n\nWithout an override, this policy defines the **floor**. The adaptive router may escalate only with enough comparable type/complexity samples, using first-pass success, review failures, regressions, duration, and a Wilson interval. It never downgrades the floor, never randomly explores critical tasks, and records the decision in `agyModelEvidence`.\n\nThe **front-end review (Phase 9)** always uses `--read-only --format json --model pro-high --effort high`, regardless of the implementation `agyModel`.\n\n## AGY: Native Gemini Sub-agent Fan-out\n\nWhen a front-end task produces two or more independent deliverables (e.g., three React components, two HTML reports), the orchestrator can activate AGY's native fan-out via `DefineSubagent` inside the prompt.\n\nThe mechanism is purely intra-task: it remains 1 task = 1 AGY delegation; `run/monitoring.md`, contracts and `validate-routing.mjs` remain intact.\n\n### New Flags\n\n| Flag | Behavior |\n|---|---|\n| `--parallel` | Forces fan-out on all AGY tasks in the execution. AGY decides the count. |\n| `--subagent-model <model>` | Model of Gemini sub-agents. Implies `--parallel`. Default: `inherit` (inherits `agyModel`). |\n| `--effort <low|medium|high>` | Optional implementation effort override; review stays at `high`. |\n| `--timeout <duration>` | Silent timeout for every AGY delegation, including review, such as `300s` or `5m`. |\n\n### Examples\n\n```text\n# Fan-out forced by user\n/orchestrator --parallel \"Create three independent React components: Header, Sidebar and Footer\"\n\n# Pro Planner coordinating Flash sub-agents\n/orchestrator --model pro-low --subagent-model flash-medium \\\n  \"Generate two HTML reports: taxes on electric cars and combustion cars\"\n\n# Automatic heuristic (orchestrator decides)\n/orchestrator \"Create Header, Sidebar and Footer as separate components in src/components/\"\n```\n\n### When Fan-out is Used by Heuristic\n\nThe orchestrator turns on `--parallel` automatically when a `FRONTEND_ONLY` task (or front-end slice of `FULLSTACK`) lists two or more independent deliverables in acceptance criteria — and the task logic is not shared between them.\n\nDependent deliverables or those sharing state remain in the single AGY sub-agent, without `--parallel`.\n\n### New Fields in `plan/tasks-classification.md` and `plan/waves.md` (AGY Tasks)\n\n- `agyParallel: yes|no`\n- `agyParallelSource: user|heuristic`\n- `agySubagentModel: <model>|inherit`\n\nStable aliases used by heuristics and adaptive routing:\n\n| Model | Tier |\n|---|---|\n| `flash-low` | Flash |\n| `flash-medium` | Flash |\n| `flash-high` | Flash |\n| `pro-low` | Pro |\n| `pro-high` | Pro |\n| `auto` | — |\n\nUser overrides may also pass a safe dynamic model slug. The bridge validates it against `agy models`; routing history remains grouped by the requested stable alias.\n\n## Preflight and Auto-remediation\n\nRun:\n\n```bash\nnode scripts/preflight.mjs --check-agent-mcp   # default path (SKILL.md/workflow.md Phase 0); also queries codex/agy live for per-agent MCP status\nnode scripts/preflight.mjs                     # without the optional.mcpPerAgent block; only if you want to skip the subprocess cost\n```\n\nThe JSON includes:\n\n- `status`\n- `checks`\n- `failed`\n- `remediation`\n- `autoRemediation`\n\nPreflight validates:\n\n- version of `agy` found in PATH;\n- Codex CLI in PATH;\n- `cc-antigravity-plugin >= 4.0.0` and the `openai-codex` plugin;\n- presence of `agents/antigravity-coder.md`, `agents/antigravity-agent.md`, `commands/antigravity.md` and `scripts/antigravity-bridge.js` in the installed AGY plugin;\n- `Bash(node:*)` permission for the Codex companion.\n\n> As of version 3.0.0, preflight no longer requires the OpenSpec CLI or `openspec-*` skills — the orchestrator does not itself drive OpenSpec. It can still ingest a handoff from Pensador with an `openspec-change` artifact role in joint mode (see `references/workflow.md` and `references/handoff-contract.md`); that ingestion never depends on the OpenSpec CLI being installed.\n\n### Auto-remediation Scope\n\nAuto-correction only exists for `codex-companion-bash`:\n\n- if `.claude/settings.json` does not exist, it can be created;\n- if it exists with valid JSON, `permissions.allow` receives `Bash(node:*)`;\n- if it exists with invalid JSON, the file is not overwritten.\n\nExample of minimum baseline:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(node:*)\"\n    ]\n  }\n}\n```\n\n## AGY Prompt Limit — CLI Limitation on Windows\n\nThe AGY CLI is invoked via `child_process` by the plugin bridge. On Windows, Node.js passes the prompt as a command-line argument, applying automatic quoting: each `\"` becomes `\\\"` and each `\\` doubles.\n\nResults from empirical tests:\n\n| Content Type | Max Prompt | Break Point |\n|---|---|---|\n| Plain text (xxx...) | 32,694 chars | 32,695 → `ENAMETOOLONG` |\n| Real prompt (quotes, `\\`, XML, `\\n`) | ~28,520 chars | ~29,140 → `ENAMETOOLONG` |\n\n**Conservative threshold adopted: 28,000 chars.**\n\nBefore delegating any task to AGY, the orchestrator assembles the complete prompt and counts the characters. If it exceeds 28,000 chars:\n\n1. Divides the task's deliverables into two independent groups (A and B).\n2. Creates subtasks `<ID>-a` and `<ID>-b`, each covering one group.\n3. Updates `plan/tasks-classification.md` and `plan/waves.md`.\n4. Reassembles the two prompts and validates that each is below the limit.\n5. Records the split in `run/monitoring.md` and `report/workflow-log.md` with original size and reason.\n\nIf the task is monolithic and indivisible by deliverables, the orchestrator tries to reduce `Relevant files and modules` and, as a last resort, records `promptOverflow: true` and requests user decision.\n\n## Quota Policy\n\n### Codex on Implementation, Adjustment or Handoff\n\nIf `QUOTA_EXHAUSTED`:\n\n- mark `BLOCKED`;\n- record evidence;\n- request user decision.\n\nThe orchestrator does not continue editing productive code on its own.\n\n### Codex on Back-end Review\n\nIf `QUOTA_EXHAUSTED`:\n\n- the orchestrator does internal read-only review;\n- saves the result in `review/review-final.md`;\n- does not edit productive code.\n\n### AGY on Front-end Review\n\nIf `QUOTA_EXAUSTED`, `AUTH_REQUIRED`, `AGY_MISSING` or `TIMEOUT`:\n\n- the orchestrator does internal read-only review;\n- saves the result in `review/review-frontend.md`;\n- does not edit productive code.\n\n### Antigravity/AGY on Implementation\n\nContinues with controlled fallback to Codex only when safe. The plugin bridge returns raw status:\n\n- `QUOTA_EXAUSTED`\n- `AUTH_REQUIRED`\n- `TIMEOUT`\n- `AGY_MISSING`\n\nThe orchestrator must record these values as they come from the bridge.\n\n## Mandatory Contracts\n\nContract is mandatory whenever there is data exchange between front-end and back-end.\n\nThis applies to:\n\n- `FULLSTACK` tasks;\n- dependent pairs `BACKEND_ONLY` + `FRONTEND_ONLY`.\n\nIn Phase 2, each task must register `contractRequired: yes|no`.\n\nFor `FRONTEND_ONLY` tasks and front-end slice of `FULLSTACK`, also register:\n\n- `agyModel`\n- `agyModelSource: user|heuristic|adaptive`\n- `agyModelEvidence` when the source is `adaptive`\n\nThe routing validator requires these fields on AGY tasks and fails if:\n\n- an AGY task does not register `agyModel`;\n- `agyModelSource` is missing;\n- `agyModelSource: adaptive` lacks auditable evidence;\n- a heuristic/adaptive decision uses a dynamic slug instead of a stable capability alias, or a user slug is syntactically unsafe;\n- a design-system task (`tokens.css`, `components.html`, `DESIGN.md`) uses a low-tier model;\n- `FRONTEND_ONLY` points to Codex as primary agent;\n- `FRONTEND_ONLY` or `FULLSTACK` delegates implementation to the read-only `antigravity-agent` instead of `antigravity-coder`.\n\nThe validator reads the same task-ID grammar as the State Engine (`T1`, `T12-A`, `BE-01`, `FE-001-B`, never a version suffix like `gemini-3.5`) and recognizes wave entries written as headings, table rows, or list items.\n\nIn Phase 4, the orchestrator creates `contracts/*.md` for every item with `contractRequired: yes`.\n\n## Wire Format and Serialization\n\nEvery contract must document:\n\n- expected JSON casing;\n- exact field names;\n- complete request and response examples;\n- global serializer or serialization attributes when present;\n- validation of real serialization against the TypeScript consumer.\n\nEspecially for C# + TypeScript:\n\n- internal DTO in `PascalCase` is not enough;\n- expected JSON payload in `camelCase` must be documented;\n- compatibility must be validated on actual payload, not just TypeScript types.\n\n## Main Files\n\n- `commands/orchestrator.md`\n- `skills/orchestrator-multi-agent-development/SKILL.md`\n- `skills/orchestrator-multi-agent-development/references/workflow.md`\n- `skills/orchestrator-multi-agent-development/references/persistent-state.md`\n- `skills/orchestrator-multi-agent-development/references/project-knowledge.md`\n- `skills/orchestrator-multi-agent-development/references/programmatic-intelligence.md`\n- `skills/orchestrator-multi-agent-development/references/lifecycle-telemetry.md`\n- `skills/orchestrator-multi-agent-development/references/learning-curator.md`\n- `skills/orchestrator-multi-agent-development/references/worktrees-routing.md`\n- `skills/orchestrator-multi-agent-development/references/hermes-adaptation.md`\n- `skills/orchestrator-multi-agent-development/references/agent-stack.md`\n- `skills/orchestrator-multi-agent-development/references/subagent-prompts.md`\n- `skills/orchestrator-multi-agent-development/references/contracts.md`\n- `skills/orchestrator-multi-agent-development/assets/contract-template.md`\n- `skills/orchestrator-multi-agent-development/assets/monitoring-template.md`\n- `skills/orchestrator-multi-agent-development/assets/implementation-report-template.md`\n- `skills/orchestrator-multi-agent-development/assets/orchestration-state.schema.json`\n- `skills/orchestrator-multi-agent-development/assets/orchestration-event.schema.json`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-state.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestrator-knowledge.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-lifecycle.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-worktree.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-router.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-telemetry.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/orchestration-learning.mjs`\n- `skills/orchestrator-multi-agent-development/scripts/lib/`\n- `scripts/orchestration-state.mjs`\n- `scripts/intelligence/`\n- `tests/*.test.mjs`\n\n## Recommended Validation\n\n```bash\nnode --check skills/orchestrator-multi-agent-development/scripts/preflight.mjs\nnode --check skills/orchestrator-multi-agent-development/scripts/orchestration-state.mjs\nnode scripts/preflight.mjs\nnode skills/orchestrator-multi-agent-development/scripts/validate-routing.mjs .orchestrator/runs/<name>\nnode --test tests/*.test.mjs\nrg --line-number --fixed-strings -- 'QUOTA_EXAUSTED' README.md commands skills\nrg --line-number --fixed-strings -- 'agyModelSource' README.md commands skills\nrg --line-number --fixed-strings -- 'agyParallel' README.md commands skills\nrg --line-number --fixed-strings -- 'pro-high' README.md commands skills\n```\n",
  "bytes": 32401,
  "sha": "6d52c76dc2607503b6a2c0e1728d4efaab10d909b9abf2ec2d629a2511fc77ce",
  "repo_slug": "allanharlen/cc-orchestrador-subagents",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_allanharlen_cc_orchestrador_subagents_cc_8076773a/readme"
}