chore(codex): add controlled Spark agents

2026-08-08 09:32:09 +03:00
parent e8729401fd
commit 30c9b8c5fd
5 changed files with 188 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Controlled Codex subagent governance
+
+This repository uses subagents as visible, bounded workers. The primary Sol agent
+remains accountable for requirements, architecture, decisions, integration,
+verification, commits, pushes, deployments, and user communication.
+
+Official references:
+
+- [Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
+- [Codex slash commands](https://learn.chatgpt.com/docs/reference/slash-commands)
+- [Codex workspace analytics](https://learn.chatgpt.com/docs/enterprise/workspace-analytics)
+
+## Available project agents
+
+| Agent | Model | Access | Intended work |
+| --- | --- | --- | --- |
+| `spark_explorer` | `gpt-5.3-codex-spark` | read-only filesystem; external reads by policy | Code-path discovery, Ops reads, contract inventories, test/log triage |
+| `spark_worker` | `gpt-5.3-codex-spark` | workspace write | Small edits within an explicit path allowlist and targeted verification |
+
+Unpinned supporting work defaults to `gpt-5.6-terra` with low reasoning. The
+primary agent must keep demanding or ambiguous work on Sol.
+
+## Hard operating limits
+
+- At most two subagent threads may run concurrently.
+- At most one write-capable subagent may run at a time.
+- Subagents may not create more subagents.
+- Only the primary agent may commit, push, deploy, mutate Ops or another external
+  system, install dependencies, or approve an expanded scope.
+- Parallel writers must never touch overlapping files. The default is one writer.
+- A worker gets one implementation pass and at most one corrective retry.
+- Scope drift, an architectural decision, a required unlisted file, or a second
+  failed verification ends the worker turn and escalates to the primary agent.
+
+## Mandatory task packet
+
+Every delegation must state:
+
+1. Objective: one concrete outcome.
+2. Allowed scope: exact files, directories, or read-only tools.
+3. Forbidden actions: especially external writes, commits, pushes, and deploys.
+4. Acceptance criteria: observable evidence of completion.
+5. Verification: exact checks the worker may run.
+6. Output: a short structured summary, not raw logs.
+
+Full conversation history should not be copied into a worker unless the task
+genuinely requires it. Prefer a compact, self-contained packet.
+
+## User-visible lifecycle
+
+The primary agent announces every delegation before it starts using this ledger:
+
+| Agent | Model | Mode | Task | Allowed scope | State |
+| --- | --- | --- | --- | --- | --- |
+| agent name | pinned model | read or write | bounded objective | paths/tools | planned/running/waiting/completed/interrupted |
+
+The primary agent then:
+
+1. Lists active agents when their state changes or the user asks for status.
+2. Reports completion, interruption, or escalation with the worker's evidence.
+3. Identifies all files changed by workers before integration.
+4. Reviews the diff and performs final verification itself.
+5. Includes a final agent ledger in the user handoff.
+
+The desktop app exposes each subagent thread for inspection. The user can ask the
+primary agent to stop one agent or all agents at any time. The primary agent must
+interrupt the requested threads immediately unless an atomic tool call is already
+finishing.
+
+## Token and usage visibility
+
+Current documented controls are deliberately separated:
+
+- The subagent panel/thread view shows agent count, activity, status, and results.
+- `/status` shows the current chat's context usage and rate limits.
+- Workspace/Codex analytics provide workspace-level aggregated reporting when the
+  account and role expose those dashboards or APIs.
+
+The official Codex documentation does not currently promise an exact real-time
+per-subagent token total in the desktop orchestration panel. Therefore:
+
+- Never invent or estimate a token count and present it as measured.
+- Record the model, agent turns, start/end state, scope, verification, and outcome.
+- If the product exposes measured per-thread usage, report that value verbatim.
+- Treat fewer agents and smaller task packets as the primary token-control tools.
+- Use `/status` inside the relevant agent thread when thread-local context usage is
+  needed and available.
+
+## Escalation policy
+
+- Clear read-heavy work: `spark_explorer`.
+- Clear small implementation: `spark_worker`.
+- Multi-file reasoning, review, or repeated Spark failure: Terra.
+- Architecture, geospatial math, migrations, security, cross-system contracts,
+  final acceptance, and all consequential decisions: primary Sol agent.
+
+Subagents are an optimization mechanism, never a substitute for ownership.