Acceptance Driven Development

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.

1. For a new project, Gate 2 copies the full hub template and fills it; do not invent a partial AC table.
2. For malformed AC, pause before planning/code, report gaps, preserve IDs/evidence/language, and ask before ambiguous migration.
3. 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.

1. 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.

1. 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.

1. Run ready AC-mapped tasks sequentially; parallelize only explicitly non-overlapping tasks. Keep the plan within approved scope.
2. Complete Phase 4.8: fresh baseline validation, then one independent review when possible, otherwise explicit self-review; every check must pass before Phase 5.
3. 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.
4. 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
• Source: ZeusYue/acceptance-driven-development-skill
• License: MIT

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