📝 docs: enhance prompter functionality and improve documentation clarity

.Building/BUILDING-CONTEXT-AWARE-SYSTEMS.md

@@ -0,0 +1,2579 @@
+# Building Context-Aware AI Systems: A Complete Guide
+
+## Overview
+
+This guide teaches you how to build sophisticated, context-aware AI systems using `.opencode` folder architecture. While this system was built for content creation, the principles apply to any domain: code generation, data analysis, customer support, research, or process automation.
+
+**What you'll learn:**
+- How to split context into modular, reusable files
+- How to structure prompts for optimal AI performance
+- How to build hierarchical agent systems
+- How to manage context flow and prevent information overload
+- How to create custom workflows and commands
+
+---
+
+## Table of Contents
+
+1. [Core Concepts](#core-concepts)
+2. [Step 1: Foundation - Directory Structure](#step-1-foundation---directory-structure)
+3. [Step 2: Prompt Engineering - XML Structure](#step-2-prompt-engineering---xml-structure)
+4. [Step 3: Context Splitting](#step-3-context-splitting)
+5. [Step 4: Building Your Main Orchestrator](#step-4-building-your-main-orchestrator)
+6. [Step 5: Creating Specialized Subagents](#step-5-creating-specialized-subagents)
+7. [Step 6: Context Management](#step-6-context-management)
+8. [Step 7: Workflows](#step-7-workflows)
+9. [Step 8: Custom Commands](#step-8-custom-commands)
+10. [Step 9: Integration and Testing](#step-9-integration-and-testing)
+11. [Advanced Patterns](#advanced-patterns)
+12. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Core Concepts
+
+### The Problem This Solves
+
+When building AI systems, you face three critical challenges:
+
+1. **Context Overload**: Passing too much information to AI agents leads to confusion and poor performance
+2. **Inconsistency**: Without structure, AI agents make different decisions for similar requests
+3. **Maintenance**: Scattered prompts and context make systems hard to update and improve
+
+### The Solution: Hierarchical Context-Aware Architecture
+
+```
+┌─────────────────────────────────────┐
+│    User Request                     │
+└───────────┬─────────────────────────┘
+            │
+┌───────────▼─────────────────────────┐
+│  Main Orchestrator Agent            │
+│  - Analyzes complexity              │
+│  - Allocates context level          │
+│  - Routes to specialists            │
+└───────────┬─────────────────────────┘
+            │
+    ┌───────┴────────┬────────────┐
+    │                │            │
+┌───▼────┐    ┌─────▼──┐    ┌───▼────┐
+│Subagent│    │Subagent│    │Subagent│
+│   A    │    │   B    │    │   C    │
+└────────┘    └────────┘    └────────┘
+```
+
+**Key Principles:**
+- **Modular Context**: Split knowledge into small, focused files
+- **Hierarchical Routing**: Main agent decides which specialists to involve
+- **Dynamic Loading**: Only load context needed for specific tasks
+- **Stateless Subagents**: Specialists receive complete, explicit instructions
+
+---
+
+## Step 1: Foundation - Directory Structure
+
+### Basic Structure
+
+```
+.opencode/
+├── agent/                    # Agent definitions
+│   ├── main-orchestrator.md # Your primary agent
+│   └── subagents/           # Specialized agents
+│       ├── specialist-a.md
+│       ├── specialist-b.md
+│       └── specialist-c.md
+│
+├── context/                 # Knowledge base
+│   ├── domain/             # Domain-specific knowledge
+│   ├── processes/          # Step-by-step workflows
+│   ├── standards/          # Quality standards and rules
+│   └── templates/          # Reusable structures
+│
+├── command/                # Custom slash commands
+│   ├── primary-workflow.md
+│   └── utility-commands.md
+│
+└── templates/              # System templates
+    └── guidelines.md
+```
+
+### Design Principles
+
+**1. Separation of Concerns**
+- `agent/` = Who does the work (prompts and instructions)
+- `context/` = What they need to know (knowledge and data)
+- `command/` = How users interact (entry points)
+- `templates/` = System patterns (reusable structures)
+
+**2. Modularity**
+Each file should serve ONE clear purpose. Bad: `everything.md`. Good: `validation-rules.md`, `format-specs.md`, `quality-checklist.md`
+
+**3. Discoverability**
+File names should clearly indicate contents:
+- ✅ `user-authentication-workflow.md`
+- ❌ `process1.md`
+
+### Example: E-commerce System
+
+```
+.opencode/
+├── agent/
+│   ├── order-orchestrator.md
+│   └── subagents/
+│       ├── inventory-checker.md
+│       ├── payment-processor.md
+│       ├── shipping-calculator.md
+│       └── notification-sender.md
+│
+├── context/
+│   ├── domain/
+│   │   ├── product-catalog.md
+│   │   ├── pricing-rules.md
+│   │   └── inventory-policies.md
+│   ├── processes/
+│   │   ├── order-fulfillment.md
+│   │   ├── refund-workflow.md
+│   │   └── fraud-detection.md
+│   └── standards/
+│       ├── data-validation.md
+│       └── error-handling.md
+│
+└── command/
+    ├── process-order.md
+    └── manage-inventory.md
+```
+
+---
+
+## Step 2: Prompt Engineering - XML Structure
+
+### Research-Backed Component Order
+
+Research from Stanford and Anthropic shows optimal prompt structure improves performance by 20-40%:
+
+```xml
+<!-- OPTIMAL ORDER: Context → Role → Task → Instructions → Output -->
+
+<context>
+  <system_context>What system is this part of?</system_context>
+  <domain_context>What domain/industry?</domain_context>
+  <task_context>What specific job?</task_context>
+</context>
+
+<role>
+  Clear description of the agent's expertise and responsibility
+</role>
+
+<task>
+  Specific objective this agent accomplishes
+</task>
+
+<instructions>
+  <step_1>First do this</step_1>
+  <step_2>Then do this</step_2>
+  <step_3>Finally this</step_3>
+</instructions>
+
+<constraints>
+  <must>Always do X</must>
+  <must_not>Never do Y</must_not>
+</constraints>
+
+<output>
+  <format>How to structure the response</format>
+  <requirements>What must be included</requirements>
+</output>
+```
+
+### Component Ratios (Research-Backed)
+
+For optimal performance, maintain these proportions:
+
+```yaml
+Role: 5-10% of prompt
+Context: 15-25% of prompt
+Task: 10-15% of prompt
+Instructions: 40-50% of prompt
+Examples: 15-20% of prompt (when needed)
+Constraints: 5-10% of prompt
+```
+
+### XML Best Practices
+
+**1. Use Semantic Tags**
+```xml
+<!-- Good: Semantic meaning -->
+<validation_criteria>
+  <mandatory>Field X must be present</mandatory>
+  <optional>Field Y is helpful but not required</optional>
+</validation_criteria>
+
+<!-- Bad: Generic tags -->
+<section1>
+  <item>Field X must be present</item>
+  <item>Field Y is helpful but not required</item>
+</section1>
+```
+
+**2. Hierarchical Structure**
+```xml
+<workflow>
+  <stage id="1" name="Validation">
+    <action>Validate input data</action>
+    <criteria>
+      <check>Field completeness</check>
+      <check>Data type correctness</check>
+    </criteria>
+  </stage>
+  <stage id="2" name="Processing">
+    <action>Transform data</action>
+  </stage>
+</workflow>
+```
+
+**3. Conditional Logic**
+```xml
+<decision>
+  <if test="complexity_simple">Route to fast path</if>
+  <else_if test="complexity_moderate">Route to standard path</else_if>
+  <else>Route to complex path</else>
+</decision>
+```
+
+### Example: Code Review Agent
+
+```xml
+---
+description: "Automated code review with security focus"
+mode: subagent
+temperature: 0.1
+---
+
+# Code Review Agent
+
+<context>
+  <system_context>Automated code quality assurance system</system_context>
+  <domain_context>Software engineering with security focus</domain_context>
+  <task_context>Review pull requests for quality and security issues</task_context>
+</context>
+
+<role>
+  Expert code reviewer specializing in security vulnerabilities, 
+  performance optimization, and maintainability standards
+</role>
+
+<task>
+  Analyze code changes and provide actionable feedback on quality, 
+  security, and best practices compliance
+</task>
+
+<instructions>
+  <step_1>
+    <action>Load code changes from pull request</action>
+    <validate>Ensure valid code syntax</validate>
+  </step_1>
+  
+  <step_2>
+    <action>Security scan</action>
+    <checks>
+      <sql_injection>Check for SQL injection vulnerabilities</sql_injection>
+      <xss>Scan for XSS attack vectors</xss>
+      <secrets>Detect hardcoded secrets or API keys</secrets>
+    </checks>
+  </step_2>
+  
+  <step_3>
+    <action>Code quality analysis</action>
+    <metrics>
+      <complexity>Calculate cyclomatic complexity</complexity>
+      <duplication>Identify code duplication</duplication>
+      <naming>Check naming conventions</naming>
+    </metrics>
+  </step_3>
+  
+  <step_4>
+    <action>Generate review report</action>
+    <prioritization>Critical issues first, then warnings, then suggestions</prioritization>
+  </step_4>
+</instructions>
+
+<constraints>
+  <must>Flag all critical security vulnerabilities</must>
+  <must>Provide specific line numbers for issues</must>
+  <must>Include code examples for fixes</must>
+  <must_not>Approve code with critical security issues</must_not>
+  <must_not>Make subjective style comments without basis in standards</must_not>
+</constraints>
+
+<output>
+  <format>
+    ### Security Issues (Critical/High/Medium/Low)
+    [List with line numbers and severity]
+    
+    ### Code Quality Issues
+    [Complexity, duplication, naming issues]
+    
+    ### Recommendations
+    [Specific, actionable improvements with examples]
+    
+    ### Approval Status
+    [Approved/Needs Changes/Blocked - with reasoning]
+  </format>
+</output>
+```
+
+---
+
+## Step 3: Context Splitting
+
+### The Context Paradox
+
+**Problem**: AI agents need context to work well, but too much context overwhelms them.
+
+**Solution**: Split context into small, focused files that can be loaded dynamically.
+
+### Context Organization Strategy
+
+**1. Domain Knowledge** (What is true about your domain)
+```
+context/domain/
+├── core-concepts.md        # Fundamental definitions
+├── business-rules.md       # Rules that govern operations
+├── data-models.md          # Structure of your data
+└── terminology.md          # Domain-specific terms
+```
+
+**2. Process Knowledge** (How things get done)
+```
+context/processes/
+├── standard-workflow.md    # Normal process flow
+├── edge-cases.md          # How to handle exceptions
+├── integrations.md        # External system interactions
+└── escalation-paths.md    # When/how to escalate
+```
+
+**3. Standards & Quality** (What defines good/bad)
+```
+context/standards/
+├── quality-criteria.md     # What makes output acceptable
+├── validation-rules.md     # How to validate work
+├── error-handling.md      # How to handle failures
+└── compliance-req.md      # Regulatory requirements
+```
+
+**4. Templates & Patterns** (Reusable structures)
+```
+context/templates/
+├── output-format-A.md     # Standard output format
+├── output-format-B.md     # Alternative format
+└── common-patterns.md     # Proven solution patterns
+```
+
+### File Size Guidelines
+
+**Optimal file size: 50-200 lines**
+- Too small (<30 lines): Overhead of many files
+- Too large (>300 lines): Hard to maintain, loading overhead
+- Sweet spot: 50-200 lines of focused content
+
+### Context Referencing Patterns
+
+**Pattern 1: Direct File References**
+```markdown
+For pricing calculations, see: `@context/domain/pricing-rules.md`
+For validation logic, see: `@context/standards/validation-rules.md`
+```
+
+**Pattern 2: Tagged References**
+```xml
+<context_dependencies>
+  <when="new_order">
+    <load>context/domain/pricing-rules.md</load>
+    <load>context/processes/order-fulfillment.md</load>
+    <load>context/standards/validation-rules.md</load>
+  </when>
+  <when="refund_request">
+    <load>context/processes/refund-workflow.md</load>
+    <load>context/domain/business-rules.md</load>
+  </when>
+</context_dependencies>
+```
+
+**Pattern 3: Conditional Loading**
+```xml
+<context_loading>
+  <base_context>
+    <!-- Always load these -->
+    <file>context/domain/core-concepts.md</file>
+  </base_context>
+  
+  <conditional>
+    <if test="task_type=analysis">
+      <load>context/standards/quality-criteria.md</load>
+    </if>
+    <if test="complexity=high">
+      <load>context/processes/edge-cases.md</load>
+    </if>
+  </conditional>
+</context_loading>
+```
+
+### Example: Customer Support System
+
+**Bad Approach** (Single massive file):
+```
+context/
+└── everything.md (2000 lines)
+    - All product info
+    - All support procedures  
+    - All policies
+    - All templates
+```
+
+**Good Approach** (Split and organized):
+```
+context/
+├── domain/
+│   ├── product-catalog.md        # 150 lines
+│   ├── customer-segments.md      # 80 lines
+│   └── pricing-tiers.md          # 100 lines
+│
+├── processes/
+│   ├── ticket-triage.md          # 120 lines
+│   ├── escalation-workflow.md   # 90 lines
+│   └── resolution-process.md    # 150 lines
+│
+├── standards/
+│   ├── response-quality.md       # 100 lines
+│   ├── sla-requirements.md      # 70 lines
+│   └── tone-guidelines.md       # 80 lines
+│
+└── templates/
+    ├── response-templates.md     # 200 lines
+    └── email-formats.md         # 100 lines
+```
+
+**Loading Strategy**:
+```yaml
+For "Simple Product Question":
+  Load: product-catalog.md, response-templates.md
+  Total: ~350 lines (efficient)
+
+For "Complex Technical Issue":  
+  Load: product-catalog.md, escalation-workflow.md, 
+        resolution-process.md, response-quality.md
+  Total: ~460 lines (still manageable)
+
+For "Billing Dispute":
+  Load: pricing-tiers.md, customer-segments.md,
+        escalation-workflow.md, sla-requirements.md
+  Total: ~340 lines (targeted)
+```
+
+---
+
+## Step 4: Building Your Main Orchestrator
+
+The main orchestrator is the "brain" that analyzes requests and coordinates specialists.
+
+### Core Responsibilities
+
+```yaml
+1. Request Analysis:
+   - What is the user trying to accomplish?
+   - How complex is this request?
+   - What domain knowledge is needed?
+
+2. Context Allocation:
+   - What context level is appropriate?
+   - Which files need to be loaded?
+   - How much information is necessary?
+
+3. Routing Decisions:
+   - Can I handle this directly?
+   - Which specialists should be involved?
+   - In what order should they work?
+
+4. Workflow Management:
+   - What's the sequence of steps?
+   - Are there dependencies between steps?
+   - What validations are needed?
+
+5. Response Integration:
+   - How do I combine outputs from specialists?
+   - What format does the user expect?
+   - Are there follow-up actions?
+```
+
+### Orchestrator Template
+
+```xml
+---
+description: "Main orchestrator for [YOUR SYSTEM]"
+mode: primary
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  task: true
+  glob: true
+  grep: true
+---
+
+# [YOUR SYSTEM] Orchestrator
+
+<!-- RESEARCH-BACKED OPTIMAL COMPONENT SEQUENCE -->
+
+<context>
+  <system_context>
+    [Describe the overall system this orchestrator manages]
+  </system_context>
+  <domain_context>
+    [What industry/domain? Who are the users?]
+  </domain_context>
+  <task_context>
+    [What types of tasks does this orchestrator handle?]
+  </task_context>
+  <execution_context>
+    [How does this orchestrator coordinate work?]
+  </execution_context>
+</context>
+
+<role>
+  [Primary Orchestrator] specializing in [domain] with expertise 
+  in [key capabilities]
+</role>
+
+<task>
+  Transform user requests into completed [outcomes] by intelligently 
+  routing work to specialized agents and managing workflow execution
+</task>
+
+<workflow name="PrimaryWorkflow">
+  <stage id="1" name="Analyze">
+    <action>Assess request complexity and requirements</action>
+    <decision>
+      <if test="simple_request">Handle directly</if>
+      <if test="needs_specialist">Route to appropriate subagent</if>
+      <if test="multi_step">Plan workflow sequence</if>
+    </decision>
+    <output>Analysis with routing plan</output>
+  </stage>
+
+  <stage id="2" name="ContextAllocation">
+    <action>Determine what context is needed</action>
+    <levels>
+      <level_1>Minimal - task description only</level_1>
+      <level_2>Filtered - relevant context files</level_2>
+      <level_3>Full - complete system state</level_3>
+    </levels>
+    <output>Context loading plan</output>
+  </stage>
+
+  <stage id="3" name="Execution">
+    <action>Execute workflow or route to specialists</action>
+    <routing>
+      <if test="needs_specialist_a">Route to @subagent-a</if>
+      <if test="needs_specialist_b">Route to @subagent-b</if>
+    </routing>
+    <output>Completed work from all required stages</output>
+  </stage>
+
+  <stage id="4" name="Validation">
+    <action>Verify quality of output</action>
+    <criteria>
+      <check>Completeness</check>
+      <check>Correctness</check>
+      <check>Quality standards</check>
+    </criteria>
+    <output>Validated output or list of issues</output>
+  </stage>
+
+  <stage id="5" name="Finalize">
+    <action>Package and deliver results</action>
+    <steps>
+      <save>Save outputs to appropriate locations</save>
+      <log>Record execution metadata</log>
+      <respond>Provide clear response to user</respond>
+    </steps>
+    <output>Final deliverable</output>
+  </stage>
+</workflow>
+
+<subagents>
+  <subagent-a>
+    <purpose>Specialized task A</purpose>
+    <trigger>When condition X is met</trigger>
+    <context>What context level to provide</context>
+  </subagent-a>
+  
+  <subagent-b>
+    <purpose>Specialized task B</purpose>
+    <trigger>When condition Y is met</trigger>
+    <context>What context level to provide</context>
+  </subagent-b>
+</subagents>
+
+<context_allocation_logic>
+  <level_1_triggers>
+    - Single domain operation
+    - Clear requirements
+    - Standard workflow
+    - No dependencies
+  </level_1_triggers>
+  
+  <level_2_triggers>
+    - Multi-step process
+    - Domain knowledge needed
+    - Quality validation required
+    - Integration points
+  </level_2_triggers>
+  
+  <level_3_triggers>
+    - Complex multi-agent coordination
+    - Requires historical context
+    - High-stakes decisions
+    - Extensive state management
+  </level_3_triggers>
+</context_allocation_logic>
+
+<routing_patterns>
+  <pattern name="direct_execution">
+    <when>Simple, well-defined request within core capabilities</when>
+    <action>Execute directly without routing to specialists</action>
+  </pattern>
+  
+  <pattern name="single_specialist">
+    <when>Request clearly maps to one specialist's domain</when>
+    <action>Route to specialist with complete, explicit instructions</action>
+  </pattern>
+  
+  <pattern name="sequential_coordination">
+    <when>Request requires multiple specialists in sequence</when>
+    <action>Execute workflow with hand-offs between specialists</action>
+  </pattern>
+  
+  <pattern name="parallel_execution">
+    <when>Multiple independent tasks can run simultaneously</when>
+    <action>Route to multiple specialists concurrently</action>
+  </pattern>
+</routing_patterns>
+
+<output_specifications>
+  <to_user>
+    - Clear confirmation of what was accomplished
+    - Key results or deliverables
+    - Next steps or options if applicable
+    - File locations if outputs were saved
+  </to_user>
+  
+  <to_system>
+    - Execution metadata (timing, agents involved, context used)
+    - Quality metrics if applicable
+    - Errors or warnings encountered
+  </to_system>
+</output_specifications>
+```
+
+### Complexity Analysis Function
+
+Your orchestrator needs a systematic way to assess request complexity:
+
+```xml
+<complexity_analysis>
+  <simple>
+    <indicators>
+      - Single clear objective
+      - Standard operation
+      - No integration needed
+      - Can complete in one step
+    </indicators>
+    <context>Level 1 - Minimal</context>
+    <routing>Direct execution or single specialist</routing>
+  </simple>
+  
+  <moderate>
+    <indicators>
+      - Multiple steps required
+      - Domain knowledge needed
+      - Quality validation important
+      - Some coordination required
+    </indicators>
+    <context>Level 2 - Filtered</context>
+    <routing>Sequential workflow with specialists</routing>
+  </moderate>
+  
+  <complex>
+    <indicators>
+      - Multi-agent coordination
+      - High stakes or critical
+      - Extensive state management
+      - Requires historical context
+    </indicators>
+    <context>Level 3 - Full</context>
+    <routing>Comprehensive workflow with validation gates</routing>
+  </complex>
+</complexity_analysis>
+```
+
+### Example: Data Pipeline Orchestrator
+
+```xml
+---
+description: "Orchestrates data processing pipelines with quality validation"
+mode: primary
+temperature: 0.2
+---
+
+# Data Pipeline Orchestrator
+
+<context>
+  <system_context>ETL pipeline management system</system_context>
+  <domain_context>Data engineering for analytics platform</domain_context>
+  <task_context>Process, transform, and validate data flows</task_context>
+</context>
+
+<role>
+  Data Pipeline Orchestrator specializing in ETL workflow coordination,
+  data quality validation, and error recovery
+</role>
+
+<task>
+  Transform user requests into executed data pipelines by intelligently
+  routing extraction, transformation, and loading tasks to specialized
+  agents while ensuring data quality and handling errors
+</task>
+
+<workflow name="DataPipelineExecution">
+  <stage id="1" name="Analyze">
+    <action>Assess data source, transformation needs, and destination</action>
+    <decision>
+      <if test="standard_schema">Use fast path</if>
+      <if test="custom_transformation">Route to transformation specialist</if>
+      <if test="data_quality_critical">Add validation steps</if>
+    </decision>
+  </stage>
+  
+  <stage id="2" name="Extract">
+    <routing>
+      <if test="database_source">Route to @database-extractor</if>
+      <if test="api_source">Route to @api-extractor</if>
+      <if test="file_source">Route to @file-extractor</if>
+    </routing>
+    <output>Extracted raw data</output>
+  </stage>
+  
+  <stage id="3" name="Transform">
+    <action>Apply transformations and business logic</action>
+    <routing>
+      <if test="simple_mapping">Execute directly</if>
+      <if test="complex_logic">Route to @transformation-engine</if>
+    </routing>
+    <output>Transformed data ready for loading</output>
+  </stage>
+  
+  <stage id="4" name="Validate">
+    <action>Verify data quality</action>
+    <routing>Route to @data-validator</routing>
+    <checkpoints>
+      <completeness>All required fields present</completeness>
+      <correctness>Data types and formats valid</correctness>
+      <consistency>Business rules satisfied</consistency>
+    </checkpoints>
+    <handling>
+      <if test="validation_passed">Proceed to load</if>
+      <if test="validation_failed">Log errors and halt</if>
+    </handling>
+  </stage>
+  
+  <stage id="5" name="Load">
+    <action>Load data into destination</action>
+    <routing>
+      <if test="database_dest">Route to @database-loader</if>
+      <if test="warehouse_dest">Route to @warehouse-loader</if>
+    </routing>
+    <output>Data successfully loaded</output>
+  </stage>
+</workflow>
+
+<subagents>
+  <database-extractor>
+    <purpose>Extract data from SQL databases</purpose>
+    <trigger>When source is database</trigger>
+    <context>Level 1 - connection params only</context>
+  </database-extractor>
+  
+  <transformation-engine>
+    <purpose>Apply complex business logic transformations</purpose>
+    <trigger>When transformations are not simple mappings</trigger>
+    <context>Level 2 - business rules + data models</context>
+  </transformation-engine>
+  
+  <data-validator>
+    <purpose>Validate data quality against standards</purpose>
+    <trigger>Always for production pipelines</trigger>
+    <context>Level 2 - validation rules + data models</context>
+  </data-validator>
+</subagents>
+
+<context_allocation>
+  <level_1>
+    <!-- 70% of cases -->
+    - Standard ETL jobs
+    - Known schemas
+    - Established pipelines
+    - No custom logic
+  </level_1>
+  
+  <level_2>
+    <!-- 25% of cases -->
+    - Custom transformations
+    - Data quality critical
+    - New data sources
+    - Integration points
+  </level_2>
+  
+  <level_3>
+    <!-- 5% of cases -->
+    - Mission-critical pipelines
+    - Complex error recovery
+    - Regulatory compliance needs
+    - Multi-system coordination
+  </level_3>
+</context_allocation>
+```
+
+---
+
+## Step 5: Creating Specialized Subagents
+
+Subagents are specialists that handle specific tasks with complete, explicit instructions.
+
+### Subagent Design Principles
+
+**1. Single Responsibility**
+Each subagent should do ONE thing extremely well.
+
+**2. Statelessness**
+Subagents should not maintain state or assume context from previous interactions.
+
+**3. Complete Instructions**
+Every call to a subagent must include ALL information needed to complete the task.
+
+**4. Explicit Output Format**
+Subagents must know exactly what format to return results in.
+
+### Subagent Template
+
+```xml
+---
+description: "[Specific task this subagent performs]"
+mode: subagent
+temperature: 0.1  # Lower temp for consistent specialist behavior
+tools:
+  read: true   # Only enable tools needed for this specific task
+  write: false
+  bash: false
+  task: false
+---
+
+# [Subagent Name]
+
+<context>
+  <specialist_domain>[What specific area does this agent specialize in?]</specialist_domain>
+  <task_scope>[What specific task does this agent complete?]</task_scope>
+  <integration>[How does this fit in the larger system?]</integration>
+</context>
+
+<role>
+  [Specialist Type] expert with deep knowledge of [specific domain]
+</role>
+
+<task>
+  [Specific, measurable objective this agent accomplishes]
+</task>
+
+<inputs_required>
+  <parameter name="param1" type="string">
+    Description of what this parameter is and acceptable values
+  </parameter>
+  <parameter name="param2" type="array">
+    Description of array contents and structure
+  </parameter>
+  <parameter name="param3" type="object">
+    Description of object structure and required fields
+  </parameter>
+</inputs_required>
+
+<inputs_forbidden>
+  <!-- Subagents should never receive these -->
+  <forbidden>conversation_history</forbidden>
+  <forbidden>full_system_state</forbidden>
+  <forbidden>unstructured_context</forbidden>
+</inputs_forbidden>
+
+<process_flow>
+  <step_1>
+    <action>First thing to do</action>
+    <validation>How to verify this step succeeded</validation>
+  </step_1>
+  
+  <step_2>
+    <action>Second thing to do</action>
+    <conditions>
+      <if test="condition_a">Do option A</if>
+      <else>Do option B</else>
+    </conditions>
+  </step_2>
+  
+  <step_3>
+    <action>Final thing to do</action>
+    <output>What to return</output>
+  </step_3>
+</process_flow>
+
+<constraints>
+  <must>Always enforce requirement X</must>
+  <must>Always validate parameter Y</must>
+  <must_not>Never make assumptions about Z</must_not>
+  <must_not>Never proceed if critical data is missing</must_not>
+</constraints>
+
+<output_specification>
+  <format>
+    [Exact structure of output, preferably in YAML or JSON format]
+  </format>
+  
+  <example>
+    ```yaml
+    status: "success" | "failure" | "partial"
+    result:
+      field1: value
+      field2: value
+    metadata:
+      execution_time: "2.3s"
+      warnings: ["warning 1", "warning 2"]
+    ```
+  </example>
+  
+  <error_handling>
+    If something goes wrong, return:
+    ```yaml
+    status: "failure"
+    error:
+      code: "ERROR_CODE"
+      message: "Human-readable error message"
+      details: "Specific information about what went wrong"
+    ```
+  </error_handling>
+</output_specification>
+
+<validation_checks>
+  <pre_execution>
+    - Verify all required inputs are present
+    - Validate input formats and types
+    - Check that any referenced files exist
+  </pre_execution>
+  
+  <post_execution>
+    - Verify output meets specifications
+    - Validate any files created or modified
+    - Ensure no side effects occurred
+  </post_execution>
+</validation_checks>
+```
+
+### Example Subagents
+
+#### Example 1: SQL Query Generator
+
+```xml
+---
+description: "Generates optimized SQL queries from natural language"
+mode: subagent
+temperature: 0.1
+---
+
+# SQL Query Generator
+
+<context>
+  <specialist_domain>Database query optimization</specialist_domain>
+  <task_scope>Generate SQL queries from structured requirements</task_scope>
+</context>
+
+<role>
+  Database specialist expert in SQL query generation, optimization,
+  and security best practices
+</role>
+
+<task>
+  Transform structured query requirements into optimized, secure
+  SQL queries with proper indexing hints and parameter binding
+</task>
+
+<inputs_required>
+  <parameter name="database_type" type="string">
+    Database system: postgresql, mysql, sqlite, sqlserver
+  </parameter>
+  <parameter name="schema" type="object">
+    Schema definition with tables and columns
+  </parameter>
+  <parameter name="requirements" type="object">
+    Query requirements: select_fields, from_tables, where_conditions,
+    join_conditions, group_by, order_by, limit
+  </parameter>
+  <parameter name="optimization_level" type="string">
+    fast_execution or readable_code
+  </parameter>
+</inputs_required>
+
+<process_flow>
+  <step_1>
+    <action>Validate schema and requirements compatibility</action>
+    <checks>
+      - All referenced tables exist in schema
+      - All columns exist in their respective tables
+      - Data types are compatible for comparisons
+    </checks>
+  </step_1>
+  
+  <step_2>
+    <action>Build SELECT clause</action>
+    <logic>
+      IF requirements.select_fields = "*": SELECT *
+      ELSE: SELECT specific fields with table prefixes
+    </logic>
+  </step_2>
+  
+  <step_3>
+    <action>Build FROM and JOIN clauses</action>
+    <logic>
+      - Start with primary table
+      - Add JOINs in order that minimizes intermediate result size
+      - Use INNER/LEFT/RIGHT based on requirements
+    </logic>
+  </step_3>
+  
+  <step_4>
+    <action>Build WHERE clause with parameter binding</action>
+    <security>
+      - NEVER concatenate user input directly
+      - ALWAYS use parameter binding: WHERE field = ?
+      - Validate and sanitize all inputs
+    </security>
+  </step_4>
+  
+  <step_5>
+    <action>Add optimization hints if requested</action>
+    <conditions>
+      <if test="optimization_level = fast_execution">
+        - Add index hints
+        - Suggest covering indexes if beneficial
+        - Order JOINs for best performance
+      </if>
+    </conditions>
+  </step_5>
+</process_flow>
+
+<constraints>
+  <must>Use parameter binding for all dynamic values</must>
+  <must>Include query execution plan estimation</must>
+  <must>Validate SQL injection safety</must>
+  <must_not>Concatenate user input into query strings</must_not>
+  <must_not>Generate queries that could cause full table scans on large tables</must_not>
+</constraints>
+
+<output_specification>
+  <format>
+    ```yaml
+    status: "success"
+    query:
+      sql: "SELECT ... FROM ... WHERE ..."
+      parameters: ["param1", "param2"]
+      parameter_types: ["string", "integer"]
+    optimization:
+      estimated_execution_time: "0.05s"
+      recommended_indexes: ["idx_table_column"]
+      warnings: ["Potential full table scan on table X"]
+    security:
+      injection_safe: true
+      uses_parameter_binding: true
+    ```
+  </format>
+</output_specification>
+```
+
+#### Example 2: Email Validator and Formatter
+
+```xml
+---
+description: "Validates and formats email content against standards"
+mode: subagent
+temperature: 0.1
+---
+
+# Email Validator and Formatter
+
+<context>
+  <specialist_domain>Email content validation and formatting</specialist_domain>
+  <task_scope>Ensure emails meet quality, compliance, and deliverability standards</task_scope>
+</context>
+
+<role>
+  Email specialist expert in deliverability, spam compliance,
+  accessibility, and professional communication standards
+</role>
+
+<task>
+  Validate email content against comprehensive quality standards
+  and provide formatted, optimized version ready for sending
+</task>
+
+<inputs_required>
+  <parameter name="email_content" type="object">
+    {
+      subject: string,
+      body_html: string,
+      body_text: string,
+      from_address: string,
+      reply_to: string (optional),
+      cc_bcc: array (optional)
+    }
+  </parameter>
+  <parameter name="email_type" type="string">
+    transactional, marketing, notification, or support
+  </parameter>
+  <parameter name="compliance_requirements" type="array">
+    [CAN-SPAM, GDPR, CCPA, etc.]
+  </parameter>
+</inputs_required>
+
+<process_flow>
+  <step_1>
+    <action>Validate required compliance elements</action>
+    <checks>
+      <can_spam>
+        - Physical mailing address present
+        - Clear unsubscribe mechanism
+        - Honest subject line
+        - Sender identification clear
+      </can_spam>
+      <gdpr>
+        - Lawful basis for contact documented
+        - Privacy policy linked
+        - Data handling transparency
+      </gdpr>
+    </checks>
+  </step_1>
+  
+  <step_2>
+    <action>Validate deliverability factors</action>
+    <checks>
+      <subject_line>
+        - Length 40-50 characters (optimal)
+        - No spam trigger words
+        - Personalization present if applicable
+        - No excessive punctuation or caps
+      </subject_line>
+      <html_content>
+        - Responsive design for mobile
+        - Images have alt text
+        - Proper HTML structure
+        - No excessive image-to-text ratio
+      </html_content>
+      <text_version>
+        - Plain text version exists
+        - Properly formatted
+        - Content matches HTML version
+      </text_version>
+    </checks>
+  </step_2>
+  
+  <step_3>
+    <action>Run spam score analysis</action>
+    <spam_checks>
+      - Subject line spam keywords
+      - Excessive punctuation or caps
+      - Suspicious links
+      - Image-heavy content
+      - Missing unsubscribe
+      - Broken links
+    </spam_checks>
+    <scoring>
+      Score 0-10: (10 = high spam likelihood)
+      Threshold for warning: 5
+      Threshold for rejection: 7
+    </scoring>
+  </step_3>
+  
+  <step_4>
+    <action>Optimize content</action>
+    <optimizations>
+      - Compress HTML
+      - Inline critical CSS
+      - Optimize image references
+      - Add tracking parameters if requested
+      - Minify whitespace
+    </optimizations>
+  </step_4>
+  
+  <step_5>
+    <action>Generate validation report</action>
+    <output>Comprehensive report with pass/fail/warning for each check</output>
+  </step_5>
+</process_flow>
+
+<constraints>
+  <must>Block sending if critical compliance violations exist</must>
+  <must>Validate all URLs are accessible and not blacklisted</must>
+  <must>Ensure accessibility standards (WCAG 2.1 AA minimum)</must>
+  <must_not>Allow sending without unsubscribe mechanism (marketing emails)</must_not>
+  <must_not>Proceed if spam score exceeds threshold</must_not>
+</constraints>
+
+<output_specification>
+  <format>
+    ```yaml
+    status: "approved" | "needs_revision" | "rejected"
+    validation_results:
+      compliance:
+        can_spam: { passed: true, issues: [] }
+        gdpr: { passed: true, issues: [] }
+      deliverability:
+        spam_score: 2.5
+        issues: ["Subject line could be more engaging"]
+        warnings: []
+      accessibility:
+        wcag_level: "AA"
+        issues: ["3 images missing alt text"]
+      
+    optimized_content:
+      subject: "Optimized subject line"
+      body_html: "<html>...</html>"
+      body_text: "Text version..."
+      
+    recommendations:
+      - priority: "high"
+        issue: "Add alt text to images"
+        fix: "Provide descriptive alt text for screen readers"
+      - priority: "medium"
+        issue: "Subject line optimization"
+        fix: "Consider: 'Save 20% this week' instead of 'Special offer'"
+        
+    send_approval:
+      approved: true
+      conditions: ["Fix alt text before sending"]
+    ```
+  </format>
+</output_specification>
+```
+
+---
+
+## Step 6: Context Management
+
+### The Three-Level Context System
+
+Research shows that dynamic context allocation improves efficiency by 60-80% without sacrificing quality.
+
+```yaml
+Level 1 - Complete Isolation (70-80% of cases):
+  Context: Task description only
+  Use for: Simple, well-defined operations
+  Performance: 80% reduction in context overhead
+  Examples:
+    - Format data according to specification
+    - Validate input against rules
+    - Generate output from template
+    
+Level 2 - Filtered Context (15-25% of cases):
+  Context: Task + relevant domain knowledge
+  Use for: Operations requiring domain expertise
+  Performance: 60% reduction in context overhead
+  Examples:
+    - Create content requiring brand alignment
+    - Process requests needing business logic
+    - Quality validation against standards
+    
+Level 3 - Full Context (0-5% of cases):
+  Context: Task + domain knowledge + historical state
+  Use for: Complex multi-step operations
+  Performance: Optimized for accuracy over speed
+  Examples:
+    - Long-running workflows with dependencies
+    - High-stakes decisions requiring full context
+    - Complex multi-agent coordination
+```
+
+### Context Provider Pattern
+
+Create a specialized subagent to intelligently select and deliver context:
+
+```xml
+---
+description: "Intelligently provides relevant context based on request analysis"
+mode: subagent
+temperature: 0.1
+---
+
+# Context Provider
+
+<context>
+  <specialist_domain>Context selection and optimization</specialist_domain>
+  <task_scope>Analyze requests and deliver precisely relevant context</task_scope>
+</context>
+
+<role>
+  Context Intelligence Specialist expert in information architecture
+  and cognitive load optimization
+</role>
+
+<task>
+  Determine optimal context level and deliver precisely the
+  information needed for the current task—nothing more, nothing less
+</task>
+
+<inputs_required>
+  <parameter name="request" type="string">
+    The user's original request or task description
+  </parameter>
+  <parameter name="task_type" type="string">
+    Category of task being performed
+  </parameter>
+  <parameter name="complexity" type="string">
+    simple, moderate, or complex
+  </parameter>
+</inputs_required>
+
+<process_flow>
+  <step_1>
+    <action>Analyze request complexity</action>
+    <factors>
+      - Number of steps required
+      - Domain knowledge needed
+      - Integration points involved
+      - Validation requirements
+      - Historical context dependence
+    </factors>
+    <output>Complexity score 1-10</output>
+  </step_1>
+  
+  <step_2>
+    <action>Determine context level</action>
+    <logic>
+      IF complexity_score <= 3 AND single_domain AND no_integrations:
+        context_level = 1 (Isolation)
+      ELSE IF complexity_score <= 7 AND multi_domain OR validation_needed:
+        context_level = 2 (Filtered)
+      ELSE:
+        context_level = 3 (Full)
+    </logic>
+  </step_2>
+  
+  <step_3>
+    <action>Select relevant context files</action>
+    <selection_logic>
+      <!-- Base context (always load) -->
+      <base>
+        - context/domain/core-concepts.md
+      </base>
+      
+      <!-- Conditional context -->
+      <if test="context_level >= 2">
+        Load domain-specific knowledge based on task_type
+      </if>
+      
+      <if test="context_level = 3">
+        Load historical state and previous interactions
+      </if>
+    </selection_logic>
+  </step_3>
+  
+  <step_4>
+    <action>Return file paths array</action>
+    <note>Return paths to files, NOT file contents (orchestrator loads)</note>
+  </step_4>
+</process_flow>
+
+<output_specification>
+  <format>
+    ```yaml
+    context_level: 1 | 2 | 3
+    reasoning: "Why this context level was chosen"
+    file_locations:
+      - path/to/file1.md
+      - path/to/file2.md
+      - path/to/file3.md
+    estimated_tokens: 1500
+    load_priority:
+      critical: ["file1.md"]
+      important: ["file2.md"]
+      optional: ["file3.md"]
+    ```
+  </format>
+</output_specification>
+
+<optimization_principles>
+  <principle_1>Prefer lower context levels when possible</principle_1>
+  <principle_2>Only escalate to higher levels when necessary</principle_2>
+  <principle_3>Return file paths, not file contents</principle_3>
+  <principle_4>Prioritize critical context for loading</principle_4>
+</optimization_principles>
+```
+
+### Context File Organization
+
+```yaml
+context/
+  core/                  # Always available (Level 1)
+    core-concepts.md
+    terminology.md
+    
+  domain/                # Load selectively (Level 2)
+    business-rules.md
+    data-models.md
+    integrations.md
+    
+  processes/             # Load by workflow (Level 2)
+    standard-workflow.md
+    edge-cases.md
+    escalation-paths.md
+    
+  standards/             # Load for validation (Level 2)
+    quality-criteria.md
+    compliance-requirements.md
+    validation-rules.md
+    
+  history/               # Load rarely (Level 3)
+    previous-decisions.md
+    learned-patterns.md
+    optimization-data.md
+```
+
+### Dynamic Context Loading Example
+
+**Orchestrator Implementation**:
+```xml
+<context_management>
+  <analyze_request>
+    user_request = "Process customer order for premium widget"
+    complexity = assess_complexity(user_request)
+    # Returns: "moderate" - needs business rules and pricing
+  </analyze_request>
+  
+  <route_to_context_provider>
+    context_plan = @context-provider({
+      request: user_request,
+      task_type: "order_processing",
+      complexity: "moderate"
+    })
+    # Returns:
+    # {
+    #   context_level: 2,
+    #   file_locations: [
+    #     "context/core/core-concepts.md",
+    #     "context/domain/pricing-rules.md",
+    #     "context/domain/inventory-policies.md",
+    #     "context/processes/order-fulfillment.md"
+    #   ]
+    # }
+  </route_to_context_provider>
+  
+  <load_context>
+    FOR each file IN context_plan.file_locations:
+      context += read_file(file)
+    END FOR
+  </load_context>
+  
+  <execute_with_context>
+    # Now execute with precisely the context needed
+    result = process_order(user_request, context)
+  </execute_with_context>
+</context_management>
+```
+
+---
+
+## Step 7: Workflows
+
+Workflows are reusable process definitions that can be selected and executed dynamically.
+
+### Workflow Template
+
+```markdown
+# [Workflow Name]
+
+## Overview
+[Brief description of what this workflow accomplishes and when to use it]
+
+<task_context>
+  <expert_role>[What expertise is needed for this workflow]</expert_role>
+  <mission_objective>[What this workflow achieves]</mission_objective>
+</task_context>
+
+<operational_context>
+  <tone_framework>[How this workflow should be executed]</tone_framework>
+  <audience_level>[Who benefits from this workflow]</audience_level>
+</operational_context>
+
+<pre_flight_check>
+  <validation_requirements>
+    - [Prerequisite 1 that must be true]
+    - [Prerequisite 2 that must be true]
+    - [Prerequisite 3 that must be true]
+  </validation_requirements>
+</pre_flight_check>
+
+<process_flow>
+
+### Step 1: [Step Name]
+<step_framework>
+  <context_dependencies>
+    - [Required context file 1]
+    - [Required context file 2]
+  </context_dependencies>
+  
+  <action>[What to do in this step]</action>
+  
+  <decision_tree>
+    <if test="[condition]">[Then do this]</if>
+    <else_if test="[other condition]">[Do this instead]</else_if>
+    <else>[Default action]</else>
+  </decision_tree>
+  
+  <output>[What this step produces]</output>
+</step_framework>
+
+### Step 2: [Next Step Name]
+<step_framework>
+  <!-- Repeat structure -->
+</step_framework>
+
+### Step N: [Final Step Name]
+<step_framework>
+  <action>[Final action]</action>
+  <success_criteria>
+    - [Criterion 1 for success]
+    - [Criterion 2 for success]
+  </success_criteria>
+</step_framework>
+
+</process_flow>
+
+<guidance_systems>
+  <when_to_use>
+    - [Scenario 1 where this workflow is appropriate]
+    - [Scenario 2 where this workflow is appropriate]
+  </when_to_use>
+  
+  <when_not_to_use>
+    - [Scenario where a different workflow would be better]
+  </when_not_to_use>
+  
+  <workflow_escalation>
+    <if test="[condition]">Escalate to [other workflow]</if>
+  </workflow_escalation>
+</guidance_systems>
+
+<post_flight_check>
+  <validation_requirements>
+    - [Success criterion 1]
+    - [Success criterion 2]
+    - [Quality check]
+  </validation_requirements>
+</post_flight_check>
+
+## Context Dependencies Summary
+- **Step 1**: file1.md, file2.md
+- **Step 2**: file3.md, file4.md
+- **Step 3**: file5.md
+
+## Success Metrics
+- [Measurable outcome 1]
+- [Measurable outcome 2]
+- [Time/quality expectation]
+```
+
+### Example Workflows
+
+#### Example 1: Customer Onboarding Workflow
+
+```markdown
+# Customer Onboarding Workflow
+
+## Overview
+Systematic workflow for onboarding new customers with account setup,
+initial configuration, welcome communications, and first-use guidance.
+
+<task_context>
+  <expert_role>Customer Success Specialist with onboarding expertise</expert_role>
+  <mission_objective>Successfully onboard new customer with positive first experience</mission_objective>
+</task_context>
+
+<pre_flight_check>
+  <validation_requirements>
+    - Customer has completed signup form
+    - Payment method verified
+    - Email address confirmed
+  </validation_requirements>
+</pre_flight_check>
+
+<process_flow>
+
+### Step 1: Account Provisioning
+<step_framework>
+  <context_dependencies>
+    - context/domain/account-types.md
+    - context/domain/service-tiers.md
+  </context_dependencies>
+  
+  <action>Create customer account with appropriate tier and features</action>
+  
+  <decision_tree>
+    <if test="paid_tier = premium">
+      Provision all features + priority support
+    </if>
+    <else_if test="paid_tier = standard">
+      Provision standard features
+    </else_if>
+    <else>
+      Provision trial features with 14-day limit
+    </else>
+  </decision_tree>
+  
+  <output>Provisioned account with credentials</output>
+</step_framework>
+
+### Step 2: Initial Configuration
+<step_framework>
+  <context_dependencies>
+    - context/processes/setup-wizard.md
+    - context/templates/default-configs.md
+  </context_dependencies>
+  
+  <action>Guide customer through initial configuration</action>
+  
+  <substeps>
+    <substep_1>Company profile setup</substep_1>
+    <substep_2>User preferences configuration</substep_2>
+    <substep_3>Integration connections (if applicable)</substep_3>
+    <substep_4>Data import (if applicable)</substep_4>
+  </substeps>
+  
+  <output>Configured account ready for use</output>
+</step_framework>
+
+### Step 3: Welcome Communications
+<step_framework>
+  <context_dependencies>
+    - context/templates/welcome-email.md
+    - context/standards/communication-tone.md
+  </context_dependencies>
+  
+  <action>Send personalized welcome communications</action>
+  
+  <communications>
+    <welcome_email>
+      - Thank you for joining
+      - Quick start guide link
+      - Support contact information
+      - Getting started video
+    </welcome_email>
+    
+    <in_app_tour>
+      - Feature highlights
+      - First task guidance
+      - Help resources
+    </in_app_tour>
+  </communications>
+  
+  <output>Customer receives welcome materials</output>
+</step_framework>
+
+### Step 4: First-Use Guidance
+<step_framework>
+  <context_dependencies>
+    - context/processes/quickstart-tasks.md
+  </context_dependencies>
+  
+  <action>Guide customer to first successful use</action>
+  
+  <guidance>
+    <task_1>Complete first meaningful action</task_1>
+    <task_2>Achieve quick win</task_2>
+    <task_3>Discover key features</task_3>
+  </guidance>
+  
+  <monitoring>
+    Track completion of first-use tasks
+    Trigger follow-up if tasks not completed within 48 hours
+  </monitoring>
+  
+  <output>Customer successfully completes first tasks</output>
+</step_framework>
+
+### Step 5: Follow-Up Check-In
+<step_framework>
+  <context_dependencies>
+    - context/templates/check-in-email.md
+  </context_dependencies>
+  
+  <action>Send follow-up to ensure satisfaction</action>
+  
+  <timing>3 days after signup</timing>
+  
+  <content>
+    - How is everything going?
+    - Any questions or issues?
+    - Resource recommendations based on usage
+    - Invitation to schedule call if needed
+  </content>
+  
+  <success_criteria>
+    - Customer has completed core tasks
+    - No outstanding issues
+    - Positive sentiment in response
+  </success_criteria>
+</step_framework>
+
+</process_flow>
+
+<guidance_systems>
+  <when_to_use>
+    - Every new customer signup
+    - Converting trial to paid
+    - Upgrading to higher tier (partial onboarding)
+  </when_to_use>
+  
+  <workflow_escalation>
+    <if test="customer_not_responding">Escalate to customer success manager</if>
+    <if test="technical_issues">Route to technical support workflow</if>
+  </workflow_escalation>
+</guidance_systems>
+
+<post_flight_check>
+  <validation_requirements>
+    - Account fully configured
+    - Customer has logged in
+    - First-use tasks completed
+    - Welcome communications sent
+    - No outstanding issues
+  </validation_requirements>
+</post_flight_check>
+
+## Context Dependencies Summary
+- **Step 1**: account-types.md, service-tiers.md
+- **Step 2**: setup-wizard.md, default-configs.md
+- **Step 3**: welcome-email.md, communication-tone.md
+- **Step 4**: quickstart-tasks.md
+- **Step 5**: check-in-email.md
+
+## Success Metrics
+- Time to first login: < 24 hours
+- First-use tasks completed: 100%
+- Customer satisfaction: > 8/10
+- Support tickets during onboarding: < 1 per customer
+```
+
+#### Example 2: Incident Response Workflow
+
+```markdown
+# Incident Response Workflow
+
+## Overview
+Systematic workflow for detecting, triaging, resolving, and learning
+from system incidents and outages.
+
+<task_context>
+  <expert_role>Site Reliability Engineer with incident management expertise</expert_role>
+  <mission_objective>Minimize incident impact and prevent recurrence</mission_objective>
+</task_context>
+
+<pre_flight_check>
+  <validation_requirements>
+    - Incident has been detected and confirmed
+    - Initial severity assessment completed
+    - Incident response team notified
+  </validation_requirements>
+</pre_flight_check>
+
+<process_flow>
+
+### Step 1: Incident Detection and Classification
+<step_framework>
+  <context_dependencies>
+    - context/domain/service-sla.md
+    - context/standards/severity-definitions.md
+  </context_dependencies>
+  
+  <action>Confirm incident and classify severity</action>
+  
+  <severity_classification>
+    <sev1>Complete service outage affecting all customers</sev1>
+    <sev2>Major functionality degraded, affecting many customers</sev2>
+    <sev3>Minor functionality issue, affecting some customers</sev3>
+    <sev4>Cosmetic issue or individual customer problem</sev4>
+  </severity_classification>
+  
+  <decision_tree>
+    <if test="severity = SEV1">
+      - Page on-call engineer immediately
+      - Notify incident commander
+      - Initiate status page update
+      - Start incident Slack channel
+    </if>
+    <else_if test="severity = SEV2">
+      - Notify on-call engineer
+      - Start incident tracking
+      - Prepare for status update
+    </else_if>
+    <else>
+      - Create ticket in queue
+      - Assign to next available engineer
+    </else>
+  </decision_tree>
+  
+  <output>Classified incident with assigned responders</output>
+</step_framework>
+
+### Step 2: Initial Response and Mitigation
+<step_framework>
+  <context_dependencies>
+    - context/processes/runbooks/{service}.md
+    - context/processes/emergency-procedures.md
+  </context_dependencies>
+  
+  <action>Begin immediate mitigation</action>
+  
+  <response_actions>
+    <assess>
+      - What is affected?
+      - How many customers impacted?
+      - What is the blast radius?
+    </assess>
+    
+    <mitigate>
+      - Can we roll back recent changes?
+      - Can we failover to backup systems?
+      - Can we implement temporary workaround?
+    </mitigate>
+    
+    <communicate>
+      - Update status page
+      - Post to incident channel
+      - Notify affected customers (for SEV1/SEV2)
+    </communicate>
+  </response_actions>
+  
+  <output>Mitigation in progress, communications sent</output>
+</step_framework>
+
+### Step 3: Diagnosis and Root Cause Analysis
+<step_framework>
+  <context_dependencies>
+    - context/domain/system-architecture.md
+    - context/processes/debugging-procedures.md
+  </context_dependencies>
+  
+  <action>Identify root cause of incident</action>
+  
+  <investigation>
+    <logs>Review application and system logs</logs>
+    <metrics>Analyze performance metrics and dashboards</metrics>
+    <changes>Review recent deployments and configuration changes</changes>
+    <dependencies>Check status of external dependencies</dependencies>
+  </investigation>
+  
+  <documentation>
+    Document findings in incident channel in real-time
+  </documentation>
+  
+  <output>Root cause identified and documented</output>
+</step_framework>
+
+### Step 4: Resolution and Recovery
+<step_framework>
+  <context_dependencies>
+    - context/processes/deployment-procedures.md
+    - context/standards/change-management.md
+  </context_dependencies>
+  
+  <action>Implement fix and verify resolution</action>
+  
+  <resolution_steps>
+    <implement_fix>
+      - Deploy fix to production
+      - OR roll back to last known good state
+      - OR implement permanent workaround
+    </implement_fix>
+    
+    <verify>
+      - Confirm metrics return to normal
+      - Verify functionality restored
+      - Test affected features
+      - Confirm with impacted customers
+    </verify>
+    
+    <communicate>
+      - Update status page to "Resolved"
+      - Post resolution to incident channel
+      - Send follow-up to affected customers
+    </communicate>
+  </resolution_steps>
+  
+  <output>Incident resolved, services restored</output>
+</step_framework>
+
+### Step 5: Post-Incident Review
+<step_framework>
+  <context_dependencies>
+    - context/templates/postmortem-template.md
+    - context/processes/continuous-improvement.md
+  </context_dependencies>
+  
+  <action>Conduct blameless postmortem</action>
+  
+  <postmortem_structure>
+    <summary>
+      - What happened?
+      - What was the impact?
+      - What was the root cause?
+    </summary>
+    
+    <timeline>
+      Detailed timeline of events from detection to resolution
+    </timeline>
+    
+    <contributing_factors>
+      What conditions allowed this incident to occur?
+    </contributing_factors>
+    
+    <action_items>
+      - Immediate fixes to prevent recurrence
+      - Long-term improvements
+      - Process changes
+      - Assigned owners and due dates
+    </action_items>
+  </postmortem_structure>
+  
+  <follow_up>
+    - Share postmortem with team
+    - Track action items to completion
+    - Update runbooks and documentation
+  </follow_up>
+  
+  <success_criteria>
+    - Postmortem completed within 48 hours
+    - Action items assigned and scheduled
+    - Lessons learned shared with team
+  </success_criteria>
+</step_framework>
+
+</process_flow>
+
+<guidance_systems>
+  <when_to_use>
+    - Any service disruption or degradation
+    - Security incidents
+    - Data loss or corruption events
+    - SLA breaches
+  </when_to_use>
+  
+  <workflow_escalation>
+    <if test="incident_duration > 4_hours">Escalate to engineering leadership</if>
+    <if test="data_breach_suspected">Initiate security incident workflow</if>
+    <if test="cannot_identify_cause">Bring in additional engineering resources</if>
+  </workflow_escalation>
+</guidance_systems>
+
+<post_flight_check>
+  <validation_requirements>
+    - Service fully restored
+    - Root cause documented
+    - Postmortem completed
+    - Action items assigned
+    - Status page updated
+    - Customer communications sent
+  </validation_requirements>
+</post_flight_check>
+
+## Context Dependencies Summary
+- **Step 1**: service-sla.md, severity-definitions.md
+- **Step 2**: runbooks/{service}.md, emergency-procedures.md
+- **Step 3**: system-architecture.md, debugging-procedures.md
+- **Step 4**: deployment-procedures.md, change-management.md
+- **Step 5**: postmortem-template.md, continuous-improvement.md
+
+## Success Metrics
+- Mean Time to Detection (MTTD): < 5 minutes
+- Mean Time to Resolution (MTTR): < 2 hours (SEV1)
+- Postmortem completion: Within 48 hours
+- Action item completion: 100% within 30 days
+- Incident recurrence: 0%
+```
+
+---
+
+## Step 8: Custom Commands
+
+Custom commands provide user-friendly entry points to your system's capabilities.
+
+### Command Template
+
+```markdown
+---
+agent: [which-agent-handles-this]
+description: "[What this command does]"
+---
+
+[Brief description of what this command accomplishes]
+
+**Request:** $ARGUMENTS
+
+**Process:**
+1. [Step 1 description]
+2. [Step 2 description]
+3. [Step 3 description]
+...
+
+**Options/Flags:**
+- `--flag1`: [What this flag does]
+- `--flag2`: [What this flag does]
+
+**Examples:**
+- [Example 1]
+- [Example 2]
+- [Example 3]
+
+**Output:**
+[What the user should expect to see/receive]
+```
+
+### Example Commands
+
+#### Example 1: Data Pipeline Command
+
+```markdown
+---
+agent: pipeline-orchestrator
+description: "Run data pipeline with validation and monitoring"
+---
+
+Execute a data pipeline from source to destination with built-in
+validation, error handling, and monitoring.
+
+**Request:** $ARGUMENTS
+
+**Process:**
+1. **Validate Inputs**: Check that source, transformations, and destination are specified
+2. **Load Configuration**: Load pipeline configuration and dependencies
+3. **Extract Data**: Pull data from specified source
+4. **Transform Data**: Apply transformation logic
+5. **Validate Quality**: Run data quality checks
+6. **Load Data**: Write to destination
+7. **Monitor**: Log metrics and send notifications
+8. **Report**: Provide execution summary
+
+**Syntax:**
+```bash
+/run-pipeline {source} {destination} [--transform {logic}] [--validate] [--dry-run]
+```
+
+**Options:**
+- `--transform {transformation_name}`: Apply named transformation
+- `--validate`: Run data quality validation (recommended)
+- `--dry-run`: Test pipeline without writing to destination
+- `--schedule {cron}`: Schedule recurring execution
+- `--notify {email}`: Send completion notification
+
+**Examples:**
+```bash
+/run-pipeline database:customers warehouse:customers_fact --validate
+/run-pipeline api:orders warehouse:orders_fact --transform enrich_with_products --notify team@company.com
+/run-pipeline file:exports/data.csv database:staging --dry-run
+```
+
+**Output:**
+```yaml
+Pipeline Execution Report
+========================
+Source: database:customers
+Destination: warehouse:customers_fact
+Status: Success ✓
+
+Metrics:
+- Rows extracted: 10,523
+- Rows transformed: 10,523
+- Rows loaded: 10,523
+- Data quality score: 98.5%
+- Execution time: 2m 34s
+
+Validation Results:
+✓ Schema validation passed
+✓ Data type validation passed
+✓ Business rule validation passed
+⚠ 150 rows flagged for review (null email addresses)
+
+Next Steps:
+- Review flagged rows at: logs/pipeline_2024_03_15.log
+- Schedule recurring run: /run-pipeline {source} {dest} --schedule "0 2 * * *"
+```
+```
+
+#### Example 2: Content Generation Command
+
+```markdown
+---
+agent: content-orchestrator
+description: "Generate content for specified platforms"
+---
+
+Create optimized content for one or more platforms with brand alignment
+and quality validation.
+
+**Request:** $ARGUMENTS
+
+**Process:**
+1. **Analyze Request**: Determine platforms, topic, and requirements
+2. **Load Context**: Get relevant brand guidelines and platform specs
+3. **Generate Content**: Create platform-optimized content
+4. **Validate**: Check quality and brand alignment
+5. **Refine**: Apply improvements based on validation
+6. **Save**: Store content in organized structure
+7. **Report**: Show generated content and file locations
+
+**Syntax:**
+```bash
+/generate-content "{topic}" --platforms {platform1,platform2} [--research] [--validate]
+```
+
+**Options:**
+- `--platforms {list}`: Target platforms (twitter, linkedin, blog, email)
+- `--research`: Include research and data backing
+- `--validate`: Run quality validation (recommended for important content)
+- `--tone {style}`: Override default brand tone
+- `--length {size}`: short, medium, long
+
+**Examples:**
+```bash
+/generate-content "Product launch announcement" --platforms twitter,linkedin,email
+/generate-content "Industry trends analysis" --platforms blog --research --validate
+/generate-content "Customer success story" --platforms linkedin,blog --tone professional
+```
+
+**Output:**
+```markdown
+Content Generation Complete ✓
+===============================
+
+Topic: Product launch announcement
+Platforms: Twitter, LinkedIn, Email
+
+Generated Content:
+------------------
+
+📱 Twitter (Thread - 5 tweets)
+File: content/2024-03-15/twitter/product-launch.md
+Preview: "Excited to announce our new feature that... 🎉"
+
+💼 LinkedIn (Professional Post)
+File: content/2024-03-15/linkedin/product-launch.md
+Preview: "Today marks an important milestone as we launch..."
+
+✉️ Email (Announcement Email)
+File: content/2024-03-15/email/product-launch.md
+Subject: "Introducing [Feature]: Transform how you..."
+
+Validation Results:
+-------------------
+✓ Brand voice alignment: 95%
+✓ Platform optimization: 100%
+✓ Engagement potential: High
+✓ Call-to-action: Clear and compelling
+
+Next Steps:
+-----------
+1. Review generated content in files above
+2. Make any final adjustments
+3. Schedule or publish using: /publish {platform} {file}
+```
+```
+
+---
+
+## Step 9: Integration and Testing
+
+### Testing Your System
+
+**1. Test Agent Prompts in Isolation**
+```bash
+# Test each agent independently with sample inputs
+# Verify they produce expected outputs
+# Check they handle errors gracefully
+```
+
+**2. Test Context Loading**
+```bash
+# Verify context files load correctly
+# Check that context allocation works
+# Validate file paths resolve
+```
+
+**3. Test Workflows End-to-End**
+```bash
+# Run complete workflows
+# Verify each step executes correctly
+# Check handoffs between agents work
+# Validate final outputs
+```
+
+**4. Test Edge Cases**
+```bash
+# Missing inputs
+# Invalid data
+# Error conditions
+# Timeout scenarios
+# Large inputs
+```
+
+### Integration Checklist
+
+```yaml
+Directory Structure:
+  ✓ .opencode/ folder created
+  ✓ agent/ subfolder with orchestrator and subagents
+  ✓ context/ subfolder organized by type
+  ✓ command/ subfolder with slash commands
+  ✓ templates/ subfolder with guidelines
+
+Agent Configuration:
+  ✓ Main orchestrator has workflow stages
+  ✓ Subagents have clear input/output specs
+  ✓ All agents use XML structure
+  ✓ Context allocation logic implemented
+  ✓ Routing patterns defined
+
+Context Management:
+  ✓ Context files are modular (50-200 lines)
+  ✓ Files have clear naming
+  ✓ Dependencies documented
+  ✓ Context provider implemented
+  ✓ Three-level system in place
+
+Workflows:
+  ✓ Common workflows documented
+  ✓ Context dependencies listed
+  ✓ Success criteria defined
+  ✓ Error handling specified
+  
+Commands:
+  ✓ Primary commands created
+  ✓ Command syntax documented
+  ✓ Examples provided
+  ✓ Help text clear
+
+Testing:
+  ✓ Agents tested individually
+  ✓ Workflows tested end-to-end
+  ✓ Edge cases handled
+  ✓ Error messages helpful
+```
+
+---
+
+## Advanced Patterns
+
+### Pattern 1: Progressive Validation
+
+Build quality checks into workflows at multiple stages:
+
+```xml
+<validation_gates>
+  <pre_execution>
+    Validate inputs before starting work
+  </pre_execution>
+  
+  <mid_workflow>
+    Check intermediate results meet standards
+  </mid_workflow>
+  
+  <pre_output>
+    Validate final output before delivery
+  </pre_output>
+</validation_gates>
+```
+
+### Pattern 2: Adaptive Workflows
+
+Allow workflows to adjust based on intermediate results:
+
+```xml
+<adaptive_routing>
+  <stage id="2">
+    Execute step 2
+    IF result.quality_score < 8:
+      Route to @quality-enhancer
+    ELSE:
+      Proceed to step 3
+    END IF
+  </stage>
+</adaptive_routing>
+```
+
+### Pattern 3: Context Caching
+
+Cache frequently-used context to improve performance:
+
+```xml
+<context_caching>
+  <cache_strategy>
+    - Cache core concepts (rarely change)
+    - Cache workflows (static)
+    - DO NOT cache user data (dynamic)
+  </cache_strategy>
+  
+  <cache_invalidation>
+    - On file modification
+    - On manual cache clear
+    - After 24 hours (configurable)
+  </cache_invalidation>
+</context_caching>
+```
+
+### Pattern 4: Parallel Execution
+
+Execute independent tasks concurrently:
+
+```xml
+<parallel_execution>
+  <when>Tasks have no dependencies</when>
+  <how>
+    PARALLEL:
+      task_a = @subagent-a(input_a)
+      task_b = @subagent-b(input_b)
+      task_c = @subagent-c(input_c)
+    WAIT_ALL
+    
+    result = integrate(task_a, task_b, task_c)
+  </how>
+</parallel_execution>
+```
+
+### Pattern 5: Learning Systems
+
+Improve system over time by learning from outcomes:
+
+```xml
+<learning_system>
+  <capture>
+    After each execution:
+    - What was requested?
+    - What context was used?
+    - What was the outcome?
+    - What was the quality score?
+  </capture>
+  
+  <analyze>
+    Periodically:
+    - Which context combinations work best?
+    - Which workflows are most successful?
+    - Which agents are underperforming?
+  </analyze>
+  
+  <optimize>
+    Based on analysis:
+    - Adjust context allocation rules
+    - Refine workflow selection logic
+    - Improve agent prompts
+  </optimize>
+</learning_system>
+```
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: Context Overload
+
+**Problem**: Passing too much context to agents
+**Solution**: Implement three-level context system, default to Level 1
+**Example**:
+```xml
+<!-- Bad -->
+<pass_to_subagent>
+  All conversation history + All context files + All system state
+</pass_to_subagent>
+
+<!-- Good -->
+<pass_to_subagent>
+  Task description + Only required context for this specific task
+</pass_to_subagent>
+```
+
+### Pitfall 2: Ambiguous Instructions
+
+**Problem**: Subagents receive vague instructions and make assumptions
+**Solution**: Always provide complete, explicit instructions
+**Example**:
+```xml
+<!-- Bad -->
+"Generate some content about AI"
+
+<!-- Good -->
+"Generate a 280-character Twitter post about AI productivity tools 
+ for developers, including:
+ - Hook about time savings
+ - 2-3 specific tool recommendations  
+ - Call-to-action to follow
+ - Professional but enthusiastic tone"
+```
+
+### Pitfall 3: Missing Error Handling
+
+**Problem**: System breaks when encountering errors
+**Solution**: Build error handling into every stage
+**Example**:
+```xml
+<error_handling>
+  TRY:
+    result = execute_task()
+  CATCH ValidationError:
+    log_error(error)
+    return helpful_error_message
+  CATCH TimeoutError:
+    log_timeout()
+    retry_with_simpler_approach()
+  CATCH:
+    log_unexpected_error()
+    escalate_to_human()
+</error_handling>
+```
+
+### Pitfall 4: Monolithic Files
+
+**Problem**: Huge context files that are hard to maintain
+**Solution**: Split into focused 50-200 line files
+**Example**:
+```
+<!-- Bad -->
+context/everything.md (3000 lines)
+
+<!-- Good -->
+context/domain/products.md (150 lines)
+context/domain/pricing.md (100 lines)
+context/domain/customers.md (120 lines)
+context/processes/sales.md (180 lines)
+context/processes/support.md (140 lines)
+```
+
+### Pitfall 5: Unclear Success Criteria
+
+**Problem**: System doesn't know when task is complete
+**Solution**: Define explicit success criteria for every workflow
+**Example**:
+```xml
+<success_criteria>
+  <must_have>
+    - Output meets format specifications
+    - All required fields present
+    - Quality score > 8/10
+  </must_have>
+  
+  <validation>
+    IF all must_have criteria met:
+      Mark as success
+    ELSE:
+      Return specific issues to fix
+    END IF
+  </validation>
+</success_criteria>
+```
+
+---
+
+## Summary: Building Your System
+
+### Step-by-Step Checklist
+
+```yaml
+Phase 1 - Foundation (Week 1):
+  ✓ Create .opencode directory structure
+  ✓ Define your domain and use cases
+  ✓ Identify core agents needed
+  ✓ Outline primary workflows
+
+Phase 2 - Core Agents (Week 2):
+  ✓ Build main orchestrator
+  ✓ Create 2-3 essential subagents
+  ✓ Implement basic routing logic
+  ✓ Test agents individually
+
+Phase 3 - Context System (Week 3):
+  ✓ Organize context into modular files
+  ✓ Implement context provider
+  ✓ Set up three-level allocation
+  ✓ Test context loading
+
+Phase 4 - Workflows (Week 4):
+  ✓ Document primary workflows
+  ✓ Define context dependencies
+  ✓ Implement workflow selection
+  ✓ Test end-to-end
+
+Phase 5 - Commands (Week 5):
+  ✓ Create custom slash commands
+  ✓ Write clear documentation
+  ✓ Provide examples
+  ✓ Test user experience
+
+Phase 6 - Polish (Week 6):
+  ✓ Add error handling
+  ✓ Improve error messages
+  ✓ Add logging and monitoring
+  ✓ Create user guide
+
+Phase 7 - Optimization (Ongoing):
+  ✓ Monitor performance
+  ✓ Gather user feedback
+  ✓ Refine prompts
+  ✓ Add new capabilities
+```
+
+### Key Principles to Remember
+
+1. **Start Simple**: Build basic functionality first, add complexity gradually
+2. **Modular Design**: Small, focused files are easier to maintain
+3. **Explicit Instructions**: Never make agents guess or assume
+4. **Context Efficiency**: Less context often produces better results
+5. **User-Centric**: Design commands for how users think, not how system works
+6. **Iterative Improvement**: Systems improve over time with real usage
+7. **Document Everything**: Good documentation = maintainable system
+
+---
+
+## Next Steps
+
+**You now understand**:
+- How to structure a context-aware AI system
+- How to write optimal prompts with XML
+- How to split and manage context
+- How to build orchestrators and subagents
+- How to create workflows and commands
+- How to test and integrate components
+
+**Start building**:
+1. Define your domain and primary use case
+2. Create basic directory structure
+3. Build one simple workflow end-to-end
+4. Test with real requests
+5. Expand and refine
+
+**Get help**:
+- Review the existing `.opencode` system as reference
+- Start with a simplified version
+- Test frequently with actual use cases
+- Iterate based on results
+
+**Good luck building your context-aware AI system!**

.Building/DATA-GOVERNANCE-AGENT-SYSTEM.md

@@ -0,0 +1,1983 @@
+# Building Data Governance Agent Systems: A Complete Guide
+
+**Version**: 2.0  
+**Date**: 2025-10-09  
+**Purpose**: Separate, specialized system for managing context data quality and lifecycle
+
+---
+
+## Overview
+
+This guide teaches you how to build a **Data Governance Agent System** that manages your context documentation as data assets. This system operates **independently** from your main orchestrator but **integrates seamlessly** when context management is needed.
+
+**What you'll learn:**
+- How to build specialized data governance agents
+- How to manage context lifecycle automatically
+- How to maintain data quality without overwhelming your main orchestrator
+- How to pass context between agents without information loss
+- How to keep everything simple but robust
+
+**Key Improvements in v2.0:**
+- **JSON Metadata Index** as primary (fast queries, no XML parsing)
+- **Explicit Context Passing** via temp files (no information loss)
+- **Simplified Workflows** with state machine (resumable, debuggable)
+- **Clear Communication Protocol** between agents
+
+---
+
+## Table of Contents
+
+1. [Core Concepts](#core-concepts)
+2. [System Architecture](#system-architecture)
+3. [Step 1: Foundation - Data Management Structure](#step-1-foundation---data-management-structure)
+4. [Step 2: Agent Communication Protocol](#step-2-agent-communication-protocol)
+5. [Step 3: Building the Context Management Agent](#step-3-building-the-context-management-agent)
+6. [Step 4: Specialized Governance Subagents](#step-4-specialized-governance-subagents)
+7. [Step 5: Automated Quality & Lifecycle Workflows](#step-5-automated-quality--lifecycle-workflows)
+8. [Step 6: Metadata Management](#step-6-metadata-management)
+9. [Complete Workflow Examples](#complete-workflow-examples)
+10. [Keeping It Simple](#keeping-it-simple)
+
+---
+
+## Core Concepts
+
+### The Problem This Solves
+
+Your main orchestrator should focus on **user tasks** (building features, writing code, processing requests). It shouldn't be burdened with:
+
+1. **Context Quality Management**: Checking if docs are accurate, complete, current
+2. **Context Lifecycle**: Moving files through CREATE → ACTIVE → REVIEW → ARCHIVE → DELETE
+3. **Metadata Maintenance**: Updating timestamps, usage stats, quality scores
+4. **Catalog Synchronization**: Keeping CATALOG.md files in sync with actual files
+
+**Solution**: A **separate Data Governance Agent System** that handles all context management autonomously.
+
+### The Architecture
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   USER REQUEST                         │
+└────────────────┬───────────────────────────────────────┘
+                 ↓
+┌────────────────────────────────────────────────────────┐
+│          MAIN ORCHESTRATOR AGENT                       │
+│  "Build feature X"                                     │
+│  "Write blog post about Y"                             │
+└────────────────┬───────────────────────────────────────┘
+                 ↓
+         Need context?
+                 ↓
+         Creates request file (tmp/context-requests/req-123.json)
+                 ↓
+┌────────────────────────────────────────────────────────┐
+│      CONTEXT MANAGEMENT AGENT (Primary)                │
+│  - Reads request file (full context)                   │
+│  - Retrieve context for task                           │
+│  - Check if context needs update                       │
+│  - Route to governance subagents with request ID       │
+└────────────────┬───────────────────────────────────────┘
+                 ↓
+         ┌───────┴────────┬────────────┬──────────────┐
+         │                │            │              │
+    ┌────▼────┐   ┌──────▼──┐   ┌────▼─────┐   ┌───▼──────┐
+    │ Quality │   │Lifecycle│   │ Metadata │   │ Catalog  │
+    │ Agent   │   │ Agent   │   │  Agent   │   │  Agent   │
+    └─────────┘   └─────────┘   └──────────┘   └──────────┘
+         ↑              ↑              ↑              ↑
+         └──────────────┴──────────────┴──────────────┘
+              All read same request file (no context loss)
+```
+
+**Key Separation**:
+- **Main Orchestrator**: User-facing tasks
+- **Context Management Agent**: All context operations
+- **Governance Subagents**: Specialized maintenance tasks
+- **Temp Files**: Pass full context between agents (no information loss)
+
+---
+
+## System Architecture
+
+### Directory Structure
+
+```
+.opencode/
+├── agent/
+│   ├── main-orchestrator.md        # User-facing agent
+│   │
+│   └── governance/                 # Governance agents
+│       ├── context-manager.md      # Primary governance agent
+│       └── subagents/
+│           ├── quality-validator.md
+│           ├── lifecycle-manager.md
+│           ├── metadata-updater.md
+│           └── catalog-maintainer.md
+│
+├── context/
+│   ├── MASTER-CATALOG.md
+│   ├── system-design/
+│   │   ├── CATALOG.md
+│   │   └── [context files with embedded metadata]
+│   ├── services/
+│   ├── business-logic/
+│   ├── styles/
+│   └── temp/
+│
+├── learning/
+│   └── [error patterns, decisions, etc.]
+│
+└── governance/                     # Governance metadata & state
+    ├── metadata-index.json         # PRIMARY: Fast queryable metadata
+    ├── workflow-state.json         # Workflow state machine
+    ├── tmp/                        # Inter-agent communication
+    │   ├── context-requests/       # Request context files
+    │   ├── validation-jobs/        # Validation job state
+    │   └── workflow-checkpoints/   # Resumable workflow state
+    ├── logs/
+    │   ├── access.log              # All file access
+    │   ├── changes.log             # All metadata changes
+    │   └── workflows.log           # Workflow execution logs
+    ├── quality-reports/
+    │   └── [automated quality reports]
+    └── lifecycle-logs/
+        └── [lifecycle transition logs]
+```
+
+### Design Principles
+
+**1. Explicit Context Passing**
+- No implicit context assumptions
+- All agent calls include request ID
+- Request ID points to temp file with full context
+- Any agent can resume from any point
+
+**2. JSON Metadata as Primary**
+- Fast queries without XML parsing
+- Embedded XML as backup/sync source
+- Nightly sync ensures consistency
+- File always wins on conflict
+
+**3. State Machine for Workflows**
+- Single workflow-state.json file
+- Resumable from any checkpoint
+- Clear locks prevent concurrent runs
+- Easy debugging with state history
+
+**4. Separation of Concerns**
+- Main Orchestrator = User tasks
+- Context Management Agent = Context operations
+- Governance Subagents = Specific maintenance tasks
+- No circular dependencies
+
+---
+
+## Step 1: Foundation - Data Management Structure
+
+### Dual Metadata System
+
+**PRIMARY: JSON Metadata Index** (Fast, Queryable)
+**SECONDARY: Embedded XML Metadata** (Travels with file, Backup)
+
+#### JSON Metadata Index (PRIMARY)
+
+**Location**: `.opencode/governance/metadata-index.json`
+
+```json
+{
+  "version": "1.0",
+  "last_updated": "2025-10-09T14:30:00Z",
+  "last_sync_with_files": "2025-10-09T14:25:00Z",
+  "sync_status": "healthy",
+  "total_files": 156,
+  
+  "files": {
+    "context/system-design/storage.md": {
+      "admin": {
+        "created": "2025-01-15",
+        "created_by": "john.doe@company.com",
+        "owner": "platform-team-lead",
+        "last_modified": "2025-07-15",
+        "modified_by": "jane.smith@company.com",
+        "next_review": "2026-01-09"
+      },
+      "classification": {
+        "tier": 1,
+        "category": "system-design",
+        "sensitivity": "internal",
+        "tags": ["storage", "database", "persistence", "postgresql"]
+      },
+      "quality": {
+        "health_score": 22,
+        "accuracy_score": 5,
+        "completeness_score": 4,
+        "consistency_score": 5,
+        "timeliness_score": 3,
+        "validity_score": 5,
+        "uniqueness_score": 5,
+        "last_validated": "2025-10-09"
+      },
+      "usage": {
+        "access_count_30d": 45,
+        "access_count_90d": 132,
+        "last_accessed": "2025-10-08"
+      },
+      "lifecycle": {
+        "state": "active",
+        "retention": "permanent"
+      },
+      "checksum": "sha256:abc123...",
+      "embedded_metadata_present": true
+    }
+  },
+  
+  "indexes": {
+    "by_tier": {
+      "1": ["context/system-design/storage.md", "context/system-design/api-patterns.md"],
+      "2": ["context/services/user-service.md"],
+      "3": ["context/styles/naming-conventions.md"],
+      "4": ["context/temp/sprint-notes.md"],
+      "5": ["learning/error-patterns.md"]
+    },
+    "by_state": {
+      "active": ["context/system-design/storage.md", "..."],
+      "review": ["context/services/old-service.md"],
+      "archive": []
+    },
+    "by_health": {
+      "healthy": ["context/system-design/storage.md", "..."],
+      "warning": ["context/services/stale-service.md"],
+      "action_required": ["context/business-logic/deprecated-rule.md"]
+    },
+    "by_tag": {
+      "storage": ["context/system-design/storage.md", "..."],
+      "database": ["context/system-design/storage.md", "..."],
+      "authentication": ["context/system-design/authentication.md", "..."]
+    }
+  },
+  
+  "quality_summary": {
+    "healthy_files": 142,
+    "warning_files": 12,
+    "action_required_files": 2,
+    "overall_health_score": 87
+  }
+}
+```
+
+**Usage**:
+```
+Fast Queries:
+- "Show all Tier 1 files" → indexes.by_tier["1"] (instant)
+- "Files needing review" → indexes.by_state["review"] (instant)
+- "Health summary" → quality_summary (instant)
+- NO XML PARSING NEEDED
+```
+
+#### Embedded XML Metadata (SECONDARY)
+
+**Location**: Top of each context file
+
+```xml
+<!-- context/system-design/storage.md -->
+
+<?xml version="1.0" encoding="UTF-8"?>
+<context_file>
+
+<!-- METADATA (Managed by Governance Agents) -->
+<metadata>
+  <admin>
+    <created>2025-01-15</created>
+    <created_by>john.doe@company.com</created_by>
+    <owner>platform-team-lead</owner>
+    <last_modified>2025-07-15</last_modified>
+    <modified_by>jane.smith@company.com</modified_by>
+    <next_review>2026-01-09</next_review>
+  </admin>
+  
+  <classification>
+    <tier>1</tier>
+    <category>system-design</category>
+    <sensitivity>internal</sensitivity>
+    <tags>storage,database,persistence,postgresql</tags>
+  </classification>
+  
+  <quality>
+    <health_score>22</health_score>
+    <accuracy_score>5</accuracy_score>
+    <completeness_score>4</completeness_score>
+    <timeliness_score>3</timeliness_score>
+    <validity_score>5</validity_score>
+    <last_validated>2025-10-09</last_validated>
+  </quality>
+  
+  <usage>
+    <access_count_30d>45</access_count_30d>
+    <access_count_90d>132</access_count_90d>
+    <last_accessed>2025-10-08</last_accessed>
+  </usage>
+  
+  <lifecycle>
+    <state>active</state>
+    <retention>permanent</retention>
+  </lifecycle>
+</metadata>
+
+<!-- CONTENT (Managed by Humans/Main Orchestrator) -->
+<system_design category="storage">
+  <overview>Data persistence patterns and database conventions</overview>
+  
+  <patterns>
+    <!-- Pattern definitions here -->
+  </patterns>
+  
+  <related>
+    <see>@context/services/CATALOG.md</see>
+  </related>
+</system_design>
+
+</context_file>
+```
+
+### Metadata Synchronization Strategy
+
+**Write Operation** (Human or Agent Updates File):
+```
+1. Update embedded XML metadata in file
+2. Calculate checksum of file
+3. Update metadata-index.json entry
+4. Update indexes (by_tier, by_tag, etc.)
+5. Write both atomically
+```
+
+**Read Operation** (Agent Queries Metadata):
+```
+1. Query metadata-index.json (FAST - no file I/O)
+2. Return metadata
+```
+
+**Read Operation** (Agent Loads File Content):
+```
+1. Query metadata-index.json for file info
+2. Load file content
+3. Verify checksum matches
+4. If mismatch: Re-sync from file (embedded XML wins)
+```
+
+**Nightly Sync Job**:
+```
+1. Scan all context files
+2. Parse embedded XML metadata
+3. Compare with metadata-index.json
+4. If mismatch: File wins, update JSON
+5. Recalculate all indexes
+6. Log any discrepancies
+7. Update sync_status
+```
+
+---
+
+## Step 2: Agent Communication Protocol
+
+### The Problem with Implicit Context
+
+**BAD (Context Loss)**:
+```
+Main Orchestrator → Context Manager: "validate authentication.md"
+Context Manager → Quality Validator: "validate authentication.md"
+
+❌ Quality Validator doesn't know:
+- WHY it's validating
+- What the user task is
+- How urgent/important this is
+- What to prioritize in validation
+```
+
+**GOOD (Explicit Context)**:
+```
+Main Orchestrator:
+  - Creates tmp/context-requests/req-abc123.json
+  - Calls Context Manager with request_id="req-abc123"
+
+Context Manager:
+  - Reads tmp/context-requests/req-abc123.json (full context)
+  - Knows user task, keywords, priority
+  - Calls Quality Validator with request_id="req-abc123"
+
+Quality Validator:
+  - Reads tmp/context-requests/req-abc123.json
+  - Knows WHY it's validating
+  - Validates appropriately
+  - Updates tmp file with results
+```
+
+### Context Request File Structure
+
+**Location**: `.opencode/governance/tmp/context-requests/{request_id}.json`
+
+```json
+{
+  "request_id": "req-abc123",
+  "timestamp": "2025-10-09T14:23:45Z",
+  "from_agent": "main-orchestrator",
+  
+  "task_context": {
+    "type": "feature_build",
+    "description": "Add password reset feature",
+    "user_request": "Allow users to reset their password via email",
+    "keywords": ["password", "reset", "authentication", "email"],
+    "priority": "normal"
+  },
+  
+  "context_needed": {
+    "files_requested": [
+      "context/system-design/authentication.md",
+      "context/services/user-service.md"
+    ],
+    "depth": 1,
+    "include_learning": true,
+    "max_files": 10
+  },
+  
+  "processing_chain": [
+    {
+      "agent": "main-orchestrator",
+      "action": "initiated_request",
+      "timestamp": "2025-10-09T14:23:45Z"
+    },
+    {
+      "agent": "context-manager",
+      "action": "processing_retrieval",
+      "timestamp": "2025-10-09T14:23:46Z",
+      "notes": "Found 2 primary files, checking quality"
+    },
+    {
+      "agent": "quality-validator",
+      "action": "validating",
+      "timestamp": "2025-10-09T14:23:47Z",
+      "files_validated": 2,
+      "warnings": ["authentication.md is 85 days stale"]
+    },
+    {
+      "agent": "context-manager",
+      "action": "completed",
+      "timestamp": "2025-10-09T14:23:48Z"
+    }
+  ],
+  
+  "result": {
+    "status": "completed",
+    "files_returned": [
+      "context/system-design/authentication.md",
+      "context/services/user-service.md",
+      "context/system-design/security.md"
+    ],
+    "warnings": ["authentication.md not updated in 85 days"],
+    "estimated_tokens": 1200
+  }
+}
+```
+
+### Communication Protocol Rules
+
+**Rule 1: Every Agent Call Includes Request ID**
+```xml
+<agent_call>
+  <from>context-manager</from>
+  <to>quality-validator</to>
+  <method>validate_files</method>
+  <request_id>req-abc123</request_id>  <!-- ALWAYS INCLUDE -->
+  <parameters>
+    <files>["authentication.md"]</files>
+  </parameters>
+</agent_call>
+```
+
+**Rule 2: First Action is Always Read Request File**
+```python
+def quality_validator_process(request_id, files):
+    # ALWAYS read request file first
+    request = read_json(f"tmp/context-requests/{request_id}.json")
+    
+    # Now you have full context:
+    user_task = request["task_context"]["description"]
+    priority = request["task_context"]["priority"]
+    
+    # Validate appropriately based on context
+    if priority == "urgent":
+        quick_validation(files)
+    else:
+        thorough_validation(files)
+```
+
+**Rule 3: Update Request File at Each Stage**
+```python
+def context_manager_process(request_id):
+    request = read_json(f"tmp/context-requests/{request_id}.json")
+    
+    # Do work...
+    files = locate_context(request)
+    
+    # Update request file with progress
+    request["processing_chain"].append({
+        "agent": "context-manager",
+        "action": "located_files",
+        "timestamp": now(),
+        "files_found": files
+    })
+    write_json(f"tmp/context-requests/{request_id}.json", request)
+    
+    # Call subagent with same request_id
+    call_quality_validator(request_id, files)
+```
+
+**Rule 4: Cleanup Temp Files After Completion**
+```python
+def main_orchestrator_after_task():
+    # Read final result
+    result = read_json(f"tmp/context-requests/req-abc123.json")
+    
+    # Archive for debugging (optional)
+    archive(f"tmp/context-requests/req-abc123.json", 
+            f"governance/logs/requests/2025-10-09/req-abc123.json")
+    
+    # Clean up
+    delete(f"tmp/context-requests/req-abc123.json")
+```
+
+### Workflow State File
+
+**Location**: `.opencode/governance/workflow-state.json`
+
+```json
+{
+  "workflows": {
+    "daily_quality_check": {
+      "schedule": "0 2 * * *",
+      "last_run": "2025-10-09T02:00:00Z",
+      "next_run": "2025-10-10T02:00:00Z",
+      "status": "completed",
+      "duration_seconds": 45,
+      "files_processed": 156
+    },
+    "weekly_lifecycle_review": {
+      "schedule": "0 3 * * 0",
+      "last_run": "2025-10-08T03:00:00Z",
+      "next_run": "2025-10-15T03:00:00Z",
+      "status": "in_progress",
+      "checkpoint": {
+        "files_processed": 45,
+        "files_total": 65,
+        "current_file": "context/services/payment-service.md",
+        "can_resume": true,
+        "checkpoint_file": "tmp/workflow-checkpoints/weekly-lifecycle-2025-10-08.json"
+      }
+    }
+  },
+  
+  "locks": {
+    "metadata_update": {
+      "locked": false,
+      "locked_by": null,
+      "locked_at": null
+    },
+    "catalog_sync": {
+      "locked": false,
+      "locked_by": null,
+      "locked_at": null
+    },
+    "quality_validation": {
+      "locked": false,
+      "locked_by": null,
+      "locked_at": null
+    }
+  }
+}
+```
+
+**Checkpoint File for Resumable Workflows**:
+
+**Location**: `.opencode/governance/tmp/workflow-checkpoints/weekly-lifecycle-2025-10-08.json`
+
+```json
+{
+  "workflow_id": "weekly-lifecycle-2025-10-08",
+  "started": "2025-10-08T03:00:00Z",
+  "current_stage": "review_transitions",
+  "files_processed": [
+    "context/system-design/storage.md",
+    "context/system-design/api-patterns.md",
+    "..."
+  ],
+  "files_remaining": [
+    "context/services/payment-service.md",
+    "context/services/order-service.md",
+    "..."
+  ],
+  "current_file": "context/services/payment-service.md",
+  "results_so_far": {
+    "files_needing_review": 5,
+    "archive_candidates": 3,
+    "temp_expiring": 2
+  }
+}
+```
+
+---
+
+## Step 3: Building the Context Management Agent
+
+### Primary Governance Agent
+
+This is the **main entry point** for all context operations.
+
+```xml
+---
+description: "Primary context management and governance coordinator"
+mode: subagent
+temperature: 0.1
+tools:
+  read: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+  task: true
+---
+
+# Context Management Agent
+
+<context>
+  <system_context>
+    Data governance system for context documentation management.
+    Uses JSON metadata index for fast queries.
+    Uses tmp files for explicit context passing between agents.
+  </system_context>
+  <specialist_domain>
+    Context retrieval, quality management, lifecycle coordination
+  </specialist_domain>
+  <integration>
+    Called by Main Orchestrator when context operations needed.
+    Calls governance subagents with explicit request context.
+  </integration>
+</context>
+
+<role>
+  Context Management Specialist responsible for all context data operations,
+  quality assurance, lifecycle management, and governance coordination.
+  ALWAYS passes full context via tmp files to prevent information loss.
+</role>
+
+<task>
+  Provide context to agents while maintaining data quality, managing
+  lifecycle, and ensuring system health—all with minimal complexity.
+  Use JSON metadata index for fast queries.
+  Use tmp files for agent communication.
+</task>
+
+<core_responsibilities>
+  <retrieval>
+    <responsibility>Retrieve relevant context for agent tasks</responsibility>
+    <method>Query metadata-index.json (fast), catalog-based discovery</method>
+    <performance>Fast (< 1 second for 90% of requests using JSON index)</performance>
+    <context_passing>Create tmp/context-requests/{request_id}.json with full context</context_passing>
+  </retrieval>
+  
+  <quality_check>
+    <responsibility>Check context quality before retrieval</responsibility>
+    <method>Query metadata-index.json for health scores</method>
+    <action>Flag stale/low-quality context, trigger updates if needed</action>
+  </quality_check>
+  
+  <lifecycle_coordination>
+    <responsibility>Coordinate lifecycle transitions</responsibility>
+    <when>Scheduled (managed by workflow-state.json)</when>
+    <action>Route to lifecycle-manager with request ID</action>
+  </lifecycle_coordination>
+  
+  <update_coordination>
+    <responsibility>Coordinate context updates after code changes</responsibility>
+    <when>After PR approval (triggered by main orchestrator)</when>
+    <action>Analyze changes, update context, update metadata (both XML and JSON)</action>
+  </update_coordination>
+</core_responsibilities>
+
+<workflow name="ContextRetrieval">
+  <step_1>
+    <action>Read request file</action>
+    <input>tmp/context-requests/{request_id}.json</input>
+    <extract>task_description, keywords, priority, user_request</extract>
+    <output>Full task context</output>
+  </step_1>
+  
+  <step_2>
+    <action>Query metadata-index.json for relevant files</action>
+    <method>
+      - Search indexes.by_tag for keyword matches
+      - Search indexes.by_tier if tier_filter specified
+      - Check health scores in metadata
+    </method>
+    <output>List of candidate files with metadata</output>
+    <note>NO XML PARSING - pure JSON query (fast)</note>
+  </step_2>
+  
+  <step_3>
+    <action>Quality check using metadata-index.json</action>
+    <checks>
+      - health_score < 20? → action_required
+      - timeliness_score < 3? → stale_warning
+      - usage.access_count_90d = 0? → rarely_used_warning
+    </checks>
+    <decision>
+      - quality_good: Proceed to load
+      - quality_warning: Load but flag for review
+      - quality_poor: Trigger update workflow, use backup if available
+    </decision>
+    <note>ALL checks from JSON - no file I/O yet</note>
+  </step_3>
+  
+  <step_4>
+    <action>Load actual file content (only now)</action>
+    <verify>Checksum matches metadata-index.json entry</verify>
+    <update>Increment access_count, update last_accessed in JSON index</update>
+    <output>File content + metadata</output>
+  </step_4>
+  
+  <step_5>
+    <action>Follow @ references (depth 1)</action>
+    <method>Load referenced files, query their metadata from JSON index</method>
+    <limit>depth=1 to prevent explosion</limit>
+  </step_5>
+  
+  <step_6>
+    <action>Update request file with results</action>
+    <update>
+      - Add processing_chain entry
+      - Set result.status = "completed"
+      - Set result.files_returned
+      - Set result.warnings (if any)
+    </update>
+    <write>tmp/context-requests/{request_id}.json</write>
+  </step_6>
+  
+  <step_7>
+    <action>Return to calling agent</action>
+    <output>Context files + metadata + warnings</output>
+    <log>Log to governance/logs/access.log</log>
+  </step_7>
+</workflow>
+
+<workflow name="ContextUpdate">
+  <step_1>
+    <action>Create update request file</action>
+    <file>tmp/context-requests/update-{request_id}.json</file>
+    <include>PR diff, changed files, commit message, timestamp</include>
+  </step_1>
+  
+  <step_2>
+    <action>Analyze what context needs updating</action>
+    <logic>
+      - New pattern introduced? → Add to system-design/
+      - Service changed? → Update services/{service}.md
+      - Business rule changed? → Update business-logic/
+      - Error fixed? → Add to learning/error-patterns.md
+    </logic>
+    <output>List of files to update</output>
+  </step_2>
+  
+  <step_3>
+    <action>Update context files</action>
+    <for_each>file in files_to_update</for_each>
+    <update>
+      - Update embedded XML metadata (last_modified, modified_by)
+      - Update file content
+      - Calculate new checksum
+    </update>
+  </step_3>
+  
+  <step_4>
+    <action>Update metadata-index.json (PRIMARY)</action>
+    <update>
+      - Update admin.last_modified
+      - Update admin.modified_by
+      - Reset quality scores (needs re-validation)
+      - Update checksum
+      - Recalculate indexes if tier/tags changed
+    </update>
+    <atomic>Write both file and JSON atomically</atomic>
+  </step_4>
+  
+  <step_5>
+    <action>Update catalogs if needed</action>
+    <if>Files added or removed</if>
+    <call>catalog-maintainer subagent with request_id</call>
+  </step_5>
+  
+  <step_6>
+    <action>Trigger quality validation</action>
+    <call>quality-validator subagent with request_id</call>
+    <async>Run in background, don't block</async>
+  </step_6>
+  
+  <step_7>
+    <action>Update request file with results</action>
+    <write>tmp/context-requests/update-{request_id}.json</write>
+    <return>Summary of updates to main orchestrator</return>
+  </step_7>
+</workflow>
+
+<integration_interface>
+  <retrieval_call>
+    <method>get_context</method>
+    <input>
+      request_id: string (UUID)
+      task_description: string
+      keywords: array[string]
+      tier_filter: array[int] (optional)
+      max_files: int (optional, default 10)
+    </input>
+    <process>
+      1. Create tmp/context-requests/{request_id}.json
+      2. Query metadata-index.json (fast)
+      3. Load files
+      4. Update request file with results
+    </process>
+    <output>
+      Read from tmp/context-requests/{request_id}.json:
+      - result.files_returned (with content)
+      - result.warnings
+      - result.estimated_tokens
+    </output>
+  </retrieval_call>
+  
+  <update_call>
+    <method>update_context_after_pr</method>
+    <input>
+      request_id: string (UUID)
+      pr_number: string
+      changed_files: array[string]
+      commit_message: string
+      diff: string
+    </input>
+    <process>
+      1. Create tmp/context-requests/update-{request_id}.json
+      2. Analyze changes
+      3. Update files + embedded XML
+      4. Update metadata-index.json (PRIMARY)
+      5. Update request file with results
+    </process>
+    <output>
+      Read from tmp/context-requests/update-{request_id}.json:
+      - result.updated_files
+      - result.catalog_updates
+      - result.validation_status
+    </output>
+  </update_call>
+  
+  <status_call>
+    <method>get_system_health</method>
+    <input>none</input>
+    <process>
+      Query metadata-index.json.quality_summary (instant)
+    </process>
+    <output>
+      - overall_health_score
+      - healthy_files, warning_files, action_required_files
+      - recent_issues from logs
+    </output>
+  </status_call>
+</integration_interface>
+
+<constraints>
+  <must>ALWAYS create request file before calling subagents</must>
+  <must>ALWAYS pass request_id to subagents</must>
+  <must>Query metadata-index.json first (never parse XML for queries)</must>
+  <must>Update both embedded XML and JSON index atomically</must>
+  <must>Update request file after each major step</must>
+  <must>Acquire lock before modifying metadata-index.json</must>
+  <must_not>Call subagents without request_id</must_not>
+  <must_not>Parse XML files for metadata queries</must_not>
+  <must_not>Modify metadata-index.json without lock</must_not>
+</constraints>
+
+<output_specifications>
+  <to_orchestrator>
+    Point to tmp/context-requests/{request_id}.json for full results
+  </to_orchestrator>
+  
+  <to_logs>
+    - governance/logs/access.log: All file access
+    - governance/logs/changes.log: All metadata updates
+    - governance/logs/workflows.log: Workflow execution
+  </to_logs>
+</output_specifications>
+```
+
+---
+
+## Step 4: Specialized Governance Subagents
+
+### 4.1 Quality Validator Agent
+
+```xml
+---
+description: "Validates context quality against six dimensions"
+mode: subagent
+temperature: 0.1
+---
+
+# Quality Validator Agent
+
+<role>
+  Data Quality Specialist expert in the six dimensions of data quality.
+  ALWAYS reads request file first to understand validation context.
+</role>
+
+<task>
+  Validate context files against quality standards and generate
+  actionable reports. Updates metadata-index.json with quality scores.
+</task>
+
+<process_flow>
+  <step_1>
+    <action>Read request file for context</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <extract>
+      - Why validation requested (user task, priority)
+      - Which files to validate
+      - Validation depth (quick vs thorough)
+    </extract>
+  </step_1>
+  
+  <step_2>
+    <action>Load files and current quality scores from JSON index</action>
+    <source>metadata-index.json (fast query)</source>
+    <extract>Current health_score, last_validated date</extract>
+  </step_2>
+  
+  <step_3>
+    <action>Run quality checks</action>
+    <accuracy>Check @ references point to existing files</accuracy>
+    <completeness>Validate against XML schema, check required sections</completeness>
+    <consistency>XML format valid, naming conventions followed</consistency>
+    <timeliness>freshness_days = days_since(last_modified)</timeliness>
+    <validity>All @ references resolve, links work, XML well-formed</validity>
+    <uniqueness>Scan for duplicate content</uniqueness>
+  </step_3>
+  
+  <step_4>
+    <action>Calculate quality scores</action>
+    <formula>
+      accuracy_score: 0-5 (@ references valid)
+      completeness_score: 0-5 (% of required sections)
+      consistency_score: 0-5 (format compliance)
+      timeliness_score: 0-5 (freshness-based: 5 if <30d, 3 if <90d, 1 if >90d)
+      validity_score: 0-5 (link/reference validity)
+      uniqueness_score: 0-5 (no duplicates = 5)
+      
+      health_score = sum(all scores)
+      max_score = 30
+      
+      status:
+        - health_score >= 25: Healthy
+        - health_score 20-24: Warning
+        - health_score < 20: Action Required
+    </formula>
+  </step_4>
+  
+  <step_5>
+    <action>Update metadata-index.json (PRIMARY)</action>
+    <lock>Acquire metadata_update lock</lock>
+    <update>
+      - quality.health_score
+      - quality.accuracy_score (through uniqueness_score)
+      - quality.last_validated = now()
+    </update>
+    <also_update>Embedded XML metadata in file</also_update>
+    <unlock>Release lock</unlock>
+  </step_5>
+  
+  <step_6>
+    <action>Update indexes if health status changed</action>
+    <if>File moved from "healthy" to "warning"</if>
+    <update>metadata-index.json.indexes.by_health</update>
+  </step_6>
+  
+  <step_7>
+    <action>Generate quality report</action>
+    <save>governance/quality-reports/validation-{timestamp}.yaml</save>
+    <format>
+      file: path
+      health_score: int/30
+      status: healthy|warning|action_required
+      quality_dimensions: {dimension: score/5}
+      issues: [{dimension, severity, description}]
+      recommendations: [string]
+    </format>
+  </step_7>
+  
+  <step_8>
+    <action>Update request file with results</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <append>
+      processing_chain entry:
+      - agent: quality-validator
+      - action: validation_completed
+      - files_validated: count
+      - warnings: [list]
+    </append>
+  </step_8>
+</process_flow>
+
+<constraints>
+  <must>ALWAYS read request file first</must>
+  <must>Update metadata-index.json AND embedded XML</must>
+  <must>Acquire lock before updating metadata-index.json</must>
+  <must>Update request file with results</must>
+  <must_not>Update metadata without lock</must_not>
+  <must_not>Call other agents (no circular dependencies)</must_not>
+</constraints>
+```
+
+### 4.2 Lifecycle Manager Agent
+
+```xml
+---
+description: "Manages context file lifecycle transitions"
+mode: subagent
+temperature: 0.1
+---
+
+# Lifecycle Manager Agent
+
+<role>
+  Lifecycle Management Specialist. Moves files through lifecycle stages.
+  ALWAYS reads request file for context.
+</role>
+
+<task>
+  Move context files through lifecycle stages (CREATE → ACTIVE → 
+  REVIEW → ARCHIVE → DELETE) based on rules and thresholds.
+  Query metadata-index.json for fast lifecycle queries.
+</task>
+
+<process_flow>
+  <step_1>
+    <action>Read request file for context</action>
+    <file>tmp/context-requests/{request_id}.json OR workflow checkpoint</file>
+    <extract>
+      - Is this scheduled workflow or triggered?
+      - What's the priority?
+      - Can resume from checkpoint?
+    </extract>
+  </step_1>
+  
+  <step_2>
+    <action>Query metadata-index.json for lifecycle candidates</action>
+    <queries>
+      <review_needed>
+        WHERE next_review < today
+        OR freshness_days > 90
+        OR usage.access_count_90d < 5
+      </review_needed>
+      
+      <archive_candidate>
+        WHERE lifecycle.state = "active"
+        AND usage.access_count_90d = 0
+        AND freshness_days > 180
+      </archive_candidate>
+      
+      <delete_candidate>
+        WHERE lifecycle.state = "archived"
+        AND archived_date > 2 years ago
+      </delete_candidate>
+    </queries>
+    <note>Pure JSON queries - fast, no file I/O</note>
+  </step_2>
+  
+  <step_3>
+    <action>Process lifecycle transitions</action>
+    <for_each>candidate in candidates</for_each>
+    <transition>
+      - REVIEW: Notify owner, update next_review
+      - ARCHIVE: Move to archive/, update state in JSON+XML
+      - DELETE: Get approvals, backup, delete, update catalogs
+    </transition>
+    <checkpoint>Save progress to workflow checkpoint file after each file</checkpoint>
+  </step_3>
+  
+  <step_4>
+    <action>Update metadata-index.json for transitioned files</action>
+    <lock>Acquire lifecycle_manager lock</lock>
+    <update>
+      - lifecycle.state (active → review → archived → deleted)
+      - Update indexes.by_state
+      - Recalculate quality_summary
+    </update>
+    <unlock>Release lock</unlock>
+  </step_4>
+  
+  <step_5>
+    <action>Generate lifecycle report</action>
+    <save>governance/lifecycle-logs/lifecycle-{timestamp}.yaml</save>
+    <content>
+      - actions_taken: {reviewed, archived, deleted}
+      - files_needing_attention: [{file, reason, owner}]
+    </content>
+  </step_5>
+  
+  <step_6>
+    <action>Update request file or workflow checkpoint</action>
+    <write>tmp/context-requests/{request_id}.json</write>
+    <include>
+      - processing_chain entry
+      - result: lifecycle transitions completed
+    </include>
+  </step_6>
+</process_flow>
+
+<constraints>
+  <must>Read request file or workflow checkpoint first</must>
+  <must>Query metadata-index.json (not files)</must>
+  <must>Save checkpoint after each file (resumable)</must>
+  <must>Get owner approval before archiving Tier 1</must>
+  <must>Get owner + steward approval before delete</must>
+  <must>Update both JSON and XML metadata</must>
+  <must_not>Process without approval for critical actions</must_not>
+</constraints>
+```
+
+### 4.3 Metadata Updater Agent
+
+```xml
+---
+description: "Updates metadata automatically based on events"
+mode: subagent
+temperature: 0.1
+---
+
+# Metadata Updater Agent
+
+<role>
+  Metadata Management Specialist. Updates metadata-index.json (PRIMARY)
+  and embedded XML (SECONDARY) based on events.
+</role>
+
+<task>
+  Keep metadata current by updating based on events.
+  ALWAYS updates both JSON index and embedded XML.
+</task>
+
+<process_flow>
+  <step_1>
+    <action>Read event from request file</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <extract>
+      - event_type (file_accessed, file_modified, quality_check, etc.)
+      - file_path
+      - event_data (new values)
+    </extract>
+  </step_1>
+  
+  <step_2>
+    <action>Acquire metadata_update lock</action>
+    <check>workflow-state.json.locks.metadata_update</check>
+    <set>locked=true, locked_by=metadata-updater, locked_at=now()</set>
+  </step_2>
+  
+  <step_3>
+    <action>Load current metadata from JSON index</action>
+    <source>metadata-index.json.files[file_path]</source>
+    <fast>No file I/O, pure JSON read</fast>
+  </step_3>
+  
+  <step_4>
+    <action>Update metadata fields based on event</action>
+    <file_accessed>
+      - usage.access_count_30d += 1
+      - usage.access_count_90d += 1
+      - usage.last_accessed = now()
+    </file_accessed>
+    
+    <file_modified>
+      - admin.last_modified = now()
+      - admin.modified_by = event_data.modified_by
+      - quality scores reset (need re-validation)
+      - recalculate checksum
+    </file_modified>
+    
+    <quality_check_completed>
+      - quality.* = event_data.quality_scores
+      - quality.last_validated = now()
+    </quality_check_completed>
+  </step_4>
+  
+  <step_5>
+    <action>Update metadata-index.json (PRIMARY)</action>
+    <write>metadata-index.json.files[file_path]</write>
+    <also_update>
+      - metadata-index.json.last_updated = now()
+      - Recalculate indexes if needed (by_health, by_state)
+    </also_update>
+  </step_5>
+  
+  <step_6>
+    <action>Update embedded XML metadata in file (SECONDARY)</action>
+    <read>file</read>
+    <parse>Extract metadata block</parse>
+    <update>Update XML fields to match JSON</update>
+    <write>file (preserve content, only update metadata)</write>
+  </step_6>
+  
+  <step_7>
+    <action>Release lock</action>
+    <set>workflow-state.json.locks.metadata_update.locked=false</set>
+  </step_7>
+  
+  <step_8>
+    <action>Log update</action>
+    <write>governance/logs/changes.log</write>
+    <include>timestamp, file, event_type, changes_made</include>
+  </step_8>
+  
+  <step_9>
+    <action>Update request file with result</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <append>processing_chain entry: metadata updated</append>
+  </step_9>
+</process_flow>
+
+<constraints>
+  <must>ALWAYS acquire lock before updating</must>
+  <must>Update JSON index first (PRIMARY)</must>
+  <must>Update embedded XML second (SECONDARY)</must>
+  <must>Keep both in sync</must>
+  <must>Release lock even if error</must>
+  <must_not>Update without lock (race conditions)</must_not>
+  <must_not>Leave lock acquired if error</must_not>
+</constraints>
+```
+
+### 4.4 Catalog Maintainer Agent
+
+```xml
+---
+description: "Keeps CATALOG.md files synchronized with actual files"
+mode: subagent
+temperature: 0.1
+---
+
+# Catalog Maintainer Agent
+
+<role>
+  Catalog Management Specialist. Maintains CATALOG.md accuracy.
+  Uses metadata-index.json for fast file listing.
+</role>
+
+<task>
+  Ensure all CATALOG.md files are accurate and synchronized.
+  Query metadata-index.json for fast catalog generation.
+</task>
+
+<process_flow>
+  <step_1>
+    <action>Read request file</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <extract>Which folders to sync (all or specific)</extract>
+  </step_1>
+  
+  <step_2>
+    <action>Query metadata-index.json for files by folder</action>
+    <query>
+      SELECT file_path, classification.tags, admin.owner
+      FROM metadata-index.json.files
+      WHERE file_path LIKE "context/system-design/%"
+      ORDER BY file_path
+    </query>
+    <note>Fast JSON query, no file I/O needed</note>
+  </step_2>
+  
+  <step_3>
+    <action>Load current CATALOG.md</action>
+    <parse>Extract file listings table</parse>
+  </step_3>
+  
+  <step_4>
+    <action>Compare actual files vs CATALOG listings</action>
+    <find>
+      - Files in folder but not in CATALOG (add them)
+      - Files in CATALOG but not in folder (remove them)
+      - File descriptions outdated (update from metadata)
+    </find>
+  </step_4>
+  
+  <step_5>
+    <action>Update CATALOG.md</action>
+    <operations>
+      - Add missing files
+      - Remove deleted files
+      - Update descriptions from metadata-index.json
+      - Update "Last Updated" timestamp
+      - Sort alphabetically
+    </operations>
+  </step_5>
+  
+  <step_6>
+    <action>Verify MASTER-CATALOG.md consistency</action>
+    <check>Does MASTER-CATALOG reference all folder CATALOGs?</check>
+    <update>If new folders, update MASTER-CATALOG</update>
+  </step_6>
+  
+  <step_7>
+    <action>Generate sync report</action>
+    <save>governance/logs/catalog-sync-{timestamp}.yaml</save>
+    <content>
+      - catalogs_updated: count
+      - files_added: [list]
+      - files_removed: [list]
+      - inconsistencies_fixed: count
+    </content>
+  </step_7>
+  
+  <step_8>
+    <action>Update request file</action>
+    <file>tmp/context-requests/{request_id}.json</file>
+    <append>processing_chain: catalog sync completed</append>
+  </step_8>
+</process_flow>
+
+<constraints>
+  <must>Query metadata-index.json for file lists (fast)</must>
+  <must>Update CATALOG.md atomically</must>
+  <must>Maintain alphabetical sort</must>
+  <must_not>Parse all XML files (use JSON index)</must_not>
+</constraints>
+```
+
+---
+
+## Step 5: Automated Quality & Lifecycle Workflows
+
+### Unified Workflow Manager
+
+**Single State Machine** instead of multiple separate schedules.
+
+**Location**: `.opencode/governance/workflow-state.json`
+
+```json
+{
+  "workflows": {
+    "maintenance": {
+      "schedule": "0 2 * * *",
+      "enabled": true,
+      "last_run": "2025-10-09T02:00:00Z",
+      "next_run": "2025-10-10T02:00:00Z",
+      "status": "idle",
+      "tasks": {
+        "daily_quality_sample": {
+          "frequency": "daily",
+          "enabled": true,
+          "last_run": "2025-10-09T02:00:00Z",
+          "duration_seconds": 45
+        },
+        "weekly_lifecycle_review": {
+          "frequency": "weekly",
+          "day": "sunday",
+          "enabled": true,
+          "last_run": "2025-10-08T03:00:00Z",
+          "status": "idle"
+        },
+        "monthly_deep_audit": {
+          "frequency": "monthly",
+          "day": 1,
+          "enabled": true,
+          "last_run": "2025-10-01T04:00:00Z",
+          "status": "idle"
+        }
+      }
+    }
+  },
+  
+  "locks": {
+    "metadata_update": {
+      "locked": false,
+      "locked_by": null,
+      "locked_at": null
+    },
+    "workflow_execution": {
+      "locked": false,
+      "locked_by": null,
+      "locked_at": null
+    }
+  }
+}
+```
+
+### Workflow Execution
+
+```yaml
+Workflow: Unified Maintenance (Daily 2:00 AM)
+
+1. Check workflow-state.json:
+   - Acquire workflow_execution lock
+   - Check which tasks need to run today
+   
+2. For each task that needs running:
+   a. Check if previous run was "in_progress"
+   b. If yes: Load checkpoint file, resume from last position
+   c. If no: Start fresh
+   
+3. Execute task:
+   a. Create tmp/context-requests/workflow-{task_id}-{date}.json
+   b. Call appropriate agent with request_id
+   c. Save checkpoint after each major step
+   d. Update workflow-state.json.workflows.maintenance.tasks[task].status
+   
+4. On completion:
+   a. Update workflow-state.json
+   b. Generate combined report
+   c. Clean up tmp files (or archive)
+   d. Release lock
+   
+5. On error/interruption:
+   a. Save checkpoint
+   b. Set status = "in_progress"
+   c. Can resume next run
+```
+
+### Daily Tasks
+
+```yaml
+Task: daily_quality_sample
+
+Frequency: Every day
+Duration: ~45 seconds
+Agent: quality-validator
+
+Process:
+  1. Create request file: tmp/context-requests/daily-quality-{date}.json
+  2. Query metadata-index.json:
+     - SELECT random 10% of files
+     - Prioritize files not validated in 7+ days
+  3. Call quality-validator with request_id
+  4. Quality validator:
+     - Reads request file
+     - Validates files
+     - Updates metadata-index.json
+     - Updates request file with results
+  5. Check results:
+     - Any files with health_score < 20? → Alert owner
+     - Any broken @ references? → Alert steward
+     - Overall health < 80%? → Alert admin
+  6. Generate daily report
+  7. Update workflow-state.json
+```
+
+### Weekly Tasks
+
+```yaml
+Task: weekly_lifecycle_review
+
+Frequency: Every Sunday
+Duration: ~5 minutes
+Agent: lifecycle-manager
+
+Process:
+  1. Create request file: tmp/context-requests/weekly-lifecycle-{date}.json
+  2. Query metadata-index.json for lifecycle candidates:
+     - Files where next_review < today
+     - Files with freshness_days > 90
+     - Files with usage.access_count_90d < 5
+     - Temp files created > 90 days ago
+  3. Call lifecycle-manager with request_id
+  4. Lifecycle manager:
+     - Reads request file
+     - Queries JSON index (fast)
+     - Processes transitions
+     - Saves checkpoint after each file
+     - Updates metadata-index.json
+     - Updates request file with results
+  5. Generate weekly report with action items
+  6. Notify owners
+  7. Update workflow-state.json
+```
+
+### Monthly Tasks
+
+```yaml
+Task: monthly_deep_audit
+
+Frequency: First day of month
+Duration: ~30 minutes
+Agent: quality-validator, catalog-maintainer
+
+Process:
+  1. Create request file: tmp/context-requests/monthly-audit-{date}.json
+  2. Deep quality audit:
+     a. Call quality-validator with ALL files (100%)
+     b. Validate everything thoroughly
+     c. Update metadata-index.json
+     d. Generate comprehensive quality report
+  3. Full catalog sync:
+     a. Call catalog-maintainer for ALL folders
+     b. Verify all CATALOG.md files
+     c. Fix inconsistencies
+     d. Update MASTER-CATALOG if needed
+  4. Metadata cleanup:
+     a. Verify JSON index matches embedded XML (sample 20%)
+     b. Fix any discrepancies
+     c. Standardize tag taxonomy
+  5. Generate monthly health dashboard
+  6. Update workflow-state.json
+```
+
+### Resumable Workflows with Checkpoints
+
+**Example: Weekly lifecycle review interrupted halfway**
+
+```json
+// workflow-state.json
+{
+  "workflows": {
+    "maintenance": {
+      "tasks": {
+        "weekly_lifecycle_review": {
+          "status": "in_progress",
+          "checkpoint_file": "tmp/workflow-checkpoints/weekly-lifecycle-2025-10-08.json"
+        }
+      }
+    }
+  }
+}
+
+// tmp/workflow-checkpoints/weekly-lifecycle-2025-10-08.json
+{
+  "workflow_id": "weekly-lifecycle-2025-10-08",
+  "started": "2025-10-08T03:00:00Z",
+  "current_stage": "review_transitions",
+  "files_processed": 45,
+  "files_total": 65,
+  "current_file": "context/services/payment-service.md",
+  "results_so_far": {
+    "files_needing_review": 5,
+    "archive_candidates": 3,
+    "temp_expiring": 2
+  }
+}
+```
+
+**Next run (Sunday following week)**:
+```
+1. Check workflow-state.json
+2. See weekly_lifecycle_review status = "in_progress"
+3. Load checkpoint file
+4. Resume from current_file = "context/services/payment-service.md"
+5. Process remaining 20 files
+6. Complete workflow
+7. Update status = "completed"
+8. Delete checkpoint file
+```
+
+---
+
+## Step 6: Metadata Management
+
+### Metadata Synchronization
+
+**PRIMARY**: metadata-index.json (Fast queries, source of truth for queries)
+**SECONDARY**: Embedded XML (Travels with file, backup, source of truth for sync)
+
+### Write Operation (Human or Agent Updates File)
+
+```
+1. Update embedded XML metadata in file
+   └─ Parse file, update <metadata> block
+   
+2. Calculate checksum
+   └─ sha256(file_content)
+   
+3. Acquire metadata_update lock
+   └─ workflow-state.json.locks.metadata_update = locked
+   
+4. Update metadata-index.json
+   ├─ Update files[path] entry
+   ├─ Recalculate indexes if needed
+   └─ Update last_updated timestamp
+   
+5. Write both atomically
+   ├─ Write file (embedded XML)
+   └─ Write metadata-index.json
+   
+6. Release lock
+   └─ workflow-state.json.locks.metadata_update = unlocked
+```
+
+### Query Operation (Agent Needs Metadata)
+
+```
+1. Query metadata-index.json
+   └─ Pure JSON query, no file I/O
+   
+2. Return results
+   └─ Instant (no parsing, no disk reads)
+   
+Example queries:
+- "All Tier 1 files" → indexes.by_tier["1"] (instant)
+- "Files needing review" → indexes.by_state["review"] (instant)
+- "Health summary" → quality_summary (instant)
+- "Files tagged 'authentication'" → indexes.by_tag["authentication"] (instant)
+```
+
+### Nightly Sync Job
+
+```
+Task: metadata_sync
+Frequency: Every night at 4:00 AM
+Duration: ~2 minutes
+
+Process:
+  1. Scan all context files
+  2. For each file:
+     a. Parse embedded XML metadata
+     b. Calculate checksum
+     c. Compare with metadata-index.json entry
+     d. If mismatch:
+        - Log discrepancy
+        - FILE WINS (embedded XML is source of truth)
+        - Update metadata-index.json from file
+  3. Recalculate all indexes
+  4. Update sync_status in metadata-index.json
+  5. Generate sync report
+  6. If discrepancies found: Alert admin
+```
+
+### Conflict Resolution
+
+**Rule**: Embedded XML (in file) ALWAYS wins on conflict.
+
+```
+Scenario: metadata-index.json says health_score=25, 
+          but file says health_score=22
+
+Resolution:
+  1. Nightly sync detects mismatch
+  2. File wins (embedded XML = source of truth)
+  3. Update metadata-index.json to health_score=22
+  4. Log: "Synced storage.md: health_score 25→22 from file"
+  5. Alert: "Metadata out of sync, resolved from files"
+```
+
+---
+
+## Complete Workflow Examples
+
+### Example 1: User Requests Feature, Needs Context
+
+```
+1. User: "Add password reset to user service"
+   ↓
+2. Main Orchestrator:
+   - Analyzes request
+   - Extracts keywords: password, reset, authentication, user
+   - Creates tmp/context-requests/req-abc123.json:
+     {
+       "request_id": "req-abc123",
+       "task_context": {
+         "description": "Add password reset feature",
+         "user_request": "Add password reset to user service",
+         "keywords": ["password", "reset", "authentication", "user"],
+         "priority": "normal"
+       }
+     }
+   ↓
+3. Main Orchestrator → Context Manager:
+   - Calls: get_context(request_id="req-abc123")
+   ↓
+4. Context Manager:
+   a. Reads tmp/context-requests/req-abc123.json (FULL CONTEXT)
+   b. Queries metadata-index.json.indexes.by_tag["authentication"] (FAST)
+   c. Finds: authentication.md, security.md, user-service.md
+   d. Queries metadata-index.json for health scores (FAST)
+   e. All files healthy, proceed
+   f. Loads file content (only now - after metadata queries)
+   g. Updates metadata-index.json.files[*].usage.access_count_30d
+   h. Updates tmp/context-requests/req-abc123.json:
+      {
+        "processing_chain": [
+          {"agent": "context-manager", "action": "located_files", "count": 3}
+        ],
+        "result": {
+          "status": "completed",
+          "files_returned": ["authentication.md", "security.md", "user-service.md"],
+          "warnings": [],
+          "estimated_tokens": 1200
+        }
+      }
+   ↓
+5. Main Orchestrator:
+   - Reads tmp/context-requests/req-abc123.json for results
+   - Routes to Feature Build Agent with context
+   ↓
+6. Feature Build Agent:
+   - Uses context to build feature
+   ↓
+7. PR Created, Approved, Merged
+   ↓
+8. Main Orchestrator → Context Manager:
+   - Creates tmp/context-requests/update-def456.json
+   - Calls: update_context_after_pr(request_id="update-def456", pr_number="PR-456", ...)
+   ↓
+9. Context Manager:
+   a. Reads tmp/context-requests/update-def456.json
+   b. Analyzes diff: authentication logic added
+   c. Updates authentication.md (embedded XML + content)
+   d. Acquires metadata_update lock
+   e. Updates metadata-index.json (PRIMARY)
+   f. Releases lock
+   g. Triggers quality-validator (async, with request_id)
+   h. Updates tmp/context-requests/update-def456.json with results
+   ↓
+10. Done: Context up-to-date, ready for next request
+
+TOTAL TIME: < 2 seconds (thanks to JSON index)
+NO CONTEXT LOSS: All agents read same request file
+RESUMABLE: Checkpoint files allow recovery from failures
+DEBUGGABLE: Full audit trail in request file
+```
+
+### Example 2: Scheduled Maintenance (Weekly)
+
+```
+1. Sunday 2:00 AM: Unified maintenance workflow triggers
+   ↓
+2. Workflow Manager:
+   - Checks workflow-state.json
+   - Sees weekly_lifecycle_review needs to run
+   - Creates tmp/context-requests/weekly-lifecycle-2025-10-15.json
+   ↓
+3. Calls lifecycle-manager with request_id="weekly-lifecycle-2025-10-15"
+   ↓
+4. Lifecycle Manager:
+   a. Reads tmp/context-requests/weekly-lifecycle-2025-10-15.json
+   b. Queries metadata-index.json for lifecycle candidates:
+      - WHERE next_review < today → 5 files
+      - WHERE freshness_days > 90 → 3 files
+      - WHERE usage.access_count_90d < 5 → 2 files
+      - Total: 10 files to process
+   c. Creates checkpoint: tmp/workflow-checkpoints/weekly-lifecycle-2025-10-15.json
+   d. Processes each file:
+      - File 1: Notify owner for review
+      - File 2: Flag as archive candidate
+      - ... (saves checkpoint after each)
+   e. Acquires lock, updates metadata-index.json
+   f. Releases lock
+   g. Updates tmp/context-requests/weekly-lifecycle-2025-10-15.json:
+      {
+        "result": {
+          "files_reviewed": 5,
+          "archive_candidates": 3,
+          "temp_expiring": 2
+        }
+      }
+   ↓
+5. Workflow Manager:
+   - Reads results from request file
+   - Generates weekly governance report
+   - Emails admin with action items
+   - Updates workflow-state.json:
+     - weekly_lifecycle_review.status = "completed"
+     - weekly_lifecycle_review.last_run = "2025-10-15T02:00:00Z"
+   - Cleans up checkpoint file
+   ↓
+6. Done: System maintained, no user involvement
+
+TOTAL TIME: ~5 minutes
+RESUMABLE: If interrupted, resumes from checkpoint next run
+NO XML PARSING: All queries from metadata-index.json (fast)
+```
+
+---
+
+## Keeping It Simple
+
+### Design Philosophy
+
+**Complexity Hidden, Interface Simple**
+
+```
+┌────────────────────────────────────────────────────────┐
+│            USER / MAIN ORCHESTRATOR                    │
+│                                                        │
+│  Simple Interface:                                     │
+│  - get_context(request_id, task_description)          │
+│  - update_context_after_pr(request_id, pr_data)       │
+│  - get_system_health()                                │
+│                                                        │
+│  Creates: tmp/context-requests/{request_id}.json      │
+│  Returns: Results from that file                      │
+│                                                        │
+└────────────────┬───────────────────────────────────────┘
+                 │
+                 │  Simple interface hides complexity ↓
+                 │
+┌────────────────▼───────────────────────────────────────┐
+│         CONTEXT MANAGEMENT AGENT                       │
+│                                                        │
+│  Handles:                                              │
+│  - Reads request file (full context)                   │
+│  - Queries metadata-index.json (fast)                 │
+│  - Routes to subagents with request_id                │
+│  - Updates request file with results                   │
+│                                                        │
+└────────────────┬───────────────────────────────────────┘
+                 │
+         ┌───────┴────────┬────────────┬──────────────┐
+         │                │            │              │
+    ┌────▼────┐   ┌──────▼──┐   ┌────▼─────┐   ┌───▼──────┐
+    │ Quality │   │Lifecycle│   │ Metadata │   │ Catalog  │
+    │Validator│   │ Manager │   │ Updater  │   │Maintainer│
+    └─────────┘   └─────────┘   └──────────┘   └──────────┘
+         ↑              ↑              ↑              ↑
+         └──────────────┴──────────────┴──────────────┘
+      All read same request file → NO CONTEXT LOSS
+      All query metadata-index.json → FAST
+      All update request file → AUDIT TRAIL
+```
+
+### Key Simplifications
+
+**1. No Context Loss**
+- Every agent call includes request_id
+- Request ID points to tmp file with FULL context
+- No implicit assumptions
+- No lazy parameter passing
+
+**2. Fast Queries**
+- Query metadata-index.json (JSON), not files (XML)
+- Most queries < 10ms (pure JSON, no I/O)
+- Load file content only when needed
+
+**3. Resumable Workflows**
+- Checkpoint files save progress
+- Workflow can resume from any point
+- No lost work on interruption
+
+**4. Clear Ownership**
+- metadata-index.json = PRIMARY (queries)
+- Embedded XML = SECONDARY (backup, sync source)
+- File always wins on conflict
+
+**5. No Circular Dependencies**
+- Context Manager → Subagents (one way)
+- Subagents NEVER call each other
+- Subagents NEVER call Context Manager
+- Clean hierarchy
+
+### What Makes It Simple
+
+**For Main Orchestrator**:
+```
+1. Create request file with task context
+2. Call Context Manager with request_id
+3. Read results from request file
+4. Done
+
+NO NEED TO KNOW:
+- How metadata is stored
+- How quality is checked
+- How lifecycle works
+- How agents communicate
+```
+
+**For Subagents**:
+```
+1. Receive request_id
+2. Read tmp/context-requests/{request_id}.json
+3. Have FULL context (no guessing)
+4. Do work
+5. Update request file with results
+6. Done
+
+NO NEED TO KNOW:
+- What other agents are doing
+- How to coordinate with others
+- Complex state management
+```
+
+**For Debugging**:
+```
+1. Check tmp/context-requests/{request_id}.json
+2. See full processing_chain
+3. See exactly what happened
+4. See any errors
+5. Done
+
+EASY TO DEBUG:
+- Full audit trail in one file
+- Timestamps for each step
+- Clear agent ownership
+- No implicit state
+```
+
+---
+
+## Summary
+
+### What We Built
+
+A **simple, robust Data Governance Agent System** that:
+
+✅ **No Context Loss**: Explicit context passing via tmp files  
+✅ **Fast Queries**: JSON metadata index (no XML parsing)  
+✅ **Resumable Workflows**: Checkpoint files for long-running tasks  
+✅ **Clear Communication**: Request files with full audit trail  
+✅ **No Circular Dependencies**: Clean agent hierarchy  
+✅ **Debuggable**: Full processing chain in request files  
+✅ **Simple Integration**: 3 function calls from main orchestrator  
+
+### Key Innovations
+
+1. **Dual Metadata System**: JSON (fast queries) + XML (backup, sync)
+2. **Explicit Context Passing**: Tmp files eliminate information loss
+3. **State Machine Workflows**: Resumable, debuggable, simple
+4. **Request ID Protocol**: Every agent has full context
+5. **Lock-Based Concurrency**: Prevent race conditions on metadata updates
+
+### Architecture Highlights
+
+```
+SIMPLE:
+- Main orchestrator: 3 function calls
+- Create request file, call agent, read result
+- That's it!
+
+FAST:
+- Query JSON index (< 10ms)
+- No XML parsing for queries
+- Load files only when needed
+
+ROBUST:
+- No context loss (explicit passing)
+- Resumable workflows (checkpoints)
+- Atomic updates (locks)
+- Full audit trail (request files)
+
+DEBUGGABLE:
+- One file per request
+- Full processing chain
+- Clear timestamps
+- Easy to trace
+```
+
+### Next Steps
+
+1. Create directory structure
+2. Create metadata-index.json template
+3. Create workflow-state.json template
+4. Build Context Management Agent
+5. Build 4 governance subagents
+6. Create nightly sync job
+7. Test with real scenarios
+8. Monitor and refine
+
+**Result**: Simple, fast, robust context governance system with ZERO context loss.

.Building/UNIFIED-ARCHITECTURE.md

@@ -0,0 +1,641 @@
+# Unified Architecture: NexusAgent
+**Combining Context-Aware Orchestration + Data Governance**
+
+---
+
+## Overview
+
+**NexusAgent** is a universal AI agent orchestration system that combines:
+1. **Context-Aware Orchestration** - Hierarchical agent systems with dynamic context loading
+2. **Data Governance** - Managing context as data with quality, lifecycle, and metadata
+
+This creates a system where:
+- Agents intelligently route work based on complexity
+- Context is treated as governed data assets
+- Everything is modular, installable, and customizable
+- Works with any AI tool (OpenCode, Cursor, Claude, etc.)
+
+---
+
+## Core Architecture Principles
+
+### 1. **Dual-Layer System**
+
+```
+┌────────────────────────────────────────────────────────┐
+│                ORCHESTRATION LAYER                      │
+│  • Hierarchical agent routing                          │
+│  • Dynamic context allocation (3 levels)               │
+│  • Workflow management                                 │
+│  • Request analysis and complexity assessment          │
+└────────────────┬───────────────────────────────────────┘
+                 │
+                 ↓ Uses context from ↓
+┌────────────────────────────────────────────────────────┐
+│                GOVERNANCE LAYER                         │
+│  • Context quality management                          │
+│  • Metadata indexing (JSON primary)                    │
+│  • Lifecycle management (CREATE → ARCHIVE)             │
+│  • Automated validation workflows                      │
+└────────────────────────────────────────────────────────┘
+```
+
+### 2. **Three Context Levels** (From Building Context-Aware Systems)
+
+```yaml
+Level 1 - Complete Isolation (80% of cases):
+  Context: Task description only
+  Performance: 80% overhead reduction
+  Governance: No metadata queries needed
+  
+Level 2 - Filtered Context (15% of cases):
+  Context: Task + relevant domain knowledge
+  Performance: 60% overhead reduction  
+  Governance: Query metadata index for relevant files
+  
+Level 3 - Full Context (5% of cases):
+  Context: Task + domain + historical state
+  Performance: Optimized for accuracy
+  Governance: Full metadata + quality validation
+```
+
+### 3. **Request ID Protocol** (From Data Governance)
+
+Every agent interaction uses explicit context passing:
+
+```yaml
+1. Orchestrator creates: tmp/requests/req-{uuid}.json
+2. Orchestrator passes: request_id to subagent
+3. Subagent reads: tmp/requests/req-{uuid}.json (FULL CONTEXT)
+4. Subagent updates: processing_chain in request file
+5. Orchestrator reads: Results from request file
+
+Benefits:
+  ✅ No context loss between agents
+  ✅ Full audit trail
+  ✅ Resumable workflows
+  ✅ Easy debugging
+```
+
+### 4. **Metadata-Driven Context** (From Data Governance)
+
+```yaml
+PRIMARY: metadata-index.json
+  • Fast queries (< 10ms)
+  • Indexed by: tier, tag, health, state
+  • No file I/O for metadata lookups
+
+SECONDARY: Embedded XML in files
+  • Travels with content
+  • Source of truth for sync
+  • File always wins on conflict
+  
+Sync: Nightly reconciliation job
+```
+
+---
+
+## Universal Folder Structure
+
+This structure works for ANY domain (content, code, data, support, etc.):
+
+```
+~/nexus/                          # Base installation
+├── config.yml                    # User configuration
+├── profiles/                     # Pre-built + custom profiles
+│   ├── default/                 # Basic orchestration
+│   ├── governance/              # Data governance
+│   ├── content/                 # Content creation
+│   └── custom/                  # User-created
+├── scripts/
+│   ├── base-install.sh
+│   ├── project-install.sh
+│   └── lib/
+└── templates/
+
+# After project installation:
+your-project/
+└── .nexus/                       # or .opencode, .ai, etc.
+    ├── agent/
+    │   ├── main-orchestrator.md
+    │   ├── context-provider.md   # Intelligent context selection
+    │   └── subagents/
+    │       ├── specialist-a.md
+    │       └── specialist-b.md
+    │
+    ├── command/                  # Slash commands
+    │   ├── workflow.md
+    │   └── execute.md
+    │
+    ├── context/                  # Domain knowledge
+    │   ├── core/
+    │   ├── domain/
+    │   ├── processes/
+    │   ├── standards/
+    │   └── workflows/
+    │
+    ├── governance/               # Context governance
+    │   ├── metadata-index.json   # PRIMARY metadata
+    │   ├── workflow-state.json   # Workflow state machine
+    │   ├── tmp/                  # Inter-agent communication
+    │   │   └── requests/         # Request context files
+    │   └── logs/                 # Audit trails
+    │
+    └── nexus.json                # Project configuration
+```
+
+---
+
+## Key Components
+
+### 1. Main Orchestrator (Context-Aware)
+
+**Responsibilities:**
+- Analyze request complexity
+- Determine context level (1, 2, or 3)
+- Route to appropriate specialists
+- Coordinate multi-agent workflows
+- Integrate results
+
+**Template Structure:**
+```xml
+---
+description: "Main orchestrator with context-aware routing"
+mode: primary
+temperature: 0.2
+---
+
+<context>
+  <system_context>[Your domain]</system_context>
+</context>
+
+<role>
+  Primary orchestrator specializing in [domain] with intelligent
+  context allocation and multi-agent coordination
+</role>
+
+<task>
+  Transform requests into outcomes by analyzing complexity,
+  allocating appropriate context, and routing to specialists
+</task>
+
+<workflow name="IntelligentRouting">
+  <stage_1_analyze>
+    <action>Assess request complexity</action>
+    <decision>
+      <simple>Context Level 1 - Direct execution</simple>
+      <moderate>Context Level 2 - Route to @context-provider</moderate>
+      <complex>Context Level 3 - Full coordination</complex>
+    </decision>
+  </stage_1_analyze>
+  
+  <stage_2_context>
+    <level_1>Task description only</level_1>
+    <level_2>
+      <create_request>tmp/requests/req-{uuid}.json</create_request>
+      <route>@context-provider with request_id</route>
+      <load>Files returned by context-provider</load>
+    </level_2>
+    <level_3>
+      <create_request>tmp/requests/req-{uuid}.json</create_request>
+      <route>@context-manager for governance</route>
+      <load>Full validated context</load>
+    </level_3>
+  </stage_2_context>
+  
+  <stage_3_execute>
+    <route_to_specialists>With explicit context</route_to_specialists>
+    <update_request_file>Progress tracking</update_request_file>
+  </stage_3_execute>
+</workflow>
+```
+
+### 2. Context Provider (Intelligent Selection)
+
+**Responsibilities:**
+- Analyze request to determine context needs
+- Select relevant context files
+- Return file paths (not contents)
+- Optimize for minimal cognitive load
+
+**Key Logic:**
+```yaml
+analyze_request:
+  complexity: simple | moderate | complex
+  domain: [domain keywords]
+  integrations: [external systems]
+  
+determine_context_level:
+  if complexity_score <= 3:
+    return Level 1 (no files)
+  if complexity_score <= 7:
+    return Level 2 (filtered files)
+  else:
+    return Level 3 (full context + governance)
+    
+select_files:
+  base: [core/essential.md]
+  domain: [based on keywords]
+  processes: [based on workflow type]
+  standards: [if validation needed]
+  
+return:
+  context_level: 2
+  file_locations: [array of paths]
+  estimated_tokens: 1500
+```
+
+### 3. Context Manager (Governance)
+
+**Responsibilities:**
+- Retrieve context with quality checks
+- Update metadata after use
+- Coordinate lifecycle transitions
+- Validate context health
+
+**Integration with Orchestrator:**
+```yaml
+# Orchestrator creates request
+orchestrator:
+  request_id: req-abc123
+  creates: tmp/requests/req-abc123.json
+  calls: @context-manager get_context(request_id)
+  
+# Context Manager processes
+context_manager:
+  reads: tmp/requests/req-abc123.json
+  queries: metadata-index.json (FAST)
+  checks: health_score, timeliness, validity
+  loads: file content (only if quality good)
+  updates: access_count in metadata-index.json
+  writes: tmp/requests/req-abc123.json (results)
+  
+# Orchestrator reads results
+orchestrator:
+  reads: tmp/requests/req-abc123.json
+  gets: files_returned, warnings, estimated_tokens
+```
+
+### 4. Specialized Subagents
+
+**Design Principles:**
+- Single responsibility
+- Stateless (no memory between calls)
+- Complete explicit instructions
+- Always read request file first
+
+**Template:**
+```xml
+---
+description: "[Specific task]"
+mode: subagent
+temperature: 0.1
+---
+
+<inputs_required>
+  <parameter name="request_id" type="string">
+    UUID pointing to tmp/requests/{request_id}.json
+  </parameter>
+</inputs_required>
+
+<process_flow>
+  <step_1>
+    <action>Read request file</action>
+    <file>tmp/requests/{request_id}.json</file>
+    <extract>Full context for this task</extract>
+  </step_1>
+  
+  <step_2>
+    <action>Perform specialized task</action>
+  </step_2>
+  
+  <step_3>
+    <action>Update request file</action>
+    <append>Processing chain entry</append>
+  </step_3>
+</process_flow>
+```
+
+---
+
+## Profile System
+
+### Profile: Default (Context-Aware Orchestration)
+
+**Purpose:** Basic hierarchical orchestration for any domain
+
+**Includes:**
+```yaml
+agents:
+  - main-orchestrator.md          # Intelligent routing
+  - context-provider.md            # Context selection
+  - task-planner.md                # Multi-step planning
+  - subagents/
+    - code-reviewer.md
+    - test-writer.md
+    - doc-writer.md
+    
+commands:
+  - workflow.md                    # Main entry point
+  - plan-task.md                   # Complex tasks
+  - execute-task.md                # Step execution
+  
+context:
+  - core/essential-patterns.md     # Always loaded
+  - architecture/project-structure.md
+  - workflows/simple-task.md
+  - workflows/complex-feature.md
+  
+governance: (minimal)
+  - metadata-index.json (basic)
+  - No automated workflows
+```
+
+### Profile: Governance (Data Management)
+
+**Purpose:** Full data governance for context management
+
+**Includes:**
+```yaml
+agents:
+  - main-orchestrator.md           # Routes to governance
+  - governance/
+    - context-manager.md           # Primary governance
+    - subagents/
+      - quality-validator.md
+      - lifecycle-manager.md
+      - metadata-updater.md
+      - catalog-maintainer.md
+      
+commands:
+  - get-context.md                 # Retrieve with quality check
+  - update-context.md              # Update after changes
+  - validate-quality.md            # Quality validation
+  - lifecycle-review.md            # Lifecycle management
+  
+context:
+  - governance/
+    - metadata-schema.md
+    - quality-dimensions.md
+    - lifecycle-states.md
+  - workflows/
+    - context-retrieval.md
+    - quality-validation.md
+    
+governance: (full)
+  - metadata-index.json (PRIMARY)
+  - workflow-state.json
+  - Automated daily/weekly/monthly workflows
+  - Nightly sync job
+  - Full audit logging
+```
+
+### Profile: Content (Content Orchestration)
+
+**Purpose:** Content creation with platform optimization
+
+**Combines both systems:**
+```yaml
+agents:
+  # Orchestration layer
+  - content-orchestrator.md
+  - context-provider.md
+  
+  # Content specialists
+  - subagents/
+    - twitter-specialist.md
+    - linkedin-specialist.md
+    - research-assistant.md
+    - content-validator.md
+    
+commands:
+  - create-content.md
+  - new-project.md
+  - validate.md
+  
+context:
+  # Domain knowledge
+  - brand/voice.md
+  - platforms/twitter/specs.md
+  - workflows/multi-platform.md
+  
+  # Governance for context
+  - governance/ (from governance profile)
+  
+governance:
+  - Full metadata management
+  - Content lifecycle tracking
+  - Quality validation
+```
+
+---
+
+## Installation Flow
+
+### Base Installation
+
+```bash
+# One command
+curl -sSL https://nexus.nextsystems.ai/install.sh | bash
+
+# What it does:
+1. Creates ~/nexus/
+2. Downloads all profiles
+3. Creates config.yml
+4. Makes scripts executable
+5. Shows quick start guide
+```
+
+### Project Installation
+
+```bash
+# Navigate to project
+cd /path/to/your/project
+
+# Install with profile
+~/nexus/scripts/project-install.sh --profile governance
+
+# What it does:
+1. Analyzes which profile to use
+2. Creates .nexus/ folder
+3. Copies agents, commands, context from profile
+4. Sets up governance/ if needed
+5. Creates nexus.json configuration
+6. Shows next steps
+```
+
+### Configuration
+
+```yaml
+# ~/nexus/config.yml
+defaults:
+  profile: default
+  ai_tool: opencode
+  context_level: 2
+  enable_governance: false
+  
+profiles:
+  governance:
+    enable_governance: true
+    metadata_sync: "0 4 * * *"
+    quality_workflows: true
+    
+  content:
+    enable_governance: true
+    context_level: 2
+    enable_research: true
+```
+
+---
+
+## How It All Works Together
+
+### Example: Simple Request (Level 1)
+
+```yaml
+User: "Format this data according to spec"
+
+Orchestrator:
+  analyze: Simple formatting task
+  complexity: Low (score: 2)
+  context_level: 1
+  
+  execute_directly:
+    - Load spec from context/standards/
+    - Format data
+    - Return result
+    
+  no_governance: No metadata queries needed
+  
+Result: Fast execution (< 1 second)
+```
+
+### Example: Moderate Request (Level 2)
+
+```yaml
+User: "Create LinkedIn post about our product"
+
+Orchestrator:
+  analyze: Content creation, needs brand alignment
+  complexity: Moderate (score: 5)
+  context_level: 2
+  
+  create_request: tmp/requests/req-abc123.json
+  
+  route_to_context_provider:
+    request_id: req-abc123
+    
+  context_provider_returns:
+    files:
+      - context/brand/voice.md
+      - context/platforms/linkedin/specs.md
+      - context/platforms/linkedin/patterns.md
+    estimated_tokens: 800
+    
+  route_to_specialist:
+    agent: @linkedin-specialist
+    request_id: req-abc123
+    
+  linkedin_specialist:
+    reads: tmp/requests/req-abc123.json
+    loads: Context files listed
+    creates: LinkedIn post
+    updates: Request file with results
+    
+  orchestrator_reads: tmp/requests/req-abc123.json
+  cleanup: Delete temp file
+  
+Result: Quality content (< 10 seconds)
+```
+
+### Example: Complex Request (Level 3)
+
+```yaml
+User: "Update authentication docs after security PR merge"
+
+Orchestrator:
+  analyze: Needs governance, quality validation, catalog updates
+  complexity: High (score: 9)
+  context_level: 3
+  
+  create_request: tmp/requests/update-def456.json
+  
+  route_to_context_manager:
+    method: update_context_after_pr
+    request_id: update-def456
+    pr_data: [PR info]
+    
+  context_manager:
+    reads: tmp/requests/update-def456.json
+    analyzes: What context files need updates
+    
+    updates_files:
+      - context/system-design/authentication.md
+    
+    updates_metadata:
+      - Embedded XML in file
+      - metadata-index.json (PRIMARY)
+      - Recalculates indexes
+      
+    routes_to_quality_validator:
+      request_id: update-def456
+      
+    routes_to_catalog_maintainer:
+      request_id: update-def456
+      
+    writes: tmp/requests/update-def456.json (results)
+    
+  orchestrator_reads: Results
+  cleanup: Archive request file for audit
+  
+Result: Governed update with quality validation (< 30 seconds)
+```
+
+---
+
+## Benefits of This Architecture
+
+### 1. **Universal Applicability**
+- Works for any domain (code, content, data, support, etc.)
+- Profiles customize for specific use cases
+- Same architecture, different knowledge
+
+### 2. **Intelligent Context Management**
+- 3-level system prevents overload
+- Metadata-driven fast queries
+- Quality validation built-in
+
+### 3. **No Context Loss**
+- Request ID protocol
+- Explicit context passing
+- Full audit trail
+
+### 4. **Governance When Needed**
+- Optional governance layer
+- Automated quality workflows
+- Lifecycle management
+
+### 5. **Easy to Install and Use**
+- One-command installation
+- Pre-built profiles
+- Clear documentation
+
+### 6. **Debuggable and Resumable**
+- Request files show full processing chain
+- Checkpoint files for long workflows
+- Easy troubleshooting
+
+---
+
+## Next: Implementation
+
+With this unified architecture, we can now build:
+
+1. ✅ **Base installation script** - Installs ~/nexus/
+2. ✅ **Project installation script** - Installs .nexus/ into projects
+3. ✅ **Default profile** - Context-aware orchestration
+4. ✅ **Governance profile** - Full data governance
+5. ✅ **Content profile** - Combines both for content creation
+6. ✅ **Documentation** - Clear guides and examples
+
+**Ready to start building?** Let me know which name you want to use (NexusAgent or MindStack) and I'll create the complete system!

.Building/planning/ARCHITECTURE-REVIEW.md

@@ -0,0 +1,471 @@
+# 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/` ✅<br>`.nexusagent/context/` ✅<br>`.opencode/command/` ✅ | ✅ ALIGNED |
+| **XML Prompt Structure** | Context → Role → Task → Instructions → Output | Agent templates use this | ✅ ALIGNED |
+| **3-Level Context System** | Level 1: Isolated<br>Level 2: Filtered<br>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
+
+```yaml
+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`:**
+
+```markdown
+# 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**
+   ```bash
+   #!/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:**
+```markdown
+<!-- .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.

.Building/planning/BUILD-PLAN.md

@@ -0,0 +1,53 @@
+# NexusAgent - Build Plan
+
+**Status:** READY TO BUILD  
+**Architecture:** CORRECTED & APPROVED
+
+---
+
+## Final Architecture
+
+```
+.nexusagent/          # ONLY shareable resources
+├── context/         # Shared context (any tool can read)
+└── governance/      # Shared governance (any tool can read)
+
+.opencode/           # OpenCode-specific (PRIMARY)
+├── agent/           # OpenCode agents (reference @../.nexusagent/context/)
+└── command/         # OpenCode commands
+```
+
+---
+
+## What We're Building
+
+### Phase 1: Repository Structure
+```
+nextsystems/nexus/
+├── scripts/
+│   └── install.sh
+├── profiles/
+│   ├── default/
+│   │   ├── nexusagent/
+│   │   └── opencode/
+│   ├── governance/
+│   │   ├── nexusagent/
+│   │   └── opencode/
+│   └── content/
+│       ├── nexusagent/
+│       └── opencode/
+└── docs/
+```
+
+### Phase 2: Build Order
+1. ✅ Default profile (basic orchestration)
+2. ✅ Governance profile (data governance)
+3. ✅ Content profile (content creation)
+
+---
+
+## Start Building Now
+
+All planning is complete. Architecture is corrected and approved.
+
+**Next Command:** Start building the actual repository structure.

.Building/planning/CORRECTED-ARCHITECTURE.md

@@ -0,0 +1,270 @@
+# 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:**
+```xml
+---
+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
+
+```bash
+~/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
+
+1. **Respects Tool Conventions**
+   - Each tool gets agents/commands in expected locations
+   - Tools work normally
+
+2. **Shares What Can Be Shared**
+   - Context (markdown files) - universal
+   - Governance data (JSON) - universal
+   - No duplication
+
+3. **Clean Separation**
+   - Shared resources in .nexusagent/
+   - Tool-specific in tool folders
+   - Clear boundaries
+
+---
+
+## Installation Process
+
+```bash
+# 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)
+
+```xml
+---
+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.**

.Building/planning/README.md

@@ -0,0 +1,302 @@
+# 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
+
+```xml
+<!-- .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
+
+```bash
+~/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.

.Building/planning/archive/00-MASTER-PLAN.md

@@ -0,0 +1,570 @@
+# NexusAgent - Master Plan
+**Version:** 1.0  
+**Date:** 2025-10-29  
+**Status:** Planning Phase
+
+---
+
+## Executive Summary
+
+**NexusAgent** is an open-source, universal AI agent orchestration system that combines:
+1. **Context-Aware Orchestration** - Hierarchical agent routing with 3-level dynamic context allocation
+2. **Data Governance** - Treating context as governed data assets with quality, lifecycle, and metadata management
+
+**Target Users:** Developers, data teams, content creators, AI engineers  
+**Primary Use Cases:** Any domain requiring intelligent AI workflows with governed context
+
+---
+
+## Core Decisions
+
+### ✅ Name & Branding
+- **Product Name:** NexusAgent
+- **CLI Command:** `nexus`
+- **Domain:** nexus.nextsystems.ai (open-source on GitHub)
+- **Repository:** nextsystems/nexus
+- **Tagline:** "The central hub for intelligent AI orchestration"
+
+### ✅ Installation Method
+```bash
+# One-command installation from GitHub
+curl -sSL https://raw.githubusercontent.com/nextsystems/nexus/main/scripts/install.sh | bash
+
+# Or manual
+git clone https://github.com/nextsystems/nexus.git ~/nexus
+~/nexus/scripts/base-install.sh
+```
+
+### ✅ Foundational Principles
+
+**From Building Context-Aware Systems:**
+1. **3-Level Context Allocation**
+   - Level 1 (80%): Complete isolation - task description only
+   - Level 2 (15%): Filtered context - relevant domain knowledge
+   - Level 3 (5%): Full context - complete system state
+
+2. **Hierarchical Agent Architecture**
+   - Main orchestrator analyzes and routes
+   - Specialized subagents execute specific tasks
+   - Context provider intelligently selects context
+
+3. **XML Prompt Engineering**
+   - Research-backed component ordering (Context → Role → Task → Instructions → Output)
+   - Semantic tags for clarity
+   - Component ratios optimized for performance
+
+4. **Modular Context Files**
+   - 50-200 lines per file (optimal)
+   - Organized by domain/processes/standards/templates
+   - Discoverable and maintainable
+
+**From Data Governance Agent System:**
+1. **Request ID Protocol**
+   - Every agent interaction creates `tmp/requests/{uuid}.json`
+   - All agents read same request file (no context loss)
+   - Full audit trail with processing chain
+   - Resumable workflows with checkpoints
+
+2. **Dual Metadata System**
+   - **PRIMARY:** `metadata-index.json` (fast JSON queries, no file I/O)
+   - **SECONDARY:** Embedded XML in files (travels with content, backup)
+   - Nightly sync ensures consistency
+   - File always wins on conflict
+
+3. **Explicit Context Passing**
+   - No implicit assumptions
+   - Complete context in temp files
+   - Any agent can resume from any point
+   - Easy debugging
+
+4. **Quality & Lifecycle Management**
+   - 6 dimensions of data quality (accuracy, completeness, consistency, timeliness, validity, uniqueness)
+   - Lifecycle states: CREATE → ACTIVE → REVIEW → ARCHIVE → DELETE
+   - Automated workflows (daily, weekly, monthly)
+   - Lock-based concurrency control
+
+---
+
+## System Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      USER REQUEST                           │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────┐
+│              MAIN ORCHESTRATOR AGENT                        │
+│  • Analyzes request complexity (simple/moderate/complex)    │
+│  • Determines context level (1/2/3)                         │
+│  • Routes to appropriate specialists                        │
+│  • Creates request files for coordination                   │
+└────────────────────────┬────────────────────────────────────┘
+                         │
+        ┌────────────────┼────────────────┐
+        │                │                │
+┌───────▼──────┐  ┌─────▼─────┐  ┌──────▼──────┐
+│  LEVEL 1     │  │  LEVEL 2   │  │   LEVEL 3   │
+│  Direct      │  │  Context   │  │   Context   │
+│  Execute     │  │  Provider  │  │   Manager   │
+│  (80%)       │  │  (15%)     │  │   (5%)      │
+└──────────────┘  └─────┬──────┘  └──────┬──────┘
+                        │                │
+                        ↓                ↓
+              Smart Context      Full Governance
+              Selection          + Quality Checks
+                        │                │
+                        ↓                ↓
+              tmp/requests/      metadata-index.json
+              req-{uuid}.json    Lifecycle Management
+                        │                │
+                        └────────┬───────┘
+                                 │
+                    ┌────────────┼────────────┐
+                    │            │            │
+              ┌─────▼────┐ ┌────▼─────┐ ┌───▼──────┐
+              │Specialist│ │Specialist│ │Specialist│
+              │    A     │ │    B     │ │    C     │
+              └──────────┘ └──────────┘ └──────────┘
+```
+
+---
+
+## Directory Structure
+
+### Base Installation (`~/nexus/`)
+```
+~/nexus/
+├── README.md
+├── LICENSE (MIT)
+├── config.example.yml
+├── config.yml (user's config)
+│
+├── profiles/                    # Pre-built profiles
+│   ├── default/                # Basic orchestration
+│   ├── governance/             # Data governance
+│   ├── content/                # Content creation
+│   └── custom-example/         # Example custom profile
+│
+├── scripts/
+│   ├── install.sh              # Main installation script
+│   ├── project-install.sh      # Install into project
+│   ├── update.sh               # Update installation
+│   ├── create-profile.sh       # Create custom profile
+│   └── lib/
+│       ├── colors.sh
+│       ├── validation.sh
+│       └── utils.sh
+│
+├── templates/                   # Templates for custom creation
+│   ├── agent-template.md
+│   ├── command-template.md
+│   ├── context-template.md
+│   └── profile-template/
+│
+└── docs/
+    ├── quick-start.md
+    ├── architecture.md
+    ├── profiles.md
+    └── customization.md
+```
+
+### Project Installation (`project/.nexus/`)
+```
+your-project/
+└── .nexus/                      # or .opencode, .ai, etc.
+    ├── nexus.json              # Project configuration
+    ├── README.md               # Auto-generated guide
+    │
+    ├── agent/
+    │   ├── main-orchestrator.md
+    │   ├── context-provider.md  # (Level 2+ contexts)
+    │   └── subagents/
+    │       ├── specialist-a.md
+    │       └── specialist-b.md
+    │
+    ├── command/                 # Slash commands
+    │   ├── workflow.md
+    │   └── execute.md
+    │
+    ├── context/                 # Domain knowledge
+    │   ├── core/               # Always available
+    │   ├── domain/             # Domain-specific
+    │   ├── processes/          # Workflows
+    │   ├── standards/          # Quality rules
+    │   └── templates/          # Reusable patterns
+    │
+    └── governance/              # (If governance enabled)
+        ├── metadata-index.json  # PRIMARY metadata
+        ├── workflow-state.json  # Workflow state machine
+        ├── tmp/
+        │   └── requests/       # Request context files
+        └── logs/
+            ├── access.log
+            ├── changes.log
+            └── workflows.log
+```
+
+---
+
+## Profile System
+
+### Profile: Default (Context-Aware Orchestration)
+
+**Purpose:** Universal hierarchical orchestration for any domain
+
+**Components:**
+```yaml
+agents:
+  - main-orchestrator.md       # Intelligent routing
+  - context-provider.md        # Smart context selection
+  - task-planner.md           # Multi-step planning
+  - subagents/
+    - code-reviewer.md
+    - test-writer.md
+    - doc-writer.md
+
+commands:
+  - workflow.md               # Main entry point
+  - plan-task.md             # Complex planning
+  - execute-task.md          # Step execution
+
+context:
+  - core/essential-patterns.md
+  - architecture/project-structure.md
+  - workflows/simple-task.md
+  - workflows/complex-feature.md
+
+governance: minimal
+  - metadata-index.json (basic tracking)
+  - No automated workflows
+  
+config:
+  context_level: 2
+  enable_governance: false
+```
+
+### Profile: Governance (Data Management)
+
+**Purpose:** Full data governance for context as data assets
+
+**Components:**
+```yaml
+agents:
+  - main-orchestrator.md       # Routes to governance
+  - governance/
+    - context-manager.md       # Primary governance agent
+    - subagents/
+      - quality-validator.md
+      - lifecycle-manager.md
+      - metadata-updater.md
+      - catalog-maintainer.md
+
+commands:
+  - get-context.md            # Retrieve with quality check
+  - update-context.md         # Update after changes
+  - validate-quality.md       # Quality validation
+  - lifecycle-review.md       # Lifecycle management
+  - sync-metadata.md          # Force metadata sync
+
+context:
+  - governance/
+    - metadata-schema.md
+    - quality-dimensions.md
+    - lifecycle-states.md
+    - sync-strategies.md
+  - workflows/
+    - context-retrieval.md
+    - context-update.md
+    - quality-validation.md
+
+governance: full
+  - metadata-index.json (PRIMARY with indexes)
+  - workflow-state.json (state machine)
+  - Automated workflows:
+    - daily_quality_sample
+    - weekly_lifecycle_review
+    - monthly_deep_audit
+  - Nightly sync job
+  - Full audit logging
+  - Lock-based concurrency
+  
+config:
+  context_level: 3
+  enable_governance: true
+  metadata_sync: "0 4 * * *"
+  quality_workflows: true
+```
+
+### Profile: Content (Combines Both)
+
+**Purpose:** Content creation with platform optimization and governance
+
+**Components:**
+```yaml
+agents:
+  # Orchestration
+  - content-orchestrator.md
+  - context-provider.md
+  
+  # Content specialists
+  - subagents/
+    - twitter-specialist.md
+    - linkedin-specialist.md
+    - blog-specialist.md
+    - research-assistant.md
+    - content-validator.md
+    
+  # Governance (inherited)
+  - governance/context-manager.md
+  - governance/subagents/ (all)
+
+commands:
+  - create-content.md
+  - new-project.md
+  - work-on.md
+  - validate.md
+  - publish.md
+
+context:
+  # Content domain
+  - brand/voice.md
+  - brand/accuracy-guidelines.md
+  - platforms/twitter/specs.md
+  - platforms/linkedin/specs.md
+  - workflows/multi-platform.md
+  
+  # Governance (inherited)
+  - governance/ (all)
+
+governance: full
+  - All governance features enabled
+  - Content lifecycle tracking
+  - Quality validation for content
+  
+config:
+  context_level: 2
+  enable_governance: true
+  enable_research: true
+```
+
+---
+
+## Configuration System
+
+### Global Config (`~/nexus/config.yml`)
+
+```yaml
+# NexusAgent Configuration
+version: "1.0.0"
+
+# User information
+user:
+  name: "Your Name"
+  email: "your@email.com"
+
+# Installation defaults
+defaults:
+  profile: "default"
+  ai_tool: "opencode"
+  folder_name: ".nexus"
+  context_level: 2
+  enable_governance: false
+  backup_existing: true
+
+# Profile-specific overrides
+profiles:
+  governance:
+    context_level: 3
+    enable_governance: true
+    metadata_sync: "0 4 * * *"
+    quality_workflows: true
+    
+  content:
+    context_level: 2
+    enable_governance: true
+    enable_research: true
+
+# AI tool integration
+ai_tools:
+  opencode:
+    commands_folder: "command"
+    agents_folder: "agent/subagents"
+    context_folder: "context"
+    use_skills: true
+    
+  cursor:
+    prompts_folder: ".cursor/prompts"
+    agents_folder: ".cursor/agents"
+    use_skills: false
+
+# Advanced settings
+advanced:
+  verbose_logging: false
+  telemetry: false           # Privacy-first
+  auto_update_check: true
+  update_channel: "stable"
+
+# Installation behavior
+install:
+  create_examples: true
+  create_docs: true
+  run_validation: true
+  show_tips: true
+```
+
+### Project Config (`.nexus/nexus.json`)
+
+```json
+{
+  "version": "1.0.0",
+  "profile": "governance",
+  "ai_tool": "opencode",
+  "installed_at": "2025-10-29T10:00:00Z",
+  "nexus_version": "1.0.0",
+  "config": {
+    "context_level": 3,
+    "enable_governance": true
+  },
+  "metadata": {
+    "project_name": "My Project",
+    "project_type": "data-governance"
+  }
+}
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Foundation ✅ (Planning)
+- [x] Architecture design
+- [x] Profile system design
+- [x] Directory structure
+- [ ] **Get approval on planning**
+
+### Phase 2: Base Installation (Week 1)
+- [ ] Create base repository structure
+- [ ] Write installation scripts
+- [ ] Create configuration templates
+- [ ] Build CLI tooling
+
+### Phase 3: Default Profile (Week 1-2)
+- [ ] Main orchestrator agent
+- [ ] Context provider agent
+- [ ] Task planner agent
+- [ ] Basic subagents (reviewer, tester, doc writer)
+- [ ] Core context files
+- [ ] Basic commands
+
+### Phase 4: Governance Profile (Week 2-3)
+- [ ] Context manager agent
+- [ ] Quality validator subagent
+- [ ] Lifecycle manager subagent
+- [ ] Metadata updater subagent
+- [ ] Catalog maintainer subagent
+- [ ] Metadata index system
+- [ ] Workflow state machine
+- [ ] Automated workflows
+
+### Phase 5: Content Profile (Week 3-4)
+- [ ] Content orchestrator
+- [ ] Platform specialists (Twitter, LinkedIn, Blog, YouTube)
+- [ ] Research assistant
+- [ ] Content validator
+- [ ] Platform context files
+- [ ] Brand guidelines
+- [ ] Content commands
+
+### Phase 6: Documentation & Testing (Week 4-5)
+- [ ] Quick start guide
+- [ ] Architecture documentation
+- [ ] Profile guides
+- [ ] Customization tutorials
+- [ ] API reference
+- [ ] Testing with real projects
+- [ ] Bug fixes and refinements
+
+### Phase 7: Launch (Week 5)
+- [ ] GitHub repository public
+- [ ] Website (nexus.nextsystems.ai)
+- [ ] Video demonstrations
+- [ ] Community Discord
+- [ ] Launch announcement
+
+---
+
+## Success Metrics
+
+### Technical Metrics
+- ✅ Installation works on macOS, Linux, Windows (WSL)
+- ✅ Context loading < 1 second for 90% of requests
+- ✅ Metadata queries < 10ms (JSON index)
+- ✅ No context loss between agents (request ID protocol)
+- ✅ Resumable workflows with checkpoints
+
+### User Metrics
+- ✅ Time to first successful use < 15 minutes
+- ✅ User satisfaction > 8/10
+- ✅ Profile adoption: Default (60%), Governance (25%), Content (15%)
+
+### Quality Metrics
+- ✅ Context quality health score > 85%
+- ✅ Code coverage > 80% for critical paths
+- ✅ Documentation completeness > 90%
+
+---
+
+## Risks & Mitigations
+
+### Risk 1: Complexity Overwhelms Users
+**Mitigation:** 
+- Start with simple default profile
+- Progressive disclosure in documentation
+- Clear examples for each use case
+- Video tutorials
+
+### Risk 2: Performance Issues with Large Context
+**Mitigation:**
+- JSON metadata index for fast queries
+- 3-level context allocation
+- Lazy loading of file contents
+- Caching strategies
+
+### Risk 3: Profile Compatibility Issues
+**Mitigation:**
+- Versioned profile schemas
+- Validation on installation
+- Clear migration guides
+- Backward compatibility guarantees
+
+### Risk 4: AI Tool Integration Breaks
+**Mitigation:**
+- Abstract integration layer
+- Tool-specific adapters
+- Comprehensive testing
+- Fallback mechanisms
+
+---
+
+## Next Steps
+
+1. **Review & Approve Planning** - Get feedback on this master plan
+2. **Create Detailed Specifications** - Technical specs for each component
+3. **Set Up Repository** - Initialize GitHub repo with structure
+4. **Start Phase 2** - Build installation scripts
+5. **Iterate** - Build, test, refine
+
+---
+
+## Open Questions
+
+1. ❓ Should we support multiple AI tools from day one, or focus on OpenCode first?
+2. ❓ What's the minimum viable profile for launch (just default, or all three)?
+3. ❓ Do we need a web UI for configuration, or is CLI + YAML sufficient?
+4. ❓ Should metadata index support plugins for custom quality dimensions?
+5. ❓ What's the governance model for community contributions?
+
+---
+
+**Status:** Ready for review and approval  
+**Next Action:** Get feedback on master plan, then proceed to detailed specifications

.Building/planning/archive/01-TECHNICAL-SPECIFICATION.md

@@ -0,0 +1,932 @@
+# NexusAgent - Technical Specification
+**Version:** 1.0  
+**Date:** 2025-10-29
+
+---
+
+## 1. Context-Aware Orchestration System
+
+### 1.1 Three-Level Context Allocation
+
+**Level 1: Complete Isolation (80% of requests)**
+
+```yaml
+Triggers:
+  - Single clear objective
+  - Standard operation
+  - No domain knowledge needed
+  - Can complete in one step
+  
+Context Provided:
+  - Task description only
+  - No file loading
+  - No metadata queries
+  
+Performance:
+  - 80% reduction in context overhead
+  - < 1 second execution time
+  
+Examples:
+  - Format data according to specification
+  - Validate input against simple rules
+  - Generate output from template
+```
+
+**Level 2: Filtered Context (15% of requests)**
+
+```yaml
+Triggers:
+  - Multiple steps required
+  - Domain knowledge needed
+  - Quality validation important
+  - Some coordination required
+  
+Context Provided:
+  - Task description
+  - Relevant domain files (2-4 files)
+  - Platform specs if applicable
+  - Quality standards if validation needed
+  
+Process:
+  1. Orchestrator creates tmp/requests/{uuid}.json
+  2. Routes to @context-provider with request_id
+  3. Context provider analyzes and returns file paths
+  4. Orchestrator loads specified files
+  5. Routes to specialist with loaded context
+  
+Performance:
+  - 60% reduction in context overhead
+  - < 5 seconds execution time
+  
+Examples:
+  - Create content requiring brand alignment
+  - Process requests needing business logic
+  - Validate against quality standards
+```
+
+**Level 3: Full Context (5% of requests)**
+
+```yaml
+Triggers:
+  - Multi-agent coordination needed
+  - High stakes or critical decisions
+  - Extensive state management required
+  - Requires historical context
+  
+Context Provided:
+  - Task description
+  - Full domain knowledge
+  - Historical state
+  - Quality metadata
+  - Lifecycle information
+  
+Process:
+  1. Orchestrator creates tmp/requests/{uuid}.json
+  2. Routes to @context-manager with request_id
+  3. Context manager queries metadata-index.json
+  4. Validates quality and health scores
+  5. Loads files with full governance
+  6. Routes to specialists with request_id
+  7. All agents update processing chain
+  
+Performance:
+  - Optimized for accuracy over speed
+  - < 30 seconds execution time
+  
+Examples:
+  - Update governed context after PR merge
+  - Complex multi-step workflows with dependencies
+  - High-stakes decisions requiring audit trail
+```
+
+### 1.2 Main Orchestrator Agent
+
+**File:** `agent/main-orchestrator.md`
+
+**Responsibilities:**
+```yaml
+1. Request Analysis:
+   - Parse user request
+   - Extract keywords and intent
+   - Assess complexity (simple/moderate/complex)
+   - Identify domain and required capabilities
+   
+2. Context Allocation:
+   - Determine context level (1/2/3)
+   - Decide if governance is needed
+   - Calculate estimated execution time
+   
+3. Routing:
+   - Direct execution (Level 1)
+   - Route to @context-provider (Level 2)
+   - Route to @context-manager (Level 3)
+   - Route to appropriate specialists
+   
+4. Coordination:
+   - Manage multi-agent workflows
+   - Track progress via request files
+   - Handle errors and retries
+   - Integrate results
+   
+5. Response:
+   - Format final output
+   - Provide clear confirmation
+   - Suggest next actions
+   - Clean up temp files
+```
+
+**Complexity Assessment Function:**
+```python
+def assess_complexity(request):
+    score = 0
+    
+    # Step count
+    estimated_steps = count_action_verbs(request)
+    score += min(estimated_steps, 5)  # Cap at 5
+    
+    # Domain knowledge
+    if requires_domain_knowledge(request):
+        score += 2
+    
+    # Integration points
+    integration_count = count_integration_keywords(request)
+    score += min(integration_count * 2, 4)  # Cap at 4
+    
+    # Validation requirements
+    if requires_quality_validation(request):
+        score += 1
+    
+    # Historical context
+    if requires_historical_context(request):
+        score += 2
+    
+    # Governance keywords
+    if contains_governance_keywords(request):
+        score += 2
+    
+    # Classification
+    if score <= 3:
+        return "simple", 1  # Level 1
+    elif score <= 7:
+        return "moderate", 2  # Level 2
+    else:
+        return "complex", 3  # Level 3
+```
+
+**Template Structure:**
+```xml
+---
+description: "Main orchestrator for NexusAgent"
+mode: primary
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  task: true
+  glob: true
+  grep: true
+---
+
+# NexusAgent Orchestrator
+
+<context>
+  <system_context>
+    Universal AI agent orchestration system combining
+    context-aware routing with data governance
+  </system_context>
+  <execution_context>
+    Analyzes requests, allocates appropriate context level,
+    and coordinates specialists with explicit context passing
+  </execution_context>
+</context>
+
+<role>
+  Primary Orchestrator specializing in intelligent routing,
+  context allocation, and multi-agent coordination
+</role>
+
+<task>
+  Transform user requests into completed outcomes by:
+  1. Analyzing complexity
+  2. Allocating appropriate context
+  3. Routing to specialists
+  4. Coordinating execution
+  5. Integrating results
+</task>
+
+<workflow name="IntelligentOrchestration">
+  <stage_1_analyze>
+    <action>Assess request complexity</action>
+    <complexity_score>Calculate 0-10 score</complexity_score>
+    <context_level>Determine 1, 2, or 3</context_level>
+    <governance_needed>Check if governance required</governance_needed>
+  </stage_1_analyze>
+  
+  <stage_2_route>
+    <level_1>
+      <execute_directly>No temp files, direct execution</execute_directly>
+    </level_1>
+    
+    <level_2>
+      <create_request_file>tmp/requests/req-{uuid}.json</create_request_file>
+      <route_to_context_provider>@context-provider with request_id</route_to_context_provider>
+      <load_context>Files specified by context-provider</load_context>
+      <route_to_specialist>With loaded context</route_to_specialist>
+    </level_2>
+    
+    <level_3>
+      <create_request_file>tmp/requests/req-{uuid}.json</create_request_file>
+      <route_to_context_manager>@context-manager with request_id</route_to_context_manager>
+      <load_governed_context>With quality validation</load_governed_context>
+      <route_to_specialists>With request_id for coordination</route_to_specialists>
+    </level_3>
+  </stage_2_route>
+  
+  <stage_3_execute>
+    <monitor_progress>Read request file for updates</monitor_progress>
+    <handle_errors>Retry logic and fallbacks</handle_errors>
+  </stage_3_execute>
+  
+  <stage_4_finalize>
+    <integrate_results>Combine outputs</integrate_results>
+    <format_response>Clear user-facing message</format_response>
+    <cleanup>Archive or delete temp files</cleanup>
+  </stage_4_finalize>
+</workflow>
+
+<context_allocation_logic>
+  <level_1_indicators>
+    - Single clear objective
+    - Standard operation type
+    - No integration requirements
+    - No domain knowledge needed
+  </level_1_indicators>
+  
+  <level_2_indicators>
+    - Multi-step process
+    - Domain knowledge helpful
+    - Quality validation needed
+    - Platform-specific requirements
+  </level_2_indicators>
+  
+  <level_3_indicators>
+    - Governance keywords present
+    - High-stakes or critical
+    - Historical context required
+    - Multi-system coordination
+    - Quality metadata needed
+  </level_3_indicators>
+</context_allocation_logic>
+```
+
+### 1.3 Context Provider Agent
+
+**File:** `agent/context-provider.md`
+
+**Responsibilities:**
+```yaml
+1. Request Analysis:
+   - Read request file for full context
+   - Parse user request and keywords
+   - Identify domain area
+   - Detect integration points
+   
+2. Context Selection:
+   - Query available context files
+   - Match keywords to tags
+   - Prioritize by relevance
+   - Limit to 2-4 files for cognitive load
+   
+3. File Path Return:
+   - Return array of file paths (not contents)
+   - Include priority levels
+   - Estimate total token count
+   - Provide reasoning for selection
+```
+
+**Selection Algorithm:**
+```python
+def select_context_files(request_id):
+    # Read request file
+    request = read_json(f"tmp/requests/{request_id}.json")
+    keywords = request["task_context"]["keywords"]
+    task_type = request["task_context"]["type"]
+    
+    # Initialize selection
+    selected_files = []
+    
+    # Always include core
+    selected_files.append({
+        "path": "context/core/essential-patterns.md",
+        "priority": "critical",
+        "reason": "Core patterns always needed"
+    })
+    
+    # Match by domain
+    if task_type in ["data_processing", "etl"]:
+        selected_files.extend(get_domain_files("data"))
+    elif task_type in ["content_creation", "writing"]:
+        selected_files.extend(get_domain_files("content"))
+    
+    # Match by keywords
+    for keyword in keywords:
+        matching_files = query_context_by_tag(keyword)
+        for file in matching_files[:2]:  # Max 2 per keyword
+            if file not in selected_files:
+                selected_files.append({
+                    "path": file,
+                    "priority": "important",
+                    "reason": f"Matched keyword: {keyword}"
+                })
+    
+    # Limit total files
+    if len(selected_files) > 4:
+        selected_files = prioritize_files(selected_files)[:4]
+    
+    # Estimate tokens
+    estimated_tokens = sum([estimate_file_tokens(f["path"]) 
+                           for f in selected_files])
+    
+    return {
+        "context_level": 2,
+        "file_locations": [f["path"] for f in selected_files],
+        "estimated_tokens": estimated_tokens,
+        "load_priority": {
+            "critical": [f["path"] for f in selected_files if f["priority"] == "critical"],
+            "important": [f["path"] for f in selected_files if f["priority"] == "important"]
+        },
+        "reasoning": [f"{f['path']}: {f['reason']}" for f in selected_files]
+    }
+```
+
+---
+
+## 2. Data Governance System
+
+### 2.1 Request ID Protocol
+
+**Purpose:** Eliminate context loss between agents through explicit context passing
+
+**Specification:**
+
+```yaml
+Request File Location: 
+  governance/tmp/requests/{request_id}.json
+
+Request ID Format:
+  req-{uuid4}  # e.g., req-a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+Request File Structure:
+  {
+    "request_id": "req-{uuid}",
+    "timestamp": "2025-10-29T10:00:00Z",
+    "from_agent": "main-orchestrator",
+    "task_context": {
+      "type": "feature_build | content_creation | data_update",
+      "description": "Human-readable description",
+      "user_request": "Original user input",
+      "keywords": ["keyword1", "keyword2"],
+      "priority": "normal | urgent | low"
+    },
+    "context_needed": {
+      "files_requested": ["file1.md", "file2.md"],
+      "depth": 1,
+      "include_metadata": true,
+      "max_files": 10
+    },
+    "processing_chain": [
+      {
+        "agent": "agent-name",
+        "action": "action_taken",
+        "timestamp": "2025-10-29T10:00:01Z",
+        "notes": "Optional details",
+        "duration_ms": 150
+      }
+    ],
+    "result": {
+      "status": "completed | in_progress | failed",
+      "files_returned": ["file1.md", "file2.md"],
+      "warnings": ["warning1"],
+      "errors": [],
+      "estimated_tokens": 1200,
+      "metadata": {
+        "quality_score": 25,
+        "health_status": "healthy"
+      }
+    }
+  }
+
+Protocol Rules:
+  1. MUST create request file before calling any subagent
+  2. MUST pass request_id (not request contents) to subagents
+  3. MUST read request file as first action in subagent
+  4. MUST update processing_chain after each major step
+  5. MUST update result section upon completion
+  6. MUST cleanup or archive after workflow complete
+
+Benefits:
+  ✅ No context loss between agents
+  ✅ Full audit trail of processing
+  ✅ Resumable workflows
+  ✅ Easy debugging
+  ✅ Distributed processing possible
+```
+
+### 2.2 Dual Metadata System
+
+**PRIMARY: metadata-index.json**
+
+```yaml
+Location: governance/metadata-index.json
+
+Purpose:
+  - Fast queries without file I/O
+  - Central source of truth for queries
+  - Pre-computed indexes for common patterns
+  
+Structure:
+  {
+    "version": "1.0",
+    "last_updated": "2025-10-29T10:00:00Z",
+    "last_sync_with_files": "2025-10-29T04:00:00Z",
+    "sync_status": "healthy | warning | error",
+    "total_files": 156,
+    
+    "files": {
+      "path/to/file.md": {
+        "admin": {
+          "created": "2025-01-15",
+          "created_by": "user@domain.com",
+          "owner": "team-name",
+          "last_modified": "2025-10-15",
+          "modified_by": "user@domain.com",
+          "next_review": "2026-01-15"
+        },
+        "classification": {
+          "tier": 1,
+          "category": "system-design",
+          "sensitivity": "internal",
+          "tags": ["tag1", "tag2"]
+        },
+        "quality": {
+          "health_score": 25,
+          "accuracy_score": 5,
+          "completeness_score": 4,
+          "consistency_score": 5,
+          "timeliness_score": 4,
+          "validity_score": 5,
+          "uniqueness_score": 5,
+          "last_validated": "2025-10-29"
+        },
+        "usage": {
+          "access_count_30d": 45,
+          "access_count_90d": 132,
+          "last_accessed": "2025-10-28"
+        },
+        "lifecycle": {
+          "state": "active | review | archived | deleted",
+          "retention": "permanent | 1year | 90days"
+        },
+        "checksum": "sha256:abc123...",
+        "embedded_metadata_present": true
+      }
+    },
+    
+    "indexes": {
+      "by_tier": {
+        "1": ["file1.md", "file2.md"],
+        "2": ["file3.md"]
+      },
+      "by_state": {
+        "active": ["file1.md", "file2.md"],
+        "review": ["file3.md"]
+      },
+      "by_health": {
+        "healthy": ["file1.md"],
+        "warning": ["file2.md"],
+        "action_required": ["file3.md"]
+      },
+      "by_tag": {
+        "authentication": ["file1.md", "file2.md"],
+        "storage": ["file3.md"]
+      }
+    },
+    
+    "quality_summary": {
+      "healthy_files": 142,
+      "warning_files": 12,
+      "action_required_files": 2,
+      "overall_health_score": 87
+    }
+  }
+
+Query Performance:
+  - Tier query: < 1ms (indexed)
+  - Tag query: < 5ms (indexed)
+  - Health summary: < 1ms (pre-computed)
+  - No file I/O required for queries
+
+Update Strategy:
+  - Update on every file modification
+  - Recalculate indexes if tier/tags change
+  - Update quality_summary periodically
+  - Atomic writes with locks
+```
+
+**SECONDARY: Embedded XML Metadata**
+
+```yaml
+Location: Top of each context file
+
+Purpose:
+  - Travels with file content
+  - Backup for metadata-index.json
+  - Source of truth for nightly sync
+  - Human-readable metadata
+
+Format:
+  <?xml version="1.0" encoding="UTF-8"?>
+  <context_file>
+  
+  <!-- METADATA (Managed by Governance Agents) -->
+  <metadata>
+    <admin>
+      <created>2025-01-15</created>
+      <created_by>user@domain.com</created_by>
+      <owner>team-name</owner>
+      <last_modified>2025-10-15</last_modified>
+      <modified_by>user@domain.com</modified_by>
+      <next_review>2026-01-15</next_review>
+    </admin>
+    
+    <classification>
+      <tier>1</tier>
+      <category>system-design</category>
+      <sensitivity>internal</sensitivity>
+      <tags>tag1,tag2,tag3</tags>
+    </classification>
+    
+    <quality>
+      <health_score>25</health_score>
+      <accuracy_score>5</accuracy_score>
+      <completeness_score>4</completeness_score>
+      <consistency_score>5</consistency_score>
+      <timeliness_score>4</timeliness_score>
+      <validity_score>5</validity_score>
+      <uniqueness_score>5</uniqueness_score>
+      <last_validated>2025-10-29</last_validated>
+    </quality>
+    
+    <usage>
+      <access_count_30d>45</access_count_30d>
+      <access_count_90d>132</access_count_90d>
+      <last_accessed>2025-10-28</last_accessed>
+    </usage>
+    
+    <lifecycle>
+      <state>active</state>
+      <retention>permanent</retention>
+    </lifecycle>
+  </metadata>
+  
+  <!-- CONTENT (Managed by Humans/Orchestrator) -->
+  <domain_knowledge>
+    [Actual content here]
+  </domain_knowledge>
+  
+  </context_file>
+
+Sync Strategy:
+  - Nightly sync job (4:00 AM)
+  - Scans all files
+  - Parses XML metadata
+  - Compares with metadata-index.json
+  - If mismatch: File wins (XML is source of truth)
+  - Updates JSON index
+  - Logs discrepancies
+```
+
+### 2.3 Quality Validation (6 Dimensions)
+
+```yaml
+Dimension 1: Accuracy
+  Score: 0-5
+  Checks:
+    - All @ references point to existing files
+    - External links are valid
+    - Code examples compile/run
+    - Data is factually correct
+  
+Dimension 2: Completeness
+  Score: 0-5
+  Checks:
+    - All required sections present
+    - XML schema validation passes
+    - Examples provided where needed
+    - Related references included
+  
+Dimension 3: Consistency
+  Score: 0-5
+  Checks:
+    - Naming conventions followed
+    - Format standards met
+    - Terminology matches glossary
+    - Style guide compliance
+  
+Dimension 4: Timeliness
+  Score: 0-5 (time-based)
+  Formula:
+    days_since_modified = now() - last_modified
+    if days_since_modified < 30:  score = 5
+    elif days_since_modified < 90: score = 3
+    elif days_since_modified < 180: score = 2
+    else: score = 1
+  
+Dimension 5: Validity
+  Score: 0-5
+  Checks:
+    - XML well-formed
+    - All references resolve
+    - Links not broken
+    - Metadata schema valid
+  
+Dimension 6: Uniqueness
+  Score: 0-5
+  Checks:
+    - No duplicate content
+    - No conflicting information
+    - Clear unique purpose
+
+Health Score Calculation:
+  health_score = sum(all dimension scores)
+  max_score = 30
+  
+  Status Classification:
+    - health_score >= 25: Healthy (green)
+    - health_score 20-24: Warning (yellow)
+    - health_score < 20: Action Required (red)
+```
+
+### 2.4 Lifecycle Management
+
+```yaml
+Lifecycle States:
+  CREATE → ACTIVE → REVIEW → ARCHIVE → DELETE
+
+State: CREATE
+  Triggers:
+    - New file created
+    - Initial metadata populated
+  Actions:
+    - Set state = "active"
+    - Set next_review = created + 1 year
+    - Initialize quality scores
+    
+State: ACTIVE
+  Conditions:
+    - Regular use (access_count_90d > 5)
+    - Recent updates (< 90 days old)
+    - Good health (score >= 20)
+  Actions:
+    - Normal operations
+    - Update access counts
+    - Periodic quality checks
+    
+State: REVIEW
+  Triggers:
+    - next_review date passed
+    - freshness_days > 90
+    - access_count_90d < 5
+    - health_score < 20
+  Actions:
+    - Notify owner
+    - Update next_review = now + 90 days
+    - Flag for human review
+    - Generate review report
+    
+State: ARCHIVE
+  Triggers:
+    - access_count_90d = 0
+    - freshness_days > 180
+    - Marked obsolete by owner
+  Actions:
+    - Move to governance/archive/
+    - Update state in metadata
+    - Remove from active indexes
+    - Keep for reference
+    
+State: DELETE
+  Triggers:
+    - Archived for > 2 years
+    - Owner approval for deletion
+    - Regulatory retention period passed
+  Actions:
+    - Backup to governance/deleted/
+    - Remove from all indexes
+    - Update catalogs
+    - Log deletion
+
+Approval Requirements:
+  - Archive Tier 1 files: Owner approval required
+  - Delete any file: Owner + steward approval required
+  - Bulk operations: Admin approval required
+```
+
+---
+
+## 3. Agent Templates
+
+### 3.1 Primary Agent Template
+
+```xml
+---
+description: "[What this agent does]"
+mode: primary
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  task: true
+  glob: true
+  grep: true
+permissions:
+  edit:
+    "**/*.env*": "deny"
+    "**/*.secret": "deny"
+---
+
+# [Agent Name]
+
+<context>
+  <system_context>[Overall system]</system_context>
+  <domain_context>[Domain/industry]</domain_context>
+  <task_context>[Types of tasks]</task_context>
+</context>
+
+<role>
+  [Role description with expertise areas]
+</role>
+
+<task>
+  [Specific objective this agent accomplishes]
+</task>
+
+<workflow name="PrimaryWorkflow">
+  <stage_1>
+    <action>[First major action]</action>
+    <decision>
+      <if test="condition">[Then do this]</if>
+      <else>[Do this]</else>
+    </decision>
+  </stage_1>
+  
+  <stage_2>
+    [Continue workflow]
+  </stage_2>
+</workflow>
+
+<constraints>
+  <must>Always do X</must>
+  <must_not>Never do Y</must_not>
+</constraints>
+
+<output_specifications>
+  [What format to return]
+</output_specifications>
+```
+
+### 3.2 Subagent Template
+
+```xml
+---
+description: "[Specific task]"
+mode: subagent
+temperature: 0.1
+tools:
+  read: true
+  write: false
+---
+
+# [Subagent Name]
+
+<context>
+  <specialist_domain>[Specific expertise]</specialist_domain>
+  <task_scope>[What this agent does]</task_scope>
+</context>
+
+<role>
+  [Specialist role]
+</role>
+
+<task>
+  [Specific measurable task]
+</task>
+
+<inputs_required>
+  <parameter name="request_id" type="string">
+    UUID for request file
+  </parameter>
+</inputs_required>
+
+<process_flow>
+  <step_1>
+    <action>Read request file</action>
+    <file>tmp/requests/{request_id}.json</file>
+  </step_1>
+  
+  <step_2>
+    <action>Perform specialized task</action>
+  </step_2>
+  
+  <step_3>
+    <action>Update request file</action>
+    <append>Processing chain entry</append>
+  </step_3>
+</process_flow>
+
+<constraints>
+  <must>ALWAYS read request file first</must>
+  <must>ALWAYS update request file with results</must>
+  <must_not>Call other agents</must_not>
+</constraints>
+
+<output_specification>
+  [Exact structure of output]
+</output_specification>
+```
+
+---
+
+## 4. Performance Requirements
+
+```yaml
+Context Loading:
+  - Level 1: < 1 second
+  - Level 2: < 5 seconds
+  - Level 3: < 30 seconds
+
+Metadata Queries:
+  - JSON index query: < 10ms
+  - Health summary: < 1ms
+  - Tag search: < 5ms
+
+File Operations:
+  - Read file: < 100ms
+  - Update metadata: < 200ms (with lock)
+  - Sync all files: < 2 minutes
+
+Workflow Execution:
+  - Simple task: < 10 seconds
+  - Moderate task: < 60 seconds
+  - Complex task: < 5 minutes
+
+Memory Usage:
+  - Base system: < 50MB
+  - With metadata index: < 100MB
+  - During execution: < 500MB
+
+Scalability:
+  - Support up to 10,000 context files
+  - Support up to 1,000 concurrent requests
+  - Metadata index size: < 10MB for 1,000 files
+```
+
+---
+
+## 5. Security Considerations
+
+```yaml
+File Permissions:
+  - Deny edit on *.env*, *.secret files
+  - Validate all file paths (no ../ traversal)
+  - Sandbox bash execution
+  
+Metadata Protection:
+  - Lock-based concurrency for writes
+  - Atomic updates to prevent corruption
+  - Backup before destructive operations
+  
+Request File Security:
+  - UUID prevents guessing
+  - Cleanup after completion
+  - Archive for audit (optional)
+  
+API Keys:
+  - Never store in context files
+  - Use environment variables
+  - Validate before use
+```
+
+---
+
+## Next: Installation Specification
+
+This technical spec provides the foundation. Next document will detail:
+- Installation scripts
+- Profile packaging
+- Configuration management
+- Update mechanisms

.Building/planning/archive/02-MULTI-TOOL-INTEGRATION.md

@@ -0,0 +1,647 @@
+# NexusAgent - Multi-Tool Integration Strategy
+**Version:** 1.0  
+**Date:** 2025-10-29  
+**Inspiration:** Agent OS pattern with universal base + tool-specific adapters
+
+---
+
+## Problem Statement
+
+Different AI tools have different conventions:
+- **OpenCode:** Uses `.opencode/` with `command/` and `agent/subagents/`
+- **Cursor:** Uses `.cursor/` with `prompts/` and `rules/`
+- **Claude Desktop:** Uses MCP servers and config JSON
+- **Aider:** Uses `.aider/` with prompts
+- **Custom tools:** May have their own conventions
+
+**Solution:** Separate universal system logic from tool-specific integration layers.
+
+---
+
+## Architecture: Universal Base + Tool Adapters
+
+### Core Concept
+
+```
+project/
+├── .nexus/                      # UNIVERSAL BASE - Tool-agnostic
+│   ├── nexus.json              # Configuration
+│   ├── profiles/               # Which profile is active
+│   ├── agents/                 # Agent logic (universal)
+│   ├── context/                # Domain knowledge (universal)
+│   ├── workflows/              # Workflows (universal)
+│   └── governance/             # Governance system (universal)
+│
+├── .opencode/                   # OPENCODE ADAPTER
+│   ├── command/                # OpenCode slash commands
+│   └── agent/subagents/        # OpenCode agent format
+│
+├── .cursor/                     # CURSOR ADAPTER
+│   ├── prompts/                # Cursor prompts
+│   └── rules/                  # Cursor rules
+│
+└── .claude/                     # CLAUDE ADAPTER
+    └── mcp-config.json         # MCP server config
+```
+
+### How It Works
+
+```
+User request via AI tool
+       ↓
+Tool-specific adapter (.opencode/command/workflow.md)
+       ↓
+Loads core logic from .nexus/agents/
+       ↓
+Loads context from .nexus/context/
+       ↓
+Executes with governance from .nexus/governance/
+       ↓
+Returns via tool-specific format
+```
+
+---
+
+## Universal Base Structure (`.nexus/`)
+
+```
+.nexus/
+├── nexus.json                   # Configuration
+│   {
+│     "version": "1.0.0",
+│     "profile": "governance",
+│     "tools": ["opencode", "cursor"],
+│     "config": { ... }
+│   }
+│
+├── agents/                      # Universal agent definitions
+│   ├── main-orchestrator.md
+│   ├── context-provider.md
+│   ├── context-manager.md
+│   └── specialists/
+│       ├── code-reviewer.md
+│       ├── quality-validator.md
+│       └── content-creator.md
+│
+├── context/                     # Domain knowledge
+│   ├── core/
+│   ├── domain/
+│   ├── processes/
+│   └── standards/
+│
+├── workflows/                   # Workflow definitions
+│   ├── simple-task.md
+│   ├── complex-feature.md
+│   └── governance-update.md
+│
+├── governance/                  # Governance system
+│   ├── metadata-index.json
+│   ├── workflow-state.json
+│   └── tmp/requests/
+│
+└── adapters/                    # Tool integration configs
+    ├── opencode.yml
+    ├── cursor.yml
+    └── claude.yml
+```
+
+---
+
+## Tool-Specific Adapters
+
+### OpenCode Adapter (`.opencode/`)
+
+```
+.opencode/
+├── command/                     # Slash commands
+│   ├── workflow.md             # Thin wrapper
+│   ├── plan-task.md
+│   └── execute-task.md
+│
+└── agent/
+    └── subagents/               # Symlinks or thin wrappers
+        ├── code-reviewer.md     # → ../.nexus/agents/specialists/code-reviewer.md
+        └── quality-validator.md
+```
+
+**Example: `.opencode/command/workflow.md`**
+```markdown
+---
+name: workflow
+agent: orchestrator
+description: "Main workflow entry point"
+---
+
+# Workflow Command
+
+You are executing the NexusAgent workflow system.
+
+**Request:** $ARGUMENTS
+
+**Load core logic from:**
+@../.nexus/agents/main-orchestrator.md
+
+**Execute the workflow as defined in the core agent.**
+```
+
+### Cursor Adapter (`.cursor/`)
+
+```
+.cursor/
+├── prompts/
+│   ├── workflow.md             # Cursor-style prompt
+│   └── code-review.md
+│
+└── rules/
+    └── nexus-rules.md          # Cursor AI rules
+```
+
+**Example: `.cursor/prompts/workflow.md`**
+```markdown
+# NexusAgent Workflow
+
+Load the main orchestrator from `.nexus/agents/main-orchestrator.md`.
+
+Execute the workflow logic with the user's request: {request}
+
+Follow the orchestration patterns defined in the core system.
+```
+
+### Claude Desktop Adapter (`.claude/`)
+
+```
+.claude/
+└── mcp-config.json
+```
+
+**Example: `.claude/mcp-config.json`**
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "node",
+      "args": ["~/.nexus/lib/mcp-server.js"],
+      "env": {
+        "NEXUS_BASE_PATH": "${workspaceFolder}/.nexus"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Installation Flow with Multi-Tool Support
+
+### Base Installation
+
+```bash
+# User installs NexusAgent
+curl -sSL https://nexus.nextsystems.ai/install.sh | bash
+
+# Creates ~/nexus/ with:
+# - All profiles
+# - Installation scripts
+# - Adapter templates
+```
+
+### Project Installation (Interactive)
+
+```bash
+cd /path/to/project
+~/nexus/scripts/install.sh
+
+# Interactive prompts:
+? Select profile: (Use arrow keys)
+  > default (Basic orchestration)
+    governance (Data governance)
+    content (Content creation)
+
+? Select AI tools to integrate: (Space to select, Enter to continue)
+  ◉ OpenCode
+  ◯ Cursor
+  ◯ Claude Desktop
+  ◯ Aider
+
+? Folder name for universal base:
+  > .nexus (recommended)
+    .agentos
+    .ai
+    
+# Installation proceeds...
+✓ Created .nexus/ with governance profile
+✓ Created .opencode/ adapter
+✓ Configured for OpenCode integration
+✓ 
+✓ Next steps:
+  1. Review .nexus/nexus.json for configuration
+  2. Try: /workflow "your request"
+```
+
+### Automated Installation (Non-Interactive)
+
+```bash
+# For CI/CD or automated setups
+~/nexus/scripts/install.sh \
+  --profile governance \
+  --tools opencode,cursor \
+  --base-folder .nexus \
+  --non-interactive
+
+# Or via config file
+~/nexus/scripts/install.sh --config nexus-install.yml
+```
+
+**Config file: `nexus-install.yml`**
+```yaml
+profile: governance
+tools:
+  - opencode
+  - cursor
+base_folder: .nexus
+features:
+  governance: true
+  workflows: true
+  context_level: 2
+```
+
+---
+
+## Adapter Generation System
+
+### Auto-Generate Adapters
+
+When installing, NexusAgent automatically generates tool-specific adapters based on templates.
+
+**Template: `~/nexus/adapters/opencode/command-template.md`**
+```markdown
+---
+name: {{command_name}}
+agent: {{agent_name}}
+description: "{{description}}"
+---
+
+# {{command_title}}
+
+You are executing {{command_name}} from NexusAgent.
+
+**Request:** $ARGUMENTS
+
+**Core Logic:**
+@../.nexus/agents/{{agent_path}}.md
+
+**Context Available:**
+{{#each context_files}}
+@../.nexus/context/{{this}}
+{{/each}}
+
+**Execute the {{command_type}} as defined in the core system.**
+```
+
+**Generation process:**
+```python
+def generate_opencode_adapter(profile, base_folder=".nexus"):
+    # Load profile configuration
+    profile_config = load_profile(profile)
+    
+    # Create .opencode/ structure
+    os.makedirs(".opencode/command", exist_ok=True)
+    os.makedirs(".opencode/agent/subagents", exist_ok=True)
+    
+    # Generate commands
+    for command in profile_config["commands"]:
+        template = load_template("opencode/command-template.md")
+        content = template.render(
+            command_name=command["name"],
+            agent_name=command["agent"],
+            agent_path=f"agents/{command['agent']}",
+            description=command["description"],
+            context_files=command.get("context", [])
+        )
+        write_file(f".opencode/command/{command['name']}.md", content)
+    
+    # Generate agent wrappers
+    for agent in profile_config["agents"]:
+        create_agent_wrapper(
+            agent_name=agent["name"],
+            source_path=f"../{base_folder}/agents/{agent['file']}",
+            dest_path=f".opencode/agent/subagents/{agent['name']}.md"
+        )
+```
+
+---
+
+## Configuration System
+
+### Global Config (`~/nexus/config.yml`)
+
+```yaml
+# NexusAgent Global Configuration
+version: "1.0.0"
+
+# Default installation preferences
+defaults:
+  profile: default
+  base_folder: .nexus
+  tools:
+    - opencode
+  context_level: 2
+
+# Tool-specific adapter settings
+adapters:
+  opencode:
+    enabled: true
+    folder: .opencode
+    structure:
+      commands: command
+      agents: agent/subagents
+    features:
+      skills: true
+      
+  cursor:
+    enabled: false
+    folder: .cursor
+    structure:
+      prompts: prompts
+      rules: rules
+      
+  claude:
+    enabled: false
+    folder: .claude
+    mcp_server: true
+```
+
+### Project Config (`.nexus/nexus.json`)
+
+```json
+{
+  "version": "1.0.0",
+  "profile": "governance",
+  "base_folder": ".nexus",
+  "tools": {
+    "opencode": {
+      "enabled": true,
+      "adapter_path": ".opencode",
+      "features": {
+        "skills": true,
+        "subagents": true
+      }
+    },
+    "cursor": {
+      "enabled": true,
+      "adapter_path": ".cursor"
+    }
+  },
+  "config": {
+    "context_level": 3,
+    "enable_governance": true
+  }
+}
+```
+
+### Adapter Config (`.nexus/adapters/opencode.yml`)
+
+```yaml
+# OpenCode Adapter Configuration
+tool: opencode
+version: "1.0.0"
+
+# Folder structure mapping
+folders:
+  commands: .opencode/command
+  agents: .opencode/agent/subagents
+  context: .nexus/context  # Shared
+
+# Command mappings
+commands:
+  - name: workflow
+    agent: main-orchestrator
+    context:
+      - core/essential-patterns.md
+      - architecture/project-structure.md
+      
+  - name: review
+    agent: code-reviewer
+    context:
+      - standards/code-quality.md
+
+# Agent mappings
+agents:
+  - name: code-reviewer
+    source: .nexus/agents/specialists/code-reviewer.md
+    wrapper: true  # Create thin wrapper
+    
+  - name: quality-validator
+    source: .nexus/agents/specialists/quality-validator.md
+    wrapper: true
+```
+
+---
+
+## Benefits of This Architecture
+
+### 1. **Tool Agnostic Core**
+- Universal base (`.nexus/`) works with any AI tool
+- Easy to add support for new tools
+- Core logic not tied to any specific tool
+
+### 2. **Easy Migration**
+```bash
+# Switching from OpenCode to Cursor
+~/nexus/scripts/add-tool.sh cursor
+
+# Removes nothing from .nexus/
+# Just adds .cursor/ adapter
+# Both tools can work simultaneously
+```
+
+### 3. **Clean Separation**
+- **`.nexus/`** = System logic, context, governance
+- **`.opencode/`** = OpenCode-specific commands/format
+- **`.cursor/`** = Cursor-specific prompts/rules
+- No duplication, no confusion
+
+### 4. **Profile Portability**
+```bash
+# Export your profile
+~/nexus/scripts/export-profile.sh my-project-profile
+
+# Creates: ~/.nexus/profiles/my-project-profile/
+# Can be shared and installed on any tool
+```
+
+### 5. **Gradual Adoption**
+```bash
+# Start with just .nexus/ (universal)
+~/nexus/scripts/install.sh --profile default --tools none
+
+# Add OpenCode later
+~/nexus/scripts/add-tool.sh opencode
+
+# Add Cursor when needed
+~/nexus/scripts/add-tool.sh cursor
+```
+
+---
+
+## Implementation Scripts
+
+### Main Install Script
+
+```bash
+#!/bin/bash
+# ~/nexus/scripts/install.sh
+
+set -e
+
+PROFILE="${1:-default}"
+TOOLS="${2:-opencode}"
+BASE_FOLDER="${3:-.nexus}"
+INTERACTIVE="${4:-true}"
+
+if [ "$INTERACTIVE" = "true" ]; then
+    # Interactive prompts
+    select_profile
+    select_tools
+    select_base_folder
+fi
+
+echo "📦 Installing NexusAgent..."
+echo "   Profile: $PROFILE"
+echo "   Tools: $TOOLS"
+echo "   Base: $BASE_FOLDER"
+echo ""
+
+# Create base structure
+create_base_structure "$BASE_FOLDER" "$PROFILE"
+
+# Generate tool adapters
+IFS=',' read -ra TOOL_ARRAY <<< "$TOOLS"
+for tool in "${TOOL_ARRAY[@]}"; do
+    generate_adapter "$tool" "$BASE_FOLDER" "$PROFILE"
+done
+
+# Create configuration
+create_config "$BASE_FOLDER" "$PROFILE" "$TOOLS"
+
+echo "✅ NexusAgent installed successfully!"
+echo ""
+echo "📚 Next steps:"
+echo "   1. Review $BASE_FOLDER/nexus.json"
+if [[ " ${TOOL_ARRAY[@]} " =~ " opencode " ]]; then
+    echo "   2. Try: /workflow \"your request\""
+fi
+```
+
+### Add Tool Script
+
+```bash
+#!/bin/bash
+# ~/nexus/scripts/add-tool.sh
+
+TOOL="$1"
+BASE_FOLDER="${2:-.nexus}"
+
+if [ -z "$TOOL" ]; then
+    echo "Usage: add-tool.sh <tool> [base-folder]"
+    echo "Available tools: opencode, cursor, claude, aider"
+    exit 1
+fi
+
+# Load current config
+PROFILE=$(jq -r '.profile' "$BASE_FOLDER/nexus.json")
+
+echo "🔧 Adding $TOOL adapter..."
+
+# Generate adapter
+generate_adapter "$TOOL" "$BASE_FOLDER" "$PROFILE"
+
+# Update config
+update_config_add_tool "$BASE_FOLDER" "$TOOL"
+
+echo "✅ $TOOL adapter added!"
+echo "   Folder: .$(echo $TOOL | tr '[:upper:]' '[:lower:]')/"
+```
+
+---
+
+## Updated Directory Structure
+
+### After Installation (Multiple Tools)
+
+```
+project/
+├── .nexus/                      # Universal base
+│   ├── nexus.json
+│   ├── agents/
+│   │   ├── main-orchestrator.md
+│   │   ├── context-provider.md
+│   │   └── specialists/
+│   ├── context/
+│   │   ├── core/
+│   │   ├── domain/
+│   │   └── standards/
+│   ├── workflows/
+│   ├── governance/
+│   │   ├── metadata-index.json
+│   │   └── tmp/requests/
+│   └── adapters/
+│       ├── opencode.yml
+│       └── cursor.yml
+│
+├── .opencode/                   # OpenCode adapter
+│   ├── command/
+│   │   ├── workflow.md         # → .nexus/agents/main-orchestrator.md
+│   │   └── review.md           # → .nexus/agents/specialists/code-reviewer.md
+│   └── agent/subagents/
+│       └── quality-validator.md # → .nexus/agents/specialists/quality-validator.md
+│
+└── .cursor/                     # Cursor adapter
+    ├── prompts/
+    │   ├── workflow.md         # → .nexus/agents/main-orchestrator.md
+    │   └── review.md           # → .nexus/agents/specialists/code-reviewer.md
+    └── rules/
+        └── nexus-rules.md
+```
+
+---
+
+## Migration Path
+
+For users with existing setups:
+
+```bash
+# From existing .opencode/ to universal .nexus/
+~/nexus/scripts/migrate.sh --from .opencode --to .nexus
+
+# Detects:
+# - Existing agents in .opencode/agent/
+# - Existing commands in .opencode/command/
+# - Existing context in .opencode/context/
+
+# Migrates:
+# 1. Moves core logic to .nexus/
+# 2. Creates adapters in .opencode/ (thin wrappers)
+# 3. Updates all references
+# 4. Creates backup before migration
+```
+
+---
+
+## Recommendation
+
+**Go with the Universal Base + Adapter pattern:**
+
+1. **`.nexus/`** = Core system (agents, context, governance)
+2. **`.opencode/`, `.cursor/`, etc.** = Tool-specific adapters
+3. **Auto-generation** = Scripts create adapters from templates
+4. **Easy migration** = Switch tools without losing work
+
+This gives us:
+- ✅ Maximum flexibility
+- ✅ Tool independence
+- ✅ Easy multi-tool support
+- ✅ Clean separation of concerns
+- ✅ Future-proof architecture
+
+**Next step:** Update the master plan to incorporate this approach?

.Building/planning/archive/03-SIMPLIFIED-ARCHITECTURE.md

@@ -0,0 +1,448 @@
+# NexusAgent - Simplified OpenCode-First Architecture
+**Version:** 1.0  
+**Date:** 2025-10-29  
+**Philosophy:** OpenCode first, other tools optional via shared core
+
+---
+
+## Core Principle
+
+**Primary:** Build for OpenCode (the best tool)  
+**Secondary:** Share core context/governance with other tools if they can use it  
+**No Maintenance Burden:** Don't maintain tool-specific versions
+
+---
+
+## Simplified Structure
+
+```
+project/
+└── .opencode/                   # PRIMARY - OpenCode standard
+    ├── agent/
+    │   ├── main-orchestrator.md
+    │   ├── context-provider.md
+    │   └── subagents/
+    │       ├── code-reviewer.md
+    │       ├── quality-validator.md
+    │       └── content-creator.md
+    │
+    ├── command/
+    │   ├── workflow.md
+    │   ├── plan-task.md
+    │   └── execute-task.md
+    │
+    ├── context/                 # SHARED - Other tools can read this
+    │   ├── core/
+    │   ├── domain/
+    │   ├── processes/
+    │   └── standards/
+    │
+    ├── governance/              # SHARED - Universal governance
+    │   ├── metadata-index.json
+    │   ├── workflow-state.json
+    │   └── tmp/requests/
+    │
+    └── nexus.json              # Configuration
+```
+
+**Key Insight:** Other AI tools can READ `.opencode/context/` and `.opencode/governance/` if they're compatible. We don't maintain separate versions.
+
+---
+
+## How Other Tools Can Use It (Optional)
+
+### Option 1: Read Shared Context (Zero Maintenance)
+
+```
+project/
+├── .opencode/                   # OpenCode uses this
+│   ├── agent/
+│   ├── command/
+│   ├── context/                ← Cursor can read this!
+│   └── governance/             ← Cursor can read this!
+│
+└── .cursor/                     # User creates if they want
+    ├── prompts/
+    │   └── workflow.md          # Points to: ../.opencode/context/
+    └── rules.md
+```
+
+**Cursor prompt example (user-created):**
+```markdown
+# Workflow
+
+Load context from `.opencode/context/core/`
+
+Follow patterns defined there.
+
+[Rest of prompt]
+```
+
+### Option 2: Smart Installer Detects Tools (Optional)
+
+```bash
+# User runs installer
+~/nexus/scripts/install.sh --profile governance
+
+# Installer detects:
+✓ Found .cursor/ folder
+? Also create Cursor-compatible structure? (Y/n)
+
+# If yes:
+✓ Created .opencode/ (primary)
+✓ Created .cursor/prompts/ pointing to .opencode/context/
+ℹ  Cursor can now read shared context
+```
+
+### Option 3: Manual Bridge Script (Optional, User-run)
+
+```bash
+# User wants to use Cursor too
+~/nexus/scripts/bridge-to-cursor.sh
+
+# Creates minimal .cursor/ structure:
+# .cursor/
+# └── prompts/
+#     └── shared-context.md  # Points to .opencode/context/
+
+✓ Bridge created
+ℹ  Cursor prompts can now reference .opencode/context/
+```
+
+---
+
+## Installation Philosophy
+
+### Primary Flow (OpenCode)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/nextsystems/nexus/main/scripts/install.sh | bash
+cd my-project
+~/nexus/scripts/install.sh --profile governance
+
+# Creates:
+# .opencode/
+# ├── agent/
+# ├── command/
+# ├── context/
+# └── governance/
+
+# That's it! 
+```
+
+### Optional Secondary Tools
+
+**We don't maintain them, but we make it easy:**
+
+```bash
+# IF user wants Cursor support:
+~/nexus/scripts/optional/bridge-cursor.sh
+
+# Creates minimal bridge
+# User can customize from there
+```
+
+---
+
+## What We Build & Maintain
+
+### ✅ We Build (OpenCode Only)
+
+1. **Installation Scripts**
+   - `install.sh` - Install to `~/nexus/`
+   - `project-install.sh` - Install `.opencode/` into project
+   - Profile system for OpenCode
+
+2. **OpenCode Profiles**
+   - Default profile (basic orchestration)
+   - Governance profile (data governance)
+   - Content profile (content creation)
+
+3. **OpenCode Agents**
+   - Main orchestrator
+   - Context provider
+   - Governance agents
+   - Specialized subagents
+
+4. **Shared Context System**
+   - Context files (other tools CAN read)
+   - Governance system (other tools CAN read)
+   - Request ID protocol (other tools CAN use)
+
+### ⚠️ We Don't Build (User Optional)
+
+1. **Cursor-specific prompts** - User can create if they want
+2. **Claude Desktop configs** - User can set up if they want
+3. **Aider configs** - User can configure if they want
+
+### 🎁 We Provide (Optional Helpers)
+
+1. **Bridge Scripts** (optional, user-run)
+   - `optional/bridge-cursor.sh`
+   - `optional/bridge-claude.sh`
+   - `optional/bridge-aider.sh`
+
+2. **Examples** (documentation)
+   - "How to use with Cursor" (example prompt that reads `.opencode/context/`)
+   - "How to use with Claude" (example MCP config)
+   - User adapts to their needs
+
+---
+
+## Updated Installation Script Design
+
+```bash
+#!/bin/bash
+# ~/nexus/scripts/install.sh
+
+set -e
+
+PROFILE="${1:-default}"
+DETECT_OTHER_TOOLS="${2:-true}"
+
+echo "🚀 Installing NexusAgent for OpenCode..."
+echo "   Profile: $PROFILE"
+echo ""
+
+# Create .opencode/ structure
+create_opencode_structure "$PROFILE"
+
+echo "✅ NexusAgent installed for OpenCode!"
+echo ""
+
+# Optional: Detect other tools
+if [ "$DETECT_OTHER_TOOLS" = "true" ]; then
+    if [ -d ".cursor" ]; then
+        echo "ℹ️  Detected .cursor/ folder"
+        echo "   You can create a bridge to share context:"
+        echo "   ~/nexus/scripts/optional/bridge-cursor.sh"
+        echo ""
+    fi
+    
+    if [ -d ".claude" ]; then
+        echo "ℹ️  Detected .claude/ folder"
+        echo "   You can configure Claude to read .opencode/context/"
+        echo "   See: ~/nexus/docs/claude-integration.md"
+        echo ""
+    fi
+fi
+
+echo "📚 Next steps:"
+echo "   1. Try: /workflow \"your request\""
+echo "   2. Configure: .opencode/nexus.json"
+echo "   3. Read: ~/nexus/docs/getting-started.md"
+```
+
+---
+
+## Directory Structure (Actual Build)
+
+### What We Actually Create
+
+```
+~/nexus/                         # Base installation
+├── README.md
+├── LICENSE
+├── install.sh                   # Main installer
+├── scripts/
+│   ├── install.sh              # Project installer (creates .opencode/)
+│   ├── update.sh
+│   └── optional/               # Optional bridge scripts
+│       ├── bridge-cursor.sh
+│       ├── bridge-claude.sh
+│       └── README.md
+│
+├── profiles/
+│   ├── default/
+│   │   ├── agent/
+│   │   ├── command/
+│   │   └── context/
+│   ├── governance/
+│   │   ├── agent/
+│   │   ├── command/
+│   │   ├── context/
+│   │   └── governance/
+│   └── content/
+│       ├── agent/
+│       ├── command/
+│       └── context/
+│
+└── docs/
+    ├── getting-started.md
+    ├── profiles.md
+    ├── opencode-usage.md
+    └── optional/
+        ├── cursor-integration.md      # Example, not automated
+        ├── claude-integration.md      # Example, not automated
+        └── aider-integration.md       # Example, not automated
+```
+
+### What Gets Installed in Project
+
+```
+project/
+└── .opencode/                   # Standard OpenCode structure
+    ├── nexus.json              # NexusAgent config
+    │
+    ├── agent/                   # OpenCode agents
+    │   ├── main-orchestrator.md
+    │   ├── context-provider.md
+    │   └── subagents/
+    │       └── *.md
+    │
+    ├── command/                 # OpenCode commands
+    │   ├── workflow.md
+    │   ├── plan-task.md
+    │   └── *.md
+    │
+    ├── context/                 # SHARED - other tools can read
+    │   ├── core/
+    │   ├── domain/
+    │   ├── processes/
+    │   └── standards/
+    │
+    └── governance/              # SHARED - other tools can read
+        ├── metadata-index.json
+        ├── workflow-state.json
+        └── tmp/requests/
+```
+
+---
+
+## Optional Bridge Script (Example)
+
+**File:** `~/nexus/scripts/optional/bridge-cursor.sh`
+
+```bash
+#!/bin/bash
+# Optional bridge for Cursor users
+
+set -e
+
+if [ ! -d ".opencode" ]; then
+    echo "❌ No .opencode/ folder found"
+    echo "   Run: ~/nexus/scripts/install.sh first"
+    exit 1
+fi
+
+echo "🌉 Creating Cursor bridge to NexusAgent..."
+
+mkdir -p .cursor/prompts
+
+cat > .cursor/prompts/nexus-workflow.md << 'EOF'
+# NexusAgent Workflow (via shared context)
+
+You are using NexusAgent context-aware orchestration.
+
+## Context Available
+All context from `.opencode/context/` is available:
+- Core patterns: `.opencode/context/core/`
+- Domain knowledge: `.opencode/context/domain/`
+- Workflows: `.opencode/context/processes/`
+- Standards: `.opencode/context/standards/`
+
+## Governance
+Quality metadata available at: `.opencode/governance/metadata-index.json`
+
+## Your Task
+[Cursor AI will use this prompt with access to shared context]
+
+Follow the patterns and standards defined in the shared context.
+EOF
+
+echo "✅ Cursor bridge created!"
+echo ""
+echo "📝 Created:"
+echo "   .cursor/prompts/nexus-workflow.md"
+echo ""
+echo "ℹ️  Cursor can now reference shared context from .opencode/"
+echo "   Edit .cursor/prompts/ to customize for your needs"
+```
+
+---
+
+## Benefits of This Approach
+
+### ✅ Simple to Build
+- Focus on OpenCode (95% of our effort)
+- Clean, standard OpenCode structure
+- No complexity of multiple tool versions
+
+### ✅ Simple to Maintain
+- One codebase (OpenCode)
+- Context is naturally shareable (just markdown)
+- Governance is naturally shareable (JSON files)
+
+### ✅ Optional Flexibility
+- Users can bridge to other tools if they want
+- We provide helpers, not full implementations
+- No maintenance burden for us
+
+### ✅ Best of Both Worlds
+- Primary tool (OpenCode) is fully supported
+- Other tools can leverage shared context
+- Users who want multi-tool can set it up
+
+---
+
+## Development Priorities
+
+### Phase 1: Core OpenCode System (Week 1-3)
+```
+✅ Focus: Perfect OpenCode experience
+✅ Build: Full profiles, agents, governance
+✅ Test: With real OpenCode projects
+```
+
+### Phase 2: Documentation (Week 4)
+```
+✅ Document: OpenCode usage (primary)
+✅ Document: How to share context with other tools (examples)
+✅ Create: Optional bridge scripts (minimal)
+```
+
+### Phase 3: Polish & Launch (Week 5-6)
+```
+✅ Test: Installation process
+✅ Polish: Error handling, UX
+✅ Launch: GitHub repo public
+```
+
+---
+
+## Updated Key Decisions
+
+1. **Primary:** OpenCode (full support, all features)
+2. **Secondary:** Shareable context/governance (read-only by other tools)
+3. **Optional:** Bridge scripts (user-run, minimal maintenance)
+4. **Focus:** Build the best OpenCode experience possible
+
+---
+
+## This Means...
+
+### We Build:
+- ✅ Perfect OpenCode integration
+- ✅ Installable profiles for OpenCode
+- ✅ Shareable context system
+- ✅ Shareable governance system
+- ✅ Optional bridge helpers
+
+### We Don't Build:
+- ❌ Full Cursor integration (users can bridge if they want)
+- ❌ Full Claude integration (users can bridge if they want)
+- ❌ Multiple maintained versions
+- ❌ Complex adapter system
+
+### Result:
+- 🎯 Clean, focused codebase
+- 🚀 Fast development
+- 🎨 Easy maintenance
+- 🌟 Best OpenCode experience
+- 🔗 Optional multi-tool via shared context
+
+---
+
+**Recommendation:** This is the way. Build for OpenCode, make context shareable, let users bridge to other tools if they want.
+
+**Ready to update the master plan and start building?**

.Building/planning/archive/FINAL-ARCHITECTURE-DECISION.md

@@ -0,0 +1,96 @@
+# NexusAgent - Final Architecture Decision
+
+**Date:** 2025-10-29  
+**Status:** APPROVED FOR BUILD  
+**Decision:** OpenCode-First with Shareable Core
+
+---
+
+## The Decision
+
+**Build for OpenCode primarily, make context shareable secondarily.**
+
+### What This Means
+
+```
+.opencode/                       # PRIMARY - Full NexusAgent for OpenCode
+├── agent/                      # OpenCode agents (full support)
+├── command/                    # OpenCode commands (full support)
+├── context/                    # SHAREABLE - other tools can read
+└── governance/                 # SHAREABLE - other tools can read
+```
+
+**OpenCode:** Full feature support, all profiles, complete integration  
+**Other Tools:** Can read shared context/governance if compatible (user configures)
+
+---
+
+## Why This Approach
+
+1. **Focus:** 95% effort on making OpenCode experience perfect
+2. **Simple:** No multi-tool maintenance burden
+3. **Flexible:** Context naturally shareable (markdown + JSON)
+4. **Clean:** Standard OpenCode structure
+5. **Optional:** Users can bridge to other tools via shared context
+
+---
+
+## What We Build
+
+### Core System (OpenCode)
+- ✅ Installation scripts
+- ✅ Three profiles (default, governance, content)
+- ✅ Full agent system
+- ✅ Context-aware orchestration
+- ✅ Data governance system
+- ✅ Complete documentation
+
+### Optional Helpers
+- ✅ Bridge scripts (cursor, claude, aider)
+- ✅ Integration examples
+- ✅ User can adapt as needed
+
+---
+
+## What We Don't Build
+
+- ❌ Full Cursor integration
+- ❌ Full Claude integration  
+- ❌ Multiple maintained versions
+- ❌ Complex adapter system
+
+---
+
+## Repository Structure
+
+```
+nextsystems/nexus/
+├── scripts/
+│   ├── install.sh              # Main installer
+│   └── optional/
+│       └── bridge-*.sh         # Optional bridges
+├── profiles/
+│   ├── default/
+│   ├── governance/
+│   └── content/
+└── docs/
+    ├── opencode-usage.md       # Primary docs
+    └── optional/
+        └── *-integration.md    # Examples
+```
+
+---
+
+## Next: Start Building
+
+Now that architecture is finalized, let's build:
+
+1. Create GitHub repository
+2. Build installation scripts
+3. Build default profile
+4. Build governance profile
+5. Build content profile
+6. Test & document
+7. Launch!
+
+**Estimated:** 6 weeks to v1.0

.Building/planning/archive/PROJECT-STRUCTURE.md

@@ -0,0 +1,563 @@
+# Project Structure & Architecture
+**For: NexusAgent / MindStack**
+
+---
+
+## Complete Repository Structure
+
+```
+nexus/                                 # Main repository
+├── README.md                         # Project overview
+├── LICENSE                           # MIT License
+├── CONTRIBUTING.md                   # Contribution guidelines
+├── CHANGELOG.md                      # Version history
+├── .github/
+│   ├── workflows/
+│   │   ├── release.yml              # Auto-release on tag
+│   │   ├── test.yml                 # Test profiles on PR
+│   │   └── docs.yml                 # Deploy docs site
+│   └── ISSUE_TEMPLATE/
+│       ├── bug_report.md
+│       ├── feature_request.md
+│       └── profile_request.md
+│
+├── scripts/                          # Installation & management
+│   ├── base-install.sh              # Install to ~/nexus
+│   ├── project-install.sh           # Install into project
+│   ├── update.sh                    # Update installation
+│   ├── create-profile.sh            # Create custom profile
+│   ├── validate-profile.sh          # Validate profile structure
+│   └── lib/                         # Shared script functions
+│       ├── colors.sh                # Terminal colors
+│       ├── validation.sh            # Validation functions
+│       └── profiles.sh              # Profile management
+│
+├── profiles/                         # Pre-built profiles
+│   ├── default/                     # Basic development workflow
+│   │   ├── profile.yml             # Profile metadata
+│   │   ├── agents/
+│   │   │   ├── workflow-orchestrator.md
+│   │   │   ├── task-planner.md
+│   │   │   ├── task-executor.md
+│   │   │   └── subagents/
+│   │   │       ├── code-reviewer.md
+│   │   │       ├── test-writer.md
+│   │   │       └── doc-writer.md
+│   │   ├── commands/
+│   │   │   ├── workflow.md
+│   │   │   ├── plan-task.md
+│   │   │   ├── execute-task.md
+│   │   │   ├── review.md
+│   │   │   └── test.md
+│   │   ├── context/
+│   │   │   ├── core/
+│   │   │   │   └── essential-patterns.md
+│   │   │   ├── architecture/
+│   │   │   │   └── project-structure.md
+│   │   │   └── workflows/
+│   │   │       ├── simple-task.md
+│   │   │       └── complex-feature.md
+│   │   └── README.md               # Profile documentation
+│   │
+│   ├── content/                     # Content orchestration
+│   │   ├── profile.yml
+│   │   ├── agents/
+│   │   │   ├── content-orchestrator.md
+│   │   │   ├── context-provider.md
+│   │   │   ├── research-assistant.md
+│   │   │   └── subagents/
+│   │   │       ├── twitter-specialist.md
+│   │   │       ├── linkedin-specialist.md
+│   │   │       ├── blog-specialist.md
+│   │   │       ├── youtube-specialist.md
+│   │   │       ├── buyer-hook-validator.md
+│   │   │       ├── value-compressor.md
+│   │   │       ├── contrarian-refiner.md
+│   │   │       ├── content-validator.md
+│   │   │       └── content-publisher.md
+│   │   ├── commands/
+│   │   │   ├── create-content-dynamic.md
+│   │   │   ├── new-project.md
+│   │   │   ├── work-on.md
+│   │   │   ├── validate.md
+│   │   │   └── publish.md
+│   │   ├── context/
+│   │   │   ├── brand/
+│   │   │   │   ├── voice.md
+│   │   │   │   ├── guidelines.md
+│   │   │   │   ├── messaging.md
+│   │   │   │   └── accuracy-guidelines.md
+│   │   │   ├── platforms/
+│   │   │   │   ├── twitter/
+│   │   │   │   │   ├── specs.md
+│   │   │   │   │   └── patterns.md
+│   │   │   │   ├── linkedin/
+│   │   │   │   ├── blog/
+│   │   │   │   └── youtube/
+│   │   │   ├── workflows/
+│   │   │   │   ├── quick-post.md
+│   │   │   │   ├── multi-platform.md
+│   │   │   │   ├── research-enhanced.md
+│   │   │   │   └── campaign-launch.md
+│   │   │   └── review/
+│   │   │       ├── checklists.md
+│   │   │       └── engagement-signals.md
+│   │   └── README.md
+│   │
+│   ├── governance/                  # Data governance & context management
+│   │   ├── profile.yml
+│   │   ├── agents/
+│   │   │   ├── context-manager.md
+│   │   │   └── subagents/
+│   │   │       ├── quality-validator.md
+│   │   │       ├── lifecycle-manager.md
+│   │   │       ├── metadata-updater.md
+│   │   │       └── catalog-maintainer.md
+│   │   ├── commands/
+│   │   │   ├── get-context.md
+│   │   │   ├── update-context.md
+│   │   │   ├── validate-quality.md
+│   │   │   ├── lifecycle-review.md
+│   │   │   └── sync-metadata.md
+│   │   ├── context/
+│   │   │   ├── governance/
+│   │   │   │   ├── metadata-schema.md
+│   │   │   │   ├── quality-dimensions.md
+│   │   │   │   ├── lifecycle-states.md
+│   │   │   │   └── sync-strategies.md
+│   │   │   └── workflows/
+│   │   │       ├── context-retrieval.md
+│   │   │       ├── context-update.md
+│   │   │       ├── quality-validation.md
+│   │   │       └── lifecycle-management.md
+│   │   └── README.md
+│   │
+│   └── custom-example/               # Example custom profile
+│       ├── profile.yml
+│       ├── agents/
+│       ├── commands/
+│       ├── context/
+│       └── README.md
+│
+├── templates/                        # Templates for custom creation
+│   ├── profile/
+│   │   ├── profile.yml.template
+│   │   └── README.md.template
+│   ├── agent/
+│   │   ├── primary-agent.md.template
+│   │   └── subagent.md.template
+│   ├── command/
+│   │   └── command.md.template
+│   ├── context/
+│   │   └── context-file.md.template
+│   └── workflow/
+│       └── workflow.md.template
+│
+├── docs/                             # Documentation site
+│   ├── index.md                     # Homepage
+│   ├── getting-started/
+│   │   ├── installation.md
+│   │   ├── quick-start.md
+│   │   └── first-workflow.md
+│   ├── core-concepts/
+│   │   ├── architecture.md
+│   │   ├── context-flow.md
+│   │   ├── agent-coordination.md
+│   │   └── profiles.md
+│   ├── profiles/
+│   │   ├── default.md
+│   │   ├── content.md
+│   │   ├── governance.md
+│   │   └── custom.md
+│   ├── guides/
+│   │   ├── creating-custom-profile.md
+│   │   ├── writing-agents.md
+│   │   ├── writing-commands.md
+│   │   ├── context-management.md
+│   │   └── workflow-orchestration.md
+│   ├── reference/
+│   │   ├── cli.md
+│   │   ├── configuration.md
+│   │   ├── profile-schema.md
+│   │   └── api.md
+│   ├── examples/
+│   │   ├── development-workflow.md
+│   │   ├── content-creation.md
+│   │   ├── data-governance.md
+│   │   └── custom-domain.md
+│   └── contributing.md
+│
+├── examples/                         # Example projects
+│   ├── basic-dev-workflow/
+│   │   ├── .nexus/                 # Installed profile
+│   │   └── README.md
+│   ├── content-marketing/
+│   │   ├── .nexus/
+│   │   └── README.md
+│   └── data-governance/
+│       ├── .nexus/
+│       └── README.md
+│
+├── tests/                           # Testing
+│   ├── profiles/
+│   │   ├── test-default.sh
+│   │   ├── test-content.sh
+│   │   └── test-governance.sh
+│   ├── scripts/
+│   │   ├── test-install.sh
+│   │   └── test-validation.sh
+│   └── fixtures/
+│       └── sample-projects/
+│
+├── config.example.yml               # Example configuration
+└── package.json                     # Optional: for npm distribution
+```
+
+---
+
+## File Structure Standards
+
+### Profile Structure (`profiles/{profile-name}/`)
+
+Every profile must have:
+
+```
+profile-name/
+├── profile.yml          # REQUIRED: Profile metadata
+├── agents/             # REQUIRED: At least one agent
+│   └── *.md
+├── commands/           # REQUIRED: At least one command
+│   └── *.md
+├── context/            # REQUIRED: Context files
+│   └── *.md
+└── README.md           # REQUIRED: Profile documentation
+```
+
+### `profile.yml` Schema
+
+```yaml
+name: "Profile Name"
+version: "1.0.0"
+description: "Brief description of what this profile does"
+author: "Author Name"
+homepage: "https://profile-docs-url.com"
+
+# Profile capabilities
+capabilities:
+  - content-creation
+  - data-governance
+  - code-review
+  - testing
+
+# AI tool compatibility
+compatible_with:
+  - opencode
+  - cursor
+  - claude-desktop
+
+# Dependencies (other profiles this extends)
+extends: 
+  - default
+
+# Configuration defaults
+config:
+  context_level: 2
+  enable_subagents: true
+  enable_workflows: true
+
+# Installation preferences
+install:
+  folder_name: ".nexus"
+  create_examples: true
+  required_tools:
+    - git
+    - node  # optional
+
+# Documentation
+documentation:
+  quick_start: "README.md"
+  examples: "examples/"
+  
+# Changelog
+changelog:
+  - version: "1.0.0"
+    date: "2025-01-15"
+    changes:
+      - "Initial release"
+```
+
+---
+
+## Installation Flow Architecture
+
+### Base Installation (`~/nexus/`)
+
+```mermaid
+graph TD
+    A[User runs curl] --> B[Download base-install.sh]
+    B --> C[Check if ~/nexus exists]
+    C -->|No| D[Create ~/nexus]
+    C -->|Yes| E{Backup?}
+    E -->|Yes| F[Backup to ~/nexus.backup.TIMESTAMP]
+    E -->|No| G[Exit]
+    F --> D
+    D --> H[Clone/download repository]
+    H --> I[Copy config.example.yml to config.yml]
+    I --> J[Make scripts executable]
+    J --> K[Show success message]
+```
+
+### Project Installation (`~/nexus/` → `project/.nexus/`)
+
+```mermaid
+graph TD
+    A[User runs project-install.sh] --> B[Parse CLI arguments]
+    B --> C[Load config.yml]
+    C --> D[Validate profile exists]
+    D -->|No| E[Error: Profile not found]
+    D -->|Yes| F[Show installation plan]
+    F --> G{Dry run?}
+    G -->|Yes| H[Show what would be created]
+    G -->|No| I[Check if .nexus exists]
+    I -->|Yes| J{Backup?}
+    I -->|No| K[Create .nexus/]
+    J -->|Yes| L[Backup to .nexus.backup.TIMESTAMP]
+    J -->|No| M[Error: Already exists]
+    L --> K
+    K --> N[Copy profile files]
+    N --> O[Generate configuration]
+    O --> P[Create README.md]
+    P --> Q[Run post-install hooks]
+    Q --> R[Show success message]
+```
+
+---
+
+## Configuration System
+
+### Global Config (`~/nexus/config.yml`)
+
+```yaml
+# Nexus Configuration
+version: "1.0.0"
+
+# User preferences
+user:
+  name: "Your Name"
+  email: "your@email.com"
+
+# Default installation settings
+defaults:
+  profile: "default"
+  ai_tool: "opencode"
+  folder_name: ".nexus"
+  context_level: 2
+  enable_subagents: true
+  backup_existing: true
+
+# Profile-specific overrides
+profiles:
+  content:
+    context_level: 2
+    enable_research: true
+    auto_validate: true
+  governance:
+    context_level: 3
+    enable_metadata_sync: true
+    sync_schedule: "0 2 * * *"
+  default:
+    context_level: 1
+
+# AI tool integration settings
+ai_tools:
+  opencode:
+    commands_folder: "command"
+    agents_folder: "agent/subagents"
+    context_folder: "context"
+    use_skills: true
+    skill_prefix: "@"
+  cursor:
+    prompts_folder: ".cursor/prompts"
+    agents_folder: ".cursor/agents"
+    context_folder: ".cursor/context"
+    use_skills: false
+  claude_desktop:
+    config_path: "~/Library/Application Support/Claude/claude_desktop_config.json"
+    mcp_servers: true
+
+# Advanced settings
+advanced:
+  verbose_logging: false
+  telemetry: false  # Privacy-first
+  auto_update_check: true
+  update_channel: "stable"  # stable, beta, nightly
+
+# Installation behavior
+install:
+  create_examples: true
+  create_docs: true
+  run_validation: true
+  show_tips: true
+```
+
+### Project Config (`.nexus/nexus.json`)
+
+```json
+{
+  "version": "1.0.0",
+  "profile": "content",
+  "ai_tool": "opencode",
+  "installed_at": "2025-01-15T10:30:00Z",
+  "nexus_version": "1.0.0",
+  "custom_config": {
+    "context_level": 2,
+    "enable_subagents": true
+  },
+  "metadata": {
+    "project_name": "My Content Project",
+    "project_type": "content-marketing",
+    "team_size": 1
+  }
+}
+```
+
+---
+
+## CLI Command Structure
+
+### Base Commands
+
+```bash
+# Installation
+nexus install [options]              # Install into current directory
+nexus install --profile content      # Install specific profile
+nexus install --dry-run              # Preview installation
+
+# Management
+nexus update                          # Update installation
+nexus uninstall                       # Remove from project
+nexus validate                        # Validate installation
+
+# Profile Management
+nexus list-profiles                   # List available profiles
+nexus create-profile <name>          # Create custom profile
+nexus show-profile <name>            # Show profile details
+nexus validate-profile <name>        # Validate profile structure
+
+# Configuration
+nexus config                          # Show current config
+nexus config set <key> <value>       # Set config value
+nexus config get <key>               # Get config value
+
+# Development
+nexus dev                            # Development mode
+nexus test-profile <name>            # Test profile
+
+# Help
+nexus help                           # Show help
+nexus version                        # Show version
+nexus docs                           # Open documentation
+```
+
+### Advanced Commands
+
+```bash
+# Profile development
+nexus scaffold agent <name>          # Create agent template
+nexus scaffold command <name>        # Create command template
+nexus scaffold context <name>        # Create context template
+
+# Import/Export
+nexus export-profile <name>          # Export profile to .tar.gz
+nexus import-profile <path>          # Import profile from file
+
+# Analytics (privacy-respecting)
+nexus stats                          # Show usage statistics
+nexus report                         # Generate usage report
+```
+
+---
+
+## Integration with Different AI Tools
+
+### OpenCode Integration
+
+```bash
+# Project structure after installation
+.nexus/
+├── agent/                    # OpenCode agents folder
+│   ├── workflow-orchestrator.md
+│   └── subagents/
+├── command/                  # OpenCode commands folder
+│   ├── workflow.md
+│   └── create.md
+└── context/                  # Context files
+    └── core/
+
+# Usage
+/workflow "create a feature"
+@workflow-orchestrator "analyze this"
+```
+
+### Cursor Integration
+
+```bash
+# Project structure after installation
+.cursor/
+├── prompts/                  # Cursor prompts folder
+│   ├── workflow.md
+│   └── create.md
+└── agents/                   # Custom agents
+    └── orchestrator.md
+
+# Usage
+@workflow create a feature
+```
+
+### Claude Desktop Integration
+
+```bash
+# Adds to claude_desktop_config.json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "node",
+      "args": ["/path/to/nexus-mcp-server.js"],
+      "env": {
+        "NEXUS_PROJECT_PATH": "/path/to/project/.nexus"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Next Steps to Build
+
+1. **Initialize repository** with this structure
+2. **Create installation scripts** (base-install.sh, project-install.sh)
+3. **Build default profile** first (simplest, most universal)
+4. **Build content profile** (your documented use case)
+5. **Build governance profile** (your documented use case)
+6. **Create documentation site**
+7. **Test with real projects**
+8. **Launch!**
+
+---
+
+## Repository Name Options
+
+Based on chosen name:
+
+**If NexusAgent:**
+- `nextsystems/nexus` ⭐
+- `nextsystems/nexusagent`
+- `nexus-ai/nexus`
+
+**If MindStack:**
+- `mysecondminds/mindstack` ⭐
+- `mysecondminds/stack`
+- `mindstack/mindstack`
+
+**Recommendation:** Use the shorter version for GitHub (e.g., `nexus` or `mindstack`)