npm package: @stackfactory/neurix
Description: NEURIX — Neural Engine for Unified Reasoning, Intelligence and eXecution. Multi-agent orchestration framework for Claude Code.
Author: NEURIX
Latest version: 1.0.0-beta.1

# 🧠 NEURIX

**Neural Engine for Unified Reasoning, Intelligence and eXecution**

Multi-agent orchestration framework for Claude Code.

[![npm](https://img.shields.io/npm/v/neurix?color=blue&label=version)](https://www.npmjs.com/package/neurix)
[![CI](https://github.com/stack-factory/neurix/actions/workflows/ci.yml/badge.svg)](https://github.com/stack-factory/neurix/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)

```bash
npx neurix install
```

---

## What is NEURIX?

NEURIX installs a team of specialized AI agents into your project, coordinated through slash commands. Instead of freeform prompting, you get structured phases — planning, execution, review — with each agent handling its domain.

A universal core team (conductor, architect, developer, reviewer, analyst, writer) is always included. Optional **tech stacks** layer framework-specific skills on top.

---

## Install

```bash
# Interactive — guides you through categories, stacks, MCP servers and IDE integration
npx neurix install

# Non-interactive — core only, all MCP servers auto-selected, no prompts
npx neurix install --yes

# Specific stacks
npx neurix install --stacks react
npx neurix install --stacks react,nestjs

# Custom name + prefix
npx neurix install --name "MyEngine" --prefix "me" --stacks react
#  → _myengine/  runtime directory
#  → /me-plan, /me-run, /me-analyse … slash commands
```

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--name` | `NEURIX` | Runtime directory name (`_neurix/`) |
| `--prefix` | `neurix` | Slash command prefix (`/neurix-plan`) |
| `--stacks` | _(none)_ | Comma-separated stack codes to install |
| `--tools` | `claude-code` | IDE integration (`claude-code`, `cursor`) |
| `--yes` | `false` | Skip all prompts, use defaults |

---

## Interactive Install Flow

The installer guides you in three steps:

**1 — Select categories**
```
? Select stack categories:
  ❯ ◯ backend
    ◯ frontend
```

**2 — Select stacks per category** (separate prompt per category, no mixing)
```
[backend] Select stacks to install:
  ❯ ◯ NestJS (10+)   — NestJS framework-specific patterns
    ◯ Node.js (20+)   — Node.js backend patterns with Express/Fastify
    ◯ Symfony (6.4+)  — Symfony framework-specific patterns

[frontend] Select stacks to install:
  ❯ ◯ Angular (20+)
    ◯ React (18+)
```

**3 — Select MCP servers per stack** (granular — zero or more per stack)
```
[React] MCP servers to install:
  ❯ ◯ context7   — Injects up-to-date React/Vite docs into prompts
    ◯ playwright  — Microsoft Playwright — E2E testing, screenshots

[NestJS] MCP servers to install:
  ❯ ◯ postgres   — PostgreSQL schema inspection and querying
    ◯ redis       — Redis key-value access for cache layer
    ◯ playwright  — E2E testing of NestJS-backed web apps
```

MCP servers are written to `.mcp.json` in your project root. Duplicate servers across stacks are deduplicated automatically.

---

## What Gets Installed

```
your-project/
├── _neurix/
│   ├── core/
│   │   ├── agents/        ← conductor, architect, developer, reviewer, analyst, writer
│   │   ├── workflows/     ← plan, run, analyse, debug, status, init
│   │   ├── skills/        ← orchestration, code-generation, file-analysis,
│   │   │                     refactoring, web-research, doc-writing
│   │   └── tasks/         ← help, graph
│   ├── react/             ← (if selected) React-specific skills
│   │   ├── context.md     ← generated at install (stack.yaml + your MCP choices)
│   │   └── skills/        ← component, hooks, state, testing
│   ├── nestjs/            ← (if selected) NestJS-specific skills
│   │   ├── context.md
│   │   └── skills/        ← module, controller, service, guard, testing
│   ├── _config/
│   │   ├── config.yaml    ← project name, prefix, installed stacks
│   │   ├── manifest.yaml  ← version, file count, stack options
│   │   └── templates/     ← plan.md, workflow-status.yaml, session.md, stack-context.md
│   └── _memory/
│       └── session.md     ← Conductor saves state here at each phase transition
├── _neurix-output/
│   ├── plan.md            ← current active plan (with Plan ID + date)
│   ├── workflow-status.yaml
│   └── plans/             ← automatic backups of previous plans
│       ├── plan-PLAN-20260315-001.md
│       └── workflow-status-PLAN-20260315-001.yaml
├── .claude/commands/      ← /neurix-* slash commands
└── .mcp.json              ← MCP server definitions (if any selected)
```

---

## Slash Commands

| Command | Description |
|---------|-------------|
| `/neurix-plan` | Create the execution plan — auto-saves, backs up previous |
| `/neurix-plan "..."` | Plan from a free-form description |
| `/neurix-plan --reset` | Force a new plan even if one is in progress |
| `/neurix-run` | Execute the current plan |
| `/neurix-run --step` | Execute one task at a time |
| `/neurix-run --dry` | Simulate without writing anything |
| `/neurix-analyse` | Full project analysis |
| `/neurix-debug` | Diagnose the NEURIX framework health |
| `/neurix-status` | Quick progress overview |
| `/neurix-init` | Initialize session tracking |
| `/neurix-graph` | Visual workflow map and agent diagram |
| `/neurix-help` | Show all commands and guidance |

---

## Plan Management

Every `/neurix-plan` invocation is fully automatic — no save prompts.

### Plan lifecycle

```
/neurix-plan
     │
     ▼
 Guard: plan already in progress?
     │ no                    │ yes → stop + show plan_id, phase, next action
     ▼
 Load stacks context
 Read project files (parallel)
 Decompose into phases
     │
     ▼
 Draft plan  →  show to user  →  "Any modifications?"
     │                                    │ changes requested → apply → show again
     │ confirmed ◄──────────────────────────────────────────────
     ▼
 Backup previous plan to _neurix-output/plans/plan-<old_id>.md
 Save _neurix-output/plan.md               Plan ID: PLAN-20260315-002
 Save _neurix-output/workflow-status.yaml  plan_id, plan_version, created_at
     │
     ▼
 ✅ Plan PLAN-20260315-002 saved. Run /neurix-run to start.
```

### Plan IDs

Each plan gets a unique identifier: `PLAN-YYYYMMDD-NNN` (auto-incremented).

```yaml
# workflow-status.yaml
plan_id: "PLAN-20260315-002"
plan_version: 1
created_at: "2026-03-15 14:30"
```

### Rollback

Previous plans are never deleted — they accumulate in `_neurix-output/plans/`:

```bash
_neurix-output/plans/
  plan-PLAN-20260315-001.md                   ← copy of the plan as executed
  workflow-status-PLAN-20260315-001.yaml      ← full task state at that time
```

To roll back: copy the backup files back to `_neurix-output/` and resume with `/neurix-run`.

---

## Agents

| Agent | Role | Key behaviors |
|-------|------|---------------|
| **Conductor** | Master orchestrator | Dispatches in parallel, retries failed tasks once then asks human, saves session state at each phase |
| **Architect** | System design, specs | Reads existing code before designing, applies stack conventions as hard constraints |
| **Developer** | Code, tests | Reads files before writing, loads stack skills, self-verifies output, asks before destructive ops |
| **Reviewer** | Quality audit (read-only) | Checks stack-specific convention violations in addition to generic quality rules |
| **Analyst** | Research, diagnostics | Reads all relevant files before analysing, calibrates findings against stack versions |
| **Writer** | Documentation | Uses actual stack CLI and package manager in examples, adapts terminology per framework |

---

## Skills

Each agent loads the relevant skill before starting complex tasks. Skills are procedures, not agents — they guide *how* to do the work.

| Skill | Used by | Purpose |
|-------|---------|---------|
| `orchestration` | Conductor | Decompose requests across agents, parallel vs sequential dispatch |
| `code-generation` | Developer | Structured implementation: spec → file tree → code → tests → lint |
| `refactoring` | Developer | Safe incremental refactoring with characterization tests |
| `file-analysis` | Analyst, Architect | Project structure scan, metrics, health report |
| `web-research` | Analyst | Parallel multi-source research with structured synthesis |
| `doc-writing` | Writer | Audience-aware documentation with stack-accurate examples |

Stack-specific skills (e.g. `react/skills/component.md`) are loaded by Developer on top of core skills when a stack is installed.

---

## Tech Stacks

| Category | Stack | Version | Skills |
|----------|-------|---------|--------|
| frontend | `react` | 18+ | component, hooks, state, testing |
| frontend | `angular` | 20+ | component, signals, service, http, routing, state, reactive-forms, pipes, directives, module, ssr, performance, animations, accessibility, testing, zoneless, migration |
| backend | `nestjs` | 10+ | module, controller, service, guard, testing |
| backend | `node` | 20+ | rest-api, database, middleware, testing |
| backend | `symfony` | 6.4+ | entity, controller, service, form, testing |

The Angular stack also includes 4 specialized agents: `angular-architect`, `angular-developer`, `angular-reviewer`, `angular-migrator`.

Each installed stack generates a `context.md` at install time (from `stack.yaml` + your MCP server choices). The Conductor reads `_config/config.yaml` at runtime and injects the relevant `context.md` into every agent dispatch.

---

## How It Works

```
/neurix-plan
     │
     ▼
 .claude/commands/neurix-plan.md
     │
     ▼
 _neurix/core/workflows/plan.md
     │
     ▼
 Conductor  ←── reads _config/config.yaml + <stack>/context.md
     │                     injects stack context into every dispatch
     ├──────────────┬───────────────┬──────────────┐
     ▼              ▼               ▼              ▼
 Analyst        Architect       Developer      Reviewer
 (research)     (design)        (code)         (audit)
    │              │               │              │
    └──────────────┴───────────────┴──────────────┘
         all agents receive <stack_context> when dispatched
                             │
                             ▼
                     _neurix-output/
```

---

## Session Memory

The Conductor automatically saves state to `_neurix/_memory/session.md` at each phase transition:
- Active plan path, current phase, completed task IDs
- Key architectural decisions made during the session
- Installed stacks active in the session

When the context window resets (long sessions), the Conductor reads `session.md` + `workflow-status.yaml` to resume exactly where it left off — no work is lost.

---

## Update

```bash
# Detects existing install → prompts for Quick Update or Full Reinstall
npx neurix install

# Explicit update — reads existing manifest, preserves name/prefix/stacks
npx neurix update
```

On update, modified files are backed up as `.bak` before being overwritten — your customizations are preserved.

---

## Customization

Edit any installed file directly — it survives updates via `.bak` backup.

```
_neurix/core/agents/your-agent.md      ← Add a custom agent
_neurix/core/skills/your-skill.md      ← Add a core skill
_neurix/react/skills/your-skill.md     ← Add a stack-specific skill
```

---

## Testing

```bash
npm test                               # all 10 phases, 400+ assertions
node tools/test/index.js --phase 2     # single phase
node tools/test/index.js --phase 1,9   # CLI + E2E only
```

The test suite validates CLI behavior, loader unit tests, all agent XML structure, workflow coherence, skill alignment, stack YAML↔file integrity, template variables, and end-to-end install flows.

---

## Status

```bash
npx neurix status --directory /path/to/project
```

Reports installed version, stacks, prefix, and runtime directory.

---

## License

MIT