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.init

Project onboarding → owner.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

/add.plan-to-ready

Bounded convergence loop — plans, then loops build ⇄ review at most 3 times against the /add.done gates evaluated in dry-run, dispatching named leaf agents at depth 1. Converges and returns control; the merge stays human

Quality

/add.review

Feature review specialist — read-only code review, spec-compliance audit and agent-judged QA (dual-judge panel over persisted run evidence); consolidates every finding into one ## Fix Routing table and writes a versioned review-NNN.md. Routes findings, never applies them

/add.audit

Full project health analysis

/add.diagnose

Pre-decision triage for ambiguous symptoms (read-only)

/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

/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])

Utilities

/add

Smart gateway — answers questions, guides flow

/add.ux

Quick UX — loads ux-design for free context

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

Convergence Flow

Bounded build ⇄ review loop — converges against the /add.done gates, then hands control back. The merge stays human

New
/add.new→Plan to Ready
/add.plan-to-ready→Done
/add.done

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. Let the bounded loop converge against the delivery gates, then take the merge decision yourself.

/add.new → define scope
/add.plan-to-ready → plans, then loops build ⇄ review until the /add.done gates pass
/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-specificationStructured about.md with RFs, RNs, criteria
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
planningTechnical planning — creates/updates plan.md with tasks and file mappings
product-discoveryFounder + product blueprint via guided questionnaire → owner.md + product.md
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
backend-architecture-workspaceWorkspace-level backend architecture scaffolding
frontend-architectureFrontend architecture patterns and workspace conventions
frontend-architecture-workspaceWorkspace-level frontend architecture scaffolding
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
claude-md-styleUse when generating or updating CLAUDE.md files — defines what belongs vs. what stays in skills/docs, format rules (JSON for data, markdown for rules/instructions), and line budget
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 — consult 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.

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

qa-pipelinedisabled by default

QA pipeline (E2E authoring + agent QA validation)

Injected into: add.plan, add.build

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.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