feat(agent-docs): single-source-of-truth pattern for agent instructions
Establish a single canonical source for ecosystem-wide AI agent behavior
rules, eliminating duplication across the 8 agent-config files that each
repo used to maintain.
New canonical sources (this repo only):
- AI.dev/SKILLS/agent-behavior-guidelines.md (Karpathy + ByteLyst rules)
- AI.dev/SKILLS/agent-onboarding.md (read-order index)
Generator rewrite (scripts/update-agent-docs.sh):
- Deletes legacy files that duplicated AGENTS.md:
.cursorrules, .windsurfrules, .clinerules, CLAUDE.md
- Regenerates .github/copilot-instructions.md as a thin pointer (no rules).
- Regenerates .aider.conf.yml and .editorconfig.
- Idempotently prepends a canonical-behavior-pointer block to AGENTS.md.
- Supports --dry-run and --no-commit flags.
Drift check (scripts/check-agent-docs-drift.sh):
- Fast marker-based check across all repos.
- Verifies legacy files absent, AGENTS.md pointer present, copilot/aider/
editorconfig markers intact.
Workflow doc updated: .windsurf/workflows/repo_update-agent-docs.md
Repos.txt: added learning_ai_talk2obsidian (was missing from canonical list).
This repo's own agent files are migrated by the same generator:
- Removed: .cursorrules, .windsurfrules, .clinerules, CLAUDE.md
- Updated: AGENTS.md (pointer block prepended)
- Updated: .github/copilot-instructions.md (rewritten as pointer)
- Updated: .aider.conf.yml (canonical format)
Karpathy attribution: behavior rules adapted from
https://github.com/multica-ai/andrej-karpathy-skills
This commit is contained in:
saravanakumardb1
parent
7e08cce95f
commit
c04ee5f054
@ -1,5 +1,6 @@
|
|||||||
# .aider.conf.yml — Aider Configuration for @bytelyst Common Platform
|
# .aider.conf.yml — Aider Configuration for @bytelyst Common Platform
|
||||||
# Helps Aider understand the project structure and conventions.
|
# Auto-generated by learning_ai_common_plat/scripts/update-agent-docs.sh
|
||||||
|
# Hand-edit will be overwritten on next run.
|
||||||
|
|
||||||
read:
|
read:
|
||||||
- AGENTS.md
|
- AGENTS.md
|
||||||
|
|||||||
24
.clinerules
24
.clinerules
@ -1,24 +0,0 @@
|
|||||||
# .clinerules — Cline / Roo Code Rules for @bytelyst Common Platform
|
|
||||||
# Read AGENTS.md for the complete onboarding guide.
|
|
||||||
|
|
||||||
## Project: @bytelyst Common Platform — Shared packages + microservices for the ByteLyst ecosystem
|
|
||||||
Architecture: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
|
||||||
|
|
||||||
## Mandatory Rules
|
|
||||||
- Package manager: pnpm — NEVER use npm
|
|
||||||
- ESM everywhere: "type": "module", .js extensions in imports
|
|
||||||
- Fastify module pattern: types.ts → repository.ts → routes.ts
|
|
||||||
- Use req.log / app.log — never console.log
|
|
||||||
- Every Cosmos document MUST include a productId field
|
|
||||||
- peerDependencies for heavy deps; workspace:* for inter-package deps
|
|
||||||
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
|
|
||||||
- Commits: `type(scope): description`
|
|
||||||
- After changes, verify: `pnpm build && pnpm test && pnpm typecheck`
|
|
||||||
|
|
||||||
## Key File Locations
|
|
||||||
- packages/ — @bytelyst/* shared libraries (errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
|
|
||||||
- services/platform-service/ — consolidated platform service (port 4003)
|
|
||||||
- services/extraction-service/ — text extraction + Python sidecar (port 4005)
|
|
||||||
- dashboards/admin-web/ — admin console (port 3001)
|
|
||||||
- dashboards/tracker-web/ — issue tracker (port 3003)
|
|
||||||
- Full guide: `AGENTS.md`
|
|
||||||
32
.cursorrules
32
.cursorrules
@ -1,32 +0,0 @@
|
|||||||
# @bytelyst Common Platform — Cursor Rules
|
|
||||||
# Read AGENTS.md for full context.
|
|
||||||
|
|
||||||
Project: @bytelyst Common Platform — Shared packages + microservices for the ByteLyst ecosystem
|
|
||||||
Product ID: (product-agnostic)
|
|
||||||
Stack: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
- packages/ — @bytelyst/* shared libraries (errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
|
|
||||||
- services/platform-service/ — consolidated platform service (port 4003)
|
|
||||||
- services/extraction-service/ — text extraction + Python sidecar (port 4005)
|
|
||||||
- dashboards/admin-web/ — admin console (port 3001)
|
|
||||||
- dashboards/tracker-web/ — issue tracker (port 3003)
|
|
||||||
|
|
||||||
## Rules
|
|
||||||
- Package manager: pnpm — NEVER use npm
|
|
||||||
- ESM everywhere: "type": "module", .js extensions in imports
|
|
||||||
- Fastify module pattern: types.ts → repository.ts → routes.ts
|
|
||||||
- Use req.log / app.log — never console.log
|
|
||||||
- Every Cosmos document MUST include a productId field
|
|
||||||
- peerDependencies for heavy deps; workspace:* for inter-package deps
|
|
||||||
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
|
|
||||||
- Commits: feat(scope): description / fix(scope): description
|
|
||||||
- Never delete existing comments/documentation unless asked
|
|
||||||
- Never add emojis unless asked
|
|
||||||
- Never hardcode secrets, colors, or API URLs
|
|
||||||
|
|
||||||
## Build Verification
|
|
||||||
- pnpm build && pnpm test && pnpm typecheck
|
|
||||||
|
|
||||||
## Key Documents
|
|
||||||
- AGENTS.md — Full AI agent instructions (read this first)
|
|
||||||
44
.github/copilot-instructions.md
vendored
44
.github/copilot-instructions.md
vendored
@ -1,40 +1,24 @@
|
|||||||
|
<!-- AUTO-GENERATED by learning_ai_common_plat/scripts/update-agent-docs.sh -->
|
||||||
|
<!-- DO NOT EDIT. Edit the canonical sources instead. -->
|
||||||
|
|
||||||
# GitHub Copilot Instructions — @bytelyst Common Platform
|
# GitHub Copilot Instructions — @bytelyst Common Platform
|
||||||
|
|
||||||
> For full agent instructions, read [`AGENTS.md`](../AGENTS.md) at the repo root.
|
**Project:** @bytelyst Common Platform — `(product-agnostic)`
|
||||||
|
**Stack:** TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
||||||
|
|
||||||
## Project Context
|
## Read these (in order) before suggesting code
|
||||||
|
|
||||||
**@bytelyst Common Platform** — Shared packages + microservices for the ByteLyst ecosystem.
|
1. **`AGENTS.md`** at the repo root — repo-specific layout, conventions,
|
||||||
Stack: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
build commands, file ownership.
|
||||||
|
2. **`AI.dev/SKILLS/agent-behavior-guidelines.md`** —
|
||||||
|
ecosystem-wide agent behavior rules (Karpathy + ByteLyst). Identical
|
||||||
|
across every repo in the workspace.
|
||||||
|
|
||||||
## Code Generation Rules
|
Both files together are the complete contract. This pointer file contains
|
||||||
|
no rules of its own to avoid duplication and drift.
|
||||||
|
|
||||||
### Always
|
## Quick verification command
|
||||||
- Package manager: pnpm — NEVER use npm
|
|
||||||
- ESM everywhere: "type": "module", .js extensions in imports
|
|
||||||
- Fastify module pattern: types.ts → repository.ts → routes.ts
|
|
||||||
- Use req.log / app.log — never console.log
|
|
||||||
- Every Cosmos document MUST include a productId field
|
|
||||||
- peerDependencies for heavy deps; workspace:* for inter-package deps
|
|
||||||
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
|
|
||||||
- Include `productId: "(product-agnostic)"` in every Cosmos DB document
|
|
||||||
- Use `type(scope): description` commit message format
|
|
||||||
- Fix source code, not tests (unless the test itself is wrong)
|
|
||||||
|
|
||||||
### Never
|
|
||||||
- `console.log` or `print()` in production code
|
|
||||||
- Hardcoded secrets, API keys, colors, or URLs
|
|
||||||
- Delete existing comments or documentation unless explicitly asked
|
|
||||||
- Add emojis unless asked
|
|
||||||
|
|
||||||
## Key Paths
|
|
||||||
- packages/ — @bytelyst/* shared libraries (errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
|
|
||||||
- services/platform-service/ — consolidated platform service (port 4003)
|
|
||||||
- services/extraction-service/ — text extraction + Python sidecar (port 4005)
|
|
||||||
- dashboards/admin-web/ — admin console (port 3001)
|
|
||||||
- dashboards/tracker-web/ — issue tracker (port 3003)
|
|
||||||
|
|
||||||
## Build Verification
|
|
||||||
```bash
|
```bash
|
||||||
pnpm build && pnpm test && pnpm typecheck
|
pnpm build && pnpm test && pnpm typecheck
|
||||||
```
|
```
|
||||||
|
|||||||
@ -1,54 +1,116 @@
|
|||||||
---
|
---
|
||||||
description: Regenerate AI agent docs (AGENTS.md, CLAUDE.md, .cursorrules, etc.) across all repos
|
description: Regenerate AI agent docs across all repos (single source of truth pattern)
|
||||||
---
|
---
|
||||||
|
|
||||||
# Update Agent Docs Across Workspace
|
# Update Agent Docs Across Workspace
|
||||||
|
|
||||||
Regenerates all 8 AI agent configuration files across all repos in the workspace.
|
Maintains AI agent docs across the ByteLyst workspace using a
|
||||||
|
**single source of truth** pattern with **zero duplication**.
|
||||||
|
|
||||||
## Files Generated Per Repo
|
## Architecture
|
||||||
|
|
||||||
| File | Tool |
|
```
|
||||||
| --------------------------------- | ----------------------------------------------- |
|
learning_ai_common_plat/AI.dev/SKILLS/
|
||||||
| `AGENTS.md` | Universal (OpenAI Codex, Claude, Copilot, etc.) |
|
├── agent-behavior-guidelines.md ← SINGLE source of truth for behavior rules
|
||||||
| `CLAUDE.md` | Claude Code |
|
└── agent-onboarding.md ← Read-order index for agents
|
||||||
| `.cursorrules` | Cursor AI |
|
|
||||||
| `.github/copilot-instructions.md` | GitHub Copilot |
|
<each repo>/
|
||||||
| `.windsurfrules` | Windsurf / Cascade |
|
├── AGENTS.md ← Repo-specific only. Auto-prepended with
|
||||||
| `.clinerules` | Cline / Roo Code |
|
│ "Read first" pointer to canonical file.
|
||||||
| `.aider.conf.yml` | Aider |
|
├── .github/copilot-instructions.md ← Thin pointer (no rules). Auto-generated.
|
||||||
| `.editorconfig` | All editors |
|
├── .aider.conf.yml ← Aider config pointing to AGENTS.md. Auto-generated.
|
||||||
|
└── .editorconfig ← Editor config. Auto-generated.
|
||||||
|
|
||||||
|
DELETED across all repos (content was duplicated AGENTS.md):
|
||||||
|
├── CLAUDE.md
|
||||||
|
├── .cursorrules
|
||||||
|
├── .windsurfrules
|
||||||
|
└── .clinerules
|
||||||
|
```
|
||||||
|
|
||||||
## Steps
|
## Steps
|
||||||
|
|
||||||
1. Run the update script:
|
1. **Edit the canonical sources** when behavior rules change:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ecosystem-wide agent behavior (Karpathy + ByteLyst)
|
||||||
|
open learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md
|
||||||
|
|
||||||
|
# read-order index
|
||||||
|
open learning_ai_common_plat/AI.dev/SKILLS/agent-onboarding.md
|
||||||
|
```
|
||||||
|
|
||||||
|
These are referenced (not copied) by every repo's AGENTS.md, so changes
|
||||||
|
take effect immediately — no regeneration needed when only behavior rules change.
|
||||||
|
|
||||||
|
2. **Run the generator** to delete legacy files / refresh pointers / sync configs:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /Users/sd9235/code/mygh/learning_ai_common_plat
|
cd /Users/sd9235/code/mygh/learning_ai_common_plat
|
||||||
./scripts/update-agent-docs.sh
|
./scripts/update-agent-docs.sh --dry-run # preview
|
||||||
|
./scripts/update-agent-docs.sh # apply + commit per repo
|
||||||
|
./scripts/update-agent-docs.sh --no-commit # apply without committing
|
||||||
```
|
```
|
||||||
|
|
||||||
The script reads `learning_ai_common_plat/.windsurf/workflows/repos.txt` as the canonical list of managed workspace repositories.
|
Reads `learning_ai_common_plat/.windsurf/workflows/repos.txt` as the
|
||||||
|
canonical list of managed repos.
|
||||||
|
|
||||||
2. Review changes per repo:
|
3. **Verify no drift**:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash scripts/check-agent-docs-drift.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Exits 1 if any repo has drifted from the canonical generator output.
|
||||||
|
Suitable for CI.
|
||||||
|
|
||||||
|
4. **Review changes per repo**:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
while IFS= read -r repo; do
|
while IFS= read -r repo; do
|
||||||
[[ -z "$repo" || "$repo" =~ ^# ]] && continue
|
[[ -z "$repo" || "$repo" =~ ^# ]] && continue
|
||||||
cd /Users/sd9235/code/mygh/$repo && git diff --stat
|
echo "── $repo ──"
|
||||||
|
git -C /Users/sd9235/code/mygh/"$repo" log -1 --oneline
|
||||||
done < /Users/sd9235/code/mygh/learning_ai_common_plat/.windsurf/workflows/repos.txt
|
done < /Users/sd9235/code/mygh/learning_ai_common_plat/.windsurf/workflows/repos.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Commit changes (if any):
|
5. **Push (when ready)**:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /Users/sd9235/code/mygh/learning_voice_ai_agent
|
while IFS= read -r repo; do
|
||||||
[ -n "$(git status --porcelain)" ] && git add -A && git commit -m "chore(docs): update agent configuration files"
|
[[ -z "$repo" || "$repo" =~ ^# ]] && continue
|
||||||
|
git -C /Users/sd9235/code/mygh/"$repo" push
|
||||||
|
done < /Users/sd9235/code/mygh/learning_ai_common_plat/.windsurf/workflows/repos.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Files generated per repo
|
||||||
|
|
||||||
|
| File | Type | Tool(s) |
|
||||||
|
| --------------------------------- | ------- | -------------------------------------- |
|
||||||
|
| `AGENTS.md` | Hybrid | Codex, Claude, Cursor, Windsurf, Cline |
|
||||||
|
| `.github/copilot-instructions.md` | Pointer | GitHub Copilot |
|
||||||
|
| `.aider.conf.yml` | Config | Aider |
|
||||||
|
| `.editorconfig` | Config | All editors |
|
||||||
|
|
||||||
|
`AGENTS.md` is hybrid: the body is hand-maintained (repo-specific content),
|
||||||
|
but the generator idempotently prepends a `<!-- BEGIN: canonical-behavior-pointer -->`
|
||||||
|
block at the top. The block is the only auto-managed region; everything else
|
||||||
|
is left alone.
|
||||||
|
|
||||||
|
## Files deleted by the generator
|
||||||
|
|
||||||
|
| File | Reason |
|
||||||
|
| ---------------- | ------------------------------------------------------------- |
|
||||||
|
| `CLAUDE.md` | Duplicated AGENTS.md. Claude Code reads AGENTS.md by default. |
|
||||||
|
| `.cursorrules` | Duplicated AGENTS.md. Cursor reads AGENTS.md. |
|
||||||
|
| `.windsurfrules` | Duplicated AGENTS.md. Windsurf reads AGENTS.md. |
|
||||||
|
| `.clinerules` | Duplicated AGENTS.md. Cline reads AGENTS.md. |
|
||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
- The script scans each repo's structure and regenerates docs based on current state
|
- Safe to run repeatedly (idempotent).
|
||||||
- Only commits if there are actual changes
|
- Only commits when actual changes exist in the repo.
|
||||||
- Safe to run repeatedly (idempotent)
|
- The script never touches the body of AGENTS.md outside the marker block.
|
||||||
- Requires `learning_ai_common_plat` to be the source of truth for templates
|
- For workspaces that include `learning_ai_common_plat` as a sibling
|
||||||
|
(default for Windsurf/Cascade), the canonical guidelines file resolves
|
||||||
|
via the relative path written into each AGENTS.md pointer.
|
||||||
|
|||||||
@ -19,6 +19,7 @@ learning_ai_trails
|
|||||||
learning_ai_local_memory_gpt
|
learning_ai_local_memory_gpt
|
||||||
learning_ai_efforise
|
learning_ai_efforise
|
||||||
learning_ai_local_llms
|
learning_ai_local_llms
|
||||||
|
learning_ai_talk2obsidian
|
||||||
|
|
||||||
# --- Auth & identity ---
|
# --- Auth & identity ---
|
||||||
learning_ai_smart_auth
|
learning_ai_smart_auth
|
||||||
|
|||||||
@ -1,25 +0,0 @@
|
|||||||
# @bytelyst Common Platform — Windsurf / Codeium Rules
|
|
||||||
# Read AGENTS.md for full context. These are the critical rules.
|
|
||||||
|
|
||||||
Project: @bytelyst Common Platform — Shared packages + microservices for the ByteLyst ecosystem
|
|
||||||
Stack: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
|
||||||
|
|
||||||
## Architecture Rules
|
|
||||||
- packages/ — @bytelyst/* shared libraries (errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
|
|
||||||
- services/platform-service/ — consolidated platform service (port 4003)
|
|
||||||
- services/extraction-service/ — text extraction + Python sidecar (port 4005)
|
|
||||||
- dashboards/admin-web/ — admin console (port 3001)
|
|
||||||
- dashboards/tracker-web/ — issue tracker (port 3003)
|
|
||||||
|
|
||||||
## Conventions
|
|
||||||
- Package manager: pnpm — NEVER use npm
|
|
||||||
- ESM everywhere: "type": "module", .js extensions in imports
|
|
||||||
- Fastify module pattern: types.ts → repository.ts → routes.ts
|
|
||||||
- Use req.log / app.log — never console.log
|
|
||||||
- Every Cosmos document MUST include a productId field
|
|
||||||
- peerDependencies for heavy deps; workspace:* for inter-package deps
|
|
||||||
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
|
|
||||||
- Commits: feat(scope): description / fix(scope): description
|
|
||||||
|
|
||||||
## Build Verification
|
|
||||||
- pnpm build && pnpm test && pnpm typecheck
|
|
||||||
12
AGENTS.md
12
AGENTS.md
@ -1,5 +1,17 @@
|
|||||||
# AGENTS.md — AI Coding Agent Instructions
|
# AGENTS.md — AI Coding Agent Instructions
|
||||||
|
|
||||||
|
<!-- BEGIN: canonical-behavior-pointer (auto-managed) -->
|
||||||
|
> **Read first (ecosystem-wide agent behavior):**
|
||||||
|
> [`AI.dev/SKILLS/agent-behavior-guidelines.md`](AI.dev/SKILLS/agent-behavior-guidelines.md)
|
||||||
|
>
|
||||||
|
> The link above is the single source of truth for agent behavior across every
|
||||||
|
> ByteLyst repo (Karpathy + ByteLyst rules: tests sacred, verify before done,
|
||||||
|
> no shared-infra hand-edits, no `console.log`/`print`, productId on every
|
||||||
|
> Cosmos doc, conventional commits, style preservation).
|
||||||
|
>
|
||||||
|
> The per-repo content below extends — never duplicates — the canonical rules.
|
||||||
|
<!-- END: canonical-behavior-pointer -->
|
||||||
|
|
||||||
> **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent.
|
> **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent.
|
||||||
> **Repo:** `learning_ai_common_plat` — Shared platform packages + microservices for the ByteLyst ecosystem.
|
> **Repo:** `learning_ai_common_plat` — Shared platform packages + microservices for the ByteLyst ecosystem.
|
||||||
> **See also:** [`README.md`](README.md) for quick start, [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) for full architecture, [`docs/ecosystem/README.md`](docs/ecosystem/README.md) for canonical ecosystem strategy/contract docs, [`docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md`](docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) for delegation/review/merge process.
|
> **See also:** [`README.md`](README.md) for quick start, [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) for full architecture, [`docs/ecosystem/README.md`](docs/ecosystem/README.md) for canonical ecosystem strategy/contract docs, [`docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md`](docs/ecosystem/ECOSYSTEM_AGENT_OPERATING_MODEL.md) for delegation/review/merge process.
|
||||||
|
|||||||
173
AI.dev/SKILLS/agent-behavior-guidelines.md
Normal file
173
AI.dev/SKILLS/agent-behavior-guidelines.md
Normal file
@ -0,0 +1,173 @@
|
|||||||
|
# Agent Behavior Guidelines — ByteLyst Ecosystem
|
||||||
|
|
||||||
|
> **Single source of truth.** This file is the canonical agent behavior contract
|
||||||
|
> for every repo in the ByteLyst workspace. Every per-repo `AGENTS.md` points
|
||||||
|
> here. Do not duplicate these rules into per-repo agent files.
|
||||||
|
>
|
||||||
|
> **Location:** `learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`
|
||||||
|
> From any sibling repo: `../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`
|
||||||
|
|
||||||
|
These rules apply to every AI coding agent (Claude Code, Cursor, Windsurf Cascade,
|
||||||
|
GitHub Copilot, OpenAI Codex, Cline, Aider, etc.) working in any ByteLyst repo.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part A — Universal Behavior (adapted from Karpathy's CLAUDE.md)
|
||||||
|
|
||||||
|
Source attribution: behavioral guidelines below adapted from
|
||||||
|
<https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md>.
|
||||||
|
|
||||||
|
These bias toward caution over speed. For trivial tasks, use judgment.
|
||||||
|
|
||||||
|
### A1. Think Before Coding
|
||||||
|
|
||||||
|
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
||||||
|
|
||||||
|
Before implementing:
|
||||||
|
|
||||||
|
- State your assumptions explicitly. If uncertain, ask.
|
||||||
|
- If multiple interpretations exist, present them — don't pick silently.
|
||||||
|
- If a simpler approach exists, say so. Push back when warranted.
|
||||||
|
- If something is unclear, stop. Name what's confusing. Ask.
|
||||||
|
|
||||||
|
### A2. Simplicity First
|
||||||
|
|
||||||
|
**Minimum code that solves the problem. Nothing speculative.**
|
||||||
|
|
||||||
|
- No features beyond what was asked.
|
||||||
|
- No abstractions for single-use code.
|
||||||
|
- No "flexibility" or "configurability" that wasn't requested.
|
||||||
|
- No error handling for impossible scenarios.
|
||||||
|
- If you write 200 lines and it could be 50, rewrite it.
|
||||||
|
|
||||||
|
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
||||||
|
|
||||||
|
### A3. Surgical Changes
|
||||||
|
|
||||||
|
**Touch only what you must. Clean up only your own mess.**
|
||||||
|
|
||||||
|
When editing existing code:
|
||||||
|
|
||||||
|
- Don't "improve" adjacent code, comments, or formatting.
|
||||||
|
- Don't refactor things that aren't broken.
|
||||||
|
- Match existing style, even if you'd do it differently.
|
||||||
|
- If you notice unrelated dead code, mention it — don't delete it.
|
||||||
|
|
||||||
|
When your changes create orphans:
|
||||||
|
|
||||||
|
- Remove imports/variables/functions that **your** changes made unused.
|
||||||
|
- Don't remove pre-existing dead code unless asked.
|
||||||
|
|
||||||
|
**The test:** Every changed line should trace directly to the user's request.
|
||||||
|
|
||||||
|
### A4. Goal-Driven Execution
|
||||||
|
|
||||||
|
**Define success criteria. Loop until verified.**
|
||||||
|
|
||||||
|
Transform tasks into verifiable goals:
|
||||||
|
|
||||||
|
- "Add validation" → "Write tests for invalid inputs, then make them pass"
|
||||||
|
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
||||||
|
- "Refactor X" → "Ensure tests pass before and after"
|
||||||
|
|
||||||
|
For multi-step tasks, state a brief plan:
|
||||||
|
|
||||||
|
```text
|
||||||
|
1. [Step] → verify: [check]
|
||||||
|
2. [Step] → verify: [check]
|
||||||
|
3. [Step] → verify: [check]
|
||||||
|
```
|
||||||
|
|
||||||
|
Strong success criteria let you loop independently. Weak criteria ("make it
|
||||||
|
work") require constant clarification.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part B — ByteLyst Ecosystem Rules
|
||||||
|
|
||||||
|
These extend Part A with ecosystem-specific discipline. They apply to every repo.
|
||||||
|
|
||||||
|
### B1. Tests are sacred
|
||||||
|
|
||||||
|
- **Never modify tests to make them pass.** Fix the source code, or stop and ask.
|
||||||
|
- **Never delete or weaken tests** without explicit user direction.
|
||||||
|
- When fixing a bug, add a regression test first.
|
||||||
|
|
||||||
|
### B2. Verify before claiming done
|
||||||
|
|
||||||
|
- Run the repo's documented `Build Verification` block (see each AGENTS.md §
|
||||||
|
"Build Verification") before reporting completion.
|
||||||
|
- If you cannot run verification, say so explicitly — don't claim "should work".
|
||||||
|
- For multi-repo changes, verify each affected repo.
|
||||||
|
|
||||||
|
### B3. Never edit shared infrastructure casually
|
||||||
|
|
||||||
|
- `.npmrc` is managed by `learning_ai_common_plat/scripts/npmrc.template`.
|
||||||
|
Never hand-edit. Use `bash scripts/sync-npmrc.sh`.
|
||||||
|
- `@bytelyst/*` packages live in `learning_ai_common_plat/packages/`. Changes
|
||||||
|
ripple across all products — flag cross-repo impact before editing.
|
||||||
|
- Agent docs (`AGENTS.md`, `.github/copilot-instructions.md`, etc.) are managed
|
||||||
|
by `learning_ai_common_plat/scripts/update-agent-docs.sh`. Never hand-edit
|
||||||
|
generated files. Edit the template or per-repo metadata instead.
|
||||||
|
|
||||||
|
### B4. Logging and secrets
|
||||||
|
|
||||||
|
- Never use `console.log` in production code — use `req.log` / `app.log`
|
||||||
|
(Fastify), `structlog` (Python), `os.Logger` (Swift).
|
||||||
|
- Never use `print()` in Swift.
|
||||||
|
- Never hardcode secrets, API keys, OAuth client IDs, or URLs. Use env vars or
|
||||||
|
Azure Key Vault.
|
||||||
|
|
||||||
|
### B5. Cosmos discipline
|
||||||
|
|
||||||
|
- Every Cosmos document MUST include a `productId` field.
|
||||||
|
- Use `PRODUCT_ID` from `@bytelyst/config` (or `shared/product.json`) — never
|
||||||
|
hardcode product IDs as string literals.
|
||||||
|
|
||||||
|
### B6. Commit hygiene
|
||||||
|
|
||||||
|
- Format: `type(scope): description`
|
||||||
|
- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
|
||||||
|
- Keep commits atomic. One logical change per commit.
|
||||||
|
- Run pre-commit hooks. Do not bypass with `--no-verify` unless asked.
|
||||||
|
|
||||||
|
### B7. Style preservation
|
||||||
|
|
||||||
|
- Never delete existing comments or documentation unless explicitly asked.
|
||||||
|
- Never add emojis unless explicitly asked.
|
||||||
|
- Match the existing code style of the file you're editing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part C — Tool-Specific Notes
|
||||||
|
|
||||||
|
All AI coding tools should read this file. The conventions for how each tool
|
||||||
|
discovers it:
|
||||||
|
|
||||||
|
- **Claude Code** — reads `AGENTS.md` (per-repo) which links here.
|
||||||
|
- **Cursor** — reads `AGENTS.md` (per-repo) which links here. Multi-root
|
||||||
|
workspace must include `learning_ai_common_plat` so the sibling path resolves.
|
||||||
|
- **Windsurf / Cascade** — reads `AGENTS.md` (per-repo). Workspace must
|
||||||
|
include `learning_ai_common_plat`.
|
||||||
|
- **GitHub Copilot** — reads `.github/copilot-instructions.md` (per-repo)
|
||||||
|
which points here. Copilot does not always follow cross-file references; the
|
||||||
|
pointer file is a best-effort.
|
||||||
|
- **OpenAI Codex** — reads `AGENTS.md` (per-repo).
|
||||||
|
- **Cline / Roo Code** — reads `AGENTS.md` (per-repo) via its standard agent
|
||||||
|
file discovery.
|
||||||
|
- **Aider** — `.aider.conf.yml` (per-repo) declares `read: AGENTS.md` and
|
||||||
|
`conventions: AGENTS.md`.
|
||||||
|
|
||||||
|
If your tool does not appear here, default to reading `AGENTS.md` at the repo
|
||||||
|
root.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
- Edit this file in place. Changes take effect for every repo on next agent
|
||||||
|
invocation — no regeneration needed (it is referenced, not copied).
|
||||||
|
- After editing, run `bash scripts/check-agent-docs-drift.sh` from
|
||||||
|
`learning_ai_common_plat` to confirm no per-repo file has drifted out of sync.
|
||||||
|
- See `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md`
|
||||||
|
for the full propagation workflow.
|
||||||
77
AI.dev/SKILLS/agent-onboarding.md
Normal file
77
AI.dev/SKILLS/agent-onboarding.md
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
# Agent Onboarding — Read Order
|
||||||
|
|
||||||
|
> Quick index for AI coding agents joining any ByteLyst repo.
|
||||||
|
> Read these documents in the order shown before making changes.
|
||||||
|
|
||||||
|
## 1. Universal behavior (ecosystem-wide, identical across every repo)
|
||||||
|
|
||||||
|
[`agent-behavior-guidelines.md`](agent-behavior-guidelines.md)
|
||||||
|
|
||||||
|
The canonical agent behavior contract — Karpathy's 4 rules (Think, Simplicity,
|
||||||
|
Surgical, Goal-Driven) plus 7 ByteLyst-specific rules (tests, verification,
|
||||||
|
shared infra, logging, Cosmos, commits, style).
|
||||||
|
|
||||||
|
## 2. Per-repo context
|
||||||
|
|
||||||
|
`<repo-root>/AGENTS.md`
|
||||||
|
|
||||||
|
Each repo has its own `AGENTS.md` with:
|
||||||
|
|
||||||
|
- Project identity (product name, ID, ports, domain)
|
||||||
|
- Repo layout
|
||||||
|
- Tech stack rules
|
||||||
|
- Coding conventions specific to that repo
|
||||||
|
- File ownership map
|
||||||
|
- Build & test commands
|
||||||
|
|
||||||
|
## 3. Per-repo product manifest
|
||||||
|
|
||||||
|
`<repo-root>/shared/product.json`
|
||||||
|
|
||||||
|
Canonical product identity (product ID, display name, bundle IDs, etc.).
|
||||||
|
Loaded at runtime via `@bytelyst/config` or read directly by build tooling.
|
||||||
|
|
||||||
|
## 4. Cross-repo automation playbook
|
||||||
|
|
||||||
|
[`../../docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md`](../../docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md)
|
||||||
|
|
||||||
|
Periodic maintenance tasks that span all repos (test audits, coverage,
|
||||||
|
dependency health, secret scans, typecheck sweeps).
|
||||||
|
|
||||||
|
## 5. Skill libraries (this directory)
|
||||||
|
|
||||||
|
Other files in [`AI.dev/SKILLS/`](.) are topic-specific playbooks
|
||||||
|
(architecture patterns, debugging, releases, testing, etc.). Read on demand,
|
||||||
|
not upfront.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How agent files compose
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────────────────────────────────────────────────┐
|
||||||
|
│ Single source of truth (this directory) │
|
||||||
|
│ │
|
||||||
|
│ agent-behavior-guidelines.md ← THE behavior contract │
|
||||||
|
│ agent-onboarding.md ← this file │
|
||||||
|
└──────────────────────────────────────────────────────────────┘
|
||||||
|
▲
|
||||||
|
│ referenced (never copied)
|
||||||
|
│
|
||||||
|
┌──────────────────────────────────────────────────────────────┐
|
||||||
|
│ Per-repo files (one per repo) │
|
||||||
|
│ │
|
||||||
|
│ AGENTS.md ← repo-specific only │
|
||||||
|
│ .github/copilot-instructions.md ← thin pointer │
|
||||||
|
│ .aider.conf.yml ← Aider config │
|
||||||
|
│ .editorconfig ← editor config │
|
||||||
|
└──────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
No behavior rule lives in two files. Drift is impossible by construction.
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
- Generator: `learning_ai_common_plat/scripts/update-agent-docs.sh`
|
||||||
|
- Drift check: `learning_ai_common_plat/scripts/check-agent-docs-drift.sh`
|
||||||
|
- Workflow: `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md`
|
||||||
33
CLAUDE.md
33
CLAUDE.md
@ -1,33 +0,0 @@
|
|||||||
# CLAUDE.md — Compact Agent Reference
|
|
||||||
|
|
||||||
Read [`AGENTS.md`](AGENTS.md) for full instructions. This file is a quick summary.
|
|
||||||
|
|
||||||
## Identity
|
|
||||||
|
|
||||||
- **Repo:** `learning_ai_common_plat` — shared `@bytelyst/*` packages + `@lysnrai/*` microservices
|
|
||||||
- **Consumers:** LysnrAI (voice dictation), MindLyst (multimodal memory)
|
|
||||||
- **Stack:** TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
|
|
||||||
|
|
||||||
## Key Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
pnpm install && pnpm build && pnpm test # full verify
|
|
||||||
pnpm --filter @lysnrai/platform-service dev # run one service
|
|
||||||
pnpm --filter @bytelyst/design-tokens generate # regen tokens
|
|
||||||
```
|
|
||||||
|
|
||||||
## Critical Rules
|
|
||||||
|
|
||||||
- Every Cosmos doc needs `productId`
|
|
||||||
- Every endpoint validates with Zod
|
|
||||||
- Services re-export `@bytelyst/*` in `src/lib/` files
|
|
||||||
- Services use self-contained Zod config (not from shared package)
|
|
||||||
- `@bytelyst/*` = packages, `@lysnrai/*` = services
|
|
||||||
- Use pnpm, never npm
|
|
||||||
- Commit format: `type(scope): description`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cross-Repo Automation
|
|
||||||
|
|
||||||
See [`docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md`](docs/devops/CODING_AGENT_AUTOMATION_PLAYBOOK.md) for periodic maintenance tasks: test audits, coverage gaps, dependency checks, secret scans, typecheck sweeps.
|
|
||||||
128
scripts/check-agent-docs-drift.sh
Executable file
128
scripts/check-agent-docs-drift.sh
Executable file
@ -0,0 +1,128 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# check-agent-docs-drift.sh — Fast drift check for per-repo agent docs.
|
||||||
|
# Exits 1 if any repo has drifted from the canonical pattern.
|
||||||
|
#
|
||||||
|
# Modelled on check-npmrc-drift.sh. Marker-based (no generator runs),
|
||||||
|
# so this is fast and side-effect-free.
|
||||||
|
#
|
||||||
|
# Usage:
|
||||||
|
# bash scripts/check-agent-docs-drift.sh
|
||||||
|
#
|
||||||
|
# What is checked per repo:
|
||||||
|
# 1. Legacy files MUST NOT exist (they used to duplicate AGENTS.md):
|
||||||
|
# .cursorrules, .windsurfrules, .clinerules, CLAUDE.md
|
||||||
|
# 2. AGENTS.md MUST contain the canonical-behavior-pointer marker.
|
||||||
|
# 3. .github/copilot-instructions.md MUST contain the AUTO-GENERATED marker
|
||||||
|
# AND a reference to the canonical guidelines file.
|
||||||
|
# 4. .aider.conf.yml MUST exist and reference AGENTS.md.
|
||||||
|
# 5. .editorconfig MUST exist with the canonical first line "root = true".
|
||||||
|
#
|
||||||
|
# Repair: bash scripts/update-agent-docs.sh
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
REPOS_TXT="${SCRIPT_DIR}/../.windsurf/workflows/repos.txt"
|
||||||
|
BASE_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
|
||||||
|
|
||||||
|
RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
|
||||||
|
|
||||||
|
if [[ ! -f "$REPOS_TXT" ]]; then
|
||||||
|
echo -e "${RED}❌ repos.txt not found: $REPOS_TXT${NC}" >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
LEGACY_FILES=(.cursorrules .windsurfrules .clinerules CLAUDE.md)
|
||||||
|
AGENTS_POINTER_MARKER="<!-- BEGIN: canonical-behavior-pointer (auto-managed) -->"
|
||||||
|
COPILOT_GENERATED_MARKER="<!-- AUTO-GENERATED by learning_ai_common_plat/scripts/update-agent-docs.sh -->"
|
||||||
|
COPILOT_CANONICAL_REF="agent-behavior-guidelines.md"
|
||||||
|
|
||||||
|
drifted=0
|
||||||
|
clean=0
|
||||||
|
missing=0
|
||||||
|
|
||||||
|
REPOS=()
|
||||||
|
while IFS= read -r line; do
|
||||||
|
[[ "$line" =~ ^[[:space:]]*# ]] && continue
|
||||||
|
[[ -z "${line// }" ]] && continue
|
||||||
|
REPOS+=("$line")
|
||||||
|
done < "$REPOS_TXT"
|
||||||
|
|
||||||
|
for repo in "${REPOS[@]}"; do
|
||||||
|
repo_dir="${BASE_DIR}/${repo}"
|
||||||
|
|
||||||
|
if [[ ! -d "$repo_dir" ]]; then
|
||||||
|
continue
|
||||||
|
fi
|
||||||
|
if [[ ! -f "${repo_dir}/AGENTS.md" ]]; then
|
||||||
|
echo -e "${YELLOW}⚠️ $repo — AGENTS.md missing${NC}"
|
||||||
|
((missing++)) || true
|
||||||
|
continue
|
||||||
|
fi
|
||||||
|
|
||||||
|
issues=()
|
||||||
|
|
||||||
|
# 1 — Legacy files must be gone.
|
||||||
|
for f in "${LEGACY_FILES[@]}"; do
|
||||||
|
if [[ -e "${repo_dir}/${f}" ]]; then
|
||||||
|
issues+=("legacy file still present: $f")
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# 2 — AGENTS.md must have the canonical pointer block.
|
||||||
|
if ! grep -qF "$AGENTS_POINTER_MARKER" "${repo_dir}/AGENTS.md"; then
|
||||||
|
issues+=("AGENTS.md missing canonical-behavior-pointer block")
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3 — Copilot file: must exist, must be AUTO-GENERATED, must reference canonical.
|
||||||
|
copilot="${repo_dir}/.github/copilot-instructions.md"
|
||||||
|
if [[ ! -f "$copilot" ]]; then
|
||||||
|
issues+=(".github/copilot-instructions.md missing")
|
||||||
|
else
|
||||||
|
if ! grep -qF "$COPILOT_GENERATED_MARKER" "$copilot"; then
|
||||||
|
issues+=(".github/copilot-instructions.md missing AUTO-GENERATED marker (hand-edited?)")
|
||||||
|
fi
|
||||||
|
if ! grep -qF "$COPILOT_CANONICAL_REF" "$copilot"; then
|
||||||
|
issues+=(".github/copilot-instructions.md missing reference to $COPILOT_CANONICAL_REF")
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 4 — Aider config: must exist and reference AGENTS.md.
|
||||||
|
aider="${repo_dir}/.aider.conf.yml"
|
||||||
|
if [[ ! -f "$aider" ]]; then
|
||||||
|
issues+=(".aider.conf.yml missing")
|
||||||
|
elif ! grep -qF "AGENTS.md" "$aider"; then
|
||||||
|
issues+=(".aider.conf.yml does not reference AGENTS.md")
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 5 — Editorconfig: must exist with canonical first line.
|
||||||
|
editorconfig="${repo_dir}/.editorconfig"
|
||||||
|
if [[ ! -f "$editorconfig" ]]; then
|
||||||
|
issues+=(".editorconfig missing")
|
||||||
|
elif ! head -1 "$editorconfig" | grep -qE '^root = true$'; then
|
||||||
|
issues+=(".editorconfig first line not 'root = true' (hand-edited?)")
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ ${#issues[@]} -gt 0 ]]; then
|
||||||
|
echo -e "${RED}❌ $repo${NC}"
|
||||||
|
for i in "${issues[@]}"; do
|
||||||
|
echo " - $i"
|
||||||
|
done
|
||||||
|
((drifted++)) || true
|
||||||
|
else
|
||||||
|
((clean++)) || true
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "────────────────────────────────"
|
||||||
|
echo -e "${GREEN}✅ $clean repos in sync${NC}"
|
||||||
|
[[ "$missing" -gt 0 ]] && echo -e "${YELLOW}⚠️ $missing repos missing AGENTS.md${NC}"
|
||||||
|
[[ "$drifted" -gt 0 ]] && echo -e "${RED}❌ $drifted repos drifted${NC}"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
if [[ "$drifted" -gt 0 ]] || [[ "$missing" -gt 0 ]]; then
|
||||||
|
echo "Fix: bash scripts/update-agent-docs.sh"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "All repos in sync ✅"
|
||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user