Getting Started

What is Code
Addiction?

Code Addiction is a spec-driven framework for AI coding assistants. It standardizes how features go from idea to production through structured, repeatable workflows — installed in any project with a single command.

.codeadd/

Shared core: commands, scripts, skills, templates

Provider adapters

Claude, Codex, Antigravity, Cursor, OpenCode

codeadd CLI

install, update, uninstall, doctor, validate, features, plugins, config

Installation

Requires Node.js 18+. Works on Windows, macOS, and Linux.

# install in your project
$ npx codeadd install
# install specific version
$ npx codeadd install --version v2.0.1
# install from a specific branch
$ npx codeadd install --branch feature-xyz

What gets installed

your-project/
├── .codeadd/← core (always)
├── .claude/← Claude Code
├── .agents/← Codex (OpenAI)
├── .agent/← Antigravity
├── .cursor/← Cursor
└── .opencode/← OpenCode

Quickstart

After installing, use these CLI commands to manage your setup:

npx codeadd doctorCheck environment health — Node, Git, installation status
npx codeadd validateValidate file integrity via SHA-256 hashes
npx codeadd validate --repairRestore missing or modified files from the release
npx codeadd updateUpdate to latest release, or re-pull current branch
npx codeadd uninstallClean removal of all Code Addiction files (user files are kept)
npx codeadd uninstall --forceSkip confirmation prompt during uninstall
npx codeadd featuresList, enable, or disable optional features (tdd-pipeline, qa-pipeline)
npx codeadd pluginsList, enable, or disable MCP plugins (e.g. GitNexus, Playwright)
npx codeadd config showDisplay installation configuration. Add --verbose to check for updates

Reference

Commands

Every command is a slash command you type in your AI coding assistant. They orchestrate discovery, planning, implementation, and delivery.

Discovery

/add.brainstorm

Explore ideas (read-only)

/add.new

AI-guided feature discovery → about.md

/add.wiki

Generate a portable project wiki (.codeadd/wiki/)

Planning

/add.plan

Technical Planning Orchestrator — dispatches UX Design, Database, Backend and Frontend agents. Sole writer of design.md (STEP 8.1) for UI-touching features

Implementation

/add.build

Development Execution Specialist — closes each delivery unit with its own Final Review

Quality

/add.review

Feature review specialist — read-only code review and spec-compliance audit; with the qa-pipeline feature enabled, also agent-judged QA (dual-judge panel over persisted run evidence). Dispatches an OWASP Top 10 pass alongside the area review when the diff touches a sensitive area (auth, payment, upload, input handling, session/token). Consolidates every finding into one ## Fix Routing table and writes a versioned review-NNN.md. Routes findings, never applies them. Optional — /add.build runs its own Final Review, and /add.done accepts whichever verdict is most recent

/add.audit

Full project health analysis

/add.diagnose

Pre-decision triage for ambiguous symptoms (read-only); persists the diagnosis for /add.hotfix to reuse

/add.qa-setup

End-to-end-verified QA bootstrap — verifies + installs the QA runner, generates qa-project, scaffolds config/screens, ignores ephemeral working evidence under a setup contract, migrates existing QA, and smoke-tests the QA judgement via /add.review

Delivery

/add.done

Branch completion and merge - promotes reviewed QA evidence, finalizes changelog and documentation, then merges. Hotfix close-out requires a passed Review receipt in about.md

/add.pull-request

Idempotent PR — creates new PR or appends update section if one is already open. Generates feature changelog on feature branches

/add.hotfix

Emergency fix with global ID (H[NNNN]) — reuses an accepted /add.diagnose when available

Utilities

/add

Smart gateway — answers questions, guides flow

/add.ux

Quick UX — loads ux-design for free context

Reference

Artefact graph

How the commands hand off to each other. Generated by the build from each command's own declaration, so it cannot drift from what ships — a test fails if this picture and the graph disagree.

Commands only, one hop. The full graph carries 225 artefacts and 857 relationships; drawn at once it is a hairball that tells you nothing. Skills, agents and scripts are reachable from the query surface below.

Loading diagram…

Query it directly: node scripts/graph.js impact add-doc-schemas

Reference

Flows

Pick the shortest path that fits. Less ceremony, same quality.

Complete Flow

Complex features with UI — full discovery, planning (design is produced inside /add.plan STEP 8.1), implementation, review.

Brainstorm
/add.brainstorm→New
/add.new→Plan
/add.plan→Code
/add.build→Check
/add.review→Done
/add.done

Standard Flow

Features without complex UI — skip brainstorm and design

New
/add.new→Plan
/add.plan→Code
/add.build→Done
/add.done

Lean Flow

Small changes, quick tasks — minimal ceremony

New
/add.new→Code
/add.build→Done
/add.done

Automatic Flow

One approval at the brainstorm — each stage hands off to the next, the build closes each delivery unit with its own Final Review, and it asks before opening the PR. The merge stays human

Brainstorm
/add.brainstorm→New
/add.new→Plan
/add.plan→Build (final review)
/add.build→PR question

Emergency Flow

Critical bug in production — fast track to fix

Hotfix
/add.hotfix→Done
/add.done

Exploration Flow

Don't know where to start? Brainstorm first, then pick any flow above

Brainstorm
/add.brainstorm→New
/add.new→...pick your flow

Reference

Scenarios

Real-world examples of when to use each flow.

COMPLETE

"Build a user dashboard with charts and filters"

Complex feature with UI, multiple user flows, needs discovery and design.

/add.brainstorm → explore scope and requirements
/add.new → define requirements, acceptance criteria
/add.plan → technical architecture, UX contract, task breakdown
/add.build → subagent-driven implementation
/add.review → automated code review
/add.done → changelog, docs, merge
STANDARD

"Add email notifications for order status"

Backend feature, no complex UI. Needs planning but no design phase.

/add.new → define notification triggers, templates
/add.plan → service architecture, queue strategy
/add.build → implement
/add.done → finalize
LEAN

"Add a loading spinner to the submit button"

Small, well-defined change. Minimal ceremony.

/add.new → quick spec
/add.build → implement
/add.done → finalize & merge
CONVERGENCE

"Implement the 5 API endpoints from the spec"

Well-specified work. Approve once, let the stages hand off, then take the merge decision yourself.

/add.brainstorm → approve with "deliver automatically"
new → plan → build (final review) → runs unattended until the PR question
/add.done → finalize
EMERGENCY

"Users can't login — auth token validation is broken"

Critical production bug. Fast-track fix with tracking.

/add.hotfix → diagnose, fix, document with global ID
/add.done → deploy
EXPLORATION

"I want to add AI to the product but don't know where to start"

Unclear scope. Start with brainstorming, then pick a flow.

/add.brainstorm → explore possibilities, no commitment
/add.new → lock in what you'll build
→ ...pick Complete, Standard, or Lean from here

Deep Dive

Skills

Skills are specialized knowledge modules loaded by commands. They provide domain expertise for backend, frontend, database, UX, security, and more.

backend-developmentSOLID, Clean Arch, DTOs, Services, Repository — stack-agnostic
frontend-developmentState, data fetching, components, forms, routing — stack-agnostic
database-developmentEntities, repositories, migrations, naming — stack-agnostic
ux-designComponents, mobile-first, SaaS patterns, shadcn, Tailwind
security-auditOWASP checklist, RLS, secrets, multi-tenancy
code-reviewCode review: IoC, RESTful, Contracts, Security (OWASP), Clean Architecture, SOLID
feature-discoveryDiscovery process, codebase analysis
feature-specificationSingle writer of about.md — reads the brainstorm intent file, extracts closed decisions without asking, and asks only what is still open. Loaded by /add.new and by /add.brainstorm when it continues into authoring.
architecture-discoveryMap architecture, detect patterns, stack-context.md
delivery-validationProduct validation: Requirements 100% implemented, prerequisites exist, acceptance criteria pass
subagent-driven-developmentCoordinate subagents with quality gates
add-tasks-checklistUse when generating, reading, or ticking tasks.md — defines the canonical 5-section schema, tick rules per section, failure marker semantics, 'non-trivial change' rule, and the architect subagent prompt template
stripeStripe integration, price versioning, grandfathering
token-efficiencyCompression, compact JSON, minimal tokens
commitSmart commit with auto-generated Conventional Commits messages
project-scaffoldingScaffold Node.js projects (Express, Fastify, NestJS, Bun) — monolith or monorepo
health-checkTech health check suite: docs, security, architecture, data analysis
plan-based-featuresSubscription plan gating — 3-layer PlanFeatures pattern and IPlanService
dev-environment-setupDetect OS, install missing tools, configure VS Code terminal
optimizing-git-workflowComplete Git config: colors, aliases, smart defaults, performance
backend-architectureBackend architecture patterns and workspace conventions
frontend-architectureFrontend architecture patterns and workspace conventions
ecosystemADD ecosystem map and framework overview
investigationDeep diagnostic investigation for ambiguous findings
resource-path-conventionConsistent resource path conventions across the project
id-conventionCanonical [NNNN][L] ID and branch naming format expected by next-id.sh, get-branch-metadata.sh, done.sh
skill-creatorCreate and structure new ADD skills
agents-md-styleUse when generating or updating the project's AGENTS.md — migrates any legacy context file into it first, then defines what belongs vs. what stays in skills/docs, format rules (JSON for data, markdown for rules/instructions), and line budget. Load before any AGENTS.md write.
add-tddRED-GREEN-REFACTOR execution discipline for AI agents. Use when implementing any feature or bugfix that has (or should have) tests — forces a failing test confirmed for the right reason before any production code. Loaded by add.build.
add-test-specificationGenerate contract test cases from feature requirements (RFs/RNs) and technical contracts. Use when add.plan needs to produce plan-test-spec.md mapping each requirement to testable cases before implementation.
add-qa-specGenerate a code-free QA/E2E specification (reachability intent, UX acceptance criteria, functional E2E scenarios, capture states, target viewports, a11y expectations) from about.md + design.md + plan-*.md, and author the _tests/screens.json screen catalog by read-merge-write. Loaded by add.plan's qa-pipeline QA-Spec step.
add-qaUse when running agent-judged QA validation (read-PNG by default; the playwright plugin adds live driving) — the Level C judge rubric, severity taxonomy, dual-judge (@ux-agent review ∥ @qa-agent) method, report schema/template, and the config.json/screens.json formats. Consumed by /add.review and both judges.
add-qa-migrationUse when a project already runs a QA/test flow (Cypress, Jest, Vitest, custom) and wants to adopt the code-addiction QA pipeline instead of starting over — defines the autonomous dogfooding sequence (add.new → add.plan → add.build → add.review) and its checkpoints. Consumed by /add.qa-setup when migration is detected and confirmed.
add-knowledge-discoveryUse at the context/discovery step of add.plan, add.hotfix, add.new, add.diagnose, add.review, add.brainstorm — consult the delivery index, then the project wiki (and code knowledge graph), for minimal token cost before dispatching agents.
add-wiki-maintenanceUse for incremental project-wiki updates — loaded by /add.wiki update (manual drift) and add.done STEP 4.9 (pre-merge, automatic). Diff-driven surgical edits only, never full rewrites.
add-setup-contractUse when a state-materializing command starts — compare the receipt setup-shape to the shipped sidecar shape and route FIRST-RUN / CURRENT / STALE. Consumed by /add.qa-setup STEP 1.5 and STEP 12.
add-feature-readbackUse when a feature's docs are closed and you need a cold reader to say back what they understood before anyone builds — catches docs that pass every review and still make the reader build the wrong thing.
add-final-reportUse at a command's closing step — the seven blocks every finishing command reports in, the banned phrasings, and the self-check. Load at the last step, not at the first.
add-review-disciplineUse when a command dispatches a reviewer or a cold reader over a document — how many times each runs, what makes a second dispatch legal, how a divergence is handled at each site, and where a verdict may reach disk.
add-delivery-modeUse when a pipeline command reaches a stop or its closing handoff — the two delivery modes and where each is carried, which stops wait in each mode, how one command hands off to the next, and where the automatic path ends — the build's publish question.

Optional Features

Features are toggleable behaviors injected into commands via fragment files. Enable or disable them with npx codeadd features enable|disable <name>.

tdd-pipelineenabled by default

TDD pipeline (test-first ordering + unit/integration generation)

Injected into: add.plan, add.build, add.review, add.hotfix

qa-pipelinedisabled by default

QA pipeline (E2E spec authoring + routed QA correction + the agent QA judgement in add.review)

Injected into: add.plan, add.build, add.review

Plugins

Plugins integrate external MCP tools into ADD commands. Code Addiction handles utilization — it validates the tool is present, injects guidance into commands and agents, and activates plugin-bound skills. Plugins are disabled by default and require the external tool to be installed first.

gitnexusdisabled by defaultmcp

Code knowledge-graph navigation (call graph, refs, blast-radius) via MCP. Enables structural code navigation across discovery, planning, diagnosis, and hotfix commands — going beyond grep to understand actual call chains and impact.

Injects into: add.new, add.plan, add.build, add.diagnose, add.hotfix, add.done, add.wiki

Injects into agent: ux-flow-agent

Activates skill: add-gitnexus — structural/relational code navigation (call graph, references, blast-radius, trace flows, safe refactors)

github.com/abhigyanpatwari/GitNexus

1 — Install GitNexus

Required before enabling the plugin. Code Addiction validates this with gitnexus --version.

$npm install -g gitnexus

2 — Enable the plugin

$npx codeadd plugins enable gitnexus
# to disable later
$npx codeadd plugins disable gitnexus

3 — Wire and index (once per repo)

Run these after enabling. Re-run analyze after large changes.

$gitnexus setup
$gitnexus analyze

Verify: ask Claude to run gitnexus list_repos (or /mcp) — this repo must appear indexed. If it does not, commands silently fall back to grep.

playwrightdisabled by defaultmcp

Adds live browser driving (screenshots + console/network) to the already-present agent-judged QA validation via Playwright MCP. QA works out of the box from persisted run evidence (screenshots + assertion/axe results) — this plugin lets the /add.review judge pair additionally drive the app live for richer evidence.

Injects into: add.review

Injects into agent: qa-agent

github.com/microsoft/playwright-mcp

1 — Install Playwright MCP

Required before enabling the plugin. Code Addiction validates this with npx --yes @playwright/mcp@latest --version. Run /add.qa-setup for a guided, per-OS install of chromium + the Playwright MCP server.

$npx --yes @playwright/mcp@latest --version

2 — Enable the plugin

$npx codeadd plugins enable playwright
# to disable later
$npx codeadd plugins disable playwright

3 — Set up and run QA (once per project)

Scaffold QA config after enabling, then run the audit per feature.

$/add.qa-setup
$/add.review <feature-id>

Verify: the Playwright MCP server must be connected (e.g. /mcp) — if it does not appear, /add.review cannot drive the browser.

Providers

Code Addiction generates provider-specific files so the same commands work across AI assistants.

ProviderDirectoryFormat
Claude Code.claude/commands/
Codex (OpenAI).agents/skills/
Google Antigravity.agent/skills/
Cursor.cursor/commands/
OpenCode.opencode/commands/

Commands and skills build to all five providers. Agent definitions ship to Claude Code, Cursor, OpenCode and Codex — Antigravity is deferred because its native .agents/agents/ path collides with the Codex skills root.

Project Structure

The Code Addiction repository is organized as follows:

code-addiction/
├── cli/← installer CLI (npm: codeadd)
├── framwork/← framework payload
│ └── .codeadd/← core: commands, skills, scripts
├── web/← this website
├── scripts/← build and release scripts
└── docs/← project documentation

Deep Dive

Ecosystem Map

Interactive map of commands, skills, and agents. Hover a node to highlight its connections. Click to inspect.

CommandsSkillsAgents
scroll to zoom · drag to pan · click to inspect