learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md

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:

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.