refactor: semantic-compression of orchestrator.md (-17.7% context, behavior preserved) + extracted references
This commit is contained in:
Your Name
+390
-735
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,233 @@
|
||||
# Operations Reference — Orchestrator Lifecycle & Environment
|
||||
|
||||
**For:** the Orchestrator (and any specialist performing a setup or post-work lifecycle action that fires OFF the mainline decision loop).
|
||||
**Read when:** the orchestrator brief points here, or you are doing one of: environment/setup verification, conflict resolution, learning/memory storage, improvement proposals, scope escalation.
|
||||
**Location:** `docs/OPERATIONS_REFERENCE.md` — the single lifecycle/operations reference for orchestrator actions that fire off the mainline loop. Bodies extracted from `agents/orchestrator.md` during the 2026-09-12 semantic-compression refactor; stewarded by Maintainer thereafter.
|
||||
|
||||
Contents: Environment and Setup · Conflict Resolution · Learning and Memory Storage · Improvement Proposals · Scope Expansion Protocol.
|
||||
|
||||
---
|
||||
|
||||
## 1. Environment and Setup
|
||||
|
||||
(origin: orchestrator "Agent Availability in This Environment")
|
||||
|
||||
This is a custom opencode setup. Agent definitions live in
|
||||
`~/.config/opencode/agents/` (global, loaded at startup); a staging copy may
|
||||
exist in `<repo>/opencode_helper/` — when present, keep both in sync after
|
||||
every edit.
|
||||
|
||||
Roster — all fourteen team agents are dedicated definitions:
|
||||
|
||||
- `orchestrator` — `mode: primary` (user-invoked coordination layer)
|
||||
- `explorer`, `builder`, `breakdowner`, `detective`, `philosopher`, `designer`, `tester`,
|
||||
`toolsmith`, `maintainer`, `writer`, `architect`, `workflow-architect`,
|
||||
`reviewer` — `mode: subagent` (dedicated, Task-dispatchable specialists)
|
||||
|
||||
Config is loaded once at startup and is not hot-reloaded. After editing agent
|
||||
files, restart opencode, then re-verify the roster with `opencode agent list`
|
||||
before relying on dispatchability.
|
||||
|
||||
Global runtime: always resolve via `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"`. Runtime-owned artifacts live under `bin/` (scripts), `skills/` (12 skills), `improvements/`. Project-scoped artifacts (`memory/`, `.opencode/`, `./AgentsReport/`) stay relative to this project.
|
||||
|
||||
---
|
||||
|
||||
## 2. Conflict Resolution
|
||||
|
||||
(origin: orchestrator "Conflict Resolution")
|
||||
|
||||
When specialist outputs disagree:
|
||||
|
||||
1. Preserve both claims.
|
||||
2. Identify exactly what conflicts.
|
||||
3. Prefer primary evidence over inference.
|
||||
4. Route the unresolved technical question to the specialist whose role owns it.
|
||||
5. Use Architect when the disagreement is about design, ownership, or boundaries.
|
||||
6. Do not merge incompatible conclusions into a vague compromise.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
Explorer vs Detective disagreement about system behavior
|
||||
→ Detective establishes runtime cause if needed
|
||||
|
||||
Detective vs Architect disagreement about intended remedy
|
||||
→ Architect owns the design decision
|
||||
|
||||
Designer vs Architect disagreement about user-facing structure
|
||||
→ Designer owns user experience; Architect owns technical constraints
|
||||
→ If conflict persists, Orchestrator coordinates resolution
|
||||
|
||||
Builder vs approved scope disagreement
|
||||
→ Architect resolves scope/design boundary
|
||||
|
||||
Maintainer vs Toolsmith disagreement about prevention
|
||||
→ choose based on whether the problem is systemic restoration or mechanical prevention
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Learning and Memory Storage (after work)
|
||||
|
||||
(origin: orchestrator "Learning and Memory Storage (after work)")
|
||||
|
||||
After completing substantial work, the Orchestrator performs a brief learning cycle:
|
||||
|
||||
### 1. Review
|
||||
|
||||
```text
|
||||
What happened? → summarize key events
|
||||
What was learned? → extract reusable knowledge
|
||||
What failed? → identify root causes and prevention
|
||||
```
|
||||
|
||||
### 2. Classify
|
||||
|
||||
- Is this a **decision** (architectural or technical choice)? → `memory/decisions/`
|
||||
- Is this a **lesson** (reusable knowledge)? → `memory/lessons/`
|
||||
- Is this a **failure** (root cause + prevention)? → `memory/failures/`
|
||||
- Is this **session state** (work in progress)? → `memory/sessions/`
|
||||
|
||||
### 3. Store
|
||||
|
||||
Use `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/bin/memory-lifecycle.sh store <category> <file>` to persist entries.
|
||||
Format entries using the templates in each category's `README.md`.
|
||||
|
||||
### 4. Update session
|
||||
|
||||
For long-running tasks, update the session record with current state so work
|
||||
survives context compaction. (This is the "Long-horizon persistence" rule's
|
||||
post-work hook — see orchestrator "Evidence-First State and Handoff Discipline".)
|
||||
|
||||
### 5. Identify improvements (optional)
|
||||
|
||||
If the work revealed a recurring problem, missing skill, or process inefficiency,
|
||||
create an improvement proposal in `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/improvements/pending/`. **Do not modify core
|
||||
agent behavior without human approval.**
|
||||
|
||||
Storage rules (store selectively — not every tool call or conversation belongs in memory; no trivial discoveries; entries evidence-backed; preserve existing memory; never task-specific noise as durable knowledge): canonical location is the Orchestrator's "Memory vs Task State" section in `agents/orchestrator.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Improvement Proposals
|
||||
|
||||
(origin: orchestrator "Improvement Proposals")
|
||||
|
||||
At the end of substantial work, detect potential improvements. The detection is
|
||||
evidence-driven and triggered by patterns, not by every task:
|
||||
|
||||
### When a proposal is warranted
|
||||
|
||||
Write a proposal to `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/improvements/pending/` when ANY of these fire:
|
||||
|
||||
1. **Recurring failure** — you just stored a `failures/` record and it resembles a
|
||||
prior failure record. A failure that repeats is a system problem, not a task
|
||||
outcome. This is a strong signal to propose a Toolsmith safeguard or a
|
||||
regression test.
|
||||
2. **Missing skill** — a specialist had to improvise a methodology that no
|
||||
existing skill covers. Propose adding a skill.
|
||||
3. **Routing inefficiency** — an agent was dispatched and the task would have been
|
||||
cheaper as a direct tool call (or a different agent). Propose a routing rule
|
||||
change.
|
||||
4. **Documentation gap** — several agents independently re-derived the same
|
||||
convention that should have been documented. Propose a docs/knowledge fix.
|
||||
5. **Process friction** — the same multi-step manual sequence recurred in this
|
||||
task and would recur again. Propose automation.
|
||||
6. **New proven pattern** — a specialist discovered a genuinely reusable pattern.
|
||||
Propose capturing it as a skill or lesson.
|
||||
|
||||
### Detection flow
|
||||
|
||||
```text
|
||||
REVIEW: "What happened?"
|
||||
LEARN: "What was learned?"
|
||||
CHECK MEMORY: "Have I seen this before?" → recall failures/lessons for the class
|
||||
ANALYZE: "Is this one-time or recurring?"
|
||||
PROPOSE: "What should change to prevent the class?"
|
||||
STORE: "Lesson/failure stored in memory?"
|
||||
APPROVAL: "Does the change touch core behavior?" → if yes, proposal not edit
|
||||
```
|
||||
|
||||
### Proposal format
|
||||
|
||||
```text
|
||||
improvements/pending/YYYY-MM-DD_<short-id>.md
|
||||
|
||||
# Proposal: <title>
|
||||
## Observed problem
|
||||
<what went wrong or what is inefficient>
|
||||
## Evidence
|
||||
<files, commands, outputs, memory records that prove it>
|
||||
## Root cause
|
||||
<why it happens — established, not guessed>
|
||||
## Proposed change
|
||||
<what should change: add skill / improve routing / add guardrail / etc.>
|
||||
## Scope
|
||||
<what is touched, what is explicitly out of scope>
|
||||
## Risks
|
||||
<what could go wrong with the change>
|
||||
## Verification plan
|
||||
<how the change will be validated if approved>
|
||||
## Approval status
|
||||
PENDING (awaiting human review)
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Do NOT silently rewrite agent prompts, skills, or architecture.
|
||||
- Do NOT modify core behavior without human approval — proposals live in
|
||||
`"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/improvements/pending/` until a human reviews them.
|
||||
- Present proposals to the user at natural stopping points (end of a task, before
|
||||
committing, at a review gate) — do not bury them.
|
||||
- Proposals are decisions, not actions: writing one does not implement it.
|
||||
- If the same proposal class recurs across multiple tasks, surface it as a
|
||||
coordination blocker rather than re-proposing silently.
|
||||
- Improvements that touch memory storage or skills are also proposals; the act of
|
||||
*using* memory/skills is allowed, but changing the systems themselves needs
|
||||
approval.
|
||||
|
||||
---
|
||||
|
||||
## 5. Scope Expansion Protocol
|
||||
|
||||
(origin: orchestrator "Scope Expansion Protocol")
|
||||
|
||||
Stop and escalate when coordination would require the Orchestrator to decide something outside its coordination authority, including:
|
||||
|
||||
- inventing a new architectural direction
|
||||
- overriding an Architect decision without new evidence
|
||||
- authorizing Builder to exceed approved scope
|
||||
- merging conflicting requirements without user/Architect authority
|
||||
- concealing a failed specialist result to preserve momentum
|
||||
- expanding the task into unrelated work
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
Status: BLOCKED_BY_DECISION
|
||||
|
||||
Original objective:
|
||||
<task>
|
||||
|
||||
Current state:
|
||||
<what has been completed>
|
||||
|
||||
Discovered:
|
||||
<new issue/conflict>
|
||||
|
||||
Why coordination alone is insufficient:
|
||||
<concrete reason>
|
||||
|
||||
Affected work:
|
||||
<agents/components>
|
||||
|
||||
Decision required:
|
||||
Architect | User | Specialist
|
||||
|
||||
Changes made outside scope:
|
||||
none
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*End of Operations Reference. Summary of extraction origins for maintainers: §1 ← orchestrator §5 (env facts); §2 ← orchestrator §21; §3 ← orchestrator §26 (storage rules canonical in orchestrator "Memory vs Task State"); §4 ← orchestrator §27; §5 ← orchestrator §29.*
|
||||
@@ -42,6 +42,16 @@ The bootstrap is **idempotent**: running it multiple times does not overwrite
|
||||
manually enriched content. Only files generated by the bootstrap tool are
|
||||
regenerated, and only when the staleness fingerprint changes.
|
||||
|
||||
## Bootstrap tool (fallback procedure)
|
||||
|
||||
The accompanying script `"${OPENCODE_DEV_AGENT_TEAM:-$HOME/.config/opencode/dev-agent-team}"/bin/repo-bootstrap.sh` (in this team's distribution)
|
||||
performs the mechanical work: scaffolding `.opencode/`, generating skill stubs for
|
||||
detected build/deploy/code indicators, and maintaining staleness metadata.
|
||||
|
||||
If the script is not available at the expected path, perform the equivalent steps
|
||||
inline: check `.opencode/.bootstrap-meta` for fingerprint freshness, create
|
||||
missing skill directories, and never overwrite manually enriched files.
|
||||
|
||||
## .opencode structure
|
||||
|
||||
After a successful bootstrap, the repository looks like this:
|
||||
@@ -154,6 +164,26 @@ When an agent makes a durable discovery that should persist beyond the session:
|
||||
4. This freezes the file as manual content — future bootstrap runs will not
|
||||
overwrite it.
|
||||
|
||||
## Knowledge lifecycle
|
||||
|
||||
Repository knowledge must be concise, evidence-backed, discoverable, updateable,
|
||||
versionable, and resistant to staleness.
|
||||
|
||||
- Knowledge lives in `.opencode/` skills (e.g. `architecture`, `build-and-test`,
|
||||
`conventions` play the role of the `knowledge/architecture.md`,
|
||||
`knowledge/build.md`, `knowledge/conventions.md` files). Do NOT create separate
|
||||
`knowledge/` or `state/` directories unless a concrete need appears — the
|
||||
existing skills + `AgentsReport/` already separate durable repo knowledge from
|
||||
task state.
|
||||
- When new durable facts are discovered: (1) decide whether they belong in
|
||||
repository knowledge, (2) identify the correct knowledge owner (ownership
|
||||
table), (3) update only that document, (4) preserve valid existing
|
||||
information, (5) never record temporary task details as permanent knowledge.
|
||||
- Stale `.opencode/` content is detected by the bootstrap fingerprints; when a
|
||||
manual fact is disproven by the repository, the owning agent corrects it
|
||||
(Maintainer for conventions, Architect for architecture, Explorer for context,
|
||||
Builder/Tester for build-and-test).
|
||||
|
||||
## Example: freshly initialized repository
|
||||
|
||||
Running `repo-bootstrap.sh bootstrap` in a Node.js project with Docker:
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
# Failure: orchestrator compression anchor matrix omitted test-path-resolution T01 canonical runtime sentence
|
||||
|
||||
- **Date**: 2026-09-12
|
||||
- **Project**: dev_agent_team
|
||||
- **What happened**: The semantic-compression refactor of `agents/orchestrator.md` extracted the canonical runtime sentence's second/third clauses (`Runtime-owned artifacts live under ...`, `Project-scoped artifacts (...) stay relative to this project.`) to `docs/OPERATIONS_REFERENCE.md:31`, leaving only the first clause in orchestrator.md:93. `scripts/test-path-resolution.sh T01` greps `agents/*.md` for the FULL byte-exact sentence, so it failed (`missing: orchestrator.md`), making `bash scripts/test-all.sh` 7/8.
|
||||
- **Root cause**: The Architect decision C anchor matrix enumerated 62 test anchors (T01–T17 fixed, sibling suites) but did NOT include test-path-resolution T01's canonical runtime sentence as a load-bearing byte string, even though it is asserted against `agents/*.md` by a different suite (the compression scope listed test-agent-architecture T01–T09/T13–T15/T17, test-integration I06–I08/I11/I12, memory T08/T09, repo T05 — path-resolution T01 was not among the enumerated exercising suites).
|
||||
- **Prevention**: When compressing any `agents/*.md` prompt, first enumerate ALL `grep -qF` byte strings asserted against that file across ALL test suites (including test-path-resolution, test-install, test-runtime), not only the suites the brief names. Verify `test-path-resolution T01` stays green pre-commit.
|
||||
- **Status**: closed 2026-09-12 — full byte-exact canonical sentence restored at orchestrator.md:93; `test-path-resolution T01` PASS; `test-all.sh` 8/8 (105 checks). Lesson for future compression tasks: enumerate ALL grep-asserted byte strings across ALL suites before extraction.
|
||||
Reference in New Issue
Block a user