150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
# Distribution Platform Agent Orchestration
|
|
|
|
This workspace uses a sequential, branch-based agent workflow.
|
|
|
|
## Roles
|
|
|
|
Codex manager:
|
|
|
|
- Owns orchestration, routing, validation, and reporting.
|
|
- Writes run metadata and decision records.
|
|
- Does not implement application code during Opus phases.
|
|
|
|
Snarky:
|
|
|
|
- Writes product proposals and acceptance criteria.
|
|
- Reviews whether Opus satisfies the product requirements.
|
|
- Has final say on product scope and required behavior.
|
|
- Challenges Opus concerns on their merits.
|
|
|
|
Opus:
|
|
|
|
- Owns layout and visual design decisions.
|
|
- Is consulted for technical problems until the manager can drive consensus.
|
|
- Is the only role allowed to write application code.
|
|
- Implements on git branches, not worktrees.
|
|
|
|
## Branch Rules
|
|
|
|
- No parallel implementation agents.
|
|
- No worktrees.
|
|
- Every implementation run uses a named branch, for example:
|
|
- `opus/redesign-distribution-mock`
|
|
- `opus/install-flow-detail`
|
|
- `opus/release-console-ui`
|
|
- The working tree must be clean before Opus implementation starts.
|
|
- Opus implementation receives an explicit `allowedPaths` list.
|
|
- Manager validates the final diff before Snarky approval.
|
|
|
|
## Run Directory Shape
|
|
|
|
Each task gets a durable run directory:
|
|
|
|
```txt
|
|
.agents/runs/<run-id>/
|
|
state.json
|
|
agents.json
|
|
brief.md
|
|
opus-proposal.md
|
|
concerns.json
|
|
snarky-review.md
|
|
decisions.json
|
|
implementation-instructions.md
|
|
progress.log
|
|
implementation-log.md
|
|
validation.md
|
|
final-approval.md
|
|
```
|
|
|
|
Planning and orchestration work also gets a run directory when it should be
|
|
visible in the dashboard. If the manager is only editing files without creating
|
|
`.agents/runs/<run-id>/state.json`, the dashboard cannot show that session.
|
|
|
|
## Agent Recovery
|
|
|
|
Agents are treated as disposable workers. The run directory is the durable
|
|
source of truth.
|
|
|
|
Each active run tracks:
|
|
|
|
- `state.json`: current phase, expected artifact, input hash, retry count, and
|
|
next action.
|
|
- `agents.json`: active role leases, heartbeat timestamps, process/thread ids
|
|
when available, and last known status.
|
|
|
|
Manager responsibilities:
|
|
|
|
- Start one agent phase at a time.
|
|
- Write the phase input before invoking the agent.
|
|
- Record the expected output path.
|
|
- Record a lease timeout for the active role.
|
|
- Poll or wait for completion.
|
|
- Mark the agent dead if the lease expires or the process/tool call fails.
|
|
- Restart the same role with the same input artifact.
|
|
- Refuse to advance phases until the expected output exists and validates.
|
|
|
|
Recovery rules:
|
|
|
|
- Snarky can be recreated from the run brief, decisions, and checkpoint files.
|
|
- Opus proposal/review calls can be retried because they do not edit files.
|
|
- Opus implementation can only be retried after checking branch and dirty state.
|
|
- If an Opus implementation dies with a dirty branch, manager must inspect the
|
|
diff before retrying. Do not blindly overwrite partial code.
|
|
- Retry count is capped. After repeated failure, manager records a blocker and
|
|
asks the user.
|
|
|
|
Recommended lease defaults:
|
|
|
|
- Snarky brief/review: 10 minutes.
|
|
- Opus proposal/review/technical consult: 30 minutes minimum.
|
|
- Opus implementation: 45 minutes minimum.
|
|
|
|
Opus CLI/tool calls must never use a timeout below 30 minutes, even for
|
|
read-only design proposals. If a shorter timeout is accidentally used, record
|
|
the attempt, update the lease, and retry with at least 30 minutes.
|
|
|
|
## Status Command
|
|
|
|
From the workspace root:
|
|
|
|
```sh
|
|
node .agents/scripts/status.mjs --tail 40
|
|
```
|
|
|
|
Browser dashboard:
|
|
|
|
```sh
|
|
node .agents/scripts/observe.mjs --port 4317
|
|
```
|
|
|
|
This prints every recorded run, every recorded agent, lease expiry state,
|
|
blockers, next action, and the tail of the active run progress file. The browser
|
|
dashboard shows the same state and refreshes automatically.
|
|
|
|
Managers should append progress events to `.agents/runs/<run-id>/progress.log`.
|
|
|
|
## Sequential Flow
|
|
|
|
1. Manager creates `.agents/runs/<run-id>/`.
|
|
2. Snarky writes `brief.md`.
|
|
3. Manager calls Opus for `opus-proposal.md`.
|
|
4. Snarky reviews product fit and challenges concerns.
|
|
5. Opus responds to accepted concern challenges.
|
|
6. Manager resolves consensus for technical issues.
|
|
7. Snarky writes `implementation-instructions.md`.
|
|
8. Manager calls Opus implementation on a named branch.
|
|
9. Manager validates the branch diff and checks.
|
|
10. Snarky approves or requests another Opus pass.
|
|
|
|
## Opus Runner Tools
|
|
|
|
The local `opus-runner` plugin exposes:
|
|
|
|
- `opus_branch_status`
|
|
- `opus_propose_design`
|
|
- `opus_review_concern`
|
|
- `opus_solve_technical_issue`
|
|
- `opus_implement_on_branch`
|
|
|
|
Only `opus_implement_on_branch` may enable file editing.
|