convez.ai
AgenteDesenvolvimento WebAvançado
MountainUnicorn

ADD — Agent Driven Development

MountainUnicorn/add

Coordena equipes de agentes IA para entregar software verificado

Ver no GitHub
BomPluginScore · de 0 a 100

Metodologia estruturada para desenvolvimento de software com IA, implementada como agent que coordena equipes especializadas. Aplica princípios de TDD e spec-driven ao trabalho colaborativo entre agentes e humanos, garantindo qualidade, verificação independente e rastreabilidade.

Instalação

$npx convez-ai MountainUnicorn/add

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
6
Acompanhando
0
Saúde
100%
Último commit
há 2 semanas
Versão
v0.11.0
Issues abertas
1
Contribuidores
6

Casos de uso

  • Desenvolvimento full-stack com verificação contínua
  • Coordenação de múltiplos agentes especializados (testes, código, review)
  • TDD e BDD com automação de agentes
  • Handoff estruturado entre humanos e IAs
  • Projetos com requisitos de auditoria e rastreabilidade

Veredito

ADD é uma proposta ambiciosa de metodologia, não apenas ferramenta — traz disciplina TDD para orquestração de agentes IA. Indicado para equipes que buscam estrutura, auditoria e reproducibilidade em desenvolvimento assistido por IA, mas exige adoção de fluxo completo (specs → testes → código → verificação).

README

A tradução para o português deste README ainda está na fila.


The Problem

AI code generation has changed how software gets built, but development practices haven't kept up. Developers and agents operate without structure, leading to specification drift, unpredictable quality, lost knowledge, and unclear handoffs.

ADD brings discipline to AI-native development the same way TDD brought discipline to testing.

What is Agent Driven Development?

TDD gave us tests before code. BDD gave us behavior before tests. ADD gives us coordinated agent teams before everything.

ADD is a structured SDLC methodology where AI agents do the development work — writing tests, implementing features, reviewing code, deploying — while humans architect, decide, and verify the user experience. It's not a tool. It's a way of working.

The six principles:

  1. Specs before code — Every feature starts as a specification. No spec, no code.
  2. Tests before implementation — Strict TDD: RED → GREEN → REFACTOR → VERIFY.
  3. Trust but verify — Sub-agents work autonomously. Orchestrators independently verify. Humans validate UX via screenshots.
  4. Structured collaboration — Interviews, away mode, decision points — humans and agents have clear protocols.
  5. Environment awareness — Skills adapt to where you're deploying: local, staging, or production.
  6. Continuous learning — Agents accumulate knowledge. Retrospectives propagate lessons across projects.

Install

Claude Code (recommended)

claude plugin marketplace add MountainUnicorn/add    # one-time: register ADD's marketplace
claude plugin install add@add-marketplace             # install the plugin

Why two commands? Claude Code distributes third-party plugins via "marketplaces" — a marketplace is a source (like a package registry), and the plugin is a package from that source. Step 1 registers the source (once per machine); step 2 installs from it. Future updates only need claude plugin update add@add-marketplace.

Verify: run /add:init in any git repository.

Update an existing install:

Two commands — first update existing marketplace, then update the plugin:

# 1. Update existing marketplace entry for this plugin
claude plugin marketplace update add-marketplace

* alternatively update all added marketplaces
claude plugin marketplace update

# 2. Update plugin to latest version from marketplace
claude plugin update add@add-marketplace         

Source install (for contributors):

git clone https://github.com/MountainUnicorn/add
claude --plugin-dir ./add/plugins/add

Codex CLI (v0.7.0+)

ADD ships a Codex adapter alongside the Claude plugin. One-line install:

curl -fsSL https://raw.githubusercontent.com/MountainUnicorn/add/main/scripts/install-codex.sh | bash

This installs ADD as Codex custom prompts + AGENTS.md template. See Codex install docs.

Troubleshooting

Hitting issues? See TROUBLESHOOTING.md for stale-cache recovery, rule-loading verification, and common first-run errors.

ADD has zero agent-side runtime dependencies and no build step on the consumer side — it's pure markdown and JSON. The hook scripts shipped with the Claude Code adapter require jq (brew install jq on macOS, apt install jq on Debian/Ubuntu); see docs/runtime-dependencies.md for the full per-OS install matrix and what degrades if jq is absent.


Quick Start

1. Initialize your project

/add:init              # full interview (~12 questions, ~5 minutes)
/add:init --quick      # greenfield fast path (5 questions, ~2 minutes)

ADD interviews you about your project (product vision, tech stack, team size, deployment model) and scaffolds the project structure. Use --quick for prototypes or when you want to start building immediately — it asks only the essentials and defaults the rest.

What gets created:

your-project/
├── .add/
│   ├── config.json      # Project configuration
│   ├── learnings.md     # Agent knowledge base
│   └── cycles/          # Work cycle tracking
├── docs/
│   ├── prd.md           # Product Requirements Document
│   ├── plans/           # Implementation plans
│   └── milestones/      # Milestone tracking
├── specs/               # Feature specifications
└── CLAUDE.md            # Project context for Claude

2. Create a feature specification

/add:spec "user authentication"

ADD runs a structured interview (6-10 questions, ~5 min) and generates a complete feature specification with acceptance criteria, test cases, data models, and edge cases.

3. Plan the implementation

/add:plan specs/user-authentication.md

Transforms the spec into an actionable implementation plan with task breakdown, effort estimation, dependency mapping, and risk assessment.

4. Build with TDD

/add:tdd-cycle specs/user-authentication.md

Executes the full TDD cycle: writes failing tests from the spec (RED), implements minimal code to pass them (GREEN), refactors for quality, then independently verifies everything.

5. Verify and validate

/add:verify

Runs up to 5 levels of quality checks: lint, type checking, unit tests, coverage, and spec compliance. For UI projects, humans validate the user experience via screenshot review.

6. Deploy

/add:deploy

Environment-aware deployment with pre-deploy verification and post-deploy smoke tests.


Coordinated Agent Teams

ADD doesn't use a single agent. It dispatches specialized sub-agents — each with scoped tool permissions — then independently verifies their work. Trust but verify.

Each sub-agent is isolated — test-writers can't deploy, reviewers can't edit code. At Beta+ maturity, agents work in parallel via git worktrees: 2-5 concurrent agents with WIP limits that scale with maturity (POC=1, Alpha=2, Beta=4, GA=5).


Human in the Loop

ADD defines three engagement modes. You choose how much autonomy agents get.

  • Guided — Human approves each step. Every file change reviewed before commit. Best for POC maturity and unfamiliar codebases.
  • Balanced (default) — Agents execute TDD cycles freely within spec boundaries. Pause at ambiguity or architecture forks. Best for Alpha/Beta.
  • Autonomous — Human defines scope and boundaries, then walks away. Agents execute full cycles, commit, verify. Best for GA maturity.

Screenshot validation is part of every mode. After agents build, humans review the actual user experience. Claude Code reads images natively — no Playwright or browser automation required.

The /add:away and /add:back commands power autonomous mode:

  1. Define scope and boundaries
  2. /add:away — agent builds a work plan
  3. Agent executes autonomously (TDD cycles, commits, verify — all decisions logged)
  4. /add:back — full briefing: what shipped, what's blocked, what needs your decision

For Product Managers

AI agents are writing your team's code. ADD gives you the governance, traceability, and progress visibility you need — without slowing anyone down.

  • Progress visibility — Hill charts show where every feature stands — still figuring out or actively executing.
  • Full traceability — Every line of code traces back through tests, to a spec, to a PRD requirement.
  • One dial for rigor — The maturity lifecycle (POC → GA) governs all process. No process debates — just turn the dial.
  • Quality gates — 5 automated gates at every stage. Agents can't skip verification.
  • Human at the right moments — Agents handle execution. Humans handle judgment — architecture, scope, production approvals.
  • Compounding intelligence — Every project makes the next one faster via cross-project knowledge.

Work Hierarchy

ADD organizes work in four nested levels. Each level adds detail.

ROADMAP  (Now / Next / Later — no fake dates)
 └── MILESTONE  (Hill chart: uphill figuring out → downhill executing)
      └── CYCLE  (Scope-boxed batch — ends when validation passes, not a timer)
           └── EXECUTION  (TDD: RED → GREEN → REFACTOR → VERIFY)

No fake dates — milestones use Now/Next/Later horizons that reflect actual priority. No sprints — cycles are scope-boxed and end when validation criteria are met. Hill charts show whether features are still being figured out (uphill: SHAPED → SPECCED → PLANNED) or being executed (downhill: IN_PROGRESS → VERIFIED → DONE).


The Maturity Dial

Every ADD project declares a maturity level that governs all process rigor. This is the master control:

POC — A paragraph PRD. Optional specs and TDD. Pre-commit gate only. Serial execution.

Alpha — 1-page PRD. Critical-path specs and TDD. Adds CI gate. Up to 2 parallel agents.

Beta — Full PRD template. All specs required, TDD enforced. Adds pre-deploy gate. 2-4 parallel agents.

GA — Full PRD + architecture docs. Acceptance criteria on every spec. Strict TDD. All 5 quality gates. 3-5 agents via worktrees.

A POC project gets almost no ceremony. A GA project gets exhaustive verification. Promotion happens deliberately — triggered by cycle completion or retrospectives when gap analysis shows readiness.


Key Features

Spec-Driven Development

No code without a spec. ADD enforces a document hierarchy — PRD → Spec → Plan → Tests → Code — so every line of implementation traces back to an approved requirement. The /add:spec command interviews you about the feature and generates acceptance criteria, test cases, data models, API contracts, and edge cases.

Strict TDD Enforcement

ADD enforces the TDD cycle at every level. The /add:tdd-cycle skill orchestrates sub-agents: one writes failing tests (RED), another writes minimal code to pass them (GREEN), a reviewer identifies refactoring opportunities, and a verifier independently confirms everything works. Commits follow the pattern: test: → feat: → refactor:.

Screenshot Validation

For projects with a UI, humans validate the actual user experience by reviewing screenshots. Claude Code reads images natively — no Playwright, Puppeteer, or browser automation required. The human takes screenshots in their browser and shares them for agent review. This is a core part of ADD's trust-but-verify loop.

Human-AI Collaboration Protocol

ADD formalizes five engagement modes between humans and agents:

  • Spec interview — Human leads, agent refines. For creating PRDs and specs.
  • Quick check — Agent asks, human answers. For clarifying a detail mid-work.
  • Decision point — Human decides, agent implements. For architectural choices.
  • Review gate — Human reviews, agent awaits. For approving artifacts.
  • Status pulse — Agent reports, human adjusts. For progress check-ins.

Interviews follow a structured protocol: questions are estimated upfront ("I have 8 questions, about 5 minutes"), asked one at a time, and prioritized so the most critical questions come first.

Away Mode

Going to lunch? Stepping into a meeting? Tell the agent:

/add:away "back in 2 hours"

ADD assesses available work, presents an autonomous work plan for your approval, and gets to work. When you return:

/add:back

You get a briefing: what was completed, what's in progress, what needs your decision. The agent won't deploy to staging/production or start features without specs while you're gone.

Quality Gates

Five checkpoints catch issues progressively earlier:

  1. Pre-commit — Lint + formatting (before write)
  2. Pre-push — Type checking (before push)
  3. CI — Unit tests + coverage (on push)
  4. Pre-deploy — Spec compliance + integration tests (before deploy)
  5. Post-deploy — Smoke tests + monitoring (after deploy)

Multi-Agent Coordination

At Beta/GA maturity, ADD coordinates multiple agents working in parallel:

  • Git worktrees for full isolation between agents
  • File reservations to prevent conflicts
  • Merge sequence (infrastructure first, then features)
  • WIP limits to prevent coordination overhead
  • Trust-but-verify — orchestrators independently check sub-agent work

Work Cycles

ADD uses cycles (not sprints) — scope-boxed batches of work that end when validation criteria are met, not when a timer expires.

/add:cycle --plan      # Plan the next batch of work
/add:cycle --status    # Check progress, update hill chart
/add:cycle --complete  # Close cycle, capture learnings

Features in a cycle progress through positions: SHAPED → SPECCED → PLANNED → IN_PROGRESS → VERIFIED → DONE. Hill charts visualize whether work is still being figured out (uphill) or being executed (downhill).


Cross-Project Learning

This is what makes ADD compound over time. Agents don't start from zero on each project.

3-Tier Knowledge Cascade

Agents read all three tiers before starting any task. More specific tiers take precedence:

  • Tier 1: Plugin-Global (knowledge/global.md) — Universal ADD best practices. Ships with ADD, read-only.
  • Tier 2: User-Local (~/.claude/add/library.md) — Your cross-project wisdom. Promoted during /add:retro.
  • Tier 3: Project-Specific (.add/learnings.md) — This project's discoveries. Auto-populated at checkpoints.

Tier 1 ships with ADD — curated best practices about agent coordination, away mode, and methodology. Every ADD user benefits immediately.

Tier 2 follows you across projects (machine-local, not committed):

~/.claude/add/
├── profile.md    # Your preferences, conventions, working style
├── library.md    # Accumulated wisdom from all your projects
└── projects.json # Index of ADD-managed projects

Tier 3 is committed to git — every team member (human or agent) benefits:

.add/learnings.md
├── Architecture decisions and rationale
├── What worked / what didn't
├── Patterns discovered during development
└── Tool and framework quirks

Knowledge flows upward

Project A: discovers "UUID columns must be type uuid, not text"
  → Stored in .add/learnings.md (Tier 3: project-level)
  → Promoted to ~/.claude/add/library.md during /add:retro (Tier 2: cross-project)

Project B: agent reads library before implementing database schema
  → Finds UUID pattern, applies it automatically
  → No one repeats the mistake

ADD maintainers: universal methodology insights
  → Promoted to knowledge/global.md (Tier 1: plugin-global)
  → Every ADD user benefits on next install/update

Checkpoint triggers

Knowledge is captured automatically — no human effort required:

  • After every /add:verify — what passed, what failed, why
  • After every TDD cycle — patterns in test writing and implementation
  • After every deployment — environment-specific discoveries
  • After every away session — what the agent learned working autonomously
  • During /add:retro — human + agent reflect, promote learnings to cross-project library

Retrospectives

/add:retro

Two modes:

  • Interactive: Human and agent reflect together (~5 questions). Best insights come from this.
  • Agent summary: Quick non-interactive pulse check. Good for solo developers.

Retrospectives update .add/learnings.md, promote patterns to ~/.claude/add/library.md, archive the retro for future reference, and suggest process changes.


Architecture

ADD is intentionally simple:

  • No agent-side runtime dependencies — Pure markdown and JSON files (the Claude hook scripts require jq; see docs/runtime-dependencies.md)
  • No build step — Install and use immediately
  • No backend — Everything lives in your git repo (.add/) or locally (~/.claude/add/)
  • No vendor lock-in — Standard markdown specs and plans work with any tool
  • Plugin format — Claude Code .claude-plugin/plugin.json manifest

The entire plugin is ~60 files of markdown, JSON, and templates. It runs entirely within Claude Code's plugin system using commands, skills, rules, hooks, knowledge, and templates.

Optional Capabilities

ADD's core is zero-dependency, but some features benefit from optional tools:

  • Screenshot validation — Used by /add:verify and human review. Requires Claude Code's built-in image reading. Fallback: agents describe UI state in text.
  • Image generation — Used by /add:infographic and /add:brand-update. Requires an image generation MCP tool (e.g., Vertex AI Imagen). Fallback: SVG generation.

Screenshot validation is a core part of ADD's trust-but-verify loop for projects with a UI. After agents build, humans review screenshots of the actual user experience. Claude Code reads images natively — no Playwright, Puppeteer, or browser automation required. The human takes screenshots in their browser and shares them for review.

Image generation enhances branding and documentation workflows. ADD auto-detects whether an image generation MCP tool is available and adapts accordingly. Without it, /add:infographic produces SVG infographics instead of raster images. No functionality is lost — just a different output format.


Who is ADD for?

Solo developers using Claude Code for daily work who want structure without overhead. ADD scales down — a POC project gets lightweight specs and optional TDD. You get the benefits of methodology without the ceremony.

Small teams (2-10 engineers) looking to standardize how they work with AI agents. ADD gives your team a shared language: specs, plans, quality gates, and a maturity model that grows with your project.

Larger teams and enterprises scaling AI agents across multiple projects. ADD's cross-project learning system means agents get smarter over time. Patterns discovered on Project A automatically inform Project B. The maturity lifecycle gives leadership visibility into project rigor.

Open source maintainers who want contributors (human or AI) to follow consistent practices. ADD's spec-driven approach means every PR traces back to a specification.


Non-Greenfield Adoption

ADD works on existing projects, not just new ones. When you run /add:init on an existing codebase:

  1. Discovery — ADD scans your project structure, detects test frameworks, linters, and conventions
  2. Non-destructive setup — Adds .add/ alongside your existing structure, never replaces
  3. Maturity assessment — Suggests a starting maturity level based on existing rigor
  4. Catch-up spike — Identifies gaps and creates a remediation cycle
  5. Retroactive specs — Seeds learnings from git history

Existing conventions are respected. ADD layers on top of what you already have.


Environment Tiers

ADD adapts to your deployment reality:

  • Tier 1 — Local development only. Personal projects, plugins, CLIs.
  • Tier 2 — Local + production. SaaS apps, APIs with a prod server.
  • Tier 3 — Full pipeline (dev → staging → prod). Enterprise applications, team projects.

Quality gates, deployment skills, and test matrices all adjust based on your tier.


Core workflow:

CommandPurpose
/add:initBootstrap ADD in your project via structured interview
/add:specCreate a feature specification through interview
/add:planCreate implementation plan from spec
/add:tdd-cycleComplete RED → GREEN → REFACTOR → VERIFY cycle
/add:test-writerWrite failing tests from spec (RED phase)
/add:implementerWrite minimal code to pass tests (GREEN phase)
/add:reviewerCode review for spec compliance (read-only)
/add:verifyRun quality gates — lint, types, tests, coverage, spec compliance
/add:optimizePerformance optimization pass
/add:deployEnvironment-aware deployment with verification

Planning & milestones:

CommandPurpose
/add:cyclePlan, track, and complete work cycles within milestones
/add:milestoneManage milestones — list, switch, split, rescope, create
/add:roadmapView and manage roadmap — milestones, horizons, reordering
/add:promoteMaturity promotion — evidence-based gap analysis + level-up

Design & documentation:

CommandPurpose
/add:uxIterate on UI/UX design before implementation (sign-off gate)
/add:docsGenerate architecture diagrams, API docs, README drift detection
/add:infographicGenerate project infographic SVG from PRD + config
/add:brandView project branding — accent color, palette, drift detection
/add:brand-updateUpdate branding materials and audit artifacts
/add:dashboardGenerate visual HTML project dashboard

Process & learning:

CommandPurpose
/add:awayDeclare absence — get autonomous work plan
/add:backReturn from absence — get briefing
/add:retroRun a retrospective — capture and promote learnings
/add:changelogGenerate/update CHANGELOG.md from conventional commits
RuleWhat it enforces
spec-drivenNo code without a spec
tdd-enforcementStrict RED → GREEN → REFACTOR → VERIFY cycle
human-collaborationInterview protocol, engagement modes, away/back
agent-coordinationTrust-but-verify, sub-agent isolation, parallel execution
source-controlFeature branches, conventional commits, TDD commit pattern
environment-awarenessTier-based behavior (local / local+prod / full pipeline)
quality-gates5-level gate system from pre-commit to post-deploy
learningAutomatic checkpoints, knowledge persistence, retro integration
project-structureStandard .add/ layout, cross-project persistence paths
maturity-lifecycleMaster dial — governs ALL ADD behavior per maturity level
maturity-loaderLoads the per-maturity preset that gates other rules
model-rolesArchitect vs Editor model-role guidance — match agent capability to task shape
design-systemSilicon Valley Unicorn aesthetic for all generated visuals
add-complianceADD methodology compliance checks
cache-disciplineMarketplace/cache hygiene and stale-cache recovery
injection-defensePrompt-injection defense for untrusted content
registry-syncKeep manifests/registries in sync after edits
secrets-handlingNever commit secrets; redaction patterns
telemetryStructured telemetry events from skills/hooks
version-migrationMulti-hop version migration ladder

After /add:init, your project gets this structure:

your-project/
├── .add/                  # ADD state (git-committed)
│   ├── config.json        # Project config
│   ├── learnings.md       # Agent knowledge base
│   └── cycles/            # Work cycle tracking
├── docs/
│   ├── prd.md             # Product Requirements Document
│   ├── plans/             # Implementation plans
│   └── milestones/        # Milestone tracking
├── specs/                 # Feature specifications
├── tests/
│   └── screenshots/       # Visual verification
└── CLAUDE.md              # Project context for Claude

Cross-project persistence (machine-local, not committed):

~/.claude/add/
├── profile.md             # Your preferences
├── library.md             # Cross-project wisdom
└── projects.json          # Project index

Roadmap

See docs/v1.0-roadmap.md for the current path to v1.0 (GA). Release history lives in CHANGELOG.md.



License

MIT


Ver o original no GitHub

Bom para

Relacionados