Nova

Nova

> Illustrative playback of the /nova:review + pre-commit gate flow. Source: [assets/demo-play.sh](assets/demo-play.sh) + [assets/demo.cast](assets/demo.cast).

[](https://github.com/TeamSPWK/nova/actions/workflows/ci.yml) [](https://github.com/TeamSPWK/nova/releases) [](LICENSE)

Self-only metrics (n AI coding tools make you type faster — but the real bottleneck isn't typing. > A single wrong decision in week 1 compounds into a full rewrite by week 4. > Nova gives AI agents the operating environment they need to work reliably.

Nova is a Claude Code plugin that makes AI agents operate dependably in real projects. It started as a Quality Gate — and that's still the strongest pillar — but it now spans five:

| Pillar | Purpose | |--------|---------| | Environment | Worktree, secret-sharing, isolated agent workspaces — see [Worktree Setup guide](docs/guides/worktree-setup.md) | | Context | Session-to-session state continuity (NOVA-STATE.md) | | Quality | Generator-Evaluator separation, file-bound pre-commit hard gate — run gate-only alongside other plugins via [NOVA_COEXIST](docs/guides/coexist.md) | | Collaboration | Design→build→verify orchestration, multi-AI consulting | | Evolution | Self-diagnosis and auto-upgrade |

The Quality pillar remains load-bearing: independent evaluation, multi-AI cross-verification, and design-implementation gap detection are injected into every session automatically.

What's New in v5.23.0 — ECC Adversarial Gap Closure

A multi-release sprint that adopted measured ideas from the ECC (Everything Claude Code) ecosystem while preserving Nova's cohesive identity. Identity is discovered after the mechanism proves itself, not declared upfront — the additions below were absorbed because they passed adversarial evaluation, not because of vocabulary fit.

| Release | Addition | Source | |---------|----------|--------| | v5.23.0 | /nova:audit-self --jury — Red(attacker) / Blue(defender) / Auditor(arbiter) 3-persona adversarial security audit. Counters single-evaluator self-justification bias. | ECC AgentShield §P2-3 | | v5.22.3 | release.sh Step 2.5 hygiene gates — fail-open advisories for review trail / NOVA-STATE.md freshness / audit-self regression integration | Self-gap (Always-On 4 enforcement) | | v5.22.2 | audit-self rule sensitivity layer (T11–T25) — 15 inline violation fixtures prove rules catch intended patterns. Self-discovered jq escape bug in T13. | Self-discovered via meta-loop | | v5.22.1 | hooks/session-start.sh MCP load alert — caches claude mcp list 1h, surfaces ⚠️ when >10 servers active | ECC §P1-2 (10/80 rule) | | v5.22.0 | /nova:audit-self command + 30-rule security rulebook (5 categories: plugin/hooks/agents/skills/commands). Generator-Evaluator separation applied to Nova's own codebase. | ECC AgentShield §P1-1 |

Closed: Known Risks Medium (release.sh review-trail gate) and Info (audit-self rule sensitivity). Identity layer untouched — five pillars, slogan, Generator-Evaluator separation, NOVA-STATE 9-entry continuity all intact. See [docs/proposals/2026-04-29-ecc-adversarial-gap.md](docs/proposals/2026-04-29-ecc-adversarial-gap.md) for the full adoption rationale and what was deliberately rejected (183-skill quantity race, auto-promotion, 100% PreToolUse observation).

Quick Start

Codex Desktop / CLI (Beta)

# Install Nova with the recommended Codex plugin set
curl -fsSL https://raw.githubusercontent.com/TeamSPWK/nova/main/scripts/install-codex-recommended-plugins.sh | bash

Restart Codex after installation. See the [Codex plugin install guide](docs/guides/codex-plugins.md) for options and troubleshooting.

> In Codex Phase 1, Nova skills and MCP tools are available. Claude Code-only hooks and slash-command differences are covered in the install section below.

For repositories that already use CLAUDE.md, keep AGENTS.md as a thin Codex bridge:

Before repository work, use the Nova `repo-preflight` skill.
Project-specific instructions live in `CLAUDE.md`.

To reorganize CLAUDE.md, AGENTS.md, rules, settings, and hooks without turning one file into a catch-all, run /nova:claude-md. It starts with a short guide and audits the current repo without editing files. See the [Agent Instruction Guide](docs/guides/claude-md.md) for the placement rules.

Claude Code

# Install (30 seconds)
claude plugin marketplace add TeamSPWK/nova
claude plugin install nova@nova-marketplace

# Start
/nova:next   # Shows what to do next

What Is Nova?

Nova is a checkpoint inside the AI orchestrator loop. It verifies that generated code is correct, and orchestrates complex multi-step workflows when needed.

┌─────────────────────────────────────────────────┐
│  User Request                                    │
│       ↓                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │ Generator │───→│  Nova    │───→│Done/Fix  │   │
│  │ (Build)   │    │ (Verify) │    │          │   │
│  └──────────┘    └──────────┘    └──────────┘   │
│                       ↑                          │
│              Independent subagent                │
│              Adversarial stance                  │
└─────────────────────────────────────────────────┘

The core principle is Generator-Evaluator Separation: the agent that writes code and the agent that verifies it are always different. This prevents the "reviewing your own homework" trap.

> Context chain (session-to-session memory) uses append-only JSONL + text-based NOVA-STATE.md — zero external dependencies (no vector DB, no embedding API). See [Nova vs claude-mem vs Continuous-Claude-v3](docs/comparison/context-chain-vs-external.md) for trade-offs.

Architecture: Harness Engineering

Nova works by engineering Claude Code's harness layer — the hooks, commands, agents, and skills system that wraps around the LLM. Instead of changing what the model knows, Nova controls when, how, and under what rules the model operates.

┌─────────────────────────────────────────────────────┐
│  Claude Code Harness                                 │
│                                                      │
│  ┌─────────────────┐   SessionStart hook             │
│  │ session-start.sh │──→ Injects 10 rules as         │
│  │                  │    LLM context every session    │
│  └─────────────────┘                                 │
│                                                      │
│  ┌─────────────────┐   slash commands                │
│  │ .claude-plugin/  │──→ /nova:plan, /nova:review,    │
│  │   *.md           │    /nova:check, /nova:run ... │
│  └─────────────────┘                                 │
│                                                      │
│  ┌─────────────────┐   5 specialist subagents        │
│  │ .claude-plugin/  │──→ architect, senior-dev,       │
│  │   agents/*.md    │    qa-engineer, security, devops │
│  └─────────────────┘                                 │
│                                                      │
│  ┌─────────────────┐   5 complex skills              │
│  │ skills/*/SKILL.md│──→ evaluator, jury,             │
│  │                  │    context-chain, field-test,   │
│  │                  │    orchestrator                 │
│  └─────────────────┘                                 │
└─────────────────────────────────────────────────────┘

| Layer | File | Mechanism | What It Does | |-------|------|-----------|-------------| | Rules injection | hooks/session-start.sh | SessionStart hook | Injects 10 auto-apply rules into every session as LLM context | | Commands | .claude-plugin/*.md | Slash commands | User-invocable workflows (/nova:plan, /nova:review, /nova:check, etc.) | | Agents | .claude-plugin/agents/*.md | Subagent types | Specialist agents with domain-specific checklists | | Skills | skills/*/SKILL.md | Skill system | Complex multi-step operations (evaluation, jury, context chain, orchestration) | | MCP Server | mcp-server/ | stdio MCP | Exposes Nova rules, state, and tools to any Claude Code session |

Key distinction: "Auto-apply rules" means session-start.sh injects rule text into Claude's context at session start. Claude then follows these rules as behavioral guidelines — it's prompt-level governance via the harness, not a code-level interceptor.

Workflow

Auto Workflow (Natural Language)

Once installed, Nova's Quality Gate automatically applies to every conversation — no commands needed. Just describe your task in natural language.

"Build a feature" ──→ Auto complexity assessment
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
           [Simple]        [Medium]        [Complex]
              │               │               │
           Implement       Plan→Approve    Plan→Design
              │               │            →Sprint split
              │            Implement        →Approve
              │               │               │
              ▼               ▼               ▼
        ┌──────────┐    ┌──────────┐    ┌──────────┐
        │Evaluator │    │Evaluator │    │Evaluator │
        │  Lite    │    │ Standard │    │  Full    │
        └──────────┘    └──────────┘    └──────────┘
              │               │               │
           [PASS]          [PASS]          [PASS]
              ↓               ↓               ↓
            Done             Done            Done

Manual Workflow (Commands)

/nova:plan → /nova:ask (if needed) → /nova:design → Build → /nova:check

How It Works: Examples

Example: "Build a login API"

User: "Build a login API"
         ↓
Nova auto-judges:
  1. Complexity → "Auth domain, escalate → Medium"
  2. Writes Plan → Waits for user approval
  3. After approval → Implements
  4. Independent Evaluator subagent runs adversarial review
     → "jwt_secret_key hardcoded → Hard-Block"
  5. Hard-Block found → Reports to user immediately

Example: "Fix this bug" (Simple)

User: "Fix the NullPointerException"
         ↓
Nova auto-judges:
  1. Complexity → "1 file, clear bug → Simple"
  2. Fixes immediately
  3. Independent Evaluator runs Lite verification
  4. PASS → Done

Example: "Refactor entire auth system" (Complex)

User: "Switch from JWT to session-based auth"
         ↓
Nova auto-judges:
  1. Complexity → "8+ files, auth domain → Complex"
  2. Plan → Design → User approval
  3. Sprint split (Sprint 1: Session model, Sprint 2: Middleware, ...)
  4. Per-sprint: Implement → Evaluate loop
  5. Full verification → Done

Auto-Apply Rules (10 Rules)

These rules apply to every conversation the moment Nova is installed. They are injected as LLM context via the session-start.sh hook.

1. Automatic Complexity Assessment

| Complexity | Criteria | Auto Behavior | |-----------|----------|--------------| | Simple | 1-2 files, clear bug | Implement → Evaluator Lite | | Medium | 3-7 files, new feature | Plan → Approve → Implement → Evaluator Standard | | Complex | 8+ files, multi-module | Plan → Design → Sprint split → Evaluator Full |

• Auth/DB/Payment domains escalate one level regardless of file count
• Re-assess if file count exceeds initial estimate during work

2. Generator-Evaluator Separation + Pre-Commit Gate (Core)

• Implementation (Generator) and verification (Evaluator) are always separate agents
• Evaluator takes an adversarial stance: "Find problems, don't rubber-stamp"
• Lite verification by default; full verification only with --strict

Pre-commit gate: Implementation complete → tsc/lint pass → Evaluator run → PASS → commit allowed. No deploy before Evaluator PASS (exception: --emergency).

3. Verification Criteria (5 Dimensions)

| Criterion | What It Checks | |-----------|---------------| | Functionality | Does it actually work? (compared against requirements) | | Data Flow | Input → Store → Load → Display → Deliver to user — complete? | | Design Alignment | Consistent with existing code/architecture? | | Craft | Error handling, edge cases, type safety | | Boundary Values | Does it survive 0, negative, empty string, max values without crashing? |

4. Execution Verification First

• "Code exists" ≠ "Code works"
• "Tests pass" ≠ "Verified" — boundary values must be checked separately
• Environment changes follow 3 steps: Check current → Change → Verify applied

5–10. Additional Rules

| Rule | Description | |------|------------| | §5 Lightweight Verification | Default is Lite. Full verification only with --strict | | §6 Sprint Split | 8+ file changes split into independently verifiable sprints | | §7 Blocker Classification | Auto-Resolve / Soft-Block / Hard-Block. Forced classification after 2 repeated failures | | §8 NOVA-STATE.md | Immediate update on deploy/test/sprint/blocker/eval results. Known Gaps required | | §9 Emergency Mode | --emergency skips Plan/Design. Fix now, verify after | | §10 Environment Safety | Never edit config files directly. Use env vars or CLI flags |

Commands

Commands provide additional control on top of auto-apply rules.

| Command | Description | |---------|------------| | /nova:ask | Run multi-AI consultation. Queries Claude + GPT + Gemini in parallel and analyzes the consensus level. | | /nova:auto | Auto-run a natural-language request through the full design → implement → verify → fix cycle. | | /nova:check | Combined code review + design-implementation gap verification in one pass. | | /nova:checkpoint | Before ending a session, checks STATE drift and honestly reports classification of suspected-done items. Does not misrepresent untracked items as complete. | | /nova:claude-md | Show a guided intro, audit CLAUDE.md/AGENTS.md instructions, and propose a new/existing project reorganization. | | /nova:deepplan | Generate a deep Plan document via an Explorer → Synth → Critic → Refiner 4-stage pipeline. | | /nova:design | Write a Design document using the CPS (Context-Problem-Solution) framework. | | /nova:migrate-state | Migrate NOVA-STATE.md to v3 work-item registry (latest). Accepts v1/v2 input directly — no multi-hop needed. Flow: dry-run → user review → apply + drift-check auto. | | /nova:next | Diagnose current project state and recommend the next Nova command to run. | | /nova:plan | Write a Plan document using the CPS (Context-Problem-Solution) framework. | | /nova:review | Review code adversarially and surface hidden issues. | | /nova:run | Run the implement → verify full cycle. Use --verify-only to run verification alone. | | /nova:scan | Auto-analyze a codebase on first entry and brief you on 'where to start looking'. | | /nova:setup | Initial Nova Quality Gate setup for a new project, or auto-fill gaps in an existing project (--upgrade). | | /nova:status | View project status (Phase/Sprint/group progress) + drift alerts as a stand-alone HTML. | | /nova:ux-audit | Deep UI/UX evaluation via 5 adversarial reviewers — accessibility (WCAG 2.2), cognitive load, performance (Core Web Vitals), and dark patterns (EU DSA) analyzed from code. | | /nova:worktree-setup | Instantly symlink the main repo's .env, secrets, and config files into the current worktree. Manual retry of the SessionStart auto-hook. |

Automatic Schedule

Runs automatically via Claude Code remote agent every Mon/Wed/Fri at 06:00 KST.

Manage: https://claude.ai/code/scheduled

MCP Server

Nova includes a local MCP (Model Context Protocol) server that exposes Nova's rules, state, and tools to any Claude Code session — even outside the Nova project.

Setup

cd mcp-server && pnpm install && pnpm build

The .mcp.json at project root auto-register

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TeamSPWK
• Source: TeamSPWK/nova
• License: MIT
• Homepage: https://jay-swk.github.io/nova-landing

Install and usage instructions live in the source repository linked above.