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 Orchestrator
Implementation
/add.build Development Execution Specialist
/add.autopilot Autonomous Feature Coordinator
Quality
/add.review Feature Code Review Specialist
/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.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 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
Deep Dive
Ecosystem Map
Interactive map of commands, skills, and agents. Hover a node to highlight its connections. Click to inspect.