# 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

The repo-native communication loop for delegated work is:

- `TASK.md` = instruction channel
- `STATUS.md` = assigned agent response channel
- `FEEDBACK.md` = reviewer channel

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.

For delegated work, agents should read the participant folder under [`docs/ecosystem/delegation/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation) and follow the `TASK.md` / `STATUS.md` / `FEEDBACK.md` loop.

---

## 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

Every active participant folder must also contain:

- `TASK.md`
- `STATUS.md`
- `FEEDBACK.md`

### 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
- the exact verification command was actually run and its result was reported, or
- the remaining blocker is explicit and environmental rather than ambiguous

Adding a script, config file, or test file is not enough by itself. A task is not complete until the agent either:

- runs the required verification command successfully and reports it, or
- reports the exact environmental blocker that prevented the command from running

---

## 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`