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, KiloCode, OpenCode
install, update, uninstall, doctor, validate, features, plugins, config
Installation
Requires Node.js 18+. Works on Windows, macOS, and Linux.
What gets installed
├── .codeadd/← core (always)
├── .claude/← Claude Code
├── .agents/← Codex (OpenAI)
├── .agent/← Antigravity
├── .kilocode/← KiloCode
└── .opencode/← OpenCode
Quickstart
After installing, use these CLI commands to manage your setup:
npx codeadd doctor Check environment health — Node, Git, installation status npx codeadd validate Validate file integrity via SHA-256 hashes npx codeadd validate --repair Restore missing or modified files from the release npx codeadd update Update to latest release, or re-pull current branch npx codeadd uninstall Clean removal of all Code Addiction files (user files are kept) npx codeadd uninstall --force Skip confirmation prompt during uninstall npx codeadd features List, enable, or disable optional features (e.g. TDD, Startup Test) npx codeadd plugins List, enable, or disable MCP plugins (e.g. GitNexus) npx codeadd config show Display 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.xray Map architecture, classify apps
Planning
/add.design UX spec, mobile-first. Coordinates subagents
/add.plan Technical Planning Orchestrator
Implementation
/add.build Development Execution Specialist
/add.autopilot Autonomous Feature Coordinator
Quality
/add.review Feature Code Review Specialist
/add.test Generate tests — coverage reported as signal, not enforced target
/add.audit Full project health analysis
/add.diagnose Pre-decision triage for ambiguous symptoms (read-only)
Delivery
/add.done Changelog, docs, finalize. Routes to PR or merge
/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, design, planning, implementation, review
/add.brainstorm → New
/add.new → Design
/add.design → 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
Autonomous Flow
Full AI implementation, no human interaction needed
/add.new → Autopilot
/add.autopilot → Done
/add.done
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.design → UX spec, mobile-first layouts
/add.plan → technical architecture, 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. Let the AI handle it end-to-end with no interaction.
/add.autopilot → AI implements everything autonomously
/add.done → finalize
"Users can't login — auth token validation is broken"
Critical production bug. Fast-track fix with tracking.
/add.done → deploy
"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-development SOLID, Clean Arch, DTOs, Services, Repository — stack-agnostic frontend-development State, data fetching, components, forms, routing — stack-agnostic database-development Entities, repositories, migrations, naming — stack-agnostic ux-design Components, mobile-first, SaaS patterns, shadcn, Tailwind security-audit OWASP checklist, RLS, secrets, multi-tenancy code-review Code review: IoC, RESTful, Contracts, Security (OWASP), Clean Architecture, SOLID feature-discovery Discovery process, codebase analysis feature-specification Structured about.md with RFs, RNs, criteria architecture-discovery Map architecture, detect patterns, stack-context.md delivery-validation Product validation: Requirements 100% implemented, prerequisites exist, acceptance criteria pass subagent-driven-development Coordinate subagents with quality gates add-tasks-checklist Use 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 stripe Stripe integration, price versioning, grandfathering token-efficiency Compression, compact JSON, minimal tokens commit Smart commit with auto-generated Conventional Commits messages planning Technical planning — creates/updates plan.md with tasks and file mappings product-discovery Founder + product blueprint via guided questionnaire → owner.md + product.md project-scaffolding Scaffold Node.js projects (Express, Fastify, NestJS, Bun) — monolith or monorepo health-check Tech health check suite: docs, security, architecture, data analysis plan-based-features Subscription plan gating — 3-layer PlanFeatures pattern and IPlanService dev-environment-setup Detect OS, install missing tools, configure VS Code terminal optimizing-git-workflow Complete Git config: colors, aliases, smart defaults, performance backend-architecture Backend architecture patterns and workspace conventions backend-architecture-workspace Workspace-level backend architecture scaffolding frontend-architecture Frontend architecture patterns and workspace conventions frontend-architecture-workspace Workspace-level frontend architecture scaffolding ecosystem ADD ecosystem map and framework overview investigation Deep diagnostic investigation for ambiguous findings resource-path-convention Consistent resource path conventions across the project id-convention Canonical [NNNN][L] ID and branch naming format expected by next-id.sh, get-branch-metadata.sh, done.sh skill-creator Create and structure new ADD skills claude-md-style Use 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-tdd RED-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 and add.test. add-test-specification Generate 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. Optional Features
Features are toggleable behaviors injected into commands via fragment files.
Enable or disable them with npx codeadd features enable|disable <name>.
tdd enabled by default TDD Pipeline (test-first development)
Injected into: add.plan, add.build
startup-test enabled by default Application Startup Test (IoC/DI validation)
Injected into: 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.
gitnexus disabled by default mcp 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.xray
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.
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/ | skills/ |
| Google Antigravity | .agent/ | skills/ |
| KiloCode | .kilocode/ | workflows/ |
| OpenCode | .opencode/ | commands/ |
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.