# Acceptance Driven Development

> Use when building features, fixing bugs, adding capabilities, or explicitly exploring a design under ADD before AC creation or update. Use with a project's AC.md acceptance table when available; also use when the user says implement, add, fix, acceptance criteria, done means, or asks ADD to compare approaches.

- **Type:** Skill
- **Install:** `agentstack add skill-zeusyue-acceptance-driven-development-skill-acceptance-driven-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ZeusYue](https://agentstack.voostack.com/s/zeusyue)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ZeusYue](https://github.com/ZeusYue)
- **Source:** https://github.com/ZeusYue/acceptance-driven-development-skill/tree/main/skills/acceptance-driven-development

## Install

```sh
agentstack add skill-zeusyue-acceptance-driven-development-skill-acceptance-driven-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Acceptance-Driven Development

Execute code changes against explicit acceptance criteria, then loop until every criterion has a settled outcome.

**Completion layers:** Agent implementation work is done only when no `[ ]` or `[~]` remain. The project is complete only when every AC is `[x]`, `[>]`, or `[-]` — no `[ ]`, `[~]`, or `[!]`.

## 🚨 FIRST RULE — Check Before You Code

Every code change enters **Phase 3.5** before Phase 4. Announce the phase and the chosen implementation mode before editing code.

- Approved `[ ]` / `[~]` backlog → **Phase 3.5A** → Mode A.
- New feature or behavior change → **Phase 3.5B** → propose AC delta + approach → explicit approval → persist AC → Phase 4.
- Bug restoring intended behavior → **Phase 3.5B** impact analysis → fast lane; if no relevant AC exists, propose and confirm one before Phase 4.
- Refactor, build/config change, or pure cosmetic change → Phase 3.5B impact analysis → fast lane; untracked work also needs a confirmed tracking AC before Phase 4.

Describing a desired change is not approval of an approach. A fast-lane bug fix skips approach discussion, not impact analysis, review, or verification.

Announce: `Phase 0`, `Gate 1`, `Gate 2`, `Phase 3.5A` or `3.5B`, `Phase 4 Mode A` or `B`, `Phase 4.8`, `Phase 5`, and `Phase 6` when each begins.

Read `references/guardrails-and-examples.md` only when rationale, rationalization handling, scenarios, extended red flags, or the compact phase map is needed.

## Capabilities and Scope

ADD is self-contained: AC parsing, impact analysis, review, verification, and completion checks must work even without companion skills.

| Optional capability | Use when available | Fallback |
|---|---|---|
| External planning tool | Mirror or assist ADD's approved-scope plan | Use the built-in plan asset/reference; never use tool status as acceptance status. |
| Review subagent | Mode A independent review | Explicit self-review against all six checks. |
| `project-experience` | Reuse cross-project lessons | Read `$DOC_HUB/_exp_memory.md` directly when present. |

Check host capabilities before using optional capabilities; their absence never blocks ADD.

Design exploration is built in. Explicit ADD exploration always reads `references/design-exploration-and-handoff.md`; also read it for Greenfield Gate 1 or a Large / genuinely ambiguous Phase 3.5B behavior change. Otherwise skip it for settled Small or Medium changes and all fast-lane work.

Use ADD for implementation, fixes, and behavior changes. Skip it for pure research, prose-only formatting/typos, or when the user declines an AC process. Code formatting or typo fixes still enter Phase 3.5B fast lane.

## Phase 0: Locate Hub, AC, and Project Document

All ACs, templates, project documents, and experience cache live in one document hub (`$DOC_HUB`), independent of code directories.

### Locate `$DOC_HUB`

1. Read `~/.add-hub`. If its trimmed path is an existing directory, it is the active hub.
2. If missing/invalid, use `_exp_memory.md` only to find candidate parents. Validate them with templates plus project `AC.md` / document directories; cache alone is insufficient.
3. Use one validated candidate; if none validates or multiple remain, ask the user to choose or confirm the hub.
4. After validation or user confirmation, write `~/.add-hub`. If only the pointer is unwritable, report it and use the hub this session; an unwritable hub requires a writable choice before code.
5. If no candidate exists, ask for a stable shared directory, create it and `_exp_memory.md` placeholder, then write `~/.add-hub`.

Cache presence never determines hub identity. Use host-native file operations; do not require a literal `Glob` tool.

### Locate AC, templates, and the AC Contract Gate

Find `$DOC_HUB/*/AC.md`. Use the named project when known; otherwise present or infer candidates.
Copy missing hub templates from the matching installed `assets/` files for AC, project documents, and implementation plans.
Seed `assets/project-index.md` only when `$DOC_HUB` is an Obsidian vault and the user confirms Dataview is available/enabled. In Obsidian, also offer `assets/ac-document-tables.css` as `.obsidian/snippets/ac-document-tables.css`; enable it only with user consent. Never recreate a template from memory.

### Step 0.3 — AC Contract Gate (before plan or code)

**`AC.md` is the sole source of truth** for accepted scope, AC IDs, acceptance status, verification evidence, acceptance confirmation, deferral, and deprecation.
A design document or conversation may retain an approved implementation approach; a plan only decomposes approved AC work and never owns acceptance state.

1. Read `$DOC_HUB/ac-template.md` and, when it exists, the target `AC.md` before Gate 2, Phase 1, any external planning tool, or code.
2. Validate Goal, meaningful sections, five semantic columns, valid markers, Status Summary, deferred/backlog area, and Verification Evidence Details.
   New documents require a Scope Decision Log; an existing document may retain its legacy Change Log until a separately approved migration. Localized header equivalents are valid.
3. For a new project, Gate 2 copies the full hub template and fills it; do not invent a partial AC table.
4. For malformed AC, pause before planning/code, report gaps, preserve IDs/evidence/language, and ask before ambiguous migration.
5. **An external planning tool may start only after** this gate passes and the relevant AC scope is approved/updated.
   Every plan needs an **Acceptance Mapping** from each task to AC IDs; plan state never changes AC status. ADD supplies a plan asset/reference.
6. Keep five-column AC rows scannable: do not place full logs, lengthy benchmark data, screenshots, or step-by-step feedback in cells.
   Put it in a fixed `EVD-YYYYMMDD-N` under Verification Evidence Details. Append `Evidence: EVD-...` to How to Verify without replacing reusable commands/steps.
7. Every MANUAL row must contain concrete prerequisites/actions and an observable expected result. A vague check fails this gate; clarify it as a proposed AC edit and obtain approval before planning or code.

Read `references/ac-contract-and-plan-boundary.md` for schema, migration, and handoff details.

### Step 0.4 — Living Project Document

**ADD owns project-document creation, update, and finalization. `project-experience` reads/mines project documents; it does not author them.**

Before substantial work on a non-trivial project, check for `$DOC_HUB//.md`. If missing:

1. Read `$DOC_HUB/project-doc-template.md` before creating or restructuring a project document.
2. Populate facts by evidence priority: code → config → comments → README → commit history → labeled inference.
3. Match the project's document language: Chinese tag/status `项目` and `开发中` / `维护中` / `已完成` / `归档`, or English `project` and `active` / `maintained` / `completed` / `archived`. Do not mix languages within one document.
4. Record verified implementation facts now. Label plans and uncertainty as `planned` or `⚠️ 无法确定`.
5. Update only after meaningful architecture, dependency, concurrency, persistence, build, or deployment changes.

### No AC: Greenfield gates

**Existing project but missing AC.md:** ask how to recover or reconstruct its scope; do not treat it as Greenfield without confirmation.
Build an unsaved five-column recovery draft, preserve evidence/uncertainty, and obtain scope approval before saving. Only a project without established code or scope enters Gates 1–2.

**Gate 1 — Design:** announce, read relevant cache and `references/design-exploration-and-handoff.md`, then follow its design process and obtain one design approval. Save `design.md`, then proceed to Gate 2 AC drafting without asking a separate permission merely to create the draft.

**Gate 2 — Acceptance Criteria:** read and copy the full hub `ac-template.md`, then draft the approved design into its five semantic columns; use new top-level IDs as `AC-`.
Present one proposed criterion per turn by default so the user can confirm, edit, split, merge, or defer it; batch only when explicitly requested. After all rows are reviewed, wait for one final approval; then save `AC.md` and enter Phases 1–3.

For detailed size classification and solution ladder, read `references/change-design-guide.md`.

## Phases 1–3: Triage, Order, Classify

### Phase 1: Parse statuses

| Mark | Action |
|---|---|
| `[ ]` | Implement. |
| `[~]` | Implement the known remainder. |
| `[x]` / `[-]` | Skip unless affected by the current change. |
| `[>]` | Skip unless the user explicitly resumes it. For unchanged accepted scope, record that decision, change to `[ ]` if untouched or `[~]` if partial implementation remains, then enter Phase 3.5A. Changed scope enters Phase 3.5B and remains `[>]` until approval. |
| `[!] [manual]` | Present for user verification. |
| `[!] [affected]` | Re-verify; AUTO now, MANUAL with user. |
| `[!] [blocked]` | Show reason and unblock condition. |

No `[ ]` or `[~]` items: if the user requested a change, enter Phase 3.5B; otherwise present the annotation-aware `[!]` report. Any `[~]` row is approved remainder and normally enters Phase 3.5A with `[ ]` rows. A `[ ]`/`[~]` row whose latest EXECUTION EVD is `state: cancelled` or `state: rejected` instead waits for explicit restart and recovers its original mode/attempt state.

### Phase 2: Order

Default order: Features → Compatibility → Performance → Quality. Infer category when absent; preserve AC ID order within a category.

### Phase 3: Classify verification

| Class | Rule | Phase 5 result |
|---|---|---|
| AUTO | `How to Verify` has an executable command | Run command; `[x]` only on fresh pass. |
| MANUAL | UI/visual/human judgment with concrete AC steps and expected result | `[!] [manual]` with those exact steps. |
| BLOCKED | Environment unavailable, or a task/AC reaches the three-attempt boundary | `[!] [blocked]` with reason and concrete unblock condition. |

## Phase 3.5: Code-Change Entry (SINGLE ENTRY POINT)

### Phase 3.5A: Approved Backlog Entry

Use after Phases 1–3 for approved `[ ]` / `[~]` rows.

1. Announce `Phase 3.5A — Approved backlog impact analysis: N triaged ACs`.
2. List target ACs and trace relevant call paths.
3. Mark any affected `[x]` rows as `[!] [affected]` with `⚠️ Affected by AC-N implementation — needs re-verification`.
4. Initial triaged work always enters **Mode A**, even for one or two rows, preserving Phase 3 classification.

### Phase 3.5B: Mid-Development Requirement Changes

Before approval, trace callers and present target ACs plus the proposed affected-AC list without mutating `AC.md`.

- **Behavior change:** consult relevant experience cache and classify size. For settled Small or Medium work, present the proposed AC delta with the approach and wait for explicit `approved` / `go ahead` / `confirm`.
  For Large or genuinely ambiguous work, read `references/design-exploration-and-handoff.md`, validate material questions, design sections, and proposed AC rows incrementally, then obtain one final combined approval for the consolidated design and AC delta.
- **Fast lane:** use only for original-behavior bug fixes, equivalent refactors, build/config changes, or pure cosmetics. If no relevant AC exists, propose the next numeric tracking AC and obtain quick confirmation; do not write it first.
- **Persistence boundary:**
  - Rejection/cancellation before approval leaves `AC.md` unchanged. After approval, atomically apply the approved delta before code; new targets start `[ ]`.
  - Cancellation after persistence but before code keeps the approved contract: new targets remain `[ ]`, while edited/resumed targets retain their persisted `[~]` or `[ ]` state.
  - An edited `[x]` target becomes `[~]` when its criterion, verification, or expected result changed. Preserve approved-delta-pending evidence.
  - A resumed `[>]` target becomes `[ ]` if untouched or `[~]` if implementation remains.
  - An approved redesign of `[!] [blocked]` starts a new attempt series and becomes `[ ]` with no retained implementation or `[~]` with retained implementation. Preserve its blocking EVD.
  - Proposed affected non-target `[x]` rows become `[!] [affected]`. A tracked bug changes its target `[x]` to `[~]`; other tracked fast-lane work with unchanged accepted behavior marks target and affected `[x]` rows `[!] [affected]`.
- **Mode choice after Phase 3.5B:** count approved target ACs after the persistence boundary; use Mode B for 1–2 related ACs, or Mode A for 3+.

Apply the detailed small/medium/large process and solution ladder in `references/change-design-guide.md`. When only physical size is uncertain, treat the change as Medium; genuine design ambiguity always loads the design reference.

## Phase 4: Implement

**Before any code, read and follow `references/implementation-planning-and-execution.md`.** Change only what the target AC requires; trace root cause before editing; re-verify affected ACs; use direct experience-cache reading or `project-experience` when available.

### Mode A: Batch

Use for all Phase 3.5A work and Phase 3.5B work spanning 3+ related ACs.

1. List every target AC before code.
2. Apply the reference's plan matching rules. Reuse the one matching active plan.
   Otherwise copy `assets/implementation-plan-template.md` to a collision-safe `$DOC_HUB//plans/YYYY-MM-DD--implementation[-N].md`. Never overwrite/reopen a completed plan. Self-check the selected plan, then execute without asking for plan approval.
3. Run ready AC-mapped tasks sequentially; parallelize only explicitly non-overlapping tasks. Keep the plan within approved scope.
4. Complete Phase 4.8: fresh baseline validation, then one independent review when possible, otherwise explicit self-review; every check must pass before Phase 5.
5. Re-run affected AUTO ACs; affected MANUAL ACs remain `[!] [manual]`. Create safe local AC-scoped checkpoints after Agent-side verification; never push unless separately requested.
6. Continue to Phase 5. Stop and escalate after three consecutive failed implementation → verification → review cycles for the same task.

**Mode A Continuation Rule:** A phase announcement or progress update is not a decision gate. While any target remains `[ ]` or `[~]`, continue ready tasks.
Do not stop after a plan task, ask whether to continue, or treat plan/subagent progress as acceptance completion. Three failed cycles block only the affected task and dependent ACs; continue independent rows.
Stop the batch only for required approval, a Phase 5 `[!] [manual]` handoff, a shared/batch-wide block, user rejection/cancellation, or a real host/tool limit. On a host/tool limit, resume the same batch next turn without reapproval.

### Mode B: Lightweight

Use only for a settled Phase 3.5B change spanning one or two ACs: a behavior change is settled by approval; eligible fast-lane work is settled by impact analysis and, for any untracked code change, quick confirmation of its tracking AC.

1. Before code, print the reference's six-field **Execution Map** in chat; do not create a persistent plan or ask for plan approval.
2. Implement, maintain the map in chat, and complete Phase 4.8 self-review.
3. Apply Phase 3 verification class to each changed AC; re-run affected AUTO ACs, while affected MANUAL ACs remain `[!] [manual]`.
4. Changed MANUAL criteria become `[!] [manual]` after review; changed AUTO criteria proceed to Phase 5 command verification. Create the same safe local AC-scoped checkpoint after Agent-side verification; never push unless separately requested.
5. Stop the target AC and apply the failure boundary after three consecutive failed implementation/verification/review cycles. Explicit user rejection instead uses the reference's persisted rejection transition and does not increment the failure counter.

## Phase 4.8: Review

Enter only after applicable baseline validation succeeds for the implementation subset being settled: build, type-check, lint, or relevant test. If baseline validat

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZeusYue](https://github.com/ZeusYue)
- **Source:** [ZeusYue/acceptance-driven-development-skill](https://github.com/ZeusYue/acceptance-driven-development-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zeusyue-acceptance-driven-development-skill-acceptance-driven-development
- Seller: https://agentstack.voostack.com/s/zeusyue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.