# Repository Directory Guide This file helps AI coding agents navigate the repository structure efficiently. Updated: 2026-04-16 ## Architecture Overview This repository is the **centralized brain** (`replica-omnisciente`) of the Portugal Futurista agent fleet (`git@github.com:fabiorafaelcoutada/replica-omnisciente.git`). It serves as a **persistent, multi-realm intelligence engine** — a Hybrid Memory Engine that replicates engineering knowledge across projects. When embedded in a host project, it is mounted as the `replica-omnisciente` Git submodule (`git@github.com:fabiorafaelcoutada/replica-omnisciente.git`). When the submodule is cloned into a host project, it maps to `replica-omnisciente/` and provides: - **Identity** — Who the agent is and how it behaves - **Realms** — Per-project knowledge boundaries with their own memory, workflows, and AGENTS.md - **Memory** — Global cross-cutting knowledge (architecture rules, synergy protocols, infrastructure) - **Skills** — Specialized capabilities (16 skills: from PDF/PPTX generation to network reconnaissance) - **Workflows** — Repeatable agentic procedures (17 workflows: commit, brainstorm, swarm, etc.) - **MCP Servers** — Model Context Protocol servers for device telemetry, electrical sourcing, etc. - **Swarm** — Multi-agent orchestration infrastructure (Kimi Agent Swarm) --- ## Submodule Layout > **Note:** This guide documents the `replica-omnisciente` central brain only. Host-project structure (source code, tools, tests, CI) is documented in each realm's `AGENTS.md` and the host repo's root `AGENTS.md`. ``` replica-omnisciente/ (central brain / submodule) │ ├── AGENTS.md ← Bootstrapping protocol (realm auto-discovery) ├── DIRECTORY_GUIDE.md ← This file ├── .agent_task ← Pending task queue for agentic dispatch (legacy name) ├── .gitignore ← Submodule-level ignores │ │ ── IDENTITY ── │ ├── identity/ ← Agent identity and behavioral directives │ └── README.md ← Replica-Omnesciente manifesto (core tenets, voice, tone) │ │ ── HYBRID MEMORY ENGINE ── │ ├── memory/ ← Global cross-cutting memory │ ├── index.md ← Central navigation hub for all memory │ ├── log.md ← Activity log (dispatches, ingestions, quota tracking) │ ├── alignment/ ← Architectural guardrails & synergy protocols │ │ ├── architecture-rules.md │ │ └── synergy-protocols.md │ ├── infrastructure/ ← Cross-realm infrastructure knowledge │ │ └── proxmox-containers.md │ └── swat-swarms/ ← Swarm orchestration knowledge │ └── orchestration-playbook.md │ │ ── REALMS (Per-Project Knowledge Boundaries) ── │ ├── realms/ ← Each realm = one project/domain context │ ├── smart-device-firmware/ ← ESP32-S3 firmware │ │ ├── AGENTS.md ← Realm-specific agent directives │ │ ├── memory/ ← Realm-scoped knowledge base │ │ │ ├── index.md ← Realm memory navigation │ │ │ ├── firmware/ ← FSM, memory architecture, power management │ │ │ ├── hardware/ ← Power electronics │ │ │ └── infrastructure/ ← AWS IoT, DynamoDB, MCP, HIL/Proxmox │ │ ├── workflows/ ← Realm-specific workflows (12 workflows) │ │ │ ├── analyze.md ← Structured CI/device/fleet/Jira analysis │ │ │ ├── demo-ci.md ← Live CI pipeline demo │ │ │ ├── doc-sync.md ← Docs ↔ code ↔ Jira sync │ │ │ ├── plan.md ← Implementation planning │ │ │ ├── pr-sync.md ← PR ↔ Jira synchronization │ │ │ ├── unit-test.md ← Unity test automation │ │ │ ├── validate-merge.md ← Merge readiness validation │ │ │ └── ... │ │ ├── skills/ ← Realm-specific skills │ │ │ ├── firmware-log-analyzer/ ← Analyze device logs for bugs │ │ │ └── telemetry-analyzer/ ← Query InfluxDB telemetry │ │ ├── plans/ ← Implementation plans │ │ ├── research/ ← Technical feasibility studies │ │ ├── chat-sessions/ ← Session persistence │ │ ├── bugfixes/ ← Bug fix documentation │ │ ├── reports/ ← Generated reports │ │ ├── presentations/ ← Presentation materials │ │ ├── sessions/ ← Named session snapshots │ │ ├── technology/ ← Tool/integration reference docs │ │ └── scratch/ ← Ephemeral research code │ │ │ ├── guarda-livros-da-ode/ ← Django backend API realm │ ├── nervura-electrica/ ← Infrastructure & DevOps realm │ ├── aprendiz-de-sensacoes/ ← Edge-AI models realm │ ├── iot-backend/ ← MQTT / telemetry pipelines realm │ ├── maquina-na-mao/ ← Mobile app realm │ ├── janela-do-desassossego-web/ ← Web dashboard realm │ ├── ode-electromagnetica/ ← Electrical / PCB design realm │ └── mafiuza-vscode-cli/ ← VS Code CLI extension realm │ │ ── SHARED SKILLS (Cross-Realm) ── │ ├── skills/ ← 16 shared skills │ ├── caveman/ ← Ultra-compressed communication mode │ ├── caveman-review/ ← Compressed PR review comments │ ├── docx/ ← Word document generation/manipulation │ ├── pdf/ ← PDF reading, merging, splitting, OCR │ ├── pptx/ ← PowerPoint creation/editing │ ├── present/ ← Technical presentations from project state │ ├── mcp-builder/ ← Build new MCP servers │ ├── skill-creator/ ← Create new skills │ ├── jules-orchestrator/ ← Google Jules task dispatch │ ├── ffind/ ← Firmware file finder + extraction │ ├── iotnet/ ← IoT network traffic analysis │ ├── logicmso/ ← Logic analyzer capture analysis │ ├── netflows/ ← Network flow extraction from pcaps │ ├── nmap/ ← Network reconnaissance │ ├── picocom/ ← UART console interaction │ └── telnetshell/ ← Telnet shell interaction │ │ ── SHARED WORKFLOWS ── │ ├── workflows/ ← 17 shared workflows (slash commands) │ ├── atomic-commits.md ← Git commit best practices │ ├── auto-save-session.md ← Auto-save session artifacts │ ├── brainstorm.md ← Requirements discovery │ ├── document.md ← Documentation generation │ ├── estimate.md ← Development estimates │ ├── explain.md ← Technical explanations │ ├── research.md ← Technical discovery │ ├── resume-session.md ← Restore previous session │ ├── save-current-session.md │ ├── save-as-new-session.md │ ├── start-new-session.md │ ├── swarm.md ← Multi-agent swarm orchestration │ ├── jules-dispatch.md ← Google Jules task dispatch │ ├── squash-commits.md ← Git squash workflow │ ├── stitch-ui-enhancement.md ← UI design with Stitch │ ├── migrate-vbox-to-proxmox.md ← VM migration │ └── transumancia-indagante.md ← Realm expansion protocol │ │ ── MCP SERVERS ── │ ├── mcp/ ← Model Context Protocol servers │ ├── savearth-mcp/ ← Primary MCP (18+ tools: device, telemetry, CI, infra) │ ├── engineering-mcp/ ← Electrical engineering MCP (sourcing, BOM, schematic) │ ├── jules-mcp/ ← Google Jules integration MCP │ ├── jules-mcp-server/ ← Jules MCP server implementation │ ├── setup.sh ← Proxmox LXC deployment script │ ├── DEPLOY_INSTRUCTIONS.md ← Deployment guide │ └── README.md ← MCP setup and configuration guide │ │ ── SWARM INFRASTRUCTURE ── │ └── swarm/ ← Kimi Agent Swarm (multi-agent orchestration) ├── orchestrator.py ← Task distribution and aggregation ├── agents/ ← Specialized agent definitions │ ├── firmware-analyzer.yaml │ ├── infra-analyzer.yaml │ ├── log-processor.yaml + server │ ├── regression-detector.yaml + server │ ├── ota-validator.yaml + server │ └── report-synthesizer.yaml + server ├── dashboard/ ← Web dashboard (Flask, port 8085) ├── results/ ← Swarm execution results ├── deploy.sh ← Main deployment script ├── deploy-agents.sh ← Agent deployment ├── deploy-specialized-agents.sh └── README.md ← Swarm quick start ``` --- ## Hybrid Memory Engine — How It Works The memory system has two levels: ### 1. Global Memory (`memory/`) Cross-cutting knowledge that applies to **all realms**: - `memory/index.md` — Central navigation hub - `memory/alignment/` — Architecture rules and synergy protocols between realms - `memory/infrastructure/` — Shared infrastructure knowledge (Proxmox containers) - `memory/swat-swarms/` — Swarm orchestration playbooks - `memory/log.md` — Activity log of significant dispatches and ingestions ### 2. Realm Memory (`realms//memory/`) Scoped knowledge for a **specific project/domain**: - Each realm has its own `AGENTS.md` → stack-specific directives - Each realm has its own `memory/index.md` → subsystem maps - Each realm has its own `workflows/`, `skills/`, `plans/`, `research/`, `chat-sessions/` **Navigation protocol:** 1. Identify the realm of the current task 2. Read that realm's `AGENTS.md` 3. Read that realm's `memory/index.md` 4. Drill into specific memory files as needed 5. Consult global `memory/index.md` for cross-realm concerns --- ## Realms Registry | Realm | Folder | Purpose | |-------|--------|---------| | **Smart Device Firmware** | `realms/smart-device-firmware/` | ESP32-S3 shower monitor firmware | | **Guarda-Livros da Ode** | `realms/guarda-livros-da-ode/` | Django backend API | | **Nervura Eléctrica** | `realms/nervura-electrica/` | Infrastructure & DevOps | | **Aprendiz de Sensações** | `realms/aprendiz-de-sensacoes/` | Edge-AI models | | **IoT Backend** | `realms/iot-backend/` | MQTT / telemetry pipelines | | **Máquina na Mão** | `realms/maquina-na-mao/` | Mobile app | | **Janela do Desassossego Web** | `realms/janela-do-desassossego-web/` | Web dashboard | | **Ode Electromagnética** | `realms/ode-electromagnetica/` | Electrical / PCB design | | **Mafiuza VS Code CLI** | `realms/mafiuza-vscode-cli/` | VS Code CLI extension | --- ## Directories to IGNORE When Searching When scanning for agent-relevant content, **skip** these directories: - `swarm/results/` — ephemeral swarm outputs - `swarm/__pycache__/` — Python bytecode cache - `realms/*/scratch/` — ephemeral research code - `mcp/**/node_modules/` — Node dependencies - `mcp/**/__pycache__/` — Python bytecode cache ## Key Entry Points | Task | Path | |------|------| | Agent identity | `identity/README.md` | | Global memory index | `memory/index.md` | | Realm memory (example) | `realms/smart-device-firmware/memory/index.md` | | MCP server (primary) | `mcp/savearth-mcp/` | | MCP server (electrical) | `mcp/engineering-mcp/` | | Swarm orchestrator | `swarm/orchestrator.py` | | Swarm dashboard | `http://192.168.0.16:8085` | ## Workflow Resolution Order When a slash command is invoked (e.g. `/unit-test`), the agent searches: 1. **Realm-specific workflows** → `realms//workflows/` (takes precedence) 2. **Shared workflows** → `workflows/` ## Skill Resolution Order When a skill is needed: 1. **Realm-specific skills** → `realms//skills/` 2. **Shared skills** → `skills/`