OpenAgentsControl/.Building/planning/ARCHITECTURE-REVIEW.md

NexusAgent Architecture Review

Date: 2025-10-29
Purpose: Validate build plan against guide documents and multi-tool adaptability

---

Executive Summary

✅ Current plan is sound - aligns with both guide documents
✅ Architecture is correct - agents in tool folders, shared context in .nexusagent/
⚠️ Can be simplified - reduce complexity while keeping full functionality
✅ Is adaptive - context/governance are tool-agnostic by design

---

Guide Document Alignment

1. BUILDING-CONTEXT-AWARE-SYSTEMS.md Compliance

Core Concept	Guide Requirement	Current Plan	Status
Directory Structure	.opencode/agent/, .opencode/context/, .opencode/command/	.opencode/agent/ ✅ .nexusagent/context/ ✅ .opencode/command/ ✅	✅ ALIGNED
XML Prompt Structure	Context → Role → Task → Instructions → Output	Agent templates use this	✅ ALIGNED
3-Level Context System	Level 1: Isolated Level 2: Filtered Level 3: Full	Need to implement in orchestrator	⚠️ TODO
Main Orchestrator	Analyze → Route → Execute → Validate → Finalize	Need to build this workflow	⚠️ TODO
Specialized Subagents	Stateless, complete instructions, explicit output	Plan includes subagents	✅ ALIGNED
Context Splitting	50-200 lines per file, modular organization	Need to apply to context files	⚠️ TODO
Workflows	Reusable process definitions with XML structure	Need to create workflow templates	⚠️ TODO

Verdict: Architecture aligns perfectly. Implementation details need to follow guide patterns.

---

2. DATA-GOVERNANCE-AGENT-SYSTEM.md Compliance

Core Concept	Guide Requirement	Current Plan	Status
Dual Metadata System	JSON index (PRIMARY) + Embedded XML (SECONDARY)	Need to implement	⚠️ TODO
Agent Communication	Explicit context passing via tmp files with request_id	Need to implement	⚠️ TODO
Context Management Agent	Primary governance coordinator	Need to build	⚠️ TODO
Governance Subagents	Quality Validator, Lifecycle Manager, Metadata Updater, Catalog Maintainer	Need to build	⚠️ TODO
Workflow State Machine	workflow-state.json with locks and checkpoints	Need to implement	⚠️ TODO
6 Quality Dimensions	Accuracy, Completeness, Consistency, Timeliness, Validity, Uniqueness	Need to implement in validator	⚠️ TODO

Verdict: Architecture supports this. Governance profile needs to implement all components.

---

Multi-Tool Adaptability Analysis

Tool Comparison

Feature	OpenCode	Claude	Cursor	NexusAgent Strategy
Agents	.opencode/agent/*.md	.claude/agents/	Rules in .cursor/	Tool-specific folders
Context	.opencode/context/	.claude/context/	Referenced in rules	.nexusagent/context/ (shared)
Commands	.opencode/command/*.md	.claude/commands/*.md	Not literal	Tool-specific folders
Governance	Not built-in	Not built-in	Not built-in	.nexusagent/governance/ (shared)
Reference Pattern	@path/to/file.md	@path/to/file.md	Context via prompts	@../.nexusagent/context/file.md

What Makes It Adaptive

┌─────────────────────────────────────────────────────────┐
│                 TOOL-AGNOSTIC LAYER                     │
│                                                         │
│  .nexusagent/                                          │
│  ├── context/          ← Plain markdown (any tool)     │
│  │   ├── core/                                         │
│  │   ├── domain/                                       │
│  │   ├── processes/                                    │
│  │   └── standards/                                    │
│  │                                                      │
│  └── governance/       ← JSON data (any tool)          │
│      ├── metadata-index.json                           │
│      └── workflow-state.json                           │
│                                                         │
└─────────────────────────────────────────────────────────┘
                           ▲
                           │ Reference via @../.nexusagent/
                           │
    ┌──────────────────────┼──────────────────────┐
    │                      │                      │
┌───▼────────┐    ┌───────▼─────┐    ┌──────────▼───┐
│ .opencode/ │    │  .claude/   │    │  .cursor/    │
│            │    │             │    │              │
│ agent/     │    │  agents/    │    │  rules/      │
│ command/   │    │  commands/  │    │  prompts/    │
│            │    │  plugins/   │    │              │
└────────────┘    └─────────────┘    └──────────────┘
  OpenCode          Claude AI          Cursor
  (PRIMARY)         (Optional)         (Optional)

Key Insight: The intelligence (context, governance rules, quality standards) is tool-agnostic. Only the execution layer (agents/commands) is tool-specific.

---

Simplification Opportunities

Current Complexity (Proposed)

nexus/
├── scripts/install.sh
├── profiles/
│   ├── default/
│   │   ├── nexusagent/context/
│   │   └── opencode/agent/
│   ├── governance/
│   │   ├── nexusagent/context/
│   │   ├── nexusagent/governance/
│   │   └── opencode/agent/ (governance agents)
│   └── content/
│       ├── nexusagent/context/
│       └── opencode/agent/
└── docs/

Simplified Approach

Recommendation: Start with ONE profile, add others as needed.

nexus/
├── install.sh                 # Simple installer
├── profiles/
│   └── default/              # Start here (includes basic governance)
│       ├── nexusagent/
│       │   ├── context/
│       │   │   ├── core/
│       │   │   ├── domain/
│       │   │   └── standards/
│       │   └── governance/
│       │       ├── metadata-index.json (template)
│       │       └── workflow-state.json (template)
│       └── opencode/
│           ├── agent/
│           │   ├── main-orchestrator.md
│           │   ├── context-provider.md
│           │   └── subagents/
│           │       ├── quality-validator.md
│           │       └── lifecycle-manager.md
│           └── command/
│               └── validate-context.md
└── README.md

Phase 2 (Later): Add specialized profiles for specific domains:

• profiles/content/ - Content creation agents
• profiles/devops/ - DevOps automation agents
  
• profiles/data-eng/ - Data engineering agents

Rationale:

1. Users get full system immediately (not "basic" then "upgrade")
2. Simpler to maintain (one profile to start)
3. Context grows organically with use
4. Can still create specialized profiles later

---

Keeping Functionality While Being Simple

Pattern: Core + Optional Extensions

CORE (Always Installed):
  .nexusagent/context/:
    - core/essential-patterns.md        # 3-level context system
    - core/prompt-structure.md          # XML prompt templates
    - standards/quality-criteria.md     # 6 quality dimensions
  
  .nexusagent/governance/:
    - metadata-index.json               # Fast queries
    - workflow-state.json               # Workflow management
  
  .opencode/agent/:
    - main-orchestrator.md              # Request analysis + routing
    - context-provider.md               # 3-level context allocation
    - subagents/quality-validator.md    # Quality checks
    - subagents/lifecycle-manager.md    # Lifecycle transitions

OPTIONAL (User Adds):
  .nexusagent/context/:
    - domain/YOUR-DOMAIN.md             # User's domain knowledge
    - processes/YOUR-WORKFLOW.md        # User's workflows
  
  .opencode/agent/:
    - subagents/YOUR-SPECIALIST.md      # User's custom agents

This gives users:

1. ✅ Complete system out of the box
2. ✅ All patterns from guide documents
3. ✅ Easy to extend for their needs
4. ✅ Not overwhelming (core files are small, well-documented)

---

Making It Adaptive: Concrete Strategy

Strategy 1: Shared Intelligence, Tool-Specific Execution

What's Shared (Tool-Agnostic):

.nexusagent/
├── context/                    # Any AI can read markdown
│   ├── core/
│   │   ├── essential-patterns.md      # 3-level context explained
│   │   ├── prompt-structure.md        # XML structure guide
│   │   └── agent-coordination.md      # How agents work together
│   ├── domain/                        # User's domain knowledge
│   └── standards/                     # Quality standards
│
└── governance/                 # Any tool can read JSON
    ├── metadata-index.json            # File metadata
    └── workflow-state.json            # Workflow state

What's Tool-Specific:

.opencode/agent/               # OpenCode agents (reference shared context)
.claude/agents/                # Claude agents (reference shared context)
.cursor/rules/                 # Cursor rules (reference shared context)

Strategy 2: Progressive Enhancement

Level 1: OpenCode only (what we build first)

.nexusagent/context/           # Shared context
.opencode/agent/               # OpenCode agents

Level 2: User adds Claude support (optional)

.nexusagent/context/           # Same shared context
.opencode/agent/               # OpenCode agents (existing)
.claude/agents/                # User creates Claude agents that reference same context

Level 3: User adds Cursor support (optional)

.nexusagent/context/           # Same shared context
.opencode/agent/               # OpenCode agents (existing)
.claude/agents/                # Claude agents (existing)
.cursor/rules/                 # User creates Cursor rules that reference same context

Key: The intelligence (.nexusagent/) doesn't duplicate. Only execution layer varies.

Strategy 3: Documentation Enables Adaptation

Include in nexus/README.md:

# Using NexusAgent with Other AI Tools

NexusAgent's intelligence lives in `.nexusagent/` (tool-agnostic).
The agents/commands are tool-specific implementations.

## OpenCode (Built-in)
Already configured. Agents reference `@../.nexusagent/context/`

## Adding Claude Support
1. Create `.claude/agents/main-orchestrator.md`
2. Reference shared context: `@../.nexusagent/context/core/essential-patterns.md`
3. Use same governance: Read `../.nexusagent/governance/metadata-index.json`

## Adding Cursor Support
1. Create `.cursor/rules/main.cursorrules`
2. Include instruction: "Read context from ../.nexusagent/context/"
3. Reference standards from ../.nexusagent/context/standards/

## The Pattern
- Intelligence: `.nexusagent/` (shared)
- Execution: Tool-specific folders (reference shared intelligence)

---

Recommended Build Approach

Phase 1: Core Foundation (Week 1)

Build Order:

1. Repository structure

   nexus/
   ├── install.sh
   ├── profiles/default/
   └── README.md
   

2. Shared context layer

   profiles/default/nexusagent/context/
   ├── core/
   │   ├── essential-patterns.md      # 3-level context system
   │   ├── prompt-structure.md        # XML templates
   │   └── agent-coordination.md      # Communication patterns
   └── standards/
      └── quality-criteria.md        # 6 quality dimensions
   

3. Shared governance layer

   profiles/default/nexusagent/governance/
   ├── metadata-index.json            # Template
   ├── workflow-state.json            # Template
   └── tmp/.gitkeep
   

4. OpenCode agents (minimal viable set)

   profiles/default/opencode/agent/
   ├── main-orchestrator.md           # Implements guide workflow
   ├── context-provider.md            # 3-level context allocation
   └── subagents/
      ├── quality-validator.md       # 6 dimensions
      └── lifecycle-manager.md       # Basic lifecycle
   

5. OpenCode commands

   profiles/default/opencode/command/
   └── validate-context.md            # Manual validation trigger
   

6. Installation script

   #!/bin/bash
   # install.sh
   # Copies default profile to .nexusagent/ and .opencode/
   

Phase 2: Enhance & Document (Week 2)

1. Improve agents - Add error handling, logging
2. Add example context - Show users what to put in domain/
3. Write comprehensive README - Installation, usage, adaptation guide
4. Create templates - Agent template, context file template
5. Add automation - Workflow scheduling (optional)

Phase 3: Test & Refine (Week 3)

1. Real-world testing - Use on actual project
2. Gather feedback - What's confusing? What's missing?
3. Refine documentation - Based on user questions
4. Optimize performance - JSON queries, file I/O
5. Create video tutorial - Show installation and usage

---

Validation Checklist

✅ Aligns with BUILDING-CONTEXT-AWARE-SYSTEMS.md

• Directory structure: agent/, context/, command/
• XML prompt structure: Context → Role → Task → Instructions → Output
• 3-level context system implemented
• Main orchestrator with 5-stage workflow
• Stateless subagents with explicit instructions
• Context files: 50-200 lines, modular
• Workflow templates with pre/post flight checks

✅ Aligns with DATA-GOVERNANCE-AGENT-SYSTEM.md

• Dual metadata: JSON (primary) + XML (secondary)
• Explicit context passing via tmp files
• Request ID protocol implemented
• Context Management Agent as coordinator
• 4 governance subagents: Quality, Lifecycle, Metadata, Catalog
• Workflow state machine with locks
• 6 quality dimensions in validator
• Nightly sync job template

✅ Is Simple

• Single profile to start (not 3)
• Core functionality included (not "basic")
• Clear file organization
• Minimal dependencies
• Easy installation (one command)
• Good documentation

✅ Is Adaptive

• Shared context in .nexusagent/ (tool-agnostic)
• Agents in tool folders (tool-specific)
• Clear reference pattern (@../.nexusagent/)
• Documented adaptation strategy
• No tool lock-in
• Progressive enhancement supported

---

Final Recommendations

1. Start Simple, Stay Simple

Do:

• ✅ Build ONE profile with FULL functionality
• ✅ Use patterns from both guides
• ✅ Keep shared intelligence in .nexusagent/
• ✅ Make it work perfectly for OpenCode first
• ✅ Document how to adapt to other tools

Don't:

• ❌ Build 3 profiles immediately
• ❌ Create "basic" vs "advanced" tiers
• ❌ Try to support all tools out of the box
• ❌ Over-engineer for hypothetical needs

2. Follow the Guides Exactly

Both guides are excellent. Don't deviate:

• Use XML prompt structure (Context → Role → Task → Instructions → Output)
• Implement 3-level context system (Isolated → Filtered → Full)
• Use dual metadata (JSON primary, XML secondary)
• Implement request ID protocol (explicit context passing)
• Build the 4 governance subagents
• Use workflow state machine

3. Make Adaptation Obvious

In every context file, add header:

<!-- .nexusagent/context/core/essential-patterns.md -->

# Essential Patterns

**Tool-Agnostic Context File**
This file can be read by OpenCode, Claude, Cursor, or any AI tool.

**Reference from agents:**
- OpenCode: `@../.nexusagent/context/core/essential-patterns.md`
- Claude: `@../.nexusagent/context/core/essential-patterns.md`
- Cursor: Include in rules: "Read ../.nexusagent/context/core/essential-patterns.md"

---

[Content here]

4. Build for Real Use

Don't build an example. Build a production system that:

• Works out of the box
• Handles real projects
• Maintains quality automatically
• Grows with the user's needs
• Is documented thoroughly

---

Conclusion

Current Plan: ✅ Architecturally sound
Guide Alignment: ✅ Follows both guides
Simplification: ⚠️ Can start with one profile
Adaptability: ✅ Design supports multiple tools

Next Steps:

1. Simplify to single profile with full functionality
2. Build following guide patterns exactly
3. Document adaptation strategy clearly
4. Test with real project
5. Refine based on actual use

Ready to build: YES, with recommended simplifications applied.