nazgul

NAZGUL

Multi-agent autonomous development loop for Claude Code
Discovery • Planning • Implementation • Review • Repeat

Nazgul runs a complete autonomous SDLC pipeline — from scanning your codebase to shipping reviewed code — with 22 core agents plus project-specific reviewers.

What Nazgul Does

• Auto-detects your project — classifies it (greenfield, brownfield, bugfix, refactor, migration) and tailors the pipeline
• Generates docs before code — PRDs, TRDs, and ADRs so agents build with context
• Multi-agent review board — Architect, Security, Code Quality + project-specific reviewers; all SELECTED reviewers must approve every task (opt-in diff-aware dispatch can skip domains the change does not touch)
• Fix-first review — auto-fixes mechanical issues (dead code, style), only asks about risky changes (security, architecture)
• Per-stage model routing — assign Opus, Sonnet, or Haiku to each pipeline stage for the right balance of cost, speed, and quality
• Tamper-evident, cost-optimized reviews — diff-bound provenance manifests catch a skipped or stale review board, a comment-verifier gate blocks templated or restated doc-comments, and diff-only reviewer context plus per-reviewer model tiering cut review token cost
• Survives interruptions — checkpoints, recovery pointers, session tracking, and hooks mean you can close your laptop and resume later; when guards.in_flight_hold is enabled and a fresh marker shows dispatched work still running, the loop holds an allowed, uncounted stop instead of burning iterations on it (markers past guards.in_flight_stale_minutes take the loud in_flight_stale path instead)
• Transactional task state, with a repair route instead of rework — every task status change goes through one sanctioned writer (scripts/task-transition.sh) that validates the live edge and its evidence, compare-and-swap writes the manifest, verifies it on disk, and only then records authority; a validated request is never treated as proof the write happened. When the loop can't trust a manifest it files a typed quarantine naming what disagreed, and the single evidence-gated repair route revalidates that evidence and closes the task out — it never re-runs an implementer over work that was already done
• Opt-in parallel dispatch — /nazgul:start --parallel lets the same sequential stop-hook loop batch-dispatch independent, zero-file-overlap plan waves together instead of one task at a time, with autonomous-first approval gates and two unconditional human-in-the-loop hard stops; sequential single-task dispatch stays the default
• Opt-in automation heartbeat — /nazgul:heartbeat (or an opt-in Claude Code scheduled-agent routine) triages a local work inbox and auto-starts the next objective when idle, behind the same two unconditional hard stops; default off
• Opt-in GitHub two-way connector — pulls labeled issues into the inbox so the heartbeat can auto-start them and pushes task status + PR links back to the mapped issue, behind a generalized provider seam (file/github); gh-auth-only (no tokens stored), auto-disables after repeated failures; default off (Linear/Slack are follow-on providers behind the same seam)
• Opt-in stacked-PR continuation — /nazgul:start --stack lets an objective's end branch straight into the next one instead of idling: objective N+1 branches off objective N's unmerged tip and stacks its PR on top via GitHub's official gh-stack CLI extension, which owns every retarget/rebase/merge mechanic server-side. Fail-closed throughout — unusable tooling falls back to today's single-PR-and-stop, a sync conflict halts stacking and files a rework item rather than ever auto-resolving; default off

Install

From the Orodruin Labs marketplace (recommended):

/plugin marketplace add OrodruinLabs/nazgul
/plugin install nazgul

Direct install from GitHub:

/plugin install nazgul@github:OrodruinLabs/nazgul

Manual install (for development or pinning a specific version):

git clone https://github.com/OrodruinLabs/nazgul.git ~/.claude/plugins/nazgul

Update:

/plugin                # Select nazgul → "Update now"

Or enable auto-updates: /plugin → Marketplaces tab → orodruin-labs → Enable auto-update.

Quick Start

[!TIP]
3 commands to get started:

/nazgul:init            # Set up Nazgul for your project
/nazgul:start           # Start the autonomous loop
/nazgul:status          # Check progress anytime

Nazgul auto-detects project state: active work resumes, existing docs trigger planning, fresh projects scan for TODOs/issues/failing tests. Override with /nazgul:start "specific objective".

[!WARNING]
Autonomous mode skips all permission prompts:

claude --dangerously-skip-permissions
/nazgul:start --yolo --max 30

Commands

See /nazgul:help for the full command list and all flags.

[!NOTE]
/nazgul:start now asks which mode (HITL / AFK / YOLO) when no mode flag is passed and no default_mode is set in config. To skip the prompt, pass --hitl, --afk, or --yolo, or set config.default_mode once via /nazgul:config. YOLO is always confirmed on every path, including an explicit --yolo flag.

Model Routing

Different pipeline stages have different complexity needs. Nazgul lets you assign the right model to each stage:

Configure during init or anytime after with /nazgul:config:

/nazgul:config models        # Jump straight to model settings

Three presets available: Balanced (default), Quality (all Opus), and Fast/cheap (Haiku where possible). Or pick per stage.

Just want docs and agents without Nazgul?

/nazgul:bootstrap-project runs the pre-planning pipeline once and outputs a portable bundle — no Nazgul dependency required. You get project docs, codebase context, and tailored Claude subagents that work with plain Claude Code.

What it generates:

• ./docs/ — PRD, TRD, ADRs
• ./docs/context/ — Codebase analysis from Discovery
• ./.claude/agents/ — Project-specific reviewer agents

Usage:

/nazgul:bootstrap-project "your objective"

All Nazgul references are scrubbed from the output. Won't run if ./nazgul/ exists (use /nazgul:start for full pipeline instead).

How It Works

Nazgul runs a pipeline of specialized agents. Discovery scans your codebase and classifies the project. The Doc Generator creates foundational documents. The Planner decomposes your objective into dependency-ordered tasks. The Implementer builds each task (delegating to specialists like Frontend Dev, DevOps, or DB Migration as needed). A Review Board of 3-13 reviewers must unanimously approve each task before it advances — mechanical issues are auto-fixed, only risky changes require discussion. The loop continues until every task is done, then Post-Loop agents handle documentation, releases, and observability.

Agents can optionally self-rate their experience and file improvement reports, creating a feedback loop for plugin quality. Concurrent sessions are detected via filesystem locks to prevent state corruption.

Autolearning

Nazgul mines recurring mistakes — review rejections, debugger diagnoses, and repeated test failures — from existing on-disk artifacts and distills them into candidate Learned Rules stored in nazgul/learning/learned-rules.md. Rules are human-gated: the learner agent proposes candidates to nazgul/learning/proposed-rules.md, and you approve, edit, or reject them interactively via /nazgul:learn (also supports --dry-run to preview candidates without writing, and --retire to clean up un-cited rules). Each approved rule gets a stable, monotonic LR-NNN identifier, declares Scope-Agents and Scope-Globs, and is injected only into the matching agents at dispatch time — so the rule registry can grow without bloating unrelated agents' context. Reviewers cite applicable rules by LR-NNN; citations feed a hit counter that surfaces the most impactful rules in /nazgul:metrics and triggers retirement of rules that are never cited.

See Architecture for the full agent roster, pipeline details, and recovery system.

Requirements

• jq — Required for JSON manipulation in hook scripts
• git — Required for commit tracking and state persistence
• Claude Code — Agent Teams is enabled automatically by /nazgul:init

Learn More

• Architecture — Pipeline, agent roster, recovery, directory structure
• Configuration — Start flags, local mode, board sync
• Safety & Rules — The 10 rules, guardrails, troubleshooting
• Plugins — Companion plugins, compatibility matrix, OpenClaw

License

MIT