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

12 KiB

Raw 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:

Identify the realm of the current task
Read that realm's AGENTS.md
Read that realm's memory/index.md
Drill into specific memory files as needed
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:

Realm-specific workflows → realms/<current-realm>/workflows/ (takes precedence)
Shared workflows → workflows/

Skill Resolution Order

When a skill is needed:

Realm-specific skills → realms/<current-realm>/skills/
Shared skills → skills/

12 KiB Raw Blame History