docs(ecosystem): add agent operating model
This commit is contained in:
parent
14802d25e4
commit
765568fd44
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
354
docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md
Normal file
354
docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md
Normal file
@ -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`
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user