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:

```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.