NOUS

One specialist planner. One focused plan. No generic AI slop.

A planning framework for AI coding agents that routes every request to a single domain expert — UI, database, backend, QA, security, performance, release, product, or fullstack — and refuses to let it stray outside its lane.

Why NOUS exists

Ask a coding agent for a "plan" and you usually get the same answer: a vague, multi-domain checklist that touches the database, the API, the UI, the tests, the deployment pipeline, and somehow none of them properly. Everything is mentioned, nothing is decided, and most of it gets ignored at execution time.

NOUS fixes this with one rule:

A planner is responsible for one domain. Anything else is "Not In Scope".

A UI planner does not design schemas. A DB planner does not write product strategy. A QA planner does not refactor backend code. The result is plans you can actually hand to an engineer.

How it works

                       ┌────────────────────────┐
   user request  ─────▶│   using-nous router    │
                       └────────────┬───────────┘
                                    │ picks exactly one
                                    ▼
            ┌──────────────────────────────────────────────────────┐
            │ ceo · ui · db · be · qa · security · perf · release  │
            │                ultraplan · execute                   │
            └─────────────────────────┬────────────────────────────┘
                                    │
                                    ▼
                       ┌────────────────────────┐
                       │  domain-scoped plan    │
                       │  fixed output contract │
                       │  Not In Scope section  │
                       └────────────────────────┘

The router loads one planner skill. Each planner has a forbidden-scope list it must respect. Every plan ends with a Not In Scope block — the mechanism that keeps a UI plan from quietly redesigning the database.

Quickstart

Install for every supported runtime, globally:

npx @max-kharena/nous --all --global

Or pick one runtime:

npx @max-kharena/nous --claude --global
npx @max-kharena/nous --codex  --global
npx @max-kharena/nous --cursor --global

Install into the current project instead of the user-global config:

npx @max-kharena/nous --claude --local

Preview what would be written, without touching the filesystem:

npx @max-kharena/nous --all --global --dry-run

Reinstalling is safe: NOUS hashes each skill at install time and on subsequent runs will skip unchanged skills, update changed ones, and refuse to overwrite skills you have edited locally. Pass --force to clobber local edits.

Updating

When a new NOUS version ships, update every installation in one shot:

npx @max-kharena/nous update          # auto-detects every install (global + local)
npx @max-kharena/nous update --global # update only global installations
npx @max-kharena/nous update --local  # update only this project's local install
npx @max-kharena/nous update --claude # narrow to a single host
npx @max-kharena/nous update -y       # skip the confirmation prompt

update finds existing NOUS installations by their <skillRoot>/.nous.json manifest, prints a per-installation version diff, asks once for confirmation, then re-runs the install path against each detected location. Locally modified skills are still protected; pass --force to overwrite.

Inspect what is installed where:

npx @max-kharena/nous status

status prints the installed version, skill count, and last-updated timestamp per host and scope, and flags installations that have an update available.

Or install via the open skills ecosystem

NOUS is also discoverable through skills.sh and the vercel-labs/skills CLI:

# install all NOUS skills, prompting per detected agent
npx skills add max-kharena/nous

# pick specific skills + agents non-interactively
npx skills add max-kharena/nous --skill nous-ui-plan --skill nous-ultraplan -a claude-code -y

Then ask your agent for a plan in natural language, or use a command:

nous:ui-plan        Create a UI plan for the onboarding flow
nous:ui-ultra-plan  Create a pixel-perfect Refactoring UI plan
nous:db-plan        Plan a safe migration from int → uuid IDs
nous:ultraplan      End-to-end fullstack plan for billing
nous:execute-plan   Run the most recent plan
nous:quick-ui       Quick-execute a small UI change
nous:quick-be       Quick-execute a small backend change
nous:quick-db       Quick-execute a small DB change
nous:verify         Prove a completion claim with fresh evidence
nous:debug          Investigate root cause before fixing
nous:review         Request focused code review

Usage scenarios

NOUS works in two shapes: one agent that walks the whole feature, or several agents pinned to a single lane each.

One agent, full feature

A single Claude (or Codex / Cursor) session runs nous:ultraplan to split a feature into dependency-ordered phases, then walks through them with nous:execute-plan. The agent stays in lane on each phase because the ultraplan names a single owner domain (ui, be, db, qa, security, perf, release, docs) per phase.

┌──── one Claude session ───────────────────────────────────────────────────┐
│                                                                           │
│  user ─▶ nous:ultraplan ─▶ phased plan ─▶ nous:execute-plan ─▶ phase 1→2→3│
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

Best for: solo developer, single machine, change that fits in one focused session. Pair with nous:verify between phases to require fresh evidence.

Many agents, one lane each

Multiple sessions run in parallel — each pinned to a single planner role. Every session writes a domain-scoped plan to .nous/plans/{domain}-plan.md; an integration session (or the user) reads those plans and sequences execution. Because each session loads only one planner skill, no session can silently widen its scope into another lane.

┌── session A ──┐  ┌── session B ──┐  ┌── session C ──┐  ┌── session D ──┐
│   ceo-plan    │  │    ui-plan    │  │    be-plan    │  │    qa-plan    │
│   scope &     │  │    flows &    │  │    APIs &     │  │  test matrix  │
│   ambition    │  │    states     │  │   contracts   │  │   & evidence  │
└───────┬───────┘  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘
        ▼                  ▼                  ▼                  ▼
              .nous/plans/{ceo,ui,be,qa}-plan.md
                                │
                                ▼
              ┌──── integration session ────┐
              │  reads plans, sequences,    │
              │  runs nous:execute-plan     │
              └─────────────────────────────┘

Best for: larger features where domains run concurrently, team workflows, or single-developer worktree-style work. Pair with nous:worktrees to keep each session on its own branch, and nous:parallel-agents if you want one driving session to fan out instead of opening terminals manually.

Mix-and-match works too: start with nous:ceo-plan to lock scope, then run nous:ultraplan to phase the agreed feature, then assign individual phases to specialist sessions when domains can move in parallel.

The skills

Planners

| Command | Domain | | -------------------- | --------------------------------------------------------------- | | nous:ceo-plan | Product strategy, scope, ambition, tradeoffs | | nous:ui-plan | Frontend architecture, UX, accessibility, interaction states | | nous:ui-ultra-plan | Pixel-perfect frontend plan using Refactoring UI rule coverage | | nous:db-plan | Schema, migrations, indexes, query shape, data integrity | | nous:be-plan | Backend APIs, services, domain logic, integrations | | nous:qa-plan | Test strategy, validation, regression, ship readiness | | nous:security-plan | Threat modeling, trust boundaries, OWASP / STRIDE, controls | | nous:perf-plan | Benchmarks, budgets, Core Web Vitals, regression thresholds | | nous:release-plan | Release sequence, rollout, rollback, infra/deploy gating | | nous:ultraplan | Phased fullstack feature plan with tiny commits and parallelism |

Utilities

| Command | What it does | | -------------------------------- | ------------------------------------------------------------------ | | nous:use | Router that selects exactly one planner or utility | | nous:execute-plan | Executes a plan that already exists; refuses to improvise | | nous:quick-ui | Quick-executes a small UI change with frontend design rules | | nous:quick-be | Quick-executes a small backend/API change with verification gates | | nous:quick-db | Quick-executes a small DB/query/migration change with DB gates | | nous:refactor | Interview-driven refactor plan, broken into tiny safe commits | | nous:write-skill | Creates new agent skills with progressive disclosure | | nous:add-skill | Adds a rule, subagent, or skill to a specific workflow | | nous:frontend-design | Bundled UI execution skill, applied automatically by nous:ui-plan | | nous:frontend-design-ultra | Pixel-perfect Refactoring UI rule system for ultra UI work | | nous:worktrees | Sets up isolated worktrees for parallel or phase execution | | nous:verify | Requires fresh evidence before completion claims | | nous:tdd | Red-Green-Refactor discipline for behavior changes | | nous:debug | Root-cause investigation before fixes | | nous:review | Prepares focused implementation review context | | nous:handle-review | Processes review feedback with technical verification | | nous:finish | Verifies, merges/PRs/keeps/discards, and cleans up branches | | nous:subagents | Executes plan tasks with fresh subagents and review gates | | nous:parallel-agents | Runs independent investigations or tasks in parallel agents | | nous:obsidian | Searches and organizes notes in an Obsidian vault |

Issue & spec workflow

GitHub-issue-first complement to NOUS plans. Useful when work needs to land in an issue tracker, get picked up by an AFK agent, or be reported asynchronously rather than executed inline.

| Command | What it does | | ---------------------- | --------------------------------------------------------------------------- | | nous:to-prd | Synthesizes the current conversation into a PRD GitHub issue (no interview) | | nous:to-issues | Breaks a plan, spec, or PRD into vertical-slice GitHub issues with HITL/AFK | | nous:triage-issue | Investigates a bug, finds root cause, files a durable issue with TDD plan | | nous:qa-report | Interactive QA session that files durable, behavior-focused issues | | nous:gh-triage | Label-based triage state machine; agent briefs; .out-of-scope/ memory |

Domain & architecture

Domain memory and architecture-deepening primitives — the layer above any single planner.

| Command | What it does | | ------------------------ | --------------------------------------------------------------------------- | | nous:grill | Decision-tree interview until every branch resolves | | nous:domain-model | Grills a plan against CONTEXT.md + ADRs; updates them inline | | nous:glossary | Extracts a DDD ubiquitous language glossary into UBIQUITOUS_LANGUAGE.md | | nous:architect | Surfaces deepening opportunities; uses CONTEXT.md and ADRs for naming | | nous:design-interface | Parallel sub-agents generate radically different interface designs |

NOUS frontend taste

nous:ui-plan applies the bundled frontend-design skill with a default NOUS taste overlay pulled from Max Brain: dark-first, precise, restrained, premium, mono/pixel accents, muted color, and no generic SaaS styling. Project or user-specific direction can override it.

nous:ui-ultra-plan uses frontend-design-skill-ultra: a tighter pixel-perfect lane built from Refactoring UI rules. Use it when the goal is premium visual polish, exact spacing/type/color constraints, designed states, and explicit visual verification.

Quick execution aliases are available for small scoped work: quick:ui, quick:be, and quick:db. They map to nous:quick-ui, nous:quick-be, and nous:quick-db, apply the relevant role rules, and still require fresh verification evidence.

The output contract

Every planner returns the same structure. This is the contract that makes plans executable, comparable, and reviewable across domains:

## Objective
## Domain Analysis
## Specialized Tasks
## Dependencies
## Risks
## Validation Requirements
## Success Metrics
## Not In Scope

Not In Scope is required. It's how NOUS prevents the all-in-one slop plan.

Principles

• Skill-first, not command-first. Natural language routes the same as a slash command.
• Load one personality at a time. No blended planners.
• Lazy, domain-scoped context. Don't read what the active planner won't use.
• Inline self-review before spawning agents. Cheaper, faster, usually enough.
• Stay inside the lane. Adjacent work goes in Not In Scope, not in the plan body.
• Evidence beats claims. Every plan defines what "done" looks like.
• Root cause before fixes. Debugging uses evidence, not guesses.
• TDD where behavior changes. Red-Green-Refactor is the default implementation discipline.
• Review before merge. Risky or merge-bound work gets focused code review.
• Boil the lake, not the ocean. When the marginal cost of completeness is near-zero, finish it. Don't defer states, tests, or docs to a follow-up.
• User sovereignty. Planners recommend, users decide. Surface decisions that would change scope, schema, or product direction.

Ultraplan and execution

nous:ultraplan produces a Superpowers-style fullstack plan: dependency-ordered phases, tiny working commits, a parallelization map, and a recommended execution mode per phase (main, subagent, worktree, or parallel-worktree).

Execution is deliberately separate from planning. nous:execute-plan checks that a plan exists before doing any work; if not, it stops and proposes the right planner instead of guessing.

Default plan locations searched, in order:

.nous/plans/{domain}-plan.md
.nous/plans/nous-{domain}-plan.md
docs/nous/plans/{domain}-plan.md
docs/plans/{domain}-plan.md

Supported execution modes:

| Mode | When to use | | ------------------- | ---------------------------------------------------------------------- | | sequential | One task at a time. Default, safest. | | parallel-terminal | Independent tasks in separate terminal or agent sessions | | parallel-wave | Dependency waves: run a wave concurrently, then the next | | phase-worktrees | Independent phases in isolated git worktrees via using-git-worktrees |

Workflow resource ingestion

nous:add-skill (aliases: nous:add-rule, nous:add-subagent) attaches a custom rule, subagent, or skill to a specific workflow. The workflow stores links, not duplicated bodies:

.nous/workflows/{workflow-slug}/WORKFLOW.md
.nous/workflows/{workflow-slug}/rules/{rule-slug}.md
.nous/workflows/{workflow-slug}/subagents/{subagent-slug}.md
.nous/workflows/{workflow-slug}/skills/{skill-slug}/SKILL.md

## Linked Resources

- Rule: [Naming Rule](rules/naming-rule.md)
- Subagent: [Migration Reviewer](subagents/migration-reviewer.md)
- Skill: [Schema Diff Skill](skills/schema-diff/SKILL.md)

Supported runtimes

Default install roots per runtime:

| Runtime | Global root | Local root | | ----------- | ------------------- | ------------------ | | Claude Code | ~/.claude/skills | .claude/skills | | Codex | ~/.agents/skills | .agents/skills | | Cursor | ~/.cursor/skills | .cursor/skills |

Override the target with --target <path> if you keep skills somewhere custom.

Repository layout

nous/
├── skills/          canonical SKILL.md definitions (the source of truth)
├── commands/        thin command aliases
├── core/            router, context policy, output contracts, rules, personality contract
├── hosts/           Claude / Codex / Cursor adapters
├── bin/             npm installer (nous-install.js)
├── docs/            architecture, publishing, reverse-engineering notes
└── tests/           package validation

Development

npm test                                          # validate package
node bin/nous-install.js --all --global --dry-run # preview install
npm pack --dry-run                                # inspect npm contents

Publishing checklist lives in docs/PUBLISHING.md. Architecture notes live in docs/architecture/v1.md. Per-version notes live in CHANGELOG.md.

License

MIT — Max Kharena.