From 07189b0f867d49bcc8be8af78a5c6aac2d3ceeaa Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 18:44:56 -0700 Subject: [PATCH] docs(ecosystem): add two-way delegation refactor plan --- docs/ecosystem/delegation/README.md | 2 + .../TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md | 201 ++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 docs/ecosystem/delegation/TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md diff --git a/docs/ecosystem/delegation/README.md b/docs/ecosystem/delegation/README.md index 9ed57725..a10d9e8b 100644 --- a/docs/ecosystem/delegation/README.md +++ b/docs/ecosystem/delegation/README.md @@ -11,6 +11,8 @@ - [`codex/PHASE1_INTEGRATION_REVIEW.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation/codex/PHASE1_INTEGRATION_REVIEW.md) - [`windsurf/NOTELETT_PHASE1_VERIFICATION.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation/windsurf/NOTELETT_PHASE1_VERIFICATION.md) - [`cursor/MINDLYST_PHASE1_VERIFICATION.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation/cursor/MINDLYST_PHASE1_VERIFICATION.md) +- [`TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/delegation/TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md) + - review this before refactoring the participant folders into the 3-file communication loop --- diff --git a/docs/ecosystem/delegation/TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md b/docs/ecosystem/delegation/TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md new file mode 100644 index 00000000..461343d3 --- /dev/null +++ b/docs/ecosystem/delegation/TWO_WAY_COMMUNICATION_REFACTOR_PLAN.md @@ -0,0 +1,201 @@ +# Two-Way Delegation Refactor Plan + +> **Status:** Proposed +> **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:** +- **Owner:** +- **Status:** not-started | in-progress | blocked | done +- **Updated at:** +- **Latest commit:** +- **Verification command:** +- **Verification result:** +- **Blocker:** + +## Notes For Reviewer + +- +``` + +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 /TASK.md and /FEEDBACK.md, execute within ownership boundaries, and write progress back to /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`