portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 73
replica-omnisciente/DIRECTORY_GUIDE.md
Fábio Cunha 4fd171b0a4 chore(conscience): upgrade to v0.10.0 and align submodule paths 
- Add savearth-workspace MCP server deployment to conscience state.
- Refactor .agent/ references to replica-omnisciente/ in operational
  scripts (setup.sh, savearth-mcp/server.py) and docs (READMEs,
  DIRECTORY_GUIDE.md, upgrade-conscience workflow).
- Document remaining legacy misspellings and stale .agent/ doc refs
  for follow-up cleanup.
- Record conscience upgrade report in data/conscience/ and
  .aurelio/memory/conscience_upgrade_report.md.

[skip ci]
2026-07-04 23:01:09 +01:00

239 lines
12 KiB
Markdown
Raw Permalink Blame History

# 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/<realm>/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/<current-realm>/workflows/` (takes precedence)
2. **Shared workflows** → `workflows/`
## Skill Resolution Order
When a skill is needed:
1. **Realm-specific skills** → `realms/<current-realm>/skills/`
2. **Shared skills** → `skills/`
Reference in a new issue View git blame Copy permalink