db5ba04fb9
Agents: - Add YAML frontmatter (model, tools) to all 7 existing agents - New agents: planner (opus), build-error-resolver (sonnet), loop-operator (sonnet) Skills: - search-first: research before building (Adopt/Extend/Compose/Build) - verification-loop: full quality gate pipeline (Build→TypeCheck→Lint→Test→Security→Diff) - strategic-compact: when and how to run /compact effectively - autonomous-loops: 6 patterns for autonomous agent workflows - continuous-learning: extract session learnings into instincts Hooks: - Profile system (minimal/standard/strict) via run-with-profile.sh - config-protection: block linter/formatter config edits (standard) - suggest-compact: remind about /compact every ~50 tool calls (standard) - auto-tmux-dev: suggest tmux for dev servers (standard) - session-save/session-load: persist and restore session context (Stop/SessionStart) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# 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.
|
||
|
||
---
|