donnyclaude

Instinct-based learning system that observes sessions via hooks, creates atomic instincts with confidence scoring, and evolves them into skills/commands/agents. v2.1 adds project-scoped instincts to prevent cross-project contamination.

Adds an idea to the backlog parking lot using 999.x numbering, kept outside the active phase sequence so it accumulates context without being scheduled. Use when an idea is worth keeping but not ready to plan into the current milestone.

Generate unit and E2E tests for a completed phase, using its SUMMARY, CONTEXT, and VERIFICATION artifacts as the spec and gating unit tests on a mutation check. Use when a finished phase needs test coverage; requires the phase number and an existing SUMMARY.md.

Analyze the current milestone's phase dependency graph (file overlap, semantic and data-flow links) and suggest Depends on entries for ROADMAP.md. Use before parallel phase execution to prevent merge conflicts from unordered phases.

Audit a milestone against its definition of done before archiving: aggregate per-phase VERIFICATION results, cross-check requirements coverage from three sources, spawn an integration checker for cross-phase wiring, and emit a structured audit report. Use when wrapping up a milestone, before /donny-complete-milestone, to confirm nothing was missed.

Retroactively audits a completed phase for security (threat mitigations from the PLAN.md threat model are implemented) and validation (Nyquist test coverage of the phase's requirements). Use after a phase is executed to confirm threats are closed and requirements are tested; runs both audits by default. --security or --validate narrows to one. Open threats block phase advancement.

Scans every phase for outstanding UAT and verification items (pending, skipped, blocked, human-needed), cross-references the codebase to flag stale entries, and produces a prioritized human test plan. Use to find all manual testing still owed across the project.

Runs all remaining milestone phases end to end - discuss, plan, execute, verify per phase - pausing only for decisions or blockers, then audits, completes, and cleans up the milestone. Use when you want to advance the roadmap hands-off; scope with --from, --to, or --only N, or --interactive to answer discuss questions inline.

Capture and triage ideas, tasks, and todos during a session. Subcommands: note (default, zero-friction quick note), todo (structured todo committed to git), todos (list and act on pending todos), promote (turn a note into a todo). Use when an idea or follow-up surfaces mid-work and should be saved without losing focus, or to review and pick up captured todos.

Archive phase directories from completed milestones into .planning/milestones/v{X.Y}-phases/ so orphaned dirs stop confusing milestone-aware commands. Use when .planning/phases/ has accumulated dirs from past milestones; pass --dry-run to preview without moving anything.

Archive a completed milestone and prepare the next cycle: snapshot ROADMAP and REQUIREMENTS into .planning/milestones/, evolve PROJECT.md, append a retrospective, and create a signed git tag. Use when every phase of the current milestone has shipped and verified and the version is ready to close out before starting the next one.

Systematic root-cause debugging by the scientific method, with session state persisted across context resets. Use when investigating a bug, error, test failure, or unexpected behavior, or resuming a prior debug session; pass --diagnose to find the root cause without applying a fix.

Gathers phase implementation decisions before planning: always surfaces Claude's key assumptions for correction, then deep-dives the gray areas the user picks, and writes CONTEXT.md. Use before planning a phase to lock choices so the researcher and planner don't re-ask. --auto picks recommended defaults non-interactively; --chain continues into plan+execute; --power batches every question into a file-based UI; --text uses plain numbered lists for remote sessions.

Routes freeform natural-language intent to the right Donny command and invokes it, acting as a dispatcher rather than doing the work itself. Use when you know what you want done but not which /donny-* command runs it.

Generate or update up to nine project documentation files, each written and fact-checked against the live codebase by subagents. Use when project docs (README, ARCHITECTURE, API, etc.) are missing or stale; pass --verify-only to check accuracy without writing, or --force to regenerate all docs.

List Donny multi-repo environments (workspaces) with name, path, repo count, strategy, and project status. Use when reviewing or managing the isolated workspaces created by /donny-env-new, before switching into one or removing it.

Create an isolated multi-repo environment: a workspace directory of git worktrees or clones, each with its own independent .planning/. Use when running parallel Donny sessions across several repos, or isolating a feature on a worktree with separate planning state. Distinct from /donny-workstreams (logical concurrency inside one project).

Remove a Donny multi-repo environment (workspace) and clean up its git worktrees, after typed confirmation. Refuses if any member repo has uncommitted changes. Use when deleting a workspace created by /donny-env-new once its work is merged or abandoned.

Executes every PLAN.md in a phase with wave-based parallel subagents, then runs phase verification and updates state. Use to build a planned phase. --wave N runs one wave for pacing or quota limits, --gaps-only runs just gap-closure plans after verify-work, --interactive runs plans inline with checkpoints instead of spawning subagents.

Post-mortem investigation for a failed or stuck Donny workflow run. Reads git history, .planning/ artifacts, and filesystem state to detect anomalies and write a diagnostic report. Use when autonomous or phase execution stalled, failed silently, looped, or behaved unexpectedly and you need to know why.

Validate .planning/ directory structural integrity (missing files, bad config, orphaned phase dirs, state drift) and optionally auto-repair fixable issues. Use when commands behave oddly, after a crash, or to check planning health; pass --repair to fix repairable problems.

Shows the complete Donny command reference, grouped by task, with arguments and common workflow recipes. Use when checking which donny commands exist or how they fit together.

Initialize Donny planning for a project: bootstrap a brand-new project (deep questioning, optional research, requirements, roadmap) or start the next milestone on an existing one. Auto-detects greenfield vs. brownfield from .planning/PROJECT.md presence. Use when starting a project from scratch, kicking off a new milestone or version cycle, or running the first Donny setup in a repo. The --milestone flag forces milestone mode; --auto runs the greenfield flow unattended from an idea document.

Single-terminal command center for a milestone: a live dashboard of every phase with status, recommended next actions, and dispatch (discuss runs inline, plan and execute run as background agents). Use when driving or parallelizing work across many phases from one terminal instead of running phase commands one at a time.

Analyze an existing codebase with parallel mapper agents to produce seven structured .planning/codebase/ documents (stack, architecture, structure, conventions, testing, integrations, concerns). Use on a brownfield project before planning, or to refresh the codebase map after major changes; pass an optional focus area.

Generate a human-readable milestone summary from the planning artifacts (ROADMAP, REQUIREMENTS, per-phase CONTEXT/SUMMARY/VERIFICATION) covering architecture, phases, key decisions, requirements, and tech debt. Use when someone needs to understand a finished or in-progress milestone from one document, for team onboarding or review.

Detects the current project state from STATE.md, ROADMAP.md, and phase directories and immediately invokes the next logical Donny step (discuss, plan, execute, verify, or complete). Use when moving fast across projects and you do not want to track which phase or step comes next.

Captures complete work state into a machine-readable HANDOFF.json and a human-readable .continue-here.md, then commits them as WIP. Use when stopping mid-phase so the next session resumes with full context.

Adds a new phase to the current milestone's roadmap. Appends the next integer phase by default; with --after N inserts a decimal phase (N.1, N.2, ...) right after phase N for urgent mid-milestone work, without renumbering. Use to extend the roadmap with planned work, or to slot in urgent work discovered during execution. Creates the phase directory and ROADMAP.md entry; does not plan or commit.

Create every fix phase needed to close the gaps a milestone audit found, in one pass instead of manual /donny-phase-add calls. Reads the latest MILESTONE-AUDIT.md, groups gaps into logical phases, and updates ROADMAP.md and the requirements traceability table. Use after /donny-audit-milestone reports gaps.

Creates executable PLAN.md files for a roadmap phase, integrating research, planning, and a verification loop. Use to turn a phase, with or without prior discuss-phase context, into verified wave-grouped plans ready to execute. Flags narrow the flow: --skip-research, --gaps (close gaps from VERIFICATION.md), --reviews (replan from cross-AI feedback), --prd <file> (plan straight from a PRD), --auto to advance into execute.

Captures a forward-looking idea as a seed with explicit trigger conditions, so it surfaces automatically during donny-init when the milestone scope matches. Use when an idea is too big for now but must not be forgotten, it preserves why it matters, when to surface, and breadcrumbs to related code.

Generates a developer behavioral profile from Claude Code session analysis (or a questionnaire fallback) and writes artifacts (USER-PROFILE.md, a donny-dev-preferences command, CLAUDE.md sections) that personalize Claude's responses. Use to teach Claude how you actually work; --refresh rebuilds an existing profile, --questionnaire skips session analysis.

Reports project progress with inline statistics (phase, plan, and requirement counts, git metrics, timeline) and routes to the next action. Use when checking where a project stands, what was recently done, and whether to execute an existing plan or plan the next phase.

Executes a small ad-hoc task with Donny guarantees (atomic commit, STATE.md tracking) without a full roadmap phase. Triages automatically: runs inline for a trivial one-liner, or spawns a planner plus executor for a real change. Use when you have a one-off task to track outside the phase workflow; add --discuss, --research, --validate, or --full to layer on quality stages.

Removes an unstarted future phase from the roadmap and renumbers every subsequent phase for a clean linear sequence. Use to drop planned work that is no longer needed. Refuses started or completed phases. --dry-run previews the deletion and renumbering without changing anything.

Researches how to implement a phase without planning it: spawns the phase-researcher in a fresh context and writes RESEARCH.md. Use when research is the goal on its own, before deciding whether a phase is viable, or to re-research after a phase is planned. To research and plan in one step, use /donny-plan-phase, which runs this automatically.

Restores full project context from a previous session - STATE.md, checkpoints, incomplete plans, and pause-work handoffs - then routes to the next action. Use when returning to a project to pick up exactly where you left off.

Reviews every 999.x backlog item one by one and promotes, keeps, or removes each. Use when clearing the backlog parking lot into the active milestone, typically before starting or planning a new milestone.

Runs cross-AI peer review of a phase's plans by invoking external AI CLIs (Gemini, Claude, Codex, CodeRabbit, OpenCode) and writes a structured REVIEWS.md with per-reviewer feedback and a consensus summary. Use to get independent review of phase plans before execution; feed results back via donny-plan-phase --reviews. The phase defaults to the current phase in STATE.md.