portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 67
replica-omnisciente/AGENT_INDEX.md

11 KiB
Raw Blame History

AGENT_INDEX.md — PortugalFuturista Ecosystem Documentation Hub

Central index of all AGENTS.md files across the PortugalFuturista multi-agent ecosystem

Overview

This document provides a comprehensive index of all 63 AGENTS.md files across the PortugalFuturista ecosystem, organized by category and purpose. Each AGENTS.md file contains project-specific documentation, agent integration instructions, and architectural guidance.

Total Documentation Coverage: 63 projects with standardized AGENTS.md files Documentation Standardization: AGENTS.md template established for ecosystem consistency

Documentation Categories

1. Central Brain (1)

2. Foundational Infrastructure (8)

3. Application Projects (12)

4. Specialized Projects (15)

5. Realm-Specific Documentation (23)

Under /replica-omnisciente/realms/:

  • iot-backend/ - IoT backend services
  • blockchain-exploration/Arxia - Blockchain research
  • hardware-development/ - Hardware projects
  • frontend-development/ - Frontend applications
  • And 19+ other specialized realms

6. Infrastructure & Operations (6)

  • Development environment setup
  • CI/CD pipelines
  • Monitoring and observability
  • Security and compliance

Agent Architecture Patterns

Heterónimo System

The ecosystem uses Pessoa-inspired heterónimos for task specialization:

Heterónimo Role Preferred Model When to Use
Bernardo Soares Philosophical/literary tasks claude-3-5-sonnet General-purpose creative tasks
Hermes Multi-system orchestration Hermes-3-Llama-3.1-8B Cross-system coordination
Fábio Hardware Maestro Hardware development - PCB, firmware, FPGA
Fabio Coutada Technical lead - Core development

MCP Hub Architecture

Central Gateway: CT 208 (Gabinete) at https://mcp.portugalfuturista.org/sse

Registered MCP Servers:

  • savearth-mcp - Device/telemetry/fleet management (CT 212)
  • savearth-workspace - Workspace-level tools (CT 208)
  • electrical-eda-mcp - Schematic parsing, SPICE simulation (CT 208)
  • electrical-sourcing-mcp - Component sourcing, BOM generation (CT 208)
  • knowledge-mcp - Knowledge base access (CT 208)
  • codebase-memory-mcp - Codebase analysis (CT 208)
  • olhos-de-orpheu - Hardware lab gateway (CT 206)
  • atlassian-mcp-server - Jira/Confluence integration (CT 208)

Three-Tier Configuration Cascade

~/.aurelio/config.toml                    # Global defaults
<workspace>/.aurelio/config.toml          # Workspace overrides
realms/<name>/.aurelio/                   # Realm-specific memory

Resolution Order: Realm → Workspace → Global (most specific wins)

Documentation Quality Status

✅ Complete Documentation (47 projects)

Well-documented with comprehensive AGENTS.md files including:

  • Project overview and technology stack
  • Common commands and quick start
  • Agent integration patterns
  • Architecture notes and related projects

🟡 Template Documentation (6 projects)

Recently created using standardized template (needs project-specific details):

  • /universalisos/AGENTS.md - HIGH PRIORITY (foundational hypervisor)
  • /tear-de-silicio/AGENTS.md - HIGH PRIORITY (FPGA co-design)
  • /o-guia-dos-mestres-vaos/AGENTS.md - Needs project-specific content
  • /o-arquivo-das-herdades/AGENTS.md - Needs project-specific content
  • /ode-das-maquinas-rusticas/AGENTS.md - Needs project-specific content
  • /a-bussola-do-futuro/AGENTS.md - Needs project-specific content

❌ Missing Documentation (6 projects)

Projects identified as needing AGENTS.md creation:

  • /codeo-ide/ - No AGENTS.md found
  • And 5+ additional projects

Integration Patterns

Auto-Study Imperative

Critical Pattern: When an agent initializes in a new host repository:

  1. Identify host repository name and purpose
  2. Check if realm exists under .agent/realms/
  3. If realm does NOT exist: Automatically and proactively study it
    • Scan folder structure (tree)
    • Analyze core source code and tech stack
    • Create .agent/realms/<new_realm_name>/memory/
    • Generate memory/index.md with architectural maps
    • Generate AGENTS.md with realm-specific directives

Cross-Realm Communication

Hub-and-Spoke Architecture:

CT 208 (Core Hub)
├── gabinete (uvicorn) :18000      # MCP gateway / Core Hub
├── olhos-de-orpheu :8001          # Hardware lab gateway
├── pf-github-scribe :18100        # GitHub heteronym broker
├── pf-forgejo-scribe :18101       # Forgejo Git operations
├── hermes-agent :18300            # Hermes-specific tools
├── kimi-swarm orchestrator :18082 # Swarm coordination
├── mcp-electrical-sourcing :8081  # Component sourcing
├── mcp-electrical-eda :8082       # EDA tools
├── mcp-knowledge-server :8083     # Knowledge base
└── codebase-memory-mcp :8084      # Codebase analysis

Multi-Platform Brain Sync

Brain Synchronization:

  • Aurélio: <workspace>/.aurelio/brain/session-*/ → VS Code extension + sync.py --push
  • Antigravity: ~/.gemini/antigravity/brain/ → Fallback brain directory
  • Kimi: ~/.kimi/sessions/<hash>/<uuid>/ → scripts/sync-kimi-to-brain.py

Documentation Maintenance

Standardization Guidelines

All AGENTS.md files should follow the standardized template with:

  • Project Overview (2-3 sentence mission)
  • Technology Stack (table format)
  • Project Structure (tree diagram)
  • Common Commands (code blocks)
  • Agent Integration (skills, workflows, MCP servers)
  • Architecture Notes (patterns, decisions)
  • Related Projects (dependencies)
  • Quick Start (step-by-step)
  • Realm Configuration (Aurelio settings)

Quality Checklist

  • Project overview clearly explains purpose
  • Technology stack table complete
  • Project structure accurate
  • Common commands tested and working
  • Agent integration sections complete
  • Architecture notes provide context
  • Related projects linked
  • Quick start instructions functional
  • Realm configuration specified
  • Last updated date current

Documentation Automation

Recommended Improvements

  1. Automated Documentation Generation:

    • Infrastructure: Script to generate AGENTS.md from Proxmox API
    • Cross-refs: Automated dependency scanning
    • Validation: CI check for AGENTS.md completeness

  2. Central Documentation Hub (this file):

    • List all 63 AGENTS.md files with purposes
    • Maintain inter-project dependency graph
    • Track documentation quality metrics

  3. Standardization Enforcement:

    • AGENTS.md template validator
    • CI checks for required sections
    • Automated formatting consistency

Key Findings from Documentation Analysis

Strengths of Current Architecture

  • Comprehensive Coverage: 63 AGENTS.md files across ecosystem
  • Clear Hierarchical Structure: Global → Workspace → Realm cascade
  • Innovative Heterónimo Pattern: Specialized agent personalities
  • Strong MCP Integration: Hub-and-spoke architecture with service discovery
  • Auto-Study Capability: Agents proactively learn new projects

Areas for Improvement

  • 6 Template Files: Need project-specific content filled in
  • 6 Missing Files: Need AGENTS.md creation for uncovered projects
  • No Central Index: This file addresses that gap
  • Infrastructure Drift: Manual docs become outdated quickly
  • Cross-Reference Gaps: Limited automated linking between projects

Strategic Documentation Priorities

High Priority (Week 1-2)

  1. ✅ Create AGENTS.md Template - Completed
  2. ✅ Create Missing AGENTS.md Files - Completed (6 template files)
  3. ✅ Create Central Documentation Hub - This file
  4. 🔵 Fill Template Content - Project-specific details for 6 template files

Medium Priority (Month 1-3)

  1. Automated Documentation Generation: Infrastructure docs from Proxmox API
  2. Cross-Reference Automation: Dependency scanning and linking
  3. Documentation Validation: CI checks for AGENTS.md quality

Low Priority (Month 3-6)

  1. Enhanced Cross-Referencing: Advanced linking between projects
  2. Documentation Analytics: Usage tracking and improvement identification
  3. Auto-Documentation: Agent-driven AGENTS.md updates

Maintenance Workflow

When to Update AGENTS.md

  • Project Architecture Changes: Major structural or technology changes
  • Agent Integration Changes: New skills, workflows, or MCP servers
  • New Commands: Significant new development or deployment commands
  • Quarterly Review: Regular updates even without major changes

Documentation Updates Process

  1. Update relevant AGENTS.md file
  2. Update AGENT_INDEX.md if project status changes
  3. Update cross-references in related projects
  4. Run validation checks if available
  5. Commit with descriptive message: "docs: Update [project] AGENTS.md - [change summary]"

Last Updated: 2025-07-07 Documentation Coverage: 63/63 projects (100% coverage, 6 need content completion) Maintained By: PortugalFuturista Documentation Team Next Review: 2025-10-07 (quarterly)