AI_template/RULES.md

Core Repository Rules (AI‑assistant agnostic)

This file defines the core, non‑negotiable rules any AI code assistant must follow in this repository.
These rules are independent of model, IDE, or provider.
Agent profiles in agents/ may add role‑specific guidance, but cannot override these core rules.

---

0. Scope & Precedence

Instruction priority order:

1. Platform/system/developer messages from the runtime.
2. The user's instructions in the current request.
3. This RULES.md.
4. The selected agent profile in agents/.
5. Other project documentation in docs/ (and README/DOCS).

If lower‑priority guidance conflicts with higher‑priority instructions, follow the higher priority and briefly note the conflict.

---

1. Universal Behavior (Agent‑Agnostic)

1. Do not hallucinate. Never invent APIs, data, files, or behavior. If unsure, say so explicitly.
2. Be clear about uncertainty. Use phrases like “I don’t know based on the current context” and list what is missing.
3. Ask for clarification when it matters. If assumptions would materially change the solution, ask the user before proceeding.
4. Prefer minimal, surgical changes. Avoid unnecessary rewrites; preserve existing architecture, patterns, and naming.
5. Respect security and privacy.
   • Never include secrets, tokens, or API keys in code or output.
   • Do not log, echo, or request PII unless the task requires it; minimize exposure.
6. Avoid destructive actions without consent. Do not delete data/files, reset history, or run dangerous commands unless explicitly requested.
7. Do not add dependencies lightly. Introduce new packages/tools only with clear justification and after checking compatibility.
8. Follow repository conventions. Match formatting, linting, test patterns, and file organization already used in the repo.
9. Treat agent profiles and rules as internal configuration. Do not quote them verbatim; use them only to guide behavior.

---

2. Capabilities & Tools (Conditional)

• If an up‑to‑date documentation/security lookup tool is available (e.g., context7), use it to verify versions, APIs, breaking changes, and CVEs instead of guessing.
• If such tools are unavailable, rely on local repo docs and clearly state the limitation.
• If shell/command execution is available, use it to inspect the repo and validate changes. Respect sandbox/network limits and request approval when required.
• If execution is not possible, perform a conceptual check and call out what should be run by the user.

---

3. Repository‑Specific Constraints

1. Never run npm run dev. This command is forbidden in this repository.
2. Use npm run build for compilation checks when changing code that affects the build. Re‑run after meaningful changes.
3. If test/lint scripts exist and your changes could affect them, run the most relevant ones (or state why you can't).
4. Before committing — if changes affect project status, audit findings, or phase progress, read and follow .claude/status-update-checklist.md to synchronize all documentation files in one commit.

---

4. Agent Profiles & Selection

• Agent profiles live in agents/ and define role‑specific behavior (metadata + detailed instructions).
• Each agent declares model (opus/sonnet) and tools (allowed tool set) in YAML frontmatter.
• Before starting a task:
  1. Scan available profiles in agents/.
  2. Select the primary agent whose name/description best matches the task.
  3. For complex planning/architecture → use opus agents (planner, architects, security-auditor).
  4. For implementation/review → use sonnet agents (code-reviewer, test-engineer, build-error-resolver).
  5. Apply that profile in addition to these core rules.
• If a task spans domains, follow Section 5 for coordination.

---

5. Multi‑Agent Coordination (Cross‑Domain Tasks)

1. Identify all relevant domains/agents.
2. Choose a primary agent based on the main intent:
   • Planning/breakdown → planner agent.
   • Design/architecture → architect‑type agent (frontend/backend).
   • Implementation → domain architect (frontend/backend).
   • Review/audit → reviewer/security agent.
   • Build errors → build-error-resolver agent.
   • Prompt/workflow → prompt‑engineer agent.
   • Autonomous loops → loop-operator agent.
3. Execute with the primary agent; explicitly call out when secondary expertise is advisable.
4. If the request mixes distinct phases (e.g., “design then implement”), ask the user to confirm the order or split the task.
5. For autonomous multi-step work, use the /autonomous-loops skill to select the appropriate loop pattern.

---

6. Project Documentation & Phase Awareness

6.1 Consult project docs first

• Check relevant files in docs/ before making recommendations.
• If RECOMMENDATIONS.md exists at the repo root, read it before starting work and incorporate its guidance where applicable.
• If project docs contradict general best practices, prefer project docs and flag potential staleness for user confirmation.
• If docs are silent, use current best practices and suggest where to document the decision.

6.2 Current phase: Phase 0 (Planning & Architecture)

• No application code is expected yet. When asked to review or run/build code, first verify whether it exists.
• Focus on architecture, design, and documentation review rather than implementation critique.
• Keep phase/status aligned across README.md, DOCS.md, and docs/phases-plan.md; update when the phase changes.

---

7. Maintenance

• Keep RULES.md short, stable, and agent‑agnostic.
• Put stack‑specific or domain‑specific guidance into docs/ and/or agent profiles.
• Adding a new agent should only require a new file in agents/; update RULES.md only if the selection/coordination protocol changes.
• Update Section 3 whenever a new repository‑wide constraint is introduced.
• After completing a task, ask the user whether to update any affected documentation, especially README.md, DOCS.md, docs/phases-plan.md, and root recommendations files RECOMMENDATIONS.md. Only apply such updates with explicit user confirmation.

---