From 765568fd441e55ac9a8852720094345faa523454 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 17:53:21 -0700 Subject: [PATCH] docs(ecosystem): add agent operating model --- AGENTS.md | 2 +- .../ECOSYSTEM_AGENT_OPERATING_MODEL.md | 354 ++++++++++++++++++ docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md | 5 + docs/ecosystem/README.md | 1 + 4 files changed, 361 insertions(+), 1 deletion(-) create mode 100644 docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md diff --git a/AGENTS.md b/AGENTS.md index 8609b02f..7efb34c2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ > **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent. > **Repo:** `learning_ai_common_plat` — Shared platform packages + microservices for the ByteLyst ecosystem. -> **See also:** [`README.md`](README.md) for quick start, [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) for full architecture, [`docs/ecosystem/README.md`](docs/ecosystem/README.md) for canonical ecosystem strategy/contract docs. +> **See also:** [`README.md`](README.md) for quick start, [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) for full architecture, [`docs/ecosystem/README.md`](docs/ecosystem/README.md) for canonical ecosystem strategy/contract docs, [`docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md`](docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) for delegation/review/merge process. --- diff --git a/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md b/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md new file mode 100644 index 00000000..f538d53d --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md @@ -0,0 +1,354 @@ +# Ecosystem Agent Operating Model + +> **Status:** Active +> **Owner:** `learning_ai_common_plat` +> **Primary Participants:** Saravana, Codex, Windsurf, Cursor +> **Purpose:** Define how ecosystem work is delegated, reviewed, tracked, approved, and pushed across repositories. + +--- + +## 1. Why This Doc Exists + +`AGENTS.md` is the repo entrypoint for coding agents. + +This document is the detailed operating model behind it. Use this file for: + +- multi-agent delegation rules +- review and merge gates +- commit and tracker update rules +- parallelization rules +- ownership and escalation rules + +If there is a conflict: + +1. Saravana's explicit instruction wins +2. shared contract docs win over repo-local convenience +3. this operating model defines the default execution process + +--- + +## 2. Current Team Model + +For now, ecosystem work is operated by four parties: + +1. `Saravana` + product owner, final technical decider, sequencing authority, and final push/release authority +2. `Codex` + high-power architecture, cross-repo integration, hard problem solving, and final integration review +3. `Windsurf` + medium-power bounded implementation and repo-local follow-through +4. `Cursor` + lower-power narrow implementation help under stronger guidance + +This document assumes no larger engineering org exists yet. + +--- + +## 3. Source Of Truth Hierarchy + +Agents should use the following hierarchy: + +1. [`AGENTS.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/AGENTS.md) + repo entrypoint and constraints +2. [`ECOSYSTEM_IMPLEMENTATION_TRACKER.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md) + execution ledger and current status +3. relevant shared-contract docs in [`docs/ecosystem/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem) +4. repo-local implementation docs in product repos + +Agents must not invent a parallel process outside these docs. + +--- + +## 4. Role Split + +### Saravana + +Own: + +- final priorities +- architecture approval +- repo strategy decisions +- go / no-go decisions +- final push or release approval when needed + +### Codex + +Own: + +- cross-repo architecture +- contract definition and enforcement +- work decomposition +- integration sequencing +- final technical review for cross-repo work +- tracker integrity and commit-link hygiene + +### Windsurf + +Own: + +- bounded repo-local implementation +- repo-local verification loops +- medium-complexity completion work +- local doc updates tied to implementation + +### Cursor + +Own: + +- small, narrow, strongly-scoped edits +- focused tests +- cleanup tasks +- low-risk follow-up changes + +--- + +## 5. Delegation Rules + +### Default Rule + +Delegate by repo or by tightly-bounded concern, never by vague intent. + +Every delegated task must define: + +- goal +- exact repo +- exact file or module ownership +- explicit do-not-touch boundaries +- expected output +- required verification command +- expected tracker/doc update if the task changes completion state + +### What Codex Should Keep + +Codex should keep work local when it: + +- changes shared contracts +- changes event/artifact schemas +- affects more than one repo in coupled ways +- changes security, approval, or trust logic +- changes cross-repo sequencing assumptions +- is on the critical path and cannot wait on sidecar work + +### What Windsurf Should Take + +Windsurf should take tasks that are: + +- bounded to one repo +- already defined by an agreed contract +- medium complexity +- verification-heavy but not architecture-heavy + +Examples: + +- repo-local endpoint wiring +- missing test coverage in one repo +- environment-unblock work in one repo +- repo-local doc/checklist updates after implementation + +### What Cursor Should Take + +Cursor should take tasks that are: + +- narrow +- low-risk +- strongly specified +- unlikely to require architectural judgment + +Examples: + +- adding a focused unit test +- tightening a small route handler +- wiring one missing field through a serializer +- fixing type/lint issues in a bounded file set + +### Do Not Delegate + +Do not delegate: + +- the same unresolved task to multiple agents +- overlapping file ownership +- ambiguous “investigate the whole repo” work unless explicitly scoped +- final integration judgment + +--- + +## 6. Parallelization Rules + +Parallelize only when: + +- task boundaries are clear +- write scopes do not overlap +- the shared contract for that work is already stable enough +- Codex is not blocked on one agent's result for the immediate next step + +Do not parallelize when: + +- multiple agents would touch the same modules +- the contract is still moving +- the work is mostly review rather than implementation +- the next step depends directly on unresolved architectural decisions + +### Current Readiness Rule + +Parallel work is allowed for: + +- bounded Phase 1 completion tasks +- repo-local verification and environment unblocking +- narrow follow-up fixes once Codex defines the slice + +Parallel work is not yet approved for: + +- broad Phase 2 ecosystem rollout +- simultaneous contract redesign across several repos + +--- + +## 7. Review Model + +Every delegated task returns to Codex for review before it is treated as complete. + +Codex reviews for: + +- bugs +- regressions +- contract drift +- missing lineage / provenance +- insufficient verification +- hidden coupling or hardcoded assumptions + +If the task is cross-repo or contract-sensitive, Codex must review it even if the code appears small. + +### Review Outcome Types + +- `approved` + implementation is acceptable as-is +- `approved-with-follow-up` + implementation is acceptable but requires a later non-blocking task +- `changes-required` + implementation is not ready to merge/push + +--- + +## 8. Merge And Push Model + +### Default Sequence + +1. Codex defines the task slice +2. Windsurf or Cursor implements only that slice +3. commit in the affected repo +4. Codex reviews the result +5. if needed, Codex patches remaining gaps +6. tracker/docs are updated with commit links +7. push to `main` + +### Merge Rules + +- use small incremental commits +- prefer one logical change per commit +- do not bundle unrelated repo changes together +- if a change spans repos, each repo should still have its own coherent commit history +- after push, update the tracker with the exact commit hash or GitHub commit link + +### Final Authority + +Saravana remains the final authority on: + +- whether work should proceed +- whether sequencing changes +- whether to stop or defer a track + +--- + +## 9. Tracker Update Rules + +When implementation lands: + +1. update the relevant execution plan +2. update [`ECOSYSTEM_IMPLEMENTATION_TRACKER.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md) +3. add commit hashes or commit links +4. record verification evidence or explicit blockers + +Do not mark work complete unless: + +- code is committed +- verification evidence exists, or +- the remaining blocker is explicit and environmental rather than ambiguous + +--- + +## 10. Standard Task Template + +Use this structure when delegating work to another coding agent: + +```md +Task: + +- Goal: +- Repo: +- Owned files/modules: +- Do not touch: +- Expected code outcome: +- Verification: +- Tracker/doc update required: +``` + +Example: + +```md +Task: + +- Goal: finish Phase 1 NoteLett backend verification +- Repo: learning_ai_notes +- Owned files/modules: backend/src/lib/ecosystem-phase1._, backend/src/modules/ecosystem-phase1/_ +- Do not touch: web/, mobile/, shared ecosystem contracts +- Expected code outcome: tests pass for transcript -> note import path and lineage handling +- Verification: pnpm --filter @notelett/backend run test +- Tracker/doc update required: yes, if verification state changes +``` + +--- + +## 11. Completion Gates + +An ecosystem task is merge-ready only when: + +- the task scope is satisfied +- contract drift has been checked +- verification evidence is attached +- tracker state is updated if completion status changed +- Codex has reviewed the result + +An ecosystem task is fully done only when: + +- pushed commits exist +- docs/tracker reflect the final state +- remaining risks are either closed or explicitly documented + +--- + +## 12. Current Recommended Working Pattern + +For the current ecosystem stage: + +- Saravana sets priorities and approves tradeoffs +- Codex drives architecture and integration +- Windsurf handles repo-local implementation where contracts are already clear +- Cursor handles smaller guided slices + +This is the default operating model until the team structure changes. + +--- + +## 13. Checklist + +- [x] define role split +- [x] define delegation rules +- [x] define review gates +- [x] define merge and push model +- [x] define tracker update rules +- [x] define parallelization rules +- [x] provide a reusable task template + +Commits: + +- `pending` diff --git a/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md index da18275b..19e01a0e 100644 --- a/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md +++ b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md @@ -111,6 +111,10 @@ This is not exclusive ownership. It is the default lead bias. 4. Saravana remains the final authority on tradeoffs and sequencing. 5. Every major ecosystem task should be visible in the tracker with one clear owner. +See also: + +- [`ECOSYSTEM_AGENT_OPERATING_MODEL.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) for the detailed delegation, review, merge, and parallelization process. + --- ## 6. Implementation Checklist @@ -124,3 +128,4 @@ Commits: - `41fa2cd` drafted the initial version - `7a86a76` updated the ownership language to Saravana +- `pending` linked ownership to the detailed operating model diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index 3a9b6e6f..5cceb6a5 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -15,6 +15,7 @@ Recommended structure: - [`ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CROSS_POLLINATION_OPPORTUNITIES.md) — strategy, opportunities, gaps, priorities - [`ECOSYSTEM_IMPLEMENTATION_TRACKER.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md) — canonical execution tracker with checkboxes and commit references +- [`ECOSYSTEM_AGENT_OPERATING_MODEL.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) — delegation, review, merge, and tracker-update process for Saravana, Codex, Windsurf, and Cursor - [`ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_SHARED_ARTIFACT_SCHEMA.md) — canonical artifact model - [`ECOSYSTEM_EVENT_TAXONOMY.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_EVENT_TAXONOMY.md) — shared events and action-log contract - [`ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_AGENT_RUNTIME_CONTRACT.md) — shared session, todo, resume, dispatch semantics