From f18134c7195d945376311e5d4878742b0583e325 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sat, 23 May 2026 12:07:58 -0700 Subject: [PATCH] docs: align ecosystem docs with single-source-of-truth agent pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/ECOSYSTEM_CONSISTENCY_AUDIT.md | 48 ++++++++++++++-------- docs/guides/PLATFORM_ACCELERATION_IDEAS.md | 4 +- docs/guides/PLATFORM_PLAYBOOK.md | 9 ++-- docs/guides/WORKFLOW_SYNC.md | 2 +- docs/learning_ai_common_plat_INVENTORY.md | 6 ++- 5 files changed, 44 insertions(+), 25 deletions(-) diff --git a/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md b/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md index c6e62145..e1ff1052 100644 --- a/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md +++ b/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md @@ -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 | diff --git a/docs/guides/PLATFORM_ACCELERATION_IDEAS.md b/docs/guides/PLATFORM_ACCELERATION_IDEAS.md index 97ac5e49..73de9c7c 100644 --- a/docs/guides/PLATFORM_ACCELERATION_IDEAS.md +++ b/docs/guides/PLATFORM_ACCELERATION_IDEAS.md @@ -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 diff --git a/docs/guides/PLATFORM_PLAYBOOK.md b/docs/guides/PLATFORM_PLAYBOOK.md index f2a31afe..38b26114 100644 --- a/docs/guides/PLATFORM_PLAYBOOK.md +++ b/docs/guides/PLATFORM_PLAYBOOK.md @@ -174,10 +174,11 @@ learning_ai_/ │ └── 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 diff --git a/docs/guides/WORKFLOW_SYNC.md b/docs/guides/WORKFLOW_SYNC.md index 1a041f3d..e504f822 100644 --- a/docs/guides/WORKFLOW_SYNC.md +++ b/docs/guides/WORKFLOW_SYNC.md @@ -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) diff --git a/docs/learning_ai_common_plat_INVENTORY.md b/docs/learning_ai_common_plat_INVENTORY.md index 93b102da..fb5ad318 100644 --- a/docs/learning_ai_common_plat_INVENTORY.md +++ b/docs/learning_ai_common_plat_INVENTORY.md @@ -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) | ---