NexusAgent - Corrected Architecture

Date: 2025-10-29
Critical Correction: Agents MUST stay in tool-specific folders

The Constraint

AI tools expect agents/commands/tools in THEIR specific folders:

OpenCode expects: .opencode/agent/, .opencode/command/
Cursor expects: .cursor/prompts/, .cursor/rules/
Claude expects: MCP servers in specific locations

We CANNOT move agents to .nexusagent/

Corrected Structure

project/
├── .nexusagent/                 # ONLY context & governance (shared)
│   ├── context/                # Domain knowledge (SHAREABLE)
│   │   ├── core/
│   │   ├── domain/
│   │   ├── processes/
│   │   └── standards/
│   │
│   └── governance/             # Data governance (SHAREABLE)
│       ├── metadata-index.json
│       ├── workflow-state.json
│       └── tmp/requests/
│
└── .opencode/                   # OpenCode-specific (PRIMARY)
    ├── agent/                  # MUST be here for OpenCode
    │   ├── main-orchestrator.md
    │   ├── context-provider.md
    │   └── subagents/
    │
    └── command/                # MUST be here for OpenCode
        ├── workflow.md
        └── plan-task.md

How It Works

1. Shared Context & Governance

.nexusagent/ contains ONLY:

Context files (markdown) - any tool can read
Governance data (JSON) - any tool can read
No agents, no commands, no tool-specific stuff

2. Tool-Specific Integration

Each tool has its own folder with agents/commands that REFERENCE the shared context:

OpenCode Agent Example:

---
description: "Main orchestrator"
mode: primary
---

# Main Orchestrator

**Load shared context from:**
@../.nexusagent/context/core/essential-patterns.md
@../.nexusagent/context/domain/business-rules.md

**Load governance metadata from:**
Read: ../.nexusagent/governance/metadata-index.json

[Rest of agent logic here]

3. Installation Creates Both

~/nexus/scripts/install.sh --profile governance

# Creates:
# 1. .nexusagent/           (shared context + governance)
# 2. .opencode/             (OpenCode agents + commands)
#    Agents reference: @../.nexusagent/context/

Directory Structure (Corrected)

project/
├── .nexusagent/                 # Universal shared resources
│   ├── nexus.json              # Configuration
│   │
│   ├── context/                # SHAREABLE context
│   │   ├── core/
│   │   │   └── essential-patterns.md
│   │   ├── domain/
│   │   │   ├── business-rules.md
│   │   │   └── data-models.md
│   │   ├── processes/
│   │   │   └── standard-workflow.md
│   │   └── standards/
│   │       └── quality-criteria.md
│   │
│   └── governance/             # SHAREABLE governance
│       ├── metadata-index.json
│       ├── workflow-state.json
│       ├── tmp/
│       │   └── requests/
│       └── logs/
│
└── .opencode/                   # OpenCode integration
    ├── agent/
    │   ├── main-orchestrator.md       # References @../.nexusagent/context/
    │   ├── context-provider.md        # References @../.nexusagent/context/
    │   └── subagents/
    │       ├── quality-validator.md   # References @../.nexusagent/governance/
    │       └── lifecycle-manager.md
    │
    └── command/
        ├── workflow.md                # References @../.nexusagent/context/
        └── validate.md

What Goes Where

`.nexusagent/` (Shared)

✅ Context files (markdown) ✅ Governance data (JSON) ✅ Metadata index ✅ Request files ✅ Workflow state ✅ Configuration

❌ Agents (they stay in tool folders) ❌ Commands (they stay in tool folders) ❌ Tool-specific anything

`.opencode/` (Tool-Specific)

✅ Agents (OpenCode format) ✅ Commands (OpenCode format) ✅ References to @../.nexusagent/context/ ✅ References to ../.nexusagent/governance/

`.cursor/` (Optional, User-Created)

✅ Prompts (Cursor format) ✅ Rules (Cursor format) ✅ Can reference ../.nexusagent/context/ ✅ Can reference ../.nexusagent/governance/

Benefits

Respects Tool Conventions
- Each tool gets agents/commands in expected locations
- Tools work normally
Shares What Can Be Shared
- Context (markdown files) - universal
- Governance data (JSON) - universal
- No duplication
Clean Separation
- Shared resources in .nexusagent/
- Tool-specific in tool folders
- Clear boundaries

Installation Process

# Install NexusAgent
~/nexus/scripts/install.sh --profile governance

# What it creates:
# 1. .nexusagent/context/     (shared context)
# 2. .nexusagent/governance/  (shared governance)
# 3. .opencode/agent/         (OpenCode agents)
# 4. .opencode/command/       (OpenCode commands)

# OpenCode agents reference:
# @../.nexusagent/context/
# ../.nexusagent/governance/

Agent Template (Corrected)

---
description: "Main orchestrator with shared context"
mode: primary
temperature: 0.2
---

# Main Orchestrator

<context>
  <system_context>
    NexusAgent orchestration system with shared context from .nexusagent/
  </system_context>
</context>

<!-- Load shared context -->
**Context files:**
@../.nexusagent/context/core/essential-patterns.md
@../.nexusagent/context/domain/business-rules.md

<!-- Access shared governance -->
**Governance data:**
Can read: ../.nexusagent/governance/metadata-index.json

<role>
  Primary orchestrator that uses shared context and governance
</role>

<task>
  Orchestrate tasks using shared context from .nexusagent/
</task>

[Rest of agent logic]

This Means We Build

In Profile (e.g., `~/nexus/profiles/governance/`)

governance/
├── nexusagent/                 # Goes to .nexusagent/
│   ├── context/
│   └── governance/
│
└── opencode/                   # Goes to .opencode/
    ├── agent/
    └── command/

Installation Copies To

Profile: governance/nexusagent/  → Project: .nexusagent/
Profile: governance/opencode/    → Project: .opencode/

Decision: Approved

This architecture: ✅ Respects tool conventions (agents stay in tool folders) ✅ Shares what can be shared (context + governance) ✅ Works with OpenCode (primary) ✅ Allows other tools to read shared resources (optional) ✅ No maintenance burden for multiple tools

Ready to build with this corrected structure.

CORRECTED-ARCHITECTURE.md 6.6 KB Permalink Histórico Raw