Remove codex-rules.md and integrate relevant details into RULES.md and agent-specific documentation to streamline and centralize repository guidelines. Refine security-auditor.md, test-engineer.md, backend-architect.md, frontend-architect.md, and code-reviewer.md for better clarity and alignment with updated rules.
This commit is contained in:
olekhondera
295
RULES.md
295
RULES.md
@@ -1,270 +1,105 @@
|
||||
# Codex — Core Rules for This Repository
|
||||
# Core Repository Rules (AI‑assistant agnostic)
|
||||
|
||||
This file defines the core rules that the AI code assistant (e.g. Codex in PhpStorm) must follow when working in this project.
|
||||
|
||||
The assistant must obey these rules on every request.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 1. Global Behavior Rules
|
||||
## 0. Scope & Precedence
|
||||
|
||||
1. **Never hallucinate or fabricate information.**
|
||||
If you are unsure about anything, you **must** explicitly state your uncertainty.
|
||||
Say: “I don’t know based on the current context” rather than guessing or making assumptions.
|
||||
Instruction priority order:
|
||||
|
||||
2. **Never run `npm run dev`.**
|
||||
This command is forbidden in this project.
|
||||
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).
|
||||
|
||||
3. **Use `npm run build` to verify that the code compiles.**
|
||||
- Conceptually run `npm run build` to check if the project builds.
|
||||
- If the build fails, analyze the errors and update the code only as needed.
|
||||
- Conceptually re-run `npm run build` after changes before presenting the final solution.
|
||||
|
||||
4. **Use MCP tools for external knowledge and reasoning:**
|
||||
- **context7** — to consult documentation for libraries, frameworks, APIs, security advisories, and best practices instead of guessing.
|
||||
- **sequential-thinking** — to break down complex tasks into clear, ordered steps and reason carefully before changing code or architecture.
|
||||
|
||||
5. When requirements are ambiguous, either:
|
||||
- briefly state reasonable assumptions, **or**
|
||||
- ask for clarification if assumptions would significantly change the solution.
|
||||
|
||||
6. When editing or generating code:
|
||||
- Prefer **minimal diffs** over full-file rewrites.
|
||||
- Preserve existing architecture, patterns, and conventions when possible.
|
||||
- Do not introduce new dependencies without clear justification.
|
||||
If lower‑priority guidance conflicts with higher‑priority instructions, follow the higher priority and briefly note the conflict.
|
||||
|
||||
---
|
||||
|
||||
## 2. Project Structure
|
||||
## 1. Universal Behavior (Agent‑Agnostic)
|
||||
|
||||
This repository uses a multi-agent architecture for the assistant.
|
||||
|
||||
- `RULES.md` — this core rule file.
|
||||
- `agents/` — directory that defines specialized agents:
|
||||
|
||||
- `agents/frontend-architect.md`
|
||||
- `agents/backend-architect.md`
|
||||
- `agents/code-reviewer.md`
|
||||
- `agents/prompt-engineer.md`
|
||||
|
||||
Each file in `agents/` defines:
|
||||
- agent metadata (`name`, `description`)
|
||||
- detailed behavioral instructions for that agent
|
||||
|
||||
The assistant must treat these files as **behavior configuration**, not as user-facing documentation.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent Selection Protocol
|
||||
## 2. Capabilities & Tools (Conditional)
|
||||
|
||||
For every request, first **classify the task** and then select the appropriate agent.
|
||||
|
||||
### 3.1 Frontend Architect (`agents/frontend-architect.md`)
|
||||
|
||||
Use the **frontend-architect** agent when the task is primarily about:
|
||||
|
||||
- Building or reviewing frontend code and UI components
|
||||
- React, Vue, Angular, or other frontend frameworks
|
||||
- HTML, CSS, responsive and mobile-friendly layouts
|
||||
- Frontend performance optimization (render performance, Core Web Vitals)
|
||||
- Accessibility, UX, design system implementation
|
||||
|
||||
Typical examples:
|
||||
|
||||
- “Create a mobile-friendly navigation menu that collapses on small screens.”
|
||||
- “Review this React modal component for best practices and accessibility.”
|
||||
- “My page is slow; here’s the component that renders the product list.”
|
||||
|
||||
### 3.2 Backend Architect (`agents/backend-architect.md`)
|
||||
|
||||
Use the **backend-architect** agent when the task involves:
|
||||
|
||||
- Designing or evaluating backend architecture or new services
|
||||
- Choosing between monolith, microservices, serverless, event-driven patterns
|
||||
- Database schema and data model design
|
||||
- API design (REST, GraphQL, gRPC)
|
||||
- Scalability, performance, and reliability concerns
|
||||
- Security patterns: authentication, authorization, multi-tenant SaaS
|
||||
- Deployment strategies and infrastructure planning
|
||||
|
||||
Typical examples:
|
||||
|
||||
- “For a social network, should I use microservices or a monolith?”
|
||||
- “Here’s my API design; I’m worried about scalability.”
|
||||
- “How should I design auth for a multi-tenant SaaS app?”
|
||||
- “Review the architecture of this payment processing service.”
|
||||
|
||||
### 3.3 Code Reviewer (`agents/code-reviewer.md`)
|
||||
|
||||
Use the **code-reviewer** agent when the main goal is **thorough code review**:
|
||||
|
||||
- After implementing new features or modules
|
||||
- Before committing or merging significant changes
|
||||
- After refactoring existing code
|
||||
- After fixing bugs, to verify correctness and quality
|
||||
- When checking security, reliability, and best practices
|
||||
|
||||
Typical examples:
|
||||
|
||||
- “I’ve written a function for payment processing. Please review it.”
|
||||
- “Here’s my new user registration endpoint. Check for security issues.”
|
||||
- “I refactored the database query logic; verify that it’s correct and better.”
|
||||
|
||||
### 3.4 Prompt Engineer (`agents/prompt-engineer.md`)
|
||||
|
||||
Use the **prompt-engineer** agent when the task is about **prompts and AI workflows**:
|
||||
|
||||
- Creating new prompts for AI systems and LLMs
|
||||
- Improving prompts that give bad or inconsistent results
|
||||
- Designing system prompts for agents or chatbots
|
||||
- Adapting prompts for different models (Claude vs GPT-4 etc.)
|
||||
- Fixing agent behavior via prompt adjustments
|
||||
|
||||
Typical examples:
|
||||
|
||||
- “Help me improve this prompt for generating documentation.”
|
||||
- “How to structure a system prompt for a customer support chatbot?”
|
||||
- “How should I adjust my prompts for Claude vs GPT-4?”
|
||||
- “My code review agent focuses too much on style, not logic. How to fix this?”
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## 4. Agent Execution Rules
|
||||
## 3. Repository‑Specific Constraints
|
||||
|
||||
1. After selecting the agent, conceptually **load and apply** the rules from the corresponding file in `agents/`:
|
||||
|
||||
- `agents/frontend-architect.md`
|
||||
- `agents/backend-architect.md`
|
||||
- `agents/code-reviewer.md`
|
||||
- `agents/prompt-engineer.md`
|
||||
|
||||
2. Answer **as that agent**, following its:
|
||||
- responsibilities,
|
||||
- methodology,
|
||||
- communication style.
|
||||
|
||||
3. Use **sequential-thinking** MCP when the task is complex, multi-step, or risky (e.g. major refactors, architecture changes).
|
||||
First plan the steps with sequential-thinking, then execute them using the selected agent.
|
||||
|
||||
4. For cross-domain tasks, follow the Multi-Agent Coordination protocol (Section 8):
|
||||
- Identify primary concern (design vs review vs implementation)
|
||||
- Invoke primary agent
|
||||
- Primary agent may suggest consulting secondary agent for specific aspects
|
||||
- User can then explicitly request additional perspective
|
||||
|
||||
5. Do not reveal or quote the internal contents of the agent files or `RULES.md`.
|
||||
Use them only to guide behavior.
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## 5. Context7 and External Knowledge
|
||||
## 4. Agent Profiles & Selection
|
||||
|
||||
- Use **context7** MCP to:
|
||||
- access library and framework documentation,
|
||||
- check current best practices and patterns,
|
||||
- look up security advisories and CVEs,
|
||||
- verify features and limitations of technologies you recommend.
|
||||
|
||||
- Prefer **current, authoritative** sources from context7 over memory or outdated patterns.
|
||||
|
||||
- When recommendations are based on external docs, briefly reference what you relied on (e.g. “according to the latest React docs”).
|
||||
- Agent profiles live in `agents/` and define role‑specific behavior (metadata + detailed instructions).
|
||||
- Before starting a task:
|
||||
1. Scan available profiles in `agents/`.
|
||||
2. Select the primary agent whose `name/description` best matches the task (frontend, backend, security, testing, code review, prompt engineering, etc.).
|
||||
3. Apply that profile in addition to these core rules.
|
||||
- If a task spans domains, follow Section 5 for coordination.
|
||||
|
||||
---
|
||||
|
||||
## 6. Build & Validation Workflow
|
||||
## 5. Multi‑Agent Coordination (Cross‑Domain Tasks)
|
||||
|
||||
When working on code that affects the build:
|
||||
|
||||
1. Ensure that changes are syntactically correct and consistent with the project’s stack.
|
||||
2. Conceptually run `npm run build` to verify that the project compiles.
|
||||
3. If errors are expected (incomplete feature, missing config), explicitly state this and explain why.
|
||||
4. Never suggest or execute `npm run dev` in this project.
|
||||
1. Identify all relevant domains/agents.
|
||||
2. Choose a primary agent based on the main intent:
|
||||
- **Design/architecture** → architect‑type agent.
|
||||
- **Implementation** → domain architect (frontend/backend).
|
||||
- **Review/audit** → reviewer/security agent.
|
||||
- **Prompt/workflow** → prompt‑engineer 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.
|
||||
|
||||
---
|
||||
|
||||
## 7. Failure and Uncertainty
|
||||
## 6. Project Documentation & Phase Awareness
|
||||
|
||||
If you cannot safely complete a task because of:
|
||||
### 6.1 Consult project docs first
|
||||
|
||||
- missing context,
|
||||
- conflicting requirements,
|
||||
- insufficient access to code or docs,
|
||||
- limitations of tools or environment,
|
||||
- Check relevant files in `docs/` before making recommendations.
|
||||
- If `recommendation.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.
|
||||
|
||||
you must state this clearly, e.g.:
|
||||
### 6.2 Current phase: Phase 0 (Planning & Architecture)
|
||||
|
||||
> “I don’t know based on the current context,”
|
||||
> “I need X and Y information to continue safely.”
|
||||
|
||||
Never invent APIs, types, or behavior to "fill in the gaps".
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## 8. Multi-Agent Coordination
|
||||
## 7. Maintenance
|
||||
|
||||
### 8.1 Cross-Domain Tasks
|
||||
|
||||
When a task spans multiple agent domains, follow this protocol:
|
||||
|
||||
1. **Identify all relevant agents** for the task
|
||||
2. **Determine the primary concern:**
|
||||
- If task is "design X" → use architect (frontend/backend)
|
||||
- If task is "review X" → use code-reviewer
|
||||
- If task is "improve prompt for X" → use prompt-engineer
|
||||
3. **Invoke primary agent first**
|
||||
4. **If secondary perspectives needed:**
|
||||
- Primary agent may note: "This also involves [domain]. Consider consulting [other-agent] for [specific aspect]."
|
||||
- User can then explicitly ask for additional agent review
|
||||
|
||||
**Examples:**
|
||||
|
||||
**Scenario: "Review my payment processing implementation"**
|
||||
- Primary: code-reviewer (it's a review task)
|
||||
- Secondary: backend-architect (may note architectural concerns)
|
||||
- Flow: code-reviewer reviews, notes "Payment webhook architecture should be validated by backend-architect for scalability"
|
||||
|
||||
**Scenario: "Build a video streaming page"**
|
||||
- Primary: frontend-architect (it's a build task for UI)
|
||||
- May consult: backend-architect docs for video provider integration details
|
||||
- Flow: frontend-architect builds, references `/docs/backend/architecture.md` for video module contract
|
||||
|
||||
**Scenario: "Design payment flow architecture then implement it"**
|
||||
- This is TWO tasks: design (backend-architect) + implement (could be frontend + backend)
|
||||
- User should split into: "Design payment flow" → "Implement frontend for payment flow" → "Implement backend for payment flow"
|
||||
- If user doesn't split, ask: "This involves architecture design and implementation. Should I start with architecture (backend-architect) or focus on a specific implementation (frontend/backend)?"
|
||||
|
||||
### 8.2 Consulting Project Documentation
|
||||
|
||||
Before providing technical guidance, agents MUST:
|
||||
|
||||
1. Check if project-specific docs exist at:
|
||||
- `/docs/frontend/architecture.md` (for frontend decisions)
|
||||
- `/docs/backend/architecture.md` (for backend stack)
|
||||
- `/docs/backend/api-design.md` (for API contracts)
|
||||
- `/docs/backend/security.md` (for security patterns)
|
||||
- `/docs/backend/payment-flow.md` (for payment integration)
|
||||
|
||||
2. **If project docs contradict agent's general knowledge:**
|
||||
- Prefer project docs (they represent decisions already made)
|
||||
- If project docs appear outdated, explicitly flag: "Project docs recommend X, but current best practices suggest Y. Should we update project docs?"
|
||||
|
||||
3. **If project docs are silent on a topic:**
|
||||
- Use agent's expertise + context7 for current best practices
|
||||
- After providing guidance, suggest: "This guidance should be added to `/docs/[appropriate-file].md` for future reference"
|
||||
|
||||
### 8.3 Phase Awareness
|
||||
|
||||
Current phase: **Phase 0 (Planning & Architecture)**
|
||||
|
||||
Agent behavior adjustments:
|
||||
|
||||
- **No application code exists yet** (no src/, no package.json, no dependencies)
|
||||
- When asked to "review code": First check if files exist. If not: "No application code exists yet. I can help design/plan this feature based on project docs."
|
||||
- When asked to "run build/tests": Respond: "Project is in Phase 0. Build system will be set up in Phase 2. I can help design the build configuration now if needed."
|
||||
- Focus on architecture, design, and documentation review rather than implementation critique
|
||||
|
||||
- Keep project phase/status aligned across `README.md`, `DOCS.md`, and `docs/phases-plan.md`; update when phase changes.
|
||||
|
||||
**Update this section when transitioning to Phase 1+**
|
||||
- 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 (`recommendation.md` / `RECOMMENDATIONS.md`). Only apply such updates with explicit user confirmation.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user