saravanakumardb1 088a9cabd6 fix(agent-docs): update AI.dev guides + script UX after single-source migration

Followup audit of the single-source-of-truth agent-docs rollout. Several
AI.dev prompts and skills still taught agents the old 8-file pattern (which
would re-introduce drift) and the generator script emitted a misleading
summary in --no-commit mode.

AI.dev guides:
- Delete AI.dev/SKILLS/update-agent-docs.md — entire doc taught the old
  8-file pattern. Canonical reference is now
  .windsurf/workflows/repo_update-agent-docs.md.
- AI.dev/SKILLS/index.md + README.md: replace dangling 'Update Agent
  Documentation' link with pointers to agent-behavior-guidelines.md,
  agent-onboarding.md, and the workflow doc.
- AI.dev/SKILLS/scan-repo-context.md: remove instructions to read
  .windsurfrules / write .cursorrules. Point at the canonical behavior file.
- AI.dev/PROMPTS/new-product-scaffold.md: remove .windsurfrules and CLAUDE.md
  from the scaffold tree. Add deprecated-files callout + regeneration hint.
- AI.dev/PROMPTS/agents-md-sync.md: drop 'Step 4 update CLAUDE.md', point at
  the generator instead. Remove CLAUDE.md from `git add`.
- AI.dev/PROMPTS/ecosystem-audit.md: replace 'CLAUDE.md exists?' with
  'canonical-behavior-pointer block present? legacy files absent?'.

Script UX:
- scripts/update-agent-docs.sh: stop printing 'All repos already in sync'
  when --no-commit suppressed commits or --dry-run was used. Emit accurate
  per-mode summaries instead.

2026-05-23 12:06:28 -07:00

4.3 KiB

Raw Blame History

name	description	argument-hint	agent
ecosystem-audit	Run a full health audit across the ByteLyst ecosystem — builds, tests, types, dependencies, config drift, and produce an actionable dashboard.	Depth and focus, e.g. "full audit", "quick health check", "backend focus", "config drift only"	agent

Ecosystem Audit Prompt

Produce a comprehensive health dashboard across all ByteLyst repos with actionable findings.

Context — ByteLyst Ecosystem

37 repos in D:\BYTELYST\CODE\, including:

Core platform:

learning_ai_common_plat — shared packages + services

Active products (with backends):

learning_ai_efforise (EffoRise, port 4020)
learning_ai_flowmonk (FlowMonk, port 4017)
learning_ai_dev_intelli (DevIntelli, port 4021)
learning_ai_peakpulse (PeakPulse, port 4010)
learning_ai_clock (ChronoMind, port 4011)
learning_ai_jarvis_jr (JarvisJr, port 4012)
learning_ai_fastgap (NomGap, port 4013)
learning_multimodal_memory_agents (MindLyst, port 4014)

Active products (platform-only):

learning_ai_auth_app (ByteLyst Auth — no backend)
learning_ai_notes (NoteLett)
learning_ai_trails (ActionTrail)

Tooling & infrastructure:

learning_ai_local_llms, learning_ai_local_memory_gpt
learning_windsurf_setup, learning_claude_code_setup, learning_sidecar_setup
learning_agent_monitoring_fx, learning_agentic_tools_portal

Audit Dimensions

1. Build Health

For each repo with a package.json:

pnpm install --frozen-lockfile  # Can deps resolve?
pnpm build                       # Does it compile?

2. Type Safety

pnpm typecheck                   # TypeScript clean?

3. Test Health

pnpm test --run                  # All tests pass?

Record: total tests, passing, failing, skipped.

4. Config Consistency

Check alignment across repos:

.npmrc matches canonical template?
.nvmrc specifies Node 22?
tsconfig.json extends base correctly?
.editorconfig present?
shared/product.json correct?
.env.example up to date?

5. Package Version Alignment

Verify shared deps are on compatible versions:

TypeScript, Zod, Fastify, Vitest, React, Next.js
@bytelyst/* packages (all on workspace:* or file:)

6. Security

pnpm audit
# Check for high/critical vulnerabilities

7. Documentation Currency

AGENTS.md exists and matches current layout?
AGENTS.md contains the canonical-behavior-pointer block? (bash scripts/check-agent-docs-drift.sh)
README.md has setup instructions?
Legacy agent files removed? (.cursorrules, .windsurfrules, .clinerules, CLAUDE.md — replaced by single-source-of-truth pattern)

8. Git Hygiene

Any repos with uncommitted changes?
Any repos behind remote?
Any repos with merge conflicts?

Output: Ecosystem Dashboard

# ByteLyst Ecosystem Health Dashboard
> Generated: <date>

## Executive Summary
- Repos audited: N
- 🟢 Healthy: N
- 🟡 Issues: N
- 🔴 Critical: N

## Scorecard

| Repo | Build | Types | Tests | Config | Deps | Security | Docs | Git |
|------|-------|-------|-------|--------|------|----------|------|-----|
| common_plat | ✅ | ✅ | 876/876 | ✅ | ✅ | ✅ | ✅ | clean |
| efforise | ✅ | ✅ | 65/65 | ✅ | ✅ | ⚠️ 2 | ✅ | clean |
| flowmonk | ✅ | ⚠️ 3 | 196/196 | ✅ | ✅ | ✅ | ✅ | dirty |
| ... | | | | | | | | |

## Critical Issues (Fix First)
| Repo | Issue | Impact | Fix |
|------|-------|--------|-----|

## Action Queue (Prioritized)
| # | Repo | Action | Effort | Impact |
|---|------|--------|--------|--------|
| 1 | ... | ... | S/M/L | High/Med/Low |

## Config Drift Report
| Config | Expected | Drifted Repos |
|--------|----------|--------------|
| .npmrc | canonical template | <list> |
| .nvmrc | "22" | <list> |

## Dependency Alignment
| Package | Version | Aligned | Misaligned |
|---------|---------|---------|-----------|

Execution Tips

Start with common_plat — it's the foundation
Skip node_modules-only repos — focus on active development repos
Parallelize where possible — run independent repo checks simultaneously
Time-box expensive checks — if pnpm install takes >2min, skip and note

Commit

# If you fix issues during audit:
cd <repo>
git add .
git commit -m "fix(<scope>): resolve audit findings

- <finding 1>
- <finding 2>"
git push

4.3 KiB Raw Blame History