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.
Shared core: commands, scripts, skills, templates
Claude, Codex, Antigravity, Cursor, OpenCode, ZCode
install, update, uninstall, doctor, validate, features, plugins, providers, modify, config
Installation
Requires Node.js 22.19.0 or newer (Node 24 LTS recommended). Works on Windows, macOS and Linux — no Bash, WSL or Git-Bash needed.
What gets installed
├── .codeadd/← core (always)
├── .claude/← Claude Code
├── .agents/← Codex (OpenAI) + ZCode (Z.ai)
├── .codex/← Codex (OpenAI) agents
├── .cursor/← Cursor
├── .agent/← Google Antigravity
├── .opencode/← OpenCode
└── .zcode/← ZCode (Z.ai) agents
Framework scripts are Node entries — node .codeadd/scripts/<entry>.cjs — so no Bash, WSL or Git-Bash is required on any platform.
Quickstart
After installing, use these CLI commands to manage your setup:
providers list|add <name>|remove <name> [--force]. Accepts --global / --user--global / --user--verbose to check for updatesGuided Setup
/add-setup is the guided onboarding for a fresh or updated install. It checks your project, then offers every feature and plugin with its benefit in one numbered list, with a recommended answer for each. Reply once, for example 1 yes, 2 no or all recommended.
Reads the project (code, frontend, wiki, QA setup) and what is already on. Changes nothing.
One numbered list. Items already on, or declined before, are not asked again.
Only the items you accept: tool installs, one codeadd modify, /add-qa-setup and /add-wiki.
codeadd install or codeadd update. After an update it asks only about items that are new in that version..codeadd/settings.json. Commit this file so teammates and future updates see what was enabled and why./add-brainstorm. Run it again once the foundations exist.Reference
Commands
Every command is a slash command you type in your AI coding assistant. They orchestrate discovery, planning, implementation, and delivery.
Discovery
/add-brainstormExplore ideas (read-only); decides stack foundations on an empty repo
/add-newAI-guided feature discovery → about.md
/add-wikiGenerate a portable project wiki (.codeadd/wiki/)
Planning
/add-planTechnical Planning Orchestrator — dispatches UX Design, Database, Backend and Frontend agents. Sole writer of design.md (STEP 8.1) for UI-touching features
Implementation
/add-buildDevelopment Execution Specialist — closes each delivery unit with its own Final Review
Quality
/add-reviewFeature 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-auditFull project health analysis
/add-diagnosePre-decision triage for ambiguous symptoms (read-only); persists the diagnosis for /add-hotfix to reuse
/add-qa-setupEnd-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-doneBranch completion and merge - promotes reviewed QA evidence, finalizes changelog and documentation, then merges. Hotfix close-out requires a passed Review receipt in about.md. Deploy is not part of a delivery - it runs after /add-done, through your own deploy process
/add-pull-requestIdempotent PR - creates new PR or appends update section if one is already open. Generates feature changelog on feature branches
/add-hotfixEmergency fix with global ID (H[NNNN]) — reuses an accepted /add-diagnose when available
Utilities
/add-helpHelp guide — which command, features and plugins, bot mode, CLI
Guided onboarding — offers each feature and plugin with its benefit, sets up the ones you accept
/add-uxQuick 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 247 artefacts and 972 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.
/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
/add-new→Plan
/add-plan→Code
/add-build→Done
/add-done
Lean Flow
Small changes, quick tasks — minimal ceremony
/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
/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
/add-hotfix→Done
/add-done
Exploration Flow
Don't know where to start? Brainstorm first, then pick any flow above
/add-brainstorm→New
/add-new→...pick your flow
Reference
Scenarios
Real-world examples of when to use each flow.
"Build a user dashboard with charts and filters"
Complex feature with UI, multiple user flows, needs discovery and design.
/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
"Add email notifications for order status"
Backend feature, no complex UI. Needs planning but no design phase.
/add-plan → service architecture, queue strategy
/add-build → implement
/add-done → finalize
"Add a loading spinner to the submit button"
Small, well-defined change. Minimal ceremony.
/add-build → implement
/add-done → finalize & merge
"Implement the 5 API endpoints from the spec"
Well-specified work. Approve once, let the stages hand off, then take the merge decision yourself.
new → plan → build (final review) → runs unattended until the PR question
/add-done → finalize
"Users can't login — auth token validation is broken"
Critical production bug. Fast-track fix with tracking.
/add-done → finalize & merge
"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-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-agnosticfrontend-developmentState, data fetching, components, forms, routing — stack-agnosticdatabase-developmentEntities, repositories, migrations, naming — stack-agnosticux-designDesign direction, UX laws, layout contract, critique rubric, SaaS patterns, mobile-firstsecurity-auditOWASP checklist, RLS, secrets, multi-tenancycode-reviewCode review: IoC, RESTful, Contracts, Security (OWASP), Clean Architecture, SOLIDfeature-discoveryDiscovery process, codebase analysisfeature-specificationSingle writer of about.md - reads the brainstorm intent file, extracts the objective and the closed decisions without asking, and asks only what is still open. Loaded by /add-new.architecture-discoveryUse when documenting project architecture - generates Technical Spec section in AGENTS.mddelivery-validationProduct validation: Requirements 100% implemented, prerequisites exist, acceptance criteria passsubagent-driven-developmentCoordinate subagents with quality gatesadd--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 templatetoken-efficiencyUse when creating commands, skills, or docs - defines generic compression patterns (minified JSON, abbreviations, glob patterns, single breaks). Load before any write where token density matters.commitSmart commit with auto-generated Conventional Commits messageshealth-checkTech health check suite: docs, security, architecture, data analysisdev-environment-setupUse when Node, git or gh CLI are missing, or Node is older than 22.19.0 - detects OS, diagnoses gaps, installs missing tools.backend-architectureGuides backend architecture decisions - over-engineering, folder structure, slices, layers, feature organization, where code goes.frontend-architectureFrontend architecture consultant for project structure, folder organization, feature boundaries, and scaling decisions. Framework-aware (React, Vue, Angular). Use when user asks about frontend folder structure, "components folder is a mess", "where should this go", over-engineering, slices, feature folders, or starting/refactoring a frontend project. Guides decisions only - does not implement (use add--frontend-development) or design UI (use ux-design).ecosystemADD ecosystem map and framework overviewinvestigationDeep diagnostic investigation for ambiguous findingsresource-path-conventionUse when writing commands or skills that reference other commands, skills, or scripts - ensures paths resolve correctly across all providers after installationid-conventionUse when allocating feature/hotfix/refactor/chore/docs IDs or creating branches - canonical [NNNN][L] format that the scripts (next-id.cjs, get-branch-metadata.cjs, build-setup.cjs, done.cjs) expectagents-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 catalog (design: path only - no expect). 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--settingsUse when a command reads or writes the project settings file .codeadd/settings.json - ownership, read/merge/write, the content rule, the qa and setup section schemas and the receipt fields. Consumed by /add-qa-setup and /add-setup.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 optional fresh-context continuation handoff and its two-response contract, 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, who is offered the optional fresh-context continuation and why, how one command hands off to the next, and where the automatic path ends.add--cross-sf-consistencyUse when judging contract consistency across an epic's subfeature plans - the five-dimension rubric, dedupe rules, and finding routes.add--doc-schemasDocumentation schemas and conventions for ADD projectsadd--plan-reviewPre-delivery executability review for freshly generated about.md and plan.md - verdict (ok / fix-then-ok / blocked) plus required fixes, not questions. Load before dispatching plan-reviewer-agent, or when applying its rubric inline as a fallback.add--human-interactionHow a command talks to a person (default interaction slot)add--agent-interactionHow a command talks to a bot via claude -p, injected by the agent-mode featureOptional 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 defaultTDD pipeline (test-first ordering + unit/integration generation)
Injected into: add-plan, add-build, add-review, add-hotfix
qa-pipelinedisabled by defaultQA pipeline (E2E spec authoring + routed QA correction + the agent QA judgement in add-review)
Injected into: add-plan, add-build, add-review
docs-pruningdisabled by defaultPrune post-merge feature scaffolding (discovery, tasks, epic, reviews) after the delivery index entry is written
Injected into: add-done
agent-modedisabled by defaultBot wording for headless runs (one numbered question batch, no continue offer). Read more
Injected into: add-brainstorm, add-new, add-plan, add-build, add-review, add-done, add-diagnose, add-hotfix, add-qa-setup, add-pull-request, add-audit, add-wiki
Agent Mode
Hand your bot a card or a slug and let it ship. With Agent Mode, an assistant like Grok Bot runs plan, build, review and release on its own. It asks only what matters, all at once, and you approve the PR.
Turn it on
Already using codeadd? Run npx codeadd modify --providers claude --force --enable-feature agent-mode.
How it works
1
You talk to your bot
Point it at a card, a slug or a one-line idea.
2
The bot runs codeadd
Plan, build, review and done, one command after the other.
3
You answer once
Open questions come together, each with a recommendation.
4
You approve the PR
The bot merges on green CI and can cut the release.
Why it is easy
- No interactive stops. Commands never wait on a menu or a yes/no to continue.
- Questions batched. Everything a step needs arrives in one numbered message. Reply
recommendedto accept them all. - Clear status at the end. Every run ends as done, stopped, needs-approval or failed, with the reason and the next command.
- Parallel agents, isolated. Each agent works in its own git worktree and its own session, so three or four can run side by side.
What you tell the bot
Take the dark-mode-toggle card, build it and open the PR for me.
Works on Claude Code, Cursor and OpenCode. Building your own bot? The technical guide (headless calls, sessions and the result schema) is installed at .codeadd/agent-mode/README.md.
Plugins
Plugins integrate external tools (MCP servers or skills you install) 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.
gitnexusmcpThe agents see who calls what before they change code, so they miss fewer side effects.
Used by: add-new, add-plan, add-build, add-diagnose, add-hotfix, add-done, add-wiki
playwrightmcpThe QA review drives the browser live (screenshots, console, network) instead of reading saved images.
Used by: add-review
designskillUI plans get a style, palette and type choice from a design library instead of defaults.
Used by: add-plan
Not sure which to enable? /add-setup offers each one with a recommendation for your project.
gitnexusdisabled by defaultmcpCode 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)
1 — Install GitNexus
Required before enabling the plugin. Code Addiction validates this with gitnexus --version.
2 — Enable the plugin
3 — Wire and index (once per repo)
Run these after enabling. Re-run analyze after large changes.
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 defaultmcpAdds 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
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.
2 — Enable the plugin
3 — Set up and run QA (once per project)
Scaffold QA config after enabling, then run the audit per feature.
Verify: the Playwright MCP server must be connected (e.g. /mcp) — if it does not appear, /add-review cannot drive the browser.
designdisabled by defaultskillMakes the design step of /add-plan use ui-ux-pro-max, which you install yourself, as the data source for style, palette, typography and chart choice. Your inspected project tokens and docs/design-system.md still come first, and the design core keeps its notation, rubric and schema gate. Code Addiction ships no copy of the skill and installs nothing.
Injects into: add-plan
Injects into agents: ux-flow-agent, ux-layout-agent, ux-agent (critique mode)
1 — Install ui-ux-pro-max (one of two official routes)
Required before enabling the plugin. Code Addiction looks for ui-ux-pro-max/SKILL.md in the project and home skill folders of every supported provider, and in Claude's installed plugins list. In Claude Code:
Any provider, with the official CLI (not the stale uipro-cli package):
2 — Enable the plugin
Python note: the skill's search script needs Python 3. Check python3 --version (Windows: py --version). Without Python the agents skip the search and use the design core. Code Addiction never installs Python. After a Claude plugin install, restart the session or run /reload-plugins.
Providers
Code Addiction generates provider-specific files so the same commands work across AI assistants.
| Provider | Directory | Format |
|---|---|---|
| Claude Code | .claude/ | commands/ |
| Codex (OpenAI) | .agents/ + .codex/ | skills/ |
| Cursor | .cursor/ | commands/ |
| Google Antigravity | .agent/ | skills/ |
| OpenCode | .opencode/ | commands/ |
| ZCode (Z.ai) | .agents/ + .zcode/ | skills/ |
Commands and skills build to all six providers. Agent definitions ship to Claude Code, Cursor, OpenCode, Codex and ZCode — Antigravity is deferred because its native .agents/agents/ path collides with the Codex skills root. ZCode reads commands and skills from the same .agents/ tree as Codex and keeps its agents in .zcode/, so the two never duplicate a file on disk.
Project Structure
The Code Addiction repository is organized as follows:
├── 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.