# Two-Way Delegation Refactor Plan

> **Status:** Implemented
> **Owner:** `learning_ai_common_plat`
> **Goal:** Refactor the delegation folders into a stable two-way communication model before broader multi-agent execution.

---

## 1. Current Gaps

The current delegation structure works, but it still has several gaps:

1. `TASK` is not standardized.
   Current task files use custom names like `COORDINATION.md` and `MINDLYST_PHASE1_VERIFICATION.md`, which makes automation and agent expectations inconsistent.

2. There is no dedicated response channel.
   We have task files and feedback logs, but no canonical place for the assigned agent to report:
   - current status
   - latest commit
   - exact verification command run
   - blocker
   - handoff note back to Codex

3. The launcher pattern is one-way.
   The current one-liner tells an agent to read the task file, but not to:
   - read prior feedback
   - write current status back into the repo

4. Review evidence is split between chat and docs.
   Some outcomes are recorded in docs, but the response loop is not yet fully self-contained within the participant folder.

5. File names are not machine-simple.
   Future automation is easier if every participant folder has the same filenames.

---

## 2. Target Folder Model

Each participant folder should use exactly these files:

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

Optional extras can remain for specialized work, but the core communication loop should always use those three files.

---

## 3. File Responsibilities

### `TASK.md`

Owned by Saravana or Codex.

Purpose:

- define the current assignment
- define boundaries
- define required outcome
- define verification command
- define tracker/doc update requirements

This is the instruction channel.

### `STATUS.md`

Owned by the assigned agent while the task is active.

Purpose:

- report `not-started | in-progress | blocked | done`
- record latest commit
- record the exact verification command
- record the exact result
- record blockers
- record notes for reviewer

This is the response channel.

### `FEEDBACK.md`

Owned by Codex after review.

Purpose:

- record review outcome
- record what was good
- record what was wrong
- record process corrections
- record final outcome

This is the review channel.

---

## 4. Proposed Refactor Mapping

### Saravana

- `saravana/COORDINATION.md` -> `saravana/TASK.md`
- add `saravana/STATUS.md`
- keep `saravana/FEEDBACK.md`

### Codex

- `codex/PHASE1_INTEGRATION_REVIEW.md` -> `codex/TASK.md`
- add `codex/STATUS.md`
- keep `codex/FEEDBACK.md`
- keep `codex/PHASE1_CLOSEOUT_CHECKLIST.md` as a specialized support file

### Windsurf

- `windsurf/NOTELETT_PHASE1_VERIFICATION.md` -> `windsurf/TASK.md`
- add `windsurf/STATUS.md`
- keep `windsurf/FEEDBACK.md`

### Cursor

- `cursor/MINDLYST_PHASE1_VERIFICATION.md` -> `cursor/TASK.md`
- add `cursor/STATUS.md`
- keep `cursor/FEEDBACK.md`

---

## 5. STATUS Template

Each `STATUS.md` should use the same structure:

```md
# Status

- **Task:** <path or short name>
- **Owner:** <participant>
- **Status:** not-started | in-progress | blocked | done
- **Updated at:** <UTC timestamp>
- **Latest commit:** <hash or none>
- **Verification command:** <exact command or none>
- **Verification result:** <pass | fail | not-run>
- **Blocker:** <none or exact blocker>

## Notes For Reviewer

- <short notes>
```

This keeps the agent response structured and reviewable.

---

## 6. Launcher Pattern After Refactor

The standard one-liner should become:

```bash
git pull origin main && read <participant>/TASK.md and <participant>/FEEDBACK.md, execute within ownership boundaries, and write progress back to <participant>/STATUS.md
```

This makes the communication loop explicit.

---

## 7. Acceptance Criteria For The Refactor

- [ ] every participant folder has `TASK.md`
- [ ] every participant folder has `STATUS.md`
- [ ] every participant folder has `FEEDBACK.md`
- [ ] old task filenames are removed or renamed cleanly
- [ ] delegation README documents the 3-file loop
- [ ] operating model documents the 3-file loop
- [ ] launcher examples use `TASK.md`, `FEEDBACK.md`, and `STATUS.md`
- [ ] current known state is seeded into at least `cursor/STATUS.md` and `codex/STATUS.md`

---

## 8. Rollout Order

1. rename existing task files to `TASK.md`
2. add `STATUS.md` templates to all participant folders
3. update delegation README
4. update `ECOSYSTEM_AGENT_OPERATING_MODEL.md`
5. update launcher examples
6. seed current state into active participant `STATUS.md` files
7. verify links and folder consistency

---

## 9. Recommendation

This refactor should be done before the next broad multi-agent wave.

Reason:

- it turns the delegation folders into a real communication system instead of a set of one-way prompts
- it reduces ambiguity around completion claims
- it gives Saravana and Codex a durable repo-native audit trail

---

## 10. Commits

- `pending`
