From 7a86a767b15787f8c7da753700b42d02bf4d402f Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Fri, 3 Apr 2026 16:03:48 -0700 Subject: [PATCH] docs: complete core ecosystem planning set --- .../ECOSYSTEM_IMPLEMENTATION_TRACKER.md | 15 +- .../ECOSYSTEM_MARKETPLACE_UNIFICATION.md | 131 ++++++++++++++++++ docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md | 30 ++-- .../ECOSYSTEM_PERSONAL_TIMELINE_PRD.md | 110 +++++++++++++++ docs/ecosystem/README.md | 4 +- docs/ecosystem/adoption/README.md | 6 + docs/ecosystem/adoption/learning_ai_notes.md | 24 ++++ .../learning_multimodal_memory_agents.md | 24 ++++ .../adoption/learning_voice_ai_agent.md | 24 ++++ 9 files changed, 348 insertions(+), 20 deletions(-) create mode 100644 docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md create mode 100644 docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md create mode 100644 docs/ecosystem/adoption/learning_ai_notes.md create mode 100644 docs/ecosystem/adoption/learning_multimodal_memory_agents.md create mode 100644 docs/ecosystem/adoption/learning_voice_ai_agent.md diff --git a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md index 16a4f18a..2a2a78bc 100644 --- a/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md +++ b/docs/ecosystem/ECOSYSTEM_IMPLEMENTATION_TRACKER.md @@ -49,8 +49,8 @@ Example: | `ECOSYSTEM_OWNERSHIP_MATRIX.md` | in-progress | `learning_ai_common_plat` | temporary four-party ownership model added | pending current commit | | `ECOSYSTEM_VERIFICATION_MATRIX.md` | in-progress | `learning_ai_common_plat` | draft verification model added | pending current commit | | `ECOSYSTEM_CONTRACT_TEST_STRATEGY.md` | in-progress | `learning_ai_common_plat` | draft contract-test model added | pending current commit | -| `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` | not-started | `learning_ai_common_plat` | depends on artifact/runtime conventions | — | -| `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` | not-started | `learning_ai_common_plat` | depends on artifacts + events | — | +| `ECOSYSTEM_MARKETPLACE_UNIFICATION.md` | in-progress | `learning_ai_common_plat` | draft exists, inventory and entitlement details open | pending current commit | +| `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` | in-progress | `learning_ai_common_plat` | draft exists, hosting and filtering decisions open | pending current commit | --- @@ -87,6 +87,15 @@ Example: - [x] Draft contract-test strategy Commits: - pending current commit +- [x] Draft marketplace unification spec + Commits: + - pending current commit +- [x] Draft personal timeline PRD + Commits: + - pending current commit +- [x] Draft first adoption docs for transcript -> note -> memory flow + Commits: + - pending current commit ### First implementation tracks @@ -121,7 +130,7 @@ Example: ## 4. Current Gaps Before Broad Implementation - [ ] event taxonomy needs phase-1 event list hardening -- [ ] no shared adoption docs exist yet under `docs/ecosystem/adoption/` +- [ ] adoption docs exist for the first flow, but broader repo coverage is still missing - [ ] ownership model is temporary and must be revised if the team changes - [ ] verification matrix needs repo-level test ownership - [ ] contract-test strategy needs fixture location and validation tooling decisions diff --git a/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md b/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md new file mode 100644 index 00000000..951feab0 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_MARKETPLACE_UNIFICATION.md @@ -0,0 +1,131 @@ +# Ecosystem Marketplace Unification + +> **Status:** Draft +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define one marketplace model for reusable ecosystem assets across products. + +--- + +## 1. Problem + +Marketplace-like concepts already exist or are implied across the ecosystem: + +- JarvisJr agent marketplace ideas +- Cowork plugin marketplace +- Note templates +- FlowMonk workflows +- ChronoMind routines +- EffoRise programs +- prompt packs, skill packs, department agents + +Without one shared marketplace model: + +- assets are siloed by product +- monetization is fragmented +- entitlement logic is duplicated +- creators cannot publish once and reach multiple products + +--- + +## 2. Goal + +Create one inventory and entitlement model that can support multiple asset types while allowing product-specific presentation. + +--- + +## 3. Canonical Inventory Types + +The marketplace should support at least: + +- `agent` +- `plugin` +- `connector` +- `skill-pack` +- `prompt-pack` +- `workflow-template` +- `note-template` +- `routine-pack` +- `habit-program` +- `review-template` + +Each listing should declare: + +- `listingId` +- `inventoryType` +- `title` +- `summary` +- `publisher` +- `supportedProducts` +- `deliveryMode` +- `version` +- `entitlementModel` + +--- + +## 4. Delivery Modes + +Supported delivery modes should include: + +- config-only +- document/template bundle +- runtime plugin +- connector integration +- agent behavior pack +- prompt or skill bundle + +--- + +## 5. Phase-1 Scope + +Start with these inventory types: + +- [ ] `plugin` +- [ ] `workflow-template` +- [ ] `note-template` +- [ ] `routine-pack` +- [ ] `skill-pack` + +These map directly to existing ecosystem capabilities. + +--- + +## 6. First Adopters + +1. `oss/learning_ai_claw-cowork` +2. `learning_ai_flowmonk` +3. `learning_ai_notes` +4. `learning_ai_clock` +5. `learning_ai_jarvis_jr` + +--- + +## 7. Open Decisions + +1. Should one listing support multiple delivery modes? +2. Should entitlement be product-scoped or ecosystem-scoped by default? +3. How should version compatibility be represented across products? +4. Which assets require review/signing before distribution? + +--- + +## 8. Acceptance Criteria + +1. One creator asset can target more than one product. +2. Platform entitlements can gate access without per-product duplication. +3. Cowork marketplace assets can map into the shared listing model. +4. Product-specific presentation does not require product-specific listing storage. + +--- + +## 9. Implementation Checklist + +- [ ] define canonical listing schema +- [ ] define inventory type taxonomy +- [ ] define entitlement model +- [ ] define compatibility/version model +- [ ] define phase-1 publishing workflow +- [ ] define review/signing requirements + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md index 87535843..50e690df 100644 --- a/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md +++ b/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md @@ -2,7 +2,7 @@ > **Status:** Draft > **Owner Model:** temporary four-party operating model -> **Parties:** User, Codex, Windsurf, Cursor +> **Parties:** Saravana, Codex, Windsurf, Cursor > **Purpose:** Clarify who owns what for ecosystem planning, implementation, review, and tracking. --- @@ -11,7 +11,7 @@ For now, the ecosystem is effectively operated by four parties: -1. **You** +1. **Saravana** Product owner, final technical decider, integration sponsor, and release authority. 2. **Codex** High-power architecture and implementation driver for complex cross-repo work. @@ -26,7 +26,7 @@ This document assumes no larger team structure exists yet. ## 2. Role Definitions -### You +### Saravana Own: @@ -69,16 +69,16 @@ Own: ## 3. Responsibility Matrix -| Work Type | You | Codex | Windsurf | Cursor | -| ---------------------------------- | --- | ----- | -------- | ------ | -| ecosystem strategy | A | R | C | C | -| shared contracts | A | R | C | C | -| cross-repo implementation planning | A | R | C | C | -| high-complexity integration work | A | R | C | I | -| medium repo-local implementation | C | C | R | I | -| low-risk guided edits | C | C | C | R | -| tracker and commit-link hygiene | A | R | C | C | -| final push/go-live decision | A | C | I | I | +| Work Type | Saravana | Codex | Windsurf | Cursor | +| ---------------------------------- | -------- | ----- | -------- | ------ | +| ecosystem strategy | A | R | C | C | +| shared contracts | A | R | C | C | +| cross-repo implementation planning | A | R | C | C | +| high-complexity integration work | A | R | C | I | +| medium repo-local implementation | C | C | R | I | +| low-risk guided edits | C | C | C | R | +| tracker and commit-link hygiene | A | R | C | C | +| final push/go-live decision | A | C | I | I | Legend: @@ -99,7 +99,7 @@ This is not exclusive ownership. It is the default lead bias. | shared contract docs | Codex | | implementation tracker updates | Codex | | product-local adoption docs | Windsurf or Cursor under guidance | -| final prioritization and acceptance | You | +| final prioritization and acceptance | Saravana | --- @@ -108,7 +108,7 @@ This is not exclusive ownership. It is the default lead bias. 1. If a change affects more than one repo or defines a shared contract, Codex should lead. 2. If a change is bounded to one repo and the contract is already clear, Windsurf can lead. 3. Cursor should be used only for narrower, strongly-scoped work until the ecosystem contracts harden further. -4. You remain the final authority on tradeoffs and sequencing. +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. --- diff --git a/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md new file mode 100644 index 00000000..6ce2cd21 --- /dev/null +++ b/docs/ecosystem/ECOSYSTEM_PERSONAL_TIMELINE_PRD.md @@ -0,0 +1,110 @@ +# Ecosystem Personal Timeline PRD + +> **Status:** Draft +> **Owner:** `learning_ai_common_plat` +> **Purpose:** Define a shared user activity timeline that makes cross-product behavior visible and useful. + +--- + +## 1. Problem + +The ecosystem can produce many meaningful user events and artifacts, but users cannot yet see them as one coherent stream. + +Examples: + +- transcript captured in LysnrAI +- note created in NoteLett +- memory created in MindLyst +- plan created in FlowMonk +- routine executed in ChronoMind +- agent run completed in Cowork +- approval granted in Auth App + +Without a personal timeline: + +- the ecosystem feels fragmented +- provenance is hard to understand +- “one action, many outcomes” is invisible + +--- + +## 2. Product Goal + +Give Saravana and future users one place to answer: + +- what happened? +- what created it? +- what did it affect? +- what needs follow-up? + +--- + +## 3. Timeline Inputs + +The timeline should consume: + +- canonical ecosystem events +- canonical artifact envelopes +- approval records +- selected trust/risk changes + +--- + +## 4. Phase-1 User Stories + +- [ ] As a user, I can see that one dictated transcript became a note and a memory candidate. +- [ ] As a user, I can see that one plan generated a routine and a habit. +- [ ] As a user, I can see that one Cowork run produced an output and required an approval. +- [ ] As a user, I can trace each item back to its source product and action. + +--- + +## 5. Minimum Timeline Item Shape + +```ts +type TimelineItem = { + itemId: string; + occurredAt: string; + eventName: string; + productId: string; + title: string; + summary?: string | null; + artifactRefs: string[]; + relatedEventIds: string[]; + actorType: 'user' | 'agent' | 'system' | 'device'; + visibility: 'private' | 'org' | 'shared' | 'local-only'; +}; +``` + +--- + +## 6. Open Decisions + +1. Should the first timeline UI live in admin-web, a new user-facing web shell, or NoteLett/MindLyst? +2. Which events are too noisy for the user-facing timeline? +3. How should local-only events from local-memory products be represented? +4. Should timeline items be materialized or queried live from event/artifact sources? + +--- + +## 7. Acceptance Criteria + +1. The two phase-1 golden flows can be rendered in one unified timeline. +2. Timeline items can link back to underlying artifacts and source products. +3. Users can tell which outputs were created automatically vs manually. +4. Approval and trust transitions can be surfaced when relevant. + +--- + +## 8. Implementation Checklist + +- [ ] define timeline item contract +- [ ] define event-to-timeline inclusion rules +- [ ] define artifact linking behavior +- [ ] define noise filtering rules +- [ ] define phase-1 UI hosting choice +- [ ] define verification flow using golden paths + +Commits: + +- initial draft: pending diff --git a/docs/ecosystem/README.md b/docs/ecosystem/README.md index 03c077dd..a46697e7 100644 --- a/docs/ecosystem/README.md +++ b/docs/ecosystem/README.md @@ -22,8 +22,8 @@ Recommended structure: - [`ECOSYSTEM_OWNERSHIP_MATRIX.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_OWNERSHIP_MATRIX.md) — temporary four-party ownership model - [`ECOSYSTEM_VERIFICATION_MATRIX.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/ECOSYSTEM_VERIFICATION_MATRIX.md) — what “done” means for cross-product features - [`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` — shared marketplace model -- `ECOSYSTEM_PERSONAL_TIMELINE_PRD.md` — unified user activity stream +- [`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 - [`adoption/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption) — per-product adoption notes Ownership model: diff --git a/docs/ecosystem/adoption/README.md b/docs/ecosystem/adoption/README.md index 61de5c87..2b61967d 100644 --- a/docs/ecosystem/adoption/README.md +++ b/docs/ecosystem/adoption/README.md @@ -12,6 +12,12 @@ Recommended file pattern: - `learning_ai_trails.md` - `oss_learning_ai_claw_cowork.md` +Current docs: + +- [`learning_voice_ai_agent.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption/learning_voice_ai_agent.md) +- [`learning_ai_notes.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption/learning_ai_notes.md) +- [`learning_multimodal_memory_agents.md`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem/adoption/learning_multimodal_memory_agents.md) + Each adoption doc should cover: - shared contracts consumed diff --git a/docs/ecosystem/adoption/learning_ai_notes.md b/docs/ecosystem/adoption/learning_ai_notes.md new file mode 100644 index 00000000..308b1d71 --- /dev/null +++ b/docs/ecosystem/adoption/learning_ai_notes.md @@ -0,0 +1,24 @@ +# Adoption: learning_ai_notes + +> **Status:** Draft +> **Owner:** `learning_ai_notes` +> **Ecosystem focus:** transcript -> note -> memory golden flow + +--- + +## Goals + +- consume transcript-derived artifacts +- store note artifacts using the shared envelope +- preserve provenance and downstream memory linking + +## Checklist + +- [ ] accept transcript-linked artifact creation +- [ ] emit canonical note artifact envelope +- [ ] emit `artifact.created` and `artifact.linked` +- [ ] preserve provenance to transcript source + +Commits: + +- pending diff --git a/docs/ecosystem/adoption/learning_multimodal_memory_agents.md b/docs/ecosystem/adoption/learning_multimodal_memory_agents.md new file mode 100644 index 00000000..15eee30e --- /dev/null +++ b/docs/ecosystem/adoption/learning_multimodal_memory_agents.md @@ -0,0 +1,24 @@ +# Adoption: learning_multimodal_memory_agents + +> **Status:** Draft +> **Owner:** `learning_multimodal_memory_agents` +> **Ecosystem focus:** transcript -> note -> memory golden flow + +--- + +## Goals + +- consume note and transcript provenance +- create or propose memory artifacts using the shared envelope +- preserve lineage to upstream sources + +## Checklist + +- [ ] accept transcript and note artifact references +- [ ] emit canonical memory artifact envelope +- [ ] emit `memory.entry.created` +- [ ] preserve lineage to source artifacts + +Commits: + +- pending diff --git a/docs/ecosystem/adoption/learning_voice_ai_agent.md b/docs/ecosystem/adoption/learning_voice_ai_agent.md new file mode 100644 index 00000000..5506c5e9 --- /dev/null +++ b/docs/ecosystem/adoption/learning_voice_ai_agent.md @@ -0,0 +1,24 @@ +# Adoption: learning_voice_ai_agent + +> **Status:** Draft +> **Owner:** `learning_voice_ai_agent` +> **Ecosystem focus:** transcript -> note -> memory golden flow + +--- + +## Goals + +- emit canonical transcript artifacts +- emit canonical capture events +- provide enough provenance for downstream NoteLett and MindLyst consumers + +## Checklist + +- [ ] map transcript output to shared artifact schema +- [ ] emit `capture.transcript.created` +- [ ] include correlation/session IDs for downstream linking +- [ ] document downstream handoff contract to NoteLett and MindLyst + +Commits: + +- pending