bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: consolidate all rules and specs into absolute sources of truth v1.2.8

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-11 12:03:27 +03:00
parent 432cd28ca5
commit 0a9ea0f575
10 changed files with 112 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
AI_RULES.md
View File

@@ -1,44 +1,42 @@
# AI AGENT RULES - SINGLE SOURCE OF TRUTH
# AI AGENT RULES - MANDATORY ENTRY POINT
This file is the single source of truth for ALL Artificial Intelligence agents working on this project (Claude, Gemini, etc.).
Agent-specific instructions are located in `GEMINI.md` and `CLAUDE.md`.
Any AI or session MUST respect these mandatory rules.
**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
This is the **Single Source of Truth** for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project.
For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
## General Rules
- **UI & Code Language**: All web interfaces, functions, variables, and any text inside the application MUST BE DIRECTLY AND ONLY IN ENGLISH.
- **Communication Language**: Conversation with the user will be in Romanian or English, preferably Romanian.
## Multi-AI Coordination & Handover
## 1. Multi-AI Coordination & Memory
- **MANDATORY STARTUP**: Every AI session MUST first read `dev_docs/SESSION_STATE.md` to understand current context.
- **MANDATORY HANDOVER**: At the end of every task/session, create or update a handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context** (details not in code), and **Next Steps**.
- **ARCHIVAL RULE**: To prevent `SESSION_STATE.md` from bloating, incoming AI agents MUST move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` before writing their own new state. This keeps `SESSION_STATE.md` focused only on the *active* session.
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it according to `SESSION_STATE.md`.
- **MANDATORY HANDOVER**: At the end of every task/session, update the handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context**, and **Next Steps**.
- **ARCHIVAL RULE**: Before writing new state, move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` to prevent bloat.
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it.
## Implementation Completion
- All code modifications MUST be committed in git before the task is considered finished. `VERSION.json` must be updated on EACH commit.
- **MANDATORY GIT RULE:** Never push to remote unless explicitly requested by the user. Only commit locally with proper messages. Always assume the user will handle all `git push` operations. If a task requires pushing, ask for explicit permission first.
- **GIT BINARY PATH**: On this macOS environment, the system `git` (in `/usr/bin/git`) is often broken due to `xcode-select` issues. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations.
- **GIT BRANCHING STRUCTURE**:
- The main stable branch is `master`.
- All active development MUST occur in the `dev` branch.
- Every major version MUST have its own dedicated archival branch named `vX` (e.g., `v1`, `v2`) which copies the state of the major release.
- **MANDATORY GIT RULE**: NO AI is allowed to write in git commits that it is the author or co-author (e.g., DO NOT add texts like `Co-Authored-By: AI...`). Commits should only contain technical messages.
- **MANDATORY LOGGING**: Any modification of code, architecture, or logic MUST be documented in `dev_docs/ARCHIVE_LOGS.md` at the end of the task. The log must include modified files, purpose of modification, and (if applicable) test results.
- **MANDATORY PLAN ARCHIVING**: Once a phase or task is confirmed as completed and verified, the Architect (Gemini/AI) MUST move these entries from `PLAN.md` into `dev_docs/PLAN_HISTORY.md`. This maintains the active plan's focus and prevents document bloat.
- After finishing an entire job, end your final response on a separate line exactly with:
## 2. Global Operational Laws
- **STRICT ENGLISH POLICY**: All web interfaces, code, variables, scripts, and documentation MUST BE DIRECTLY AND ONLY IN ENGLISH. If you find Romanian text in code, translate it immediately.
- **COMMUNICATION LANGUAGE**: Conversation with the user will be in Romanian or English (preferably Romanian).
- **GIT BINARY PATH**: On this macOS environment, the system `git` is often broken. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations.
- **COMMIT & PUSH STRICT RULE**:
- Never push to remote (`git push`) or use force flags (`--hard`, `--force`) unless explicitly requested.
- Always update `VERSION.json` on every commit.
- Do NOT add AI co-author signatures (e.g., `Co-Authored-By: AI...`) to commit messages.
- Branching: `master` (stable), `dev` (active development), `vX` (archival releases).
- **MANDATORY LOGGING**: Document coding/architecture changes in `dev_docs/ARCHIVE_LOGS.md` at the end of the task.
- **TRIPLE CONFIRMATION (Safe Forget)**: You cannot delete a physical location, item, or critical entity without explicit user permission three times.
## 3. UI/UX Fidelity Specifications
- **Fidelity First**: Never simplify the UI unless asked. Density and aesthetics must remain "Premium".
- **Styling**: Tailwind CSS. Font weights/spacing must be consistent (Inter/Roboto).
- **Readability**: NO `uppercase` or `tracking-widest` styles. Use standard camel/Title case.
- **Icons**: Use **Lucide Icons** exclusively. NO emojis.
- **Interactive Affordance**: All select/dropdown boxes MUST have a `ChevronDown` icon. Masked passwords should have reduced opacity (`text-white/50`).
- **Iconography Standardization**:
- **Categories**: ALWAYS use `Layers` (Color: `text-primary`).
- **Item Types**: ALWAYS use `Package` (Color: `text-green-500`).
## 4. End of Session Protocol
- Once a phase/task from `PLAN.md` is completed and verified, move that entry into `dev_docs/PLAN_HISTORY.md`.
- After finishing an entire job (including updating session state, architecture logs, and versioning), end your final response on a separate line exactly with:
```
---
✓ Done.
```
- Do not provide unnecessary summaries of the code.
## Triple Confirmation & Safety Limits
- **Safe Forget**: You cannot delete a physical location, item, or critical entity without a triple confirmation mechanism.
- **No Force Operations**: Never use destructive flags (e.g., `git reset --hard`, `git push --force`, `rm -rf`) without explicit user permission.
## UI/UX & Documentation Rules
- **STRICT ENGLISH POLICY**: ANY TEXT within the application (documentation, scripts, CLI, UI, internal comments, logs, etc.) MUST be strictly in English. NO Romanian characters (ăâîșț) or words are allowed in the repository.
- **MANDATORY TRANSLATION**: Any Romanian text found during an AI session (in any file) MUST be translated to English immediately.
- Use Lucide Icons (standard React components); never use emojis or legacy Bootstrap icons.
- The UI must remain fully functional offline (no external CDNs).
- **MANDATORY UI FIDELITY**: Any modification to UI components (headers, banners, cards, buttons) MUST comply with the specifications in `dev_docs/UI_FIDELITY_SPEC.md` to prevent regressions. All agents MUST read that document before modifying frontend code.
- Do not provide unnecessary verbatim summaries of the code.