Nourivex Runtime

Nourivex Runtime is a provider-agnostic AI engineering framework. It enforces a strict Research → Architecture → Planning → TDD Execution workflow with 17 discipline skills, 5 specialized agents, a persistent memory system, and an MCP server with 25 executable tools so agents never forget your goals across sessions. Supports OpenCode, Gemini CLI, Claude, and Codex.

🚀 Key Features

• Engineering Discipline: 17 built-in skills for TDD, Goal Preservation, Scope Watchdog, Anti-Overengineering, and more.
• Persistent Memory: Agents store and recall patterns, lessons, and user preferences across sessions via .nourivex/.
• Goal Tracking: Objective locks survive session restarts — agents always remember what you're building.
• Living Todo Lists: Plans automatically become tracked todo lists with progress that persists across sessions.
• Session Manager: Every session starts with a brief of active goals, unfinished tasks, and relevant memory.
• Collaborative Team: 5 specialized agents (Researcher, Architect, Planner, Implementer, Reviewer) that work as partners.
• Multi-Platform: Works with OpenCode, Gemini CLI, Claude, and Codex via platform adapters.
• Auto-Discovery: OpenCode auto-discovers skills from .agents/skills/ and agents from .opencode/agents/.
• npm Installable: Can be installed via npm and used as a plugin/MCP.
• MCP Server with 25 Tools: Available via npx nourivex-mcp-server — tools for goals, memory, todos, and session management.
• CLI Tools: nourivex memory, nourivex goals, nourivex todos, nourivex mcp for inspecting persistent state from terminal.

🛠️ Installation

Nourivex Runtime has two modes that complement each other:

| Mode | What It Does | How | |------|-------------|-----| | 🧩 Plugin | Provides 17 skills + 5 agents (agentic workflow) | plugin: ["nourivex-runtime"] | | 🔌 MCP Server | Exposes 25 tools via MCP protocol (tool-based) | npx -y nourivex-mcp-server |

Step 1: Install the Runtime

# Install CLI globally (recommended)
npm install -g nourivex-runtime

# Or install in your project
npm install nourivex-runtime

Step 2: Configure

For OpenCode users — dual config (opencode.json):

Add both plugin and MCP entries to your opencode.json:

{
  "plugin": ["nourivex-runtime"],

  "mcp": {
    "nourivex": {
      "type": "local",
      "command": ["npx", "-y", "nourivex-mcp-server"],
      "enabled": true
    }
  }
}

Plugin enables agentic workflow: skill(), task(), specialized sub-agents. MCP enables direct tool access: 26 atomic tools for goals/memory/todos/sessions. Keduanya coexist — bukan either/or.

For CLI-only use:

# Initialize your project for a specific AI assistant
cd /path/to/your/project
nourivex init --ai opencode      # OpenCode
nourivex init --ai claude        # Claude Code
nourivex init --ai gemini        # Gemini CLI
nourivex init --ai codex         # Codex CLI
nourivex init --ai cursor        # Cursor
nourivex init --ai windsurf      # Windsurf
nourivex init --ai copilot       # GitHub Copilot
nourivex init --ai continue      # Continue
nourivex init --ai all           # All assistants

Or add the MCP server only (no plugin):

Any MCP-compatible client can use just the server:

{
  "mcp": {
    "nourivex": {
      "type": "local",
      "command": ["npx", "-y", "nourivex-mcp-server"]
    }
  }
}

Local Plugin (development):

opencode plugin add ./opencode-plugin.mjs

Register Custom Subagents (Advanced):

To use agents via task(subagent_type="nvx-researcher", ...), merge opencode.agents.json into your project's opencode.json under the "agent" field.

Gemini CLI:

gemini extensions install <path-to-nourivex-runtime> --consent

🎯 OpenCode Quick Start (v5.0.0)

// 0. ALWAYS FIRST — restore session context
skill(name="nvx-session-manager")
// → SESSION BRIEF shows active goal, todo progress, relevant memory

// 1. Load discipline skills
skill(name="nvx-goal-preservation")   // Lock objective + persist to .nourivex/goals/
skill(name="nvx-watchdog")            // Patrol scope drift + log alerts
skill(name="nvx-superpower-memory")   // RECALL patterns, STORE lessons

// 2. Delegate to specialized agents
task(category="deep", load_skills=["nvx-researcher"], run_in_background=true, prompt="Research...")
task(category="deep", load_skills=["nvx-architect"], run_in_background=false, prompt="Design...")
task(category="deep", load_skills=["nvx-planner"], run_in_background=false, prompt="Plan...")
// → Plan auto-persists as .nourivex/todos/ living list

task(category="deep", load_skills=["nvx-implementer", "nvx-tdd-enforcer"], run_in_background=false, prompt="Implement...")
// → Todo progress updated automatically

task(subagent_type="oracle", load_skills=["nvx-reviewer"], run_in_background=false, prompt="Review...")
// → 7 passes including memory capture (Pass 7)

See adapters/opencode/AGENTS.md for the full OpenCode handbook.

🔌 MCP Server

MCP (Model Context Protocol) lets any MCP-compatible AI client call tools directly — no plugin or skill system needed. Install via: npx -y nourivex-mcp-server (no global install required)

25 Tools

| Domain | Tool | What It Does | |--------|------|-------------| | Goals (7) | goal_get | Read the current active goal | | | goal_create | Create a new active goal with title, objective, success criteria | | | goal_update | Update a field on the active goal | | | goal_complete | Complete and archive the active goal | | | goal_abandon | Abandon the active goal with a reason | | | goal_add_scope_alarm | Log a scope drift alarm to the active goal | | | goal_history | Read completed and abandoned goals from history | | Memory (8) | memory_store | Store a new memory entry (pattern, lesson, or note) | | | memory_list | List all memory entries with search and filter | | | memory_get | Get a specific memory entry by ID | | | memory_recall | Recall patterns before planning — returns relevant memories | | | memory_update_user_dna | Update user preferences and coding style profile | | | memory_get_user_dna | Get stored user preferences and coding profile | | | memory_get_domain_rules | Get stored business domain rules (invariants) | | | memory_add_domain_rule | Add a new business domain rule | | Sessions (3) | session_init | Initialize a new session with project context | | | session_restore | Restore session context — returns active goal, todo, and recent memory | | | session_save | Save the current session summary to persistent storage | | Todos (7) | todo_create | Create a new todo list from a plan | | | todo_get | Get a todo list by ID | | | todo_list | List all active todo lists | | | todo_update_item | Update a single todo item (status, description, priority) | | | todo_add_item | Add an item to an existing todo list | | | todo_complete | Mark a todo list as completed and archive it | | | todo_progress | Get aggregated progress across all todo lists |

These tools interact with the same .nourivex/ persistent storage as the plugin skills — data written via MCP is visible to plugin skills and vice versa.

🧠 CLI Commands (v5.0.0)

Inspect and manage your persistent state from the terminal:

# Memory vault
nourivex memory list              # List all stored patterns & lessons
nourivex memory --search express  # Search by keyword or tag
nourivex memory --show <id>       # Full entry detail

# Goals
nourivex goals                    # Show active goal + scope alarm history
nourivex goals --complete <id>    # Archive completed goal
nourivex goals --history          # Show all past goals

# Todos
nourivex todos                    # Show active todo list
nourivex todos --progress         # Visual progress bar
nourivex todos --show <id>        # Detailed view

# MCP Server
nourivex mcp                      # Spawn MCP server locally (stdio)

🗂️ Persistent Storage (.nourivex/)

.nourivex/
├── goals/
│   ├── _active.json        # Current active goal + scope alarm log
│   ├── _history.json       # Completed and abandoned goals
│   └── archive/            # Full goal details
├── todos/
│   ├── _active.json        # Pointer to active todo list
│   ├── _completed.json     # Index of completed lists
│   └── lists/              # Individual todo lists with progress
│       └── {id}.json
├── memory/
│   ├── _index.json         # Master registry of all memory entries
│   ├── knowledge-vault/
│   │   ├── patterns/       # Reusable implementation patterns
│   │   └── lessons/        # Bug post-mortems & lessons learned
│   ├── user-dna/
│   │   └── profile.json    # User preferences & coding style
│   └── project-map/
│       ├── architecture.json   # Module relationships
│       └── domain-rules.json   # Business invariants (never violate)
└── sessions/
    └── latest.json         # Most recent session summary

👥 The Dream Team

| Agent | Role | Phase | |-------|------|-------| | 🕵️ nvx-researcher | Deep technical discovery & approach proposals | Phase 1: Research | | 📐 nvx-architect | System design & structural blueprints | Phase 2: Architecture | | 📝 nvx-planner | Task breakdown & TDD roadmap + todo list creation | Phase 3: Planning | | 💻 nvx-implementer | TDD code execution + todo progress tracking | Phase 4: Execution | | 🧐 nvx-reviewer | 7-pass review + memory capture (Pass 7) | Phase 5: Review |

📦 Available Skills (17)

All skills are registered in .agents/skills/ for OpenCode auto-discovery.

| Skill | Description | |-------|-------------| | nvx-session-manager | Restore/save session context (goals, todos, memory) | | nvx-goal-preservation | Lock objective + persist to .nourivex/goals/ — survives restarts | | nvx-superpower-memory | STORE patterns after GREEN, RECALL before planning | | nvx-watchdog | Scope patrol + logs all alerts to goal file | | nvx-planner | Plan + auto-persist as living todo list | | nvx-reviewer | 7-pass review including memory capture (Pass 7) | | nvx-agent-synchronizer | Context Pack v2 with PERSISTENT_REFS for handoffs | | nvx-tdd-enforcer | Test-first discipline enforcement | | nvx-anti-overengineering | Enforce simplicity & YAGNI | | nvx-architectural-consistency | Match naming/pattern conventions | | nvx-verification | Verify before completion claims | | nvx-idempotency-guard | Ensure idempotent operations | | nvx-context-pruning | Keep context window lean | | nvx-dependency-lockdown | Control dependency additions | | nvx-reasoning-trace | Reasoning transparency | | nvx-systematic-debugging | Structured debugging protocol | | nvx-token-efficiency | Token optimization |

📁 Project Structure

nourivex-runtime/
├── .agents/skills/              # 17 skill definitions (OpenCode auto-discovered)
│   ├── nvx-session-manager/
│   ├── nvx-superpower-memory/
│   ├── nvx-goal-preservation/
│   ├── nvx-planner/
│   ├── nvx-watchdog/
│   ├── nvx-reviewer/
│   └── nvx-agent-synchronizer/
├── .opencode/
│   ├── agents/                  # Agent instruction files (5 agents)
│   └── skills/                  # OpenCode skill entry point
├── .nourivex/                   # Persistent storage (auto-created)
│   ├── goals/                   # Goal tracking
│   ├── todos/                   # Todo lists
│   ├── memory/                  # Knowledge vault
│   └── sessions/                # Session summaries
├── adapters/
│   ├── opencode/AGENTS.md       # OpenCode handbook (v5.0.0)
│   ├── gemini/GEMINI.md         # Gemini CLI handbook (v5.0.0)
│   ├── claude/CLAUDE.md         # Claude adapter (v5.0.0)
│   └── codex/AGENTS.md          # Codex adapter (v5.0.0)
├── agents/                      # Agent role definitions
├── cli/src/
│   ├── commands/
│   │   ├── init.ts              # nourivex init
│   │   ├── memory.ts            # nourivex memory
│   │   ├── goals.ts             # nourivex goals
│   │   ├── todos.ts             # nourivex todos
│   │   └── mcp.ts               # nourivex mcp
│   └── index.ts                 # CLI entry point
├── mcp/                         # MCP server source
│   ├── src/
│   │   ├── server.ts            # MCP entry point (26 tools)
│   │   ├── tools/               # Tool implementations (goals, memory, session, todos)
│   │   ├── prompts/             # MCP prompt definitions
│   │   ├── resources/           # MCP resource definitions
│   │   └── schemas/             # Zod schemas for all operations
│   ├── dist/                    # Build output
│   ├── tsconfig.json
│   └── package.json             # [email protected] (published to npm)
├── opencode-plugin.mjs          # OpenCode plugin entry
├── opencode-mcp.json            # Project-local MCP server config
├── package.json                 # v5.0.0
└── skill.json                   # v5.0.0

📜 Principles

1. Evidence before Implementation: No code without a plan.
2. Test-First: Failing tests are mandatory before production code.
3. Simplicity Wins: Abstractions must be earned, not assumed.
4. Full Traceability: Every change must trace back to an approved plan.
5. Memory Compounds: Every session builds on the last. Store lessons. Recall patterns.
6. Goals Persist: Objectives are never lost to session restarts.

Maintained by Nourivex — No code without a plan. No plan without verification. No session without memory.