Getting Started with ADD

Overview

ADD (Agent Driven Development) is a structured SDLC methodology where AI agents are first-class development team members. It brings the same discipline to AI-native development that TDD brought to testing.

ADD is a free Claude Code plugin — pure markdown and JSON, zero dependencies. Install it in one command and start building with coordinated agent teams that write specs, run TDD cycles, verify quality, and deploy — all with structured human collaboration at every decision point.

The six principles that govern everything ADD does:

1. Specs before code — Everything flows from specifications. No spec, no code.
2. Tests before implementation — Strict TDD: RED → GREEN → REFACTOR → VERIFY.
3. Trust but verify — Sub-agents work. Orchestrators independently verify.
4. Structured collaboration — Interviews, away mode, decision points, engagement modes.
5. Environment awareness — Skills adapt to your deployment tier.
6. Continuous learning — Agents accumulate knowledge through checkpoints and retrospectives.

Installation

ADD is installed through the Claude Code plugin system. One command, nothing else required.

That's it. No build step, no dependencies, no configuration files to create manually. The plugin installs commands, skills, rules, and templates into your Claude Code environment.

Prerequisites

• Claude Code — ADD is a Claude Code plugin. You need Claude Code installed and working.
• A git repository — ADD stores project state in .add/ which should be committed to version control.

Verify Installation

After installing, you can verify by running any ADD command. The simplest check:

If ADD is installed correctly, this will begin the structured project interview.

Quick Start

The ADD workflow follows a clear progression: initialize your project, create specs for features, plan the implementation, build with TDD, verify quality, and deploy. Here is the complete flow.

1. Initialize your project

The init command runs a structured interview that captures your project's purpose, tech stack, maturity level, and team preferences. It creates:

• .add/config.json — central project configuration
• docs/prd.md — product requirements document
• .add/learnings.md — project knowledge file
• Behavioral rules tailored to your maturity level

2. Create a feature spec

A guided interview captures everything agents need: description, acceptance criteria, test cases, edge cases, dependencies, and scope boundaries. The output is a structured specification file at specs/{feature}.md.

3. Plan the implementation

The plan skill reads the spec and generates a step-by-step implementation plan at docs/plans/{feature}-plan.md. It identifies file changes, dependencies, test strategy, and execution order.

4. Build with TDD

The full TDD cycle: agents write failing tests from the spec (RED), implement minimal code to pass (GREEN), refactor for quality (REFACTOR), and independently verify everything works (VERIFY).

5. Verify quality

The verify skill runs up to five quality gates depending on your maturity level: linting, type checking, tests, coverage, and spec compliance. All gates must pass before deployment.

6. Deploy

Environment-aware deployment that promotes through your configured environments (local → dev → staging → production). Agents climb the promotion ladder autonomously until production, which always requires human approval.

Your First Feature

Here is a concrete walkthrough of creating a feature end-to-end using ADD. This assumes you have already run /add:init to set up your project.

Step 1: Create the spec

Run /add:spec and answer the interview questions. The agent will ask about:

• What the feature does and why it exists
• Acceptance criteria — the conditions that define "done"
• Test cases — specific scenarios to verify
• Edge cases — boundary conditions and error handling
• Dependencies and scope boundaries

The output is a structured specification at specs/{your-feature}.md. This file becomes the single source of truth for everything that follows.

Step 2: Generate the plan

Run /add:plan specs/{your-feature}.md to get an implementation plan. The plan breaks the spec into ordered steps, identifies which files need to be created or modified, and outlines the test strategy.

Step 3: Execute the TDD cycle

Run /add:tdd-cycle specs/{your-feature}.md and let the agents work. The cycle proceeds through four phases:

1. RED — The test-writer agent creates failing tests from your spec's acceptance criteria. Every criterion maps to at least one test.
2. GREEN — The implementer agent writes the minimal code needed to make all tests pass. No gold-plating.
3. REFACTOR — The reviewer agent examines the code for quality, patterns, and spec compliance.
4. VERIFY — An independent agent (fresh context, no shared state) verifies everything works. If verification fails, the cycle restarts.

Step 4: Verify and ship

Run /add:verify to confirm all quality gates pass. Once verified, run /add:deploy to deploy through your environment ladder. The agent handles promotion, smoke tests, and rollback automatically — pausing only at production for your approval.

Config Reference

.add/config.json is the central configuration file for your ADD project. It is created during /add:init and controls all agent behavior.

{
  "maturity": "alpha",
  "autonomy": "balanced",
  "techStack": {
    "languages": ["typescript"],
    "framework": "next.js",
    "testRunner": "vitest",
    "linter": "eslint",
    "formatter": "prettier"
  },
  "environments": {
    "local":      { "autoPromote": true,  "verify": "test:unit" },
    "dev":        { "autoPromote": true,  "verify": "test:integration" },
    "staging":    { "autoPromote": true,  "verify": "test:e2e" },
    "production": { "autoPromote": false, "verify": "test:smoke" }
  },
  "branding": {
    "accent": "#b00149",
    "palette": "raspberry",
    "fonts": { "heading": "Inter", "body": "Inter", "mono": "SF Mono" },
    "tone": "professional"
  }
}

Key Fields

Knowledge System (3-Tier)

ADD's knowledge system is what makes agents get smarter over time. Knowledge is organized in three tiers, each with different scope and persistence.

Knowledge flows upward: project discoveries can be promoted to the user library during retrospectives, and universal insights can be promoted to plugin-global. Precedence flows downward: project-specific overrides user-local, which overrides plugin-global.

Automatic Checkpoint Triggers

Agents automatically capture learnings at key moments, without requiring manual intervention:

• After every /add:verify run
• After completing a TDD cycle
• After each deployment
• After an away-mode session
• During /add:retro retrospectives

Maturity Levels

The maturity dial is the master control that governs everything in ADD. It determines how much process rigor is applied at every level — from PRD depth to TDD enforcement to quality gates to agent parallelism.

Choose your maturity level during /add:init. You can change it at any time by updating .add/config.json — the maturity dial scales up and down as your project evolves.

What each level means in practice

• POC — Minimal overhead. Specs and TDD are optional. Single agent, WIP limit of 1. Move fast and explore. Pre-commit checks only.
• Alpha — Critical-path specs and TDD. You write specs for important features, skip them for utilities. 1-2 agents, WIP 2. CI checks added.
• Beta — Full specs are required. TDD is enforced for all features. Pre-deploy quality gates. 2-4 parallel agents with git worktree isolation. WIP 4.
• GA — Maximum rigor. Strict TDD with all 5 quality gates. Full acceptance criteria required. 3-5 parallel agents. WIP 5. Production-grade process.

Document Hierarchy

Every artifact in ADD traces to a parent. Every test traces to a spec. Every spec traces to a PRD. This traceability chain ensures nothing drifts from the original intent.

Roadmap (docs/prd.md milestones section)
 → Milestones (docs/milestones/M{N}-{name}.md)
   → Cycles (.add/cycles/cycle-{N}.md)
     → Feature Specs (specs/{feature}.md)
       → Implementation Plans (docs/plans/{feature}-plan.md)
         → User Test Cases (in spec)
           → Automated Tests (RED phase)
             → Implementation (GREEN phase)

The hierarchy mirrors how work flows from strategy to execution:

• Roadmap — Now / Next / Later horizons. No fake dates. Milestones live here.
• Milestones — Meaningful increments tracked on a hill chart. Features move uphill (figuring it out) then downhill (executing).
• Cycles — Scope-boxed batches of work. Not sprints — they end when validation passes, not when a timer expires.
• Feature Specs — The single source of truth for each feature. Acceptance criteria, test cases, edge cases.
• Implementation Plans — Step-by-step execution plans generated from specs.
• Tests and Code — The TDD cycle output: failing tests first, then implementation.

Plugin Structure

ADD is a Claude Code plugin composed entirely of markdown, JSON, and template files. No runtime dependencies, no build step, no backend.

add/
├── commands/     # 9 slash commands (/add:init, /add:spec, /add:away, etc.)
├── skills/       # 9 workflow skills (/add:tdd-cycle, /add:verify, /add:plan, etc.)
├── rules/        # 11 auto-loading behavioral rules
├── hooks/        # PostToolUse automation
├── knowledge/    # Plugin-global best practices (Tier 1)
└── templates/    # 13 document scaffolding templates

What lives where

Project state

When you run /add:init, ADD creates a .add/ directory in your project root. This is where project-specific state lives:

your-project/
├── .add/
│   ├── config.json       # Project configuration
│   ├── learnings.md      # Project-specific knowledge (Tier 3)
│   ├── cycles/           # Work cycle tracking
│   └── away-logs/        # Away session archives
├── docs/
│   ├── prd.md            # Product requirements document
│   ├── plans/            # Implementation plans
│   └── milestones/       # Milestone tracking
└── specs/                # Feature specifications

Cross-project state lives locally at ~/.claude/add/ — your user profile, the cross-project learning library, and an index of all ADD-managed projects.