Skill Reference — All 26 Skills

/add:init Setup Initialize an ADD Project

Bootstrap a new (or adopt an existing) project into ADD. Runs a structured PRD interview, scaffolds .add/ state, sets the maturity level (POC → Alpha → Beta → GA), and registers the project in the cross-project registry.

The interview adapts to whether the directory is empty (greenfield) or has existing code (--adopt flow). --quick skips the PRD interview for prototypes. --reconfigure re-runs setup against an existing .add/ without losing state. The migration system runs automatically on first invocation if the project was last touched by an older ADD version.

/add:spec Specification Create a Feature Spec

Structured interview that converts a feature idea into a complete spec with acceptance criteria, prioritized as Must/Should/Could. Spec-before-code is non-negotiable in ADD — every implementation traces back to a numbered AC.

Specs follow a fixed template: overview, user stories, acceptance criteria table (with AC-001-style IDs), non-goals, and open questions. The interview enforces a complexity check: questions are batched by topic, not asked one-at-a-time. --from-prd-section seeds the spec from a PRD section to maintain traceability.

/add:plan Planning Implementation Planning

Parse a feature spec and decompose it into an ordered task list with phases (Prep → Core → Testing → Polish). Identifies parallelizable work streams, estimates effort, and produces a risk assessment.

Plans are designed to be consumed by /add:tdd-cycle. Tasks map directly to acceptance criteria. The plan document is committed to git as an audit trail of the implementation approach and informs swarm parallelism decisions when running cycles at Beta+ maturity.

/add:ux Design Gate UX Design Sign-off

Iterate on UI/UX design before implementation: wireframes, flow validation, and explicit human approval. At Alpha+ maturity, blocks implementation of UI features without an approved UX artifact. Prevents the most expensive class of rework: building the right thing wrong.

Community contribution from David Giambarresi in v0.6.0. The skill walks through user flows, edge states, accessibility considerations, and visual hierarchy with the human, then produces a sign-off document referenced by downstream skills as the UI source of truth.

/add:tdd-cycle Full TDD Full TDD Cycle

Execute the complete RED → GREEN → REFACTOR → VERIFY cycle against a feature specification. The orchestrator reads the spec, dispatches sub-agents for each phase, coordinates results, and independently verifies the final output. This is the primary skill for feature development in ADD.

The --ac flag targets specific acceptance criteria for a partial cycle. The --parallel flag enables concurrent sub-agent execution at Beta+ maturity using git worktrees for isolation. After successful completion, a knowledge checkpoint is automatically captured.

/add:test-writer RED Write Failing Tests

Parse the feature spec, extract acceptance criteria and test cases, generate test files, and verify that all tests fail with clear, descriptive messages. This is the RED phase — tests must exist and must fail before any implementation begins.

Test files map one-to-one to acceptance criteria. Each test includes a descriptive failure message that references the AC ID (e.g., “AC-001: should reject empty email”). The --type flag controls the test layer; when omitted, the skill picks the layer implied by each criterion.

/add:implementer GREEN Make Tests Pass

Verify that tests exist and currently fail, then implement the minimal code necessary to achieve GREEN state. No gold-plating — write only what the tests require.

The implementer first confirms RED state by running the test suite. It then implements code incrementally — one acceptance criterion at a time — re-running tests after each change. If a test seems incorrect or ambiguous, it halts and requests clarification rather than guessing.

/add:reviewer REFACTOR Code Review

Read-only analysis of the implementation. Checks spec compliance, code quality, test coverage, architecture consistency, and ADD methodology adherence. Produces a structured review report with actionable findings.

Strictly read-only — cannot modify files. Findings are graded by severity (critical, warning, suggestion) with specific file locations. Critical findings block progression to the verify phase.

/add:verify VERIFY Quality Gates

Execute the 5-level quality gate system: Gate 1 (lint/format), Gate 2 (type checking), Gate 3 (tests and coverage), Gate 4 (spec compliance and integration), Gate 5 (smoke tests). Each gate must pass before the next runs.

local runs Gates 1-3, ci adds Gate 4, deploy includes all 5, smoke runs only Gate 5 post-deployment. --fix auto-remediates Gate 1 (formatting/lint). A knowledge checkpoint is captured after every verify.

/add:deploy Deployment Environment-Aware Deployment

Run quality gates, compose a conventional commit, push, monitor CI, and execute deployment per environment rules. Agents climb local → dev → staging autonomously when gates pass. Production always requires human approval.

Per-env behavior: local = commit only (Gates 1-3); dev = commit+push, monitor CI for Gate 4; staging = wait full pipeline, run Gate 5 smoke tests; production = open PR, await human approval. Production deploys honor a confirm-phrase gate added in v0.7.1. Rollback strategies vary by env: revert-commit for dev, redeploy-previous-tag for staging.

/add:optimize Optimization Performance Optimization

Profile the codebase, identify performance bottlenecks, prioritize by ROI (impact vs. effort), and implement optimizations with TDD discipline — write a performance test first, then optimize to pass it.

--profile-first runs profiling tools and gathers baseline metrics before proposing changes. Without it, the skill analyzes statically for known anti-patterns. Each optimization gets a perf test that asserts the target metric (e.g., response time under 200ms), preventing regression and documenting the perf contract.

/add:changelog Changelog Generate or Refresh CHANGELOG.md

Build CHANGELOG.md from conventional commit history. Follows Keep-a-Changelog format. Cross-references ADD specs for traceability. Auto-appends to the [Unreleased] section on every push via the conventional-commits hook.

--from-scratch rebuilds the entire changelog from git log; default behavior just synchronizes [Unreleased] with new commits since last sync. /add:deploy promotes [Unreleased] into a versioned section automatically when cutting a release.

/add:cycle Cycle Plan and Execute a Work Cycle

Select a batch of features for the current cycle, assess parallelism options (sequential vs. swarm), define validation criteria, and execute. Replaces “sprint” framing with explicit, scoped work batches.

--plan selects features against the current milestone, --status reports progress, --complete closes a cycle and writes validation result, --milestone ties the cycle to a specific milestone ID. WIP limits and parallel-agent caps are enforced from .add/config.json.

/add:retro Retrospective Run a Retrospective

Context-aware, data-driven review session. Auto-gathers metrics, classifies human directives and agent observations into pre-populated tables, and presents findings for the human to refine — not recall from scratch.

Detects whether the period was autonomous (/add:away), collaborative, or mixed and adapts tone accordingly. Records collab/ADD/swarm scores to .add/retro-scores.json for trendlines. Promotion to Tier 1 knowledge happens here when patterns are universal enough.

/add:away Away Declare Absence

Get an autonomous work plan for the duration. Explicit list of operations the agent will take (commit, push, fix gates, open PRs) and an explicit boundary list (no production deploy, no merge to main, no features without specs). Default duration: 2 hours.

The away log records every action with timestamp, plus reasoning. On /add:back, the log is archived to .add/away-logs/away-{date}.md and a return briefing is generated. Boundaries are enforced by autoload rules; even a confused agent can't ship to production during an away session.

/add:back Briefing Return Briefing

Synthesize what happened during the away session. Reads the away log, identifies completed work, surfaces decisions made autonomously, and lists items needing human review.

Surfaces the “here’s what I’d do differently next time” reflections that feed the next retro. If anything was blocked or skipped during the autonomous run, it’s flagged here for explicit human attention before the next cycle.

/add:roadmap Roadmap Roadmap Horizon Management

Interactive view and edit of the roadmap: Now / Next / Later horizons mapped to milestones. Reorder priorities, split horizons, or rescope without losing dependency context.

Community contribution from Piotr Pawluk in v0.6.0. Fills the gap between high-level PRD and per-feature specs — gives stakeholders a single artifact for “what we’re working on, in order, why.”

/add:milestone Milestone Milestone Operations

List, switch, split, rescope, or create milestones. Each milestone bundles features toward a target maturity level (e.g., M1 → alpha, M2 → beta).

Splitting a milestone preserves the parent's success criteria across both children. Rescoping updates target maturity without losing feature attribution. Cycles can be tied to specific milestones via /add:cycle --milestone M2.

/add:promote Promotion Maturity Promotion

14-category gap analysis against the next maturity level (POC → Alpha → Beta → GA). Reports what's met, what's missing, and what's in flight. Executes the promotion when criteria are satisfied.

Community contribution from Piotr Pawluk in v0.6.0. --check is read-only and returns a maturity-readiness report; --execute performs the bump in .add/config.json after gap analysis passes. The maturity dial cascades into rule strictness, parallel-agent limits, and quality-gate severity automatically.

/add:learnings Learnings Manage the Learning Library

Lifecycle management for the project's accumulated knowledge: generate the pre-filtered active view, archive stale entries, and report stats on token savings. Added in v0.8.0.

migrate generates active views from JSON (or converts pre-v0.4 markdown to JSON first). archive interactively reviews entries older than the configured threshold (default 90 days, low/medium severity). stats reports counts, sizes, and realized context savings. Thresholds are configurable in .add/config.json's learnings block (see v0.8 blog post).

/add:brand Brand View Project Branding

Inspect the project's accent color, palette, fonts, tone, image-gen status, and drift between branding config and generated artifacts (infographic, dashboard, reports).

Reads .add/config.json's branding block. If artifacts exist that disagree with the config, drift is reported with file paths so they can be regenerated.

/add:brand-update Brand Update Project Branding

Edit the project's branding config and regenerate dependent artifacts (infographic, dashboard, branded reports) so visual identity stays consistent.

Interactive update of accent color, palette, fonts, tone, and image-gen preferences. After changes are saved, dependent artifacts are auto-regenerated unless --no-regen is passed.

/add:infographic Visual Generate Infographic

Generate an SVG infographic from the project PRD and configuration, applying project branding (colors, fonts, tone). Adapts content depth to the project's maturity level. GitHub-compatible (no <style> or <script> tags) for README embedding.

--update regenerates using existing content structure, updating only changed data. Without it, the skill performs full content gathering and may ask clarifying questions. Image-gen MCP tools (if available) are detected at runtime and used to enhance visuals; falls back to pure SVG if not.

/add:docs Docs Generate Project Documentation

Archetype-aware documentation generation: architecture diagrams, API docs, README drift detection. Detects whether the project is a web API, library, CLI, data pipeline, or monorepo and generates appropriate docs.

Community contribution from Caleb Dunn in v0.6.0, validated against Home Assistant core. --check reports drift without writing changes. --discover profiles the codebase to identify the archetype and recommend doc strategy.

/add:dashboard Dashboard Generate HTML Project Dashboard

Self-contained HTML snapshot of project state — outcome health, hill chart, cycle progress, decision queue, intelligence metrics, and timeline. All CSS and JS inlined; opens in a browser, no server required.

Six panels read from .add/, specs, docs, and config: PRD-to-AC traceability, hill-chart feature positions, current cycle, items in the human decision queue, learnings/decisions/cycles/specs metrics, and a chronological timeline. Visual treatment matches getadd.dev (raspberry accent, dark canvas).

/add:version Utility Version Status & Upgrade Check

Show installed plugin version vs. project version. Highlights when the project is behind and a migration will run on next skill invocation. Summarizes what changed across versions when a CHANGELOG.md is present.

Added in v0.7.3 to support upgrade visibility. --check exits non-zero if the project version is behind, which is useful as a CI guard. Cross-runtime aware since v0.9.1 — resolves the plugin version from plugin.json (Claude), plugin.toml (Codex), or VERSION (fallback).

/add:agents-md Interop Generate tool-portable AGENTS.md

Generates a tool-portable AGENTS.md at project root from .add/ state. Any agent in any tool (Cursor, Codex CLI, Copilot, Windsurf, Amp, Devin) can read the file without needing the ADD plugin installed — ADD treats AGENTS.md as an output, not an input.

Maturity-aware verbosity: POC gets bullet points, Alpha gets sectioned content, Beta gets the full structure (autonomy ceiling + active-spec pointer + conditional TDD section), GA adds team conventions. ADD-managed content is wrapped in <!-- ADD:MANAGED:START ... --> marker blocks so hand-authored sections survive regeneration. --check is a CI drift gate (exit 1 on drift). --merge / --import absorb an existing hand-curated AGENTS.md.

A PostToolUse staleness hook writes .add/agents-md.stale when .add/config.json, core/rules/*.md, or core/skills/*/SKILL.md changes and an AGENTS.md exists at root. The hook never auto-rewrites — the human triggers regen. Opt-in agentsMd.gateOnVerify in .add/config.json enables Gate 4.5 in /add:verify. Added in v0.9.0 as part of M3.