# Agent Rules

Shared rules for all projects in this environment. Technology appendices at end extend these rules only for matching stacks.

## 1. Coding Standards

- Clarity over cleverness; prefer obvious multi-line code to dense tricks.
- Use explicit access modifiers, return types, and argument types where language supports them.
- Scope variables narrowly; never pollute global/shared namespaces.
- Sanitize inputs and encode output for its context: HTML, JS, URL, attribute, SQL, etc.
- Never leave debug dumps, temporary exits, aborts, or throwaway logging in committed code.
- SQL: no `SELECT *`; parameterize queries with explicit type binding; inspect plans for complex/expensive SQL.
- Dates/localization: use app config/localization, not hardcoded masks.
- Style defaults: concise focused methods; named booleans for complex conditions; filenames `lowercase`; variables/methods `camelCase`; constants `UPPER_SNAKE_CASE`.
- For non-trivial changes, ask whether a cleaner solution exists. Avoid hacks/workarounds; find root cause.
- Minimal impact: touch only what is needed; no unrelated refactors or new patterns without clear reason.
- Encoding default: UTF-8 without BOM unless appendix says otherwise.

## 2. Tool Priority

Prefer MCP/native tools over shell when equivalent exists. Use shell for builds, tests, dev servers, installs, Git operations not exposed by MCP, or subprocess-only tasks.

MCP routing:
- `projectfs-mcp-server`: `list_dir`, `read_file`, `read_many`, `grep_files`, `stat` for filesystem exploration.
- `docs-mcp-server`: search/read internal docs before new logic. If search empty: `list_tags` -> `list_documents(include_tags=true)` -> retry with bilingual/domain synonyms.
- `memory-mcp-server`: operational memory retrieval/persistence for reusable context; keep project isolation explicit and verify against primary sources before decisions.
- `git-mcp-server`: status, history, blame, repo info, diffs, conflict handling. Shell Git allowed for missing advanced checks; keep narrow.
- `linter-mcp-server`: get lint config when unclear; lint all modified files before final delivery.
- `sql-mcp-server`: inspect schema before SQL; SELECT-only data checks; explain plans for complex queries.
- `playwright-mcp-server`: navigate UI, inspect DOM, screenshots, console/network, deterministic interactions.
- `office-mcp-server`: Word/Excel/PDF read/write/extract; prefer over raw binary reads.
- `mantis-mcp-server`: read/search issues, handle attachments, add private technical notes when findings must persist.
- `cf-mcp-server`: CF bridge/logs for CFML inspection; see `COLDFUSION.md` when relevant.

Skills:
- Pick one primary skill matching the objective; add sidecar skills only for direct evidence/validation.
- Read chosen `SKILL.md`; load referenced files only as needed.
- Specialist skill for single-domain work; `mcp-technical-analyst` for multi-source reconstruction; `mcp-master-orchestrator` for multi-phase coordination.
- Skill file is authoritative if it conflicts with this summary.
- For memory-heavy tasks, prefer `mcp-memory-operator` for consolidation/handoff and keep analyst/orchestrator as primary for multi-source intake.

Minimal skill map:
- Browser/UI: `mcp-browser-automation`
- Review: `mcp-code-reviewer`
- CFML: `mcp-coldfusion-developer`
- SQL/data: `mcp-database-expert`
- Docs: `mcp-docs-navigator`
- Git/Mantis traceability: `mcp-git-mantis-workflow`
- Ticket writing: `mcp-mantis-ticket-writer`
- Office files: `mcp-office-expert`
- Memory operations: `mcp-memory-operator`
- Multi-source analysis: `mcp-technical-analyst`
- Multi-phase orchestration: `mcp-master-orchestrator`
- Sophia/Yii: `mcp-sophia-yii-developer`

## 2.1 Memory Context Discipline

Use operational memory as a context layer, not as an authoritative source.

Rules:
- Verify memory-derived claims against primary sources (docs/code/tickets/commits) before implementation decisions.
- Keep project isolation explicit: provide project context (project_path or equivalent project identifier) for project-scoped memory operations.
- Prefer memory search/read before writing new entries; avoid duplicates and low-value noise.
- Persist only reusable outcomes: decisions, validated workarounds, root causes, constraints, handoff checkpoints.
- Never persist secrets, credentials, raw sensitive payloads, or verbose dumps.
- Favor stable contracts over tool-version details: if memory capabilities evolve, continue to apply these rules.
- Write trigger: persist memory only when it is likely to prevent repeated analysis or reduce regression risk in future tasks.
- Update policy: when the same fact changes, create an explicit superseding memory record rather than silently rewriting historical context.
- Conflict policy: when memory conflicts with primary sources, primary evidence wins; keep the memory item marked for reconfirmation.

## 3. Work Loop

Before starting:
- Review relevant Knowledge Items before independent research.
- Search docs first; use docs fallback before saying no docs found.
- For non-trivial work, make a checkable plan. If execution derails, stop and re-plan.
- Ask only when intent is genuinely ambiguous or assumption would be risky.
- For merge/rebase: verify repo root, branch, upstream, worktree cleanliness, source/target branches, and backup/original branch if available.

During work:
- Verify before editing: read nearby code, conventions, blame/history when useful.
- Stay within scope; do not surprise user with unrelated mutations.
- For bug reports, investigate logs/errors/tests and resolve root cause independently.
- Audit/review/regression passes stay read-only unless remediation is requested.
- If `RULES.md` exists in the target directory, read it before touching files there. It extends these rules within that directory; follow the more restrictive rule on conflicts.

After changes:
- Prove outcome with tests, lint, logs, diff, smoke checks, or equivalent evidence.
- Never call work done without validation or clearly stating what could not run.
- For rebases, compare against target branch and original source branch when possible.
- Record durable analysis/decisions as structured outputs when useful; avoid duplicating full content inline.
- If memory and primary evidence diverge, report the divergence explicitly and proceed based on primary evidence.
- After user correction, capture root cause and update the relevant rule/Knowledge Item when appropriate.

## 4. Version Control

- Do not commit unless explicitly requested.
- Commit messages should follow standard conventions; prefix tracked issues when relevant, e.g. `#1234 Fix role attribute deletion`.
- Before multi-step workflows, check `{.agents,.agent,_agents,_agent}/workflows/` and follow existing workflow docs.
- For conflicts, avoid blind `ours/theirs` on semantic files; inspect code/history and stop when business meaning is unclear.

## 5. Token/File Discipline

- Avoid reading huge files or raw Base64 into the chat. Warn and ask before full read if token saturation is likely.
- Prefer server-side save/download/export and return paths, not large inline blobs.
- For non-text artifacts, use dedicated MCP/tooling before raw reads.
- Prefer concise, evidence-first answers. No throat-clearing.
- Do not restate large code blocks, diffs, logs, JSON, SQL, or file contents unless requested.
- For findings, use: issue -> evidence -> fix -> validation.
- For tool results, summarize only relevant facts and cite path/line/range when possible.
- Prefer paths, saved artifacts, structured outputs, and checklists over inline blobs.
- For multi-step work, keep plans short and update only when state changes.
- Avoid repeating unchanged context already present in the conversation.
- When spawning sub-agents, require compact outputs: files, findings, risks, validation only.

## 6. Technology Appendices

If present beside this file, read and follow the matching appendix:
- Repo rules: `RULES.md` if exists
- CFML: `COLDFUSION.md`
- Yii/SOPHIA: `Yii.md`
- For output minimization and token-bloat control, follow `TOKEN_DISCIPLINE.md`.