bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align ecosystem docs with single-source-of-truth agent pattern

Browse Source 
Followup to single-source-of-truth migration. Active docs that taught or
described the old 8-file agent-config pattern are updated to reflect the
new architecture.

- docs/ECOSYSTEM_CONSISTENCY_AUDIT.md: update §7 Agent Documentation,
  resolve F19 (ActionTrail missing CLAUDE.md) and F20 (Auth App missing
  agent docs) — both eliminated by the migration. Update §9 consistency
  checklist with new file inventory (AGENTS.md + canonical pointer,
  thin copilot pointer, legacy files removed across all 17 active repos).

- docs/learning_ai_common_plat_INVENTORY.md: replace deleted
  AI.dev/SKILLS/update-agent-docs.md with agent-behavior-guidelines.md
  and agent-onboarding.md entries. Add check-agent-docs-drift.sh to the
  scripts table.

- docs/guides/PLATFORM_PLAYBOOK.md: update new-product scaffold tree to
  show the 4 canonical files (AGENTS.md + 3 auto-generated derivatives),
  drop CLAUDE.md/.cursorrules/.windsurfrules.

- docs/guides/PLATFORM_ACCELERATION_IDEAS.md: update create-app CLI
  description to reference the canonical pointer + derived files.

- docs/guides/WORKFLOW_SYNC.md: clarify what /repo_update-agent-docs does.

Historical/completed roadmaps in docs/roadmaps/completed/ are left as-is —
they accurately describe state at the time and editing them would rewrite
history.
This commit is contained in:
saravanakumardb1 2026-05-23 12:07:58 -07:00
parent 088a9cabd6
commit f18134c719
5 changed files with 44 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/ECOSYSTEM_CONSISTENCY_AUDIT.md
View File

@ -230,19 +230,35 @@ JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SD
## 7. Agent Documentation
### File Presence Matrix
> **Migrated (May 2026) to single-source-of-truth pattern.** Behavior rules
> live in one canonical file:
> `learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`.
> Per-repo `AGENTS.md` references it via an auto-managed pointer block.
> Legacy files (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`)
> have been deleted across all repos — they duplicated AGENTS.md content and
> drifted.
| File | Present (of 13) | Missing |
| ---------------- | --------------- | ------------------------------ |
| `AGENTS.md` | 13/13 ✅ | — |
| `CLAUDE.md` | 11/13 | ActionTrail, ByteLyst Auth App |
| `.windsurfrules` | 12/13 | ByteLyst Auth App |
| `.cursorrules` | 12/13 | ByteLyst Auth App |
### File Presence Matrix (post-migration)
| Finding | Severity |
| -------------------------------------------------------------------------- | --------- |
| **F19: ActionTrail missing CLAUDE.md** | 🟢 Low |
| **F20: ByteLyst Auth App missing CLAUDE.md, .windsurfrules, .cursorrules** | 🟡 Medium |
| File | Present (of 17 active) | Notes |
| --------------------------------- | ---------------------- | ------------------------------------------- |
| `AGENTS.md` | 17/17 ✅ | Hand-maintained; canonical pointer prepended |
| `.github/copilot-instructions.md` | 17/17 ✅ | Thin pointer, auto-generated |
| `.aider.conf.yml` | 17/17 ✅ | Aider config, auto-generated |
| `.editorconfig` | 17/17 ✅ | Auto-generated |
| `CLAUDE.md` | 0/17 ✅ | **Deprecated** (deleted) |
| `.cursorrules` | 0/17 ✅ | **Deprecated** (deleted) |
| `.windsurfrules` | 0/17 ✅ | **Deprecated** (deleted) |
| `.clinerules` | 0/17 ✅ | **Deprecated** (deleted) |
F19 and F20 are now **resolved** by the migration — ActionTrail and ByteLyst
Auth App no longer need the legacy files. Drift is enforced via
`scripts/check-agent-docs-drift.sh`.
| Finding | Status |
| -------------------------------------------------------------------------- | --------------------- |
| ~~F19: ActionTrail missing CLAUDE.md~~ | ✅ Resolved (deleted) |
| ~~F20: ByteLyst Auth App missing CLAUDE.md, .windsurfrules, .cursorrules~~ | ✅ Resolved (deleted) |
---
@ -269,7 +285,7 @@ JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SD
| F14 | ChronoMind web missing product-config.ts | Create product-config.ts |
| F15 | Only 3 webs import @bytelyst/design-tokens | Add to remaining webs |
| F16 | LysnrAI + MindLyst CI disabled | Re-enable ci.yml |
| F20 | ByteLyst Auth App missing agent docs | Add CLAUDE.md, .windsurfrules, .cursorrules |
| ~~F20~~ | ByteLyst Auth App missing agent docs | ✅ Resolved by single-source migration |
### Low / Informational
@ -281,7 +297,7 @@ JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SD
| F9 | MindLyst no Tailwind | Intentional per AGENTS.md |
| F17 | Auth App no CI | Minimal repo, mostly native |
| F18 | 5 repos no Docker | Not all repos need containerization yet |
| F19 | ActionTrail missing CLAUDE.md | Low priority doc gap |
| ~~F19~~ | ActionTrail missing CLAUDE.md | ✅ Resolved by single-source migration |
---
@ -301,8 +317,8 @@ JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SD
| Web `product-config.ts` | ⚠️ 7/8 (ChronoMind missing) |
| iOS `Platform/` directory | ✅ 4/5 (ChronoMind valid alternative) |
| Android kotlin-platform-sdk | ✅ All 3 Android apps |
| `AGENTS.md` | ✅ 13/13 |
| `CLAUDE.md` | ⚠️ 11/13 |
| `.windsurfrules` + `.cursorrules` | ⚠️ 12/13 |
| `AGENTS.md` + canonical pointer | ✅ 17/17 |
| `.github/copilot-instructions.md` | ✅ 17/17 (thin pointer, auto-generated) |
| Legacy agent files removed | ✅ 17/17 (CLAUDE.md, .cursorrules, .windsurfrules, .clinerules) |
| GitHub Actions CI | ⚠️ 8/12 active |
| `shared/product.json` | ⚠️ Inconsistent schemas across older/newer repos |

4
docs/guides/PLATFORM_ACCELERATION_IDEAS.md
View File

@ -55,7 +55,7 @@ A CLI tool (`npx @bytelyst/create-app` or `pnpm dlx @bytelyst/create-app`) that:
2. Generates the entire repo structure
3. Wires all `src/lib/` files with correct product ID
4. Creates `.env.example` with all required vars
5. Generates AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules from a template
5. Generates AGENTS.md from the template + canonical pointer to `agent-behavior-guidelines.md`
6. Creates `package.json` with correct `file:` refs
7. Initializes git, creates first commit
@ -117,7 +117,7 @@ $ npx @bytelyst/create-app
✓ Created learning_ai_focuspal/
✓ Generated web/ with Next.js 16 + @bytelyst/* wiring
✓ Generated ios/ scaffold with TelemetryService + PlatformSyncManager
✓ Generated AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules
✓ Generated AGENTS.md (+ derived .github/copilot-instructions.md, .aider.conf.yml, .editorconfig)
✓ Registered product "focuspal" in platform-service
✓ Seeded default feature flags for focuspal
✓ Added to workspace backup scripts

9
docs/guides/PLATFORM_PLAYBOOK.md
View File

@ -174,10 +174,11 @@ learning_ai_<codename>/
│ └── roadmap.md # Implementation roadmap
├── scripts/
│ └── docker-prep.sh # Copy from any existing product repo
├── AGENTS.md # AI agent instructions (copy + customize template)
├── CLAUDE.md # Symlink or copy of AGENTS.md
├── .cursorrules # Symlink or copy of AGENTS.md
├── .windsurfrules # Symlink or copy of AGENTS.md
├── AGENTS.md # AI agent instructions (hand-maintained; canonical pointer auto-prepended)
├── .github/
│ └── copilot-instructions.md # Thin pointer (auto-generated by update-agent-docs.sh)
├── .aider.conf.yml # Aider config (auto-generated)
├── .editorconfig # Editor config (auto-generated)
├── .gitignore
├── .env.example
└── README.md

2
docs/guides/WORKFLOW_SYNC.md
View File

@ -177,4 +177,4 @@ If a workflow was edited independently in two repos:
- `/refresh-chat-history` — Archive refresh workflow
- `/repo_sync-repos` — Pull latest from all repos
- `/repo_update-agent-docs` — Regenerate AGENTS.md, CLAUDE.md, etc.
- `/repo_update-agent-docs` — Regenerate AGENTS.md pointer + derived agent files (single-source-of-truth pattern)

6
docs/learning_ai_common_plat_INVENTORY.md
View File

@ -401,7 +401,8 @@ Workflow scripts for AI agents and developers:
| `test-desktop-app.md` | Desktop app testing |
| `test-ios-app.md` | iOS testing in Simulator |
| `test-strategies.md` | Testing patterns |
| `update-agent-docs.md` | Regenerate AGENTS.md, CLAUDE.md, etc. |
| `agent-behavior-guidelines.md` | Canonical agent behavior rules (Karpathy + ByteLyst) |
| `agent-onboarding.md` | Read-order index for agents |
---
@ -424,7 +425,8 @@ Workflow scripts for AI agents and developers:
| `setup-husky.sh` | Setup Git hooks |
| `switch-network.sh` | Switch between corporate/home network |
| `sync-workflows.sh` | Sync workflows across repos |
| `update-agent-docs.sh` | Regenerate AGENTS.md, CLAUDE.md across repos |
| `update-agent-docs.sh` | Regenerate AGENTS.md pointer + derived files across repos |
| `check-agent-docs-drift.sh` | Verify single-source-of-truth invariants (CI gate) |
---