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, 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 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 → plan.md. Epic vs Feature detection
Implementation
/add.build Subagent-driven implementation. Supports Epics
/add.autopilot Full autonomous implementation, no interaction
Quality
/add.review Code review + auto-correction
/add.test Generate tests (80% coverage 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.pr Create PR for code review
/add.hotfix Emergency fix with global ID (H[NNNN])
Utilities
/add Smart gateway — answers questions, guides flow
/add.copy SaaS copy generator
/add.landing High-conversion SaaS landing page builder
/add.ux Quick UX — loads ux-design for free context
/add.commit Mid-workflow smart commit with Conventional Commits message
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 Validation, auto-correction, quality gates 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 Validate RF/RN implemented, acceptance criteria subagent-driven-development Coordinate subagents with quality gates landing-page-saas High-conversion landing page framework saas-copy Copy frameworks and templates for SaaS 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 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
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