@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/GOAL_STATE_ARCHITECTURE.md

@@ -0,0 +1,395 @@
+# Nexus Agent System - Goal State Architecture
+
+*Defining the ideal architecture for how agents interact with the Nexus ecosystem.*
+
+---
+
+## Executive Summary
+
+This document captures the ideal end-state architecture for the Nexus agent system. It describes how agents should discover, operate within, and interact with the Nexus ecosystem - covering identity, configuration, memory, and capabilities.
+
+The core insight: **Nexus is the source of truth, agents are guests who follow nexus protocols.**
+
+---
+
+## Design Principles
+
+### 1. Minimal Agent Responsibility
+Agents should do as little "thinking" about infrastructure as possible. Nexus handles:
+- Detecting state (is identity configured? what capabilities are available?)
+- Providing clear instructions (what to do next)
+- Tracking usage (automatic logging through gateway)
+
+### 2. Nexus as Single Source of Truth
+The `nexus` CLI is authoritative. Agents query it rather than directly parsing state files. This allows:
+- State format changes without breaking agents
+- Consistent behavior across different IDE contexts
+- Automatic usage tracking
+
+### 3. Clear Ownership Boundaries
+| Owner | Owns | Can Modify |
+|-------|------|------------|
+| **User** | `home/` directory entirely | Everything in home/, identity files via conversation |
+| **Nexus CLI** | Root AGENTS.md, .cursorrules, state/nexus/, skills/ | All nexus-owned files, auto-repair if deleted |
+| **Agent** | Nothing directly | Writes to state/agents/{agent}/ with user permission |
+
+### 4. Graceful Degradation
+System works without full configuration. Pure prompt-only skills work immediately. More capabilities unlock as credentials are added.
+
+---
+
+## Component Architecture
+
+### Root AGENTS.md (Nexus-Owned)
+
+**Purpose**: Entry point that tells agents how to operate in a Nexus workspace.
+
+**Characteristics**:
+- **Static content** - Rarely changes, contains protocols not state
+- **Nexus-managed** - Created by `nexus init`, can be repopulated if deleted
+- **Points to nexus CLI** - Agent's first action is always `nexus skills status`
+- **Contains**: Identity file pointers, safety rules, memory protocols, gateway instructions
+
+**Key Instruction**:
+```markdown
+## First Action - Always
+Before doing ANYTHING else, run:
+nexus skills status
+
+This tells you who you are, what you can do, and what to do next.
+```
+
+### .cursor/rules (Nexus-Owned)
+
+**Purpose**: Cursor-specific configuration that mirrors root AGENTS.md.
+
+**Characteristics**:
+- **Pointer pattern** - Contains cursor-specific language plus reference to AGENTS.md
+- **Nexus-managed** - Created/updated by `nexus init`
+- **Lightweight** - Most content lives in AGENTS.md to avoid duplication
+
+**Example Structure**:
+```markdown
+# Nexus Workspace - Cursor Configuration
+
+This workspace uses Nexus. Follow the root AGENTS.md file for all protocols.
+
+## Cursor-Specific
+- Use the Shell tool for `nexus` commands
+- Skills are available via the nexus CLI, not as direct tools
+- Read ~/nexus/AGENTS.md for full instructions
+```
+
+### home/ (User-Owned)
+
+**Purpose**: User's personal workspace - they control everything here.
+
+**Structure**:
+```
+home/
+├── AGENTS.md          # Optional user customizations (not read by default)
+├── memory/            # Daily logs (YYYY-MM-DD.md)
+├── projects/          # User's git repos
+├── todo/              # Task tracking
+└── ...                # Whatever user wants
+```
+
+**Key Decisions**:
+- `home/AGENTS.md` is purely user space - nexus doesn't read it by default
+- Will eventually become a map/index of user content (like intent layer)
+- Agents can update memory/ files during sessions
+
+### state/ (Nexus-Owned)
+
+**Purpose**: All runtime state, credentials, and identity.
+
+**Structure**:
+```
+state/
+├── nexus/
+│   ├── gateway.json       # Gateway configuration
+│   ├── skills/            # Per-skill state and usage logs
+│   │   ├── manifest.json
+│   │   └── {skill}/
+│   │       ├── state.json
+│   │       └── usage.log
+│   └── onboarding/
+│       ├── progress.json
+│       └── wizard.json
+├── credentials/           # Centralized credentials tree
+├── user/
+│   └── identity/
+│       └── PROFILE.md     # User profile
+└── agents/
+    └── {agent}/
+        ├── identity/
+        │   ├── IDENTITY.md
+        │   ├── SOUL.md
+        │   └── MEMORY.md
+        └── config.json
+```
+
+### skills/ (Nexus-Owned)
+
+**Purpose**: Skill definitions (SKILL.md prompts).
+
+**Characteristics**:
+- Read-only for agents (they execute, don't modify)
+- Discovered via `nexus skills status`
+- Executed via `nexus skill run`
+
+---
+
+## Identity System
+
+### The Bootstrap Problem
+
+New installations have no identity configured. How does the agent know to bootstrap?
+
+**Solution**: Nexus detects missing identity and triggers the conversation.
+
+### Detection Flow
+
+```
+Agent runs: nexus skills status
+    │
+    ├─► Nexus checks: Does state/agents/{agent}/identity/IDENTITY.md exist and have content?
+    │
+    ├─► If NO → Return: "Identity not configured. Starting bootstrap conversation..."
+    │            Include: BOOTSTRAP.md contents or instructions
+    │
+    └─► If YES → Return: Normal status (ready skills, locked skills, recommendations)
+```
+
+### Bootstrap as Conversation
+
+Bootstrap is fundamentally an **identity conversation**, not a configuration wizard.
+
+The agent discovers:
+1. **Who it is** - Name, creature type, vibe, emoji
+2. **Who the user is** - Name, preferences, how to address them
+3. **Shared values** - What matters, boundaries, working style
+
+Output: Agent writes to `state/agents/{agent}/identity/` and `state/user/identity/`
+
+### Agent Identity Tracking
+
+**Location**: `state/agents/{agent}/identity/`
+
+**Files**:
+- `IDENTITY.md` - Name, emoji, creature type, vibe
+- `SOUL.md` - Values, boundaries, personality (template provided, evolved over time)
+- `MEMORY.md` - Curated long-term memories
+
+**User Understanding**:
+The agent's understanding of the user lives in `state/user/identity/PROFILE.md`:
+- How to address them
+- Timezone
+- Communication preferences
+- Important context
+
+---
+
+## nexus init Behavior
+
+### What It Creates
+
+```bash
+nexus init
+```
+
+Creates the following structure with sensible defaults:
+
+```
+~/nexus/
+├── AGENTS.md              # Root agent instructions (from template)
+├── .cursor/
+│   └── rules              # Cursor-specific config (pointer + extras)
+├── state/
+│   ├── nexus/
+│   │   ├── skills/
+│   │   │   └── manifest.json
+│   │   └── onboarding/
+│   │       └── progress.json
+│   ├── credentials/
+│   │   └── index.json
+│   ├── user/
+│   │   └── identity/
+│   │       └── PROFILE.md  # Empty template
+│   └── agents/
+│       └── default/
+│           └── identity/
+│               ├── IDENTITY.md  # Empty template
+│               ├── SOUL.md      # Template content
+│               └── MEMORY.md    # Empty
+├── home/
+│   ├── memory/            # For daily logs
+│   └── projects/          # For user's repos
+└── skills/                # Symlink to bundled skills
+```
+
+### Automatic Setup
+
+- **AGENTS.md** - Populated from template, contains full protocols
+- **.cursor/rules** - Populated with pointer pattern + cursor specifics
+- **State folders** - Created with empty/template files
+- **Skills** - Symlinked to bundled skills location
+
+### Idempotent Behavior
+
+Running `nexus init` on existing workspace:
+- Repairs missing files (AGENTS.md, .cursor/rules)
+- Does NOT overwrite user-modified content
+- Updates templates only if explicitly requested
+
+---
+
+## Memory System
+
+### Current Approach (v1)
+
+**Location**: `home/memory/YYYY-MM-DD.md`
+
+**Behavior**:
+- Created by agents during sessions
+- Raw daily logs of what happened
+- Agent reads today + yesterday on session start
+
+**Long-term Memory**: `state/agents/{agent}/identity/MEMORY.md`
+- Curated by agent
+- Distilled insights, not raw logs
+- Security: only loaded in main sessions (not shared contexts)
+
+### Future Vision (v2)
+
+Use `aix`/`comms` tools to:
+- Extract insights from AI sessions in Cursor
+- Use independent agents to process and curate memories
+- Memory becomes extracted rather than manually written
+
+**For now**: Use existing file-based memory system. Works, is simple.
+
+---
+
+## Agent Assumptions
+
+### Single Agent (v1)
+
+For simplicity, assume one agent per workspace:
+- Default agent at `state/agents/default/`
+- All identity files live there
+- Multi-agent support can be added later
+
+### Agent Name Discovery
+
+When `nexus skills status` runs:
+1. Look for agents in `state/agents/`
+2. If exactly one → use that
+3. If zero → use "default"
+4. If multiple → error or require explicit selection
+
+---
+
+## CLI Gateway Pattern
+
+### Why Gateway?
+
+All skill execution flows through `nexus skill run`:
+- **Automatic logging** - No agent cooperation needed
+- **State tracking** - lastUsed, errors, success rate
+- **Verification** - Check configuration before first run
+- **Consistent errors** - Clear guidance when things fail
+
+### Command Grammar
+
+```bash
+# Status and discovery
+nexus skills status              # What's ready, what's locked, recommendations
+nexus skills status --ready      # Only configured skills
+nexus skills status --locked     # Only unconfigured skills
+
+# Skill operations
+nexus skill show <name>          # Details and prompt
+nexus skill verify <name>        # Check configuration
+nexus skill run <name> [args...] # Execute through gateway
+nexus skill stats [name]         # Usage analytics
+
+# Identity and credentials
+nexus credential add             # Add new credential
+nexus accounts list [--owner ...]
+```
+
+---
+
+## Existing System Integration
+
+### Keep What Works
+
+The existing BOOTSTRAP.md and SOUL.md templates are good. Changes:
+- **BOOTSTRAP.md** - Used as content for identity conversation, not standalone
+- **SOUL.md** - Template provided at init, agent evolves it
+
+### What Changes
+
+| Current | Goal State |
+|---------|------------|
+| .cursor/rules has full instructions | Points to AGENTS.md |
+| Agent reads multiple config files | Agent queries `nexus skills status` |
+| Onboarding is separate skill | Built into nexus core |
+| Manual skill verification | Automatic via gateway |
+
+---
+
+## Session Flow Summary
+
+```
+1. User opens workspace in IDE
+    │
+2. IDE loads .cursor/rules (or AGENTS.md)
+    │
+3. Agent sees: "Run nexus skills status first"
+    │
+4. Agent runs: nexus skills status
+    │
+    ├─► No identity? → Nexus returns bootstrap instructions
+    │                  Agent starts identity conversation
+    │                  Agent writes identity files
+    │
+    └─► Has identity? → Nexus returns:
+                        - Agent identity summary
+                        - Ready skills (✅)
+                        - Locked skills (🔒)
+                        - Recommended next action
+    │
+5. Agent reads identity files (as instructed by status output)
+    │
+6. Agent reads recent memory (home/memory/)
+    │
+7. Agent is ready to help user
+```
+
+---
+
+## Key Decisions Summary
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Where does identity live? | `state/agents/{agent}/identity/` | Protected from user accidents |
+| Who owns home/? | User entirely | Clean separation |
+| How does agent know state? | `nexus skills status` | Single source of truth |
+| What triggers bootstrap? | Nexus detects missing identity | Minimal agent responsibility |
+| AGENTS.md vs .cursorrules? | Cursor rules points to AGENTS.md | Avoid duplication |
+| Multi-agent support? | Defer, assume single agent | Simplicity first |
+| Memory system? | File-based for now | Works, defer advanced extraction |
+
+---
+
+## Next Steps
+
+1. **Gap Analysis** - Compare this goal state to existing implementation
+2. **Implementation Plan** - Prioritized list of changes needed
+3. **Migration Path** - How to move from current to goal without breaking things
+
+---
+
+*This document defines where we're going. Compare against existing system to identify the gaps.*