OpenAgentsControl/.Building/planning

NexusAgent Planning - Final Documentation

Status: READY TO BUILD
Date: 2025-10-29
Architecture: Approved & Simplified

---

📋 Active Planning Documents

1. CORRECTED-ARCHITECTURE.md

The fundamental constraint and solution:

• ✅ Agents MUST stay in tool-specific folders (.opencode/agent/)
• ✅ Context CAN be shared (.nexusagent/context/)
• ✅ Governance CAN be shared (.nexusagent/governance/)
• ✅ Reference pattern: @../.nexusagent/context/file.md

Read this first - explains why the architecture is structured this way.

---

2. ARCHITECTURE-REVIEW.md

Comprehensive validation against guide documents:

• ✅ Validates alignment with BUILDING-CONTEXT-AWARE-SYSTEMS.md
• ✅ Validates alignment with DATA-GOVERNANCE-AGENT-SYSTEM.md
• ✅ Multi-tool adaptability analysis
• ✅ Simplification recommendations
• ✅ Build approach recommendations

Read this second - confirms the approach is sound and provides guidance.

---

3. BUILD-PLAN.md

Simple status document:

• Current status: READY TO BUILD
• Final architecture diagram
• What we're building
• Build order

Read this last - quick reference for current status.

---

🎯 The Final Architecture

project/
├── .nexusagent/                 # SHAREABLE (tool-agnostic)
│   ├── context/                # Domain knowledge (any tool reads)
│   │   ├── core/
│   │   ├── domain/
│   │   ├── processes/
│   │   └── standards/
│   │
│   └── governance/             # Data governance (any tool reads)
│       ├── metadata-index.json
│       ├── workflow-state.json
│       └── tmp/
│
└── .opencode/                   # TOOL-SPECIFIC (OpenCode)
    ├── agent/                  # OpenCode agents (MUST be here)
    │   ├── main-orchestrator.md
    │   ├── context-provider.md
    │   └── subagents/
    │       ├── quality-validator.md
    │       └── lifecycle-manager.md
    │
    └── command/                # OpenCode commands (MUST be here)
        └── validate-context.md

How Agents Reference Shared Context

<!-- .opencode/agent/main-orchestrator.md -->

**Load shared context:**
@../.nexusagent/context/core/essential-patterns.md
@../.nexusagent/context/standards/quality-criteria.md

**Read governance data:**
Read: ../.nexusagent/governance/metadata-index.json

---

🚀 What We're Building

Repository Structure

nexus/
├── install.sh              # Simple installer
├── profiles/
│   └── default/           # Full system (not "basic")
│       ├── nexusagent/
│       │   ├── context/
│       │   └── governance/
│       └── opencode/
│           ├── agent/
│           └── command/
└── README.md

Installation Creates

~/nexus/install.sh

# Creates in project:
.nexusagent/               # Shared resources
├── context/              # From profile
└── governance/           # From profile

.opencode/                 # OpenCode integration
├── agent/                # From profile
└── command/              # From profile

---

📖 Foundation Guides

Located in parent directory (.Building/):

1. BUILDING-CONTEXT-AWARE-SYSTEMS.md (2000+ lines)

   • Directory structure patterns
   • XML prompt engineering
   • 3-level context system
   • Orchestrator design
   • Subagent patterns
   • Workflow templates

2. DATA-GOVERNANCE-AGENT-SYSTEM.md (2000+ lines)

   • Dual metadata system (JSON + XML)
   • Explicit context passing (request files)
   • Context Management Agent
   • Governance subagents (4 types)
   • Workflow state machine
   • Quality validation (6 dimensions)

3. UNIFIED-ARCHITECTURE.md

   • How both systems work together

These are THE SOURCE OF TRUTH - follow them exactly.

---

✅ Key Decisions

1. Start Simple

• ✅ ONE profile (default) with FULL functionality
• ❌ NOT three profiles (basic/governance/content)
• ✅ Let context grow organically with use

2. Follow Guides Exactly

• ✅ XML prompt structure (Context → Role → Task → Instructions → Output)
• ✅ 3-level context system (Isolated → Filtered → Full)
• ✅ Dual metadata (JSON primary, XML secondary)
• ✅ Request ID protocol (explicit context passing)
• ✅ 6 quality dimensions

3. Adaptive by Design

• ✅ Context in .nexusagent/ (any tool can read)
• ✅ Agents in .opencode/ (tool-specific)
• ✅ Document how to add Claude/Cursor support
• ✅ Progressive enhancement (OpenCode first, others optional)

4. Production Ready

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

---

📦 Archived Documents

Moved to archive/ folder:

• 00-MASTER-PLAN.md - Early planning, superseded
• 01-TECHNICAL-SPECIFICATION.md - Details now in guides
• 02-MULTI-TOOL-INTEGRATION.md - Covered in ARCHITECTURE-REVIEW
• 03-SIMPLIFIED-ARCHITECTURE.md - Superseded by CORRECTED-ARCHITECTURE
• FINAL-ARCHITECTURE-DECISION.md - Merged into current docs
• PROJECT-STRUCTURE.md - Will be generated from actual build

These are kept for historical reference but are no longer active.

---

🎬 Next Steps

1. ✅ Planning complete
2. ✅ Architecture validated
3. ✅ Guides aligned
4. ✅ Simplified to single profile
5. ➡️ Ready to build

Start with: Create repository structure in nexus/

---

📊 Build Phases

Phase 1: Repository Structure (Day 1)

• Create nexus/ directory
• Create install.sh
• Create profiles/default/ structure

Phase 2: Shared Context Layer (Days 2-3)

• Build profiles/default/nexusagent/context/
• Core patterns, standards, templates
• Tool-agnostic markdown files

Phase 3: Shared Governance Layer (Day 4)

• Build profiles/default/nexusagent/governance/
• JSON templates (metadata-index, workflow-state)
• Tmp structure

Phase 4: OpenCode Agents (Days 5-10)

• Build profiles/default/opencode/agent/
• Main orchestrator (3-level context)
• Context provider
• Governance subagents

Phase 5: OpenCode Commands (Day 11)

• Build profiles/default/opencode/command/
• Validation command
• Workflow commands

Phase 6: Test & Document (Days 12-14)

• Test installation
• Test all agents
• Write comprehensive README
• Create examples

---

🎯 Success Criteria

Installation:

• One command installs full system
• Creates correct directory structure
• Files are in correct locations

Functionality:

• Main orchestrator works
• 3-level context allocation works
• Quality validation works
• Lifecycle management works
• Request ID protocol works

Documentation:

• Clear installation guide
• Agent usage examples
• Adaptation guide (for other tools)
• Troubleshooting guide

Quality:

• Follows guide patterns exactly
• No deviations from proven architecture
• Production-ready code
• Comprehensive error handling

---

💡 Key Insights

What Makes This Work

1. Separation of Concerns

   • Intelligence (.nexusagent/) = tool-agnostic
   • Execution (.opencode/) = tool-specific
   • Clean boundary

2. Progressive Enhancement

   • Works perfectly with OpenCode (primary)
   • Other tools can read shared context (optional)
   • No maintenance burden

3. Proven Patterns

   • Both guides are battle-tested
   • No need to invent new approaches
   • Follow them exactly

4. Production Focus

   • Not a demo or example
   • Real system for real projects
   • Quality built-in from day one

---

📞 Questions?

Review the three active documents in order:

1. CORRECTED-ARCHITECTURE.md (why)
2. ARCHITECTURE-REVIEW.md (validation)
3. BUILD-PLAN.md (status)

Then refer to foundation guides for implementation details.