From 3d59e7bbedada53d6be9779b6f3d8d5f700b0351 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 16:21:04 -0700 Subject: [PATCH] docs: add phase 1 ecosystem execution plan --- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 8 + ...1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md | 237 ++++++++++++++++++ docs/ecosystem/README.md | 1 + 3 files changed, 246 insertions(+) create mode 100644 docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index cce2a8d9..519b2e18 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -137,3 +137,11 @@ Example: - [ ] contract-test strategy needs fixture location and validation tooling decisions These should be resolved before claiming the ecosystem docs are fully implementation-ready. + +--- + +## 5. Active Execution Plan + +Current implementation kickoff document: + +- [`PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md) diff --git a/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md b/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md new file mode 100644 index 00000000..372a3131 --- /dev/null +++ b/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md @@ -0,0 +1,237 @@ +# Phase 1 Execution Plan: Transcript -> Note -> Memory + +> **Status:** Ready for implementation +> **Owner:** `learning_ai_common_plat` +> **Golden Flow:** LysnrAI transcript -> NoteLett note -> MindLyst memory +> **Primary Leads:** Codex for shared-contract and sequencing work, Saravana for final approval and prioritization + +--- + +## 1. Scope + +This phase implements one end-to-end ecosystem flow: + +1. a transcript is created in `learning_voice_ai_agent` +2. that transcript is represented as a shared artifact +3. `learning_ai_notes` consumes it and creates or links a note artifact +4. `learning_multimodal_memory_agents` consumes the transcript/note lineage and creates or proposes a memory artifact +5. canonical events and provenance are preserved across the chain + +This phase is intentionally narrow. It is the first implementation proof for the shared ecosystem contracts. + +--- + +## 2. Repos In Scope + +- [`learning_ai_common_plat`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat) +- [`learning_voice_ai_agent`](/Users/saravana/BytelystAI/learning_ai/learning_voice_ai_agent) +- [`learning_ai_notes`](/Users/saravana/BytelystAI/learning_ai/learning_ai_notes) +- [`learning_multimodal_memory_agents`](/Users/saravana/BytelystAI/learning_ai/learning_multimodal_memory_agents) + +Out of scope for this phase: + +- ActionTrail replay UI +- auth approvals for the flow +- timeline UI +- marketplace work + +--- + +## 3. Implementation Order + +Strict order: + +1. harden shared contracts in `learning_ai_common_plat` +2. implement producer side in `learning_voice_ai_agent` +3. implement note consumer/producer in `learning_ai_notes` +4. implement memory consumer/producer in `learning_multimodal_memory_agents` +5. run cross-repo verification and update tracker + +Do not start product implementation before contract fields and event names are stable enough for Phase 1. + +--- + +## 4. Shared Contract Tasks + +Repo: [`learning_ai_common_plat`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat) + +### 4.1 Artifact contract hardening + +- [ ] finalize the transcript artifact envelope +- [ ] finalize the note artifact envelope expectations +- [ ] finalize the memory artifact envelope expectations +- [ ] define required provenance fields for the flow +- [ ] define `artifact.linked` relation usage for transcript -> note and note -> memory + +### 4.2 Event taxonomy hardening + +- [ ] finalize `capture.transcript.created` +- [ ] finalize `artifact.created` +- [ ] finalize `artifact.linked` +- [ ] finalize `memory.entry.created` +- [ ] add one canonical example payload per event + +### 4.3 Verification/fixture prep + +- [ ] decide fixture location for Phase 1 examples +- [ ] create canonical JSON examples for transcript/note/memory artifacts +- [ ] create canonical JSON examples for the 4 phase-1 events + +Commits: + +- pending + +--- + +## 5. Repo Task Breakdown + +### 5.1 learning_voice_ai_agent + +Repo: [`learning_voice_ai_agent`](/Users/saravana/BytelystAI/learning_ai/learning_voice_ai_agent) + +Implementation tasks: + +- [ ] identify the transcript creation boundary to hook artifact emission +- [ ] map transcript output into the shared artifact envelope +- [ ] emit `capture.transcript.created` +- [ ] attach correlation/session identifiers for downstream consumers +- [ ] expose or persist the artifact in a way downstream consumers can access + +Verification: + +- [ ] transcript artifact matches canonical fixture +- [ ] event payload matches canonical fixture +- [ ] provenance fields are populated + +Commits: + +- pending + +### 5.2 learning_ai_notes + +Repo: [`learning_ai_notes`](/Users/saravana/BytelystAI/learning_ai/learning_ai_notes) + +Implementation tasks: + +- [ ] consume transcript artifact reference or payload +- [ ] create a linked note artifact using the shared envelope +- [ ] emit `artifact.created` +- [ ] emit `artifact.linked` +- [ ] preserve provenance to the originating transcript artifact + +Verification: + +- [ ] note artifact matches canonical fixture +- [ ] link relation is present and correct +- [ ] no transcript provenance is lost + +Commits: + +- pending + +### 5.3 learning_multimodal_memory_agents + +Repo: [`learning_multimodal_memory_agents`](/Users/saravana/BytelystAI/learning_ai/learning_multimodal_memory_agents) + +Implementation tasks: + +- [ ] consume transcript/note lineage +- [ ] create or propose a memory artifact using the shared envelope +- [ ] emit `memory.entry.created` +- [ ] preserve lineage to transcript and note artifacts + +Verification: + +- [ ] memory artifact matches canonical fixture +- [ ] lineage points back to upstream artifacts +- [ ] event payload matches canonical fixture + +Commits: + +- pending + +--- + +## 6. Recommended Commit Sequence + +Use this sequence unless a better dependency split is discovered: + +1. `learning_ai_common_plat` + - contract hardening +2. `learning_ai_common_plat` + - fixture/examples and tracker updates +3. `learning_voice_ai_agent` + - transcript artifact + event emission +4. `learning_ai_notes` + - note artifact + linking +5. `learning_multimodal_memory_agents` + - memory artifact + lineage +6. `learning_ai_common_plat` + - final verification/tracker commit + +This keeps downstream repos aligned to a stable contract before product work lands. + +--- + +## 7. Verification Commands + +The exact commands may evolve by repo, but the evidence should include at least: + +### learning_ai_common_plat + +- [ ] schema/examples validated locally +- [ ] docs/tracker updated + +### learning_voice_ai_agent + +- [ ] relevant backend or product tests covering transcript creation path +- [ ] fixture conformance evidence recorded + +### learning_ai_notes + +- [ ] relevant backend/web tests covering artifact creation/linking path +- [ ] fixture conformance evidence recorded + +### learning_multimodal_memory_agents + +- [ ] relevant backend tests covering memory creation/proposal path +- [ ] fixture conformance evidence recorded + +### Cross-repo + +- [ ] one end-to-end golden flow walkthrough recorded in the tracker +- [ ] commit hashes added for all participating repos +- [ ] residual risks captured + +--- + +## 8. Done Criteria + +This phase is done only when all of the following are true: + +- [ ] transcript artifact exists in canonical shape +- [ ] note artifact exists in canonical shape +- [ ] memory artifact exists in canonical shape +- [ ] required phase-1 events are emitted in canonical form +- [ ] provenance and lineage are preserved +- [ ] tracker has commit links for all participating repos +- [ ] residual gaps are documented + +--- + +## 9. Known Risks + +1. Product repos may have different persistence models that make the artifact handoff uneven. +2. Event emission may be easier than downstream retrieval, so transport or lookup assumptions must stay explicit. +3. Memory creation may need a “proposed” intermediate state rather than immediate durable creation. +4. If the phase-1 event set changes mid-implementation, product repos can drift quickly. + +--- + +## 10. Next Step After Phase 1 + +If this flow succeeds, the next recommended implementation flow is: + +- FlowMonk plan -> ChronoMind routine -> EffoRise habit + +That would validate a second shared seam: planning/time/habits rather than capture/knowledge/memory. diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index a46697e7..b92307c5 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -24,6 +24,7 @@ Recommended structure: - [`ECOSYSTEM_CONTRACT_TEST_STRATEGY.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_CONTRACT_TEST_STRATEGY.md) — how to prevent contract drift across repos - [`ECOSYSTEM_MARKETPLACE_UNIFICATION.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md) — shared marketplace model - [`ECOSYSTEM_PERSONAL_TIMELINE_PRD.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md) — unified user activity stream +- [`PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/PHASE1_TRANSCRIPT_NOTE_MEMORY_EXECUTION_PLAN.md) — execution-ready plan for the first golden flow - [`adoption/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption) — per-product adoption notes Ownership model: