AVSDD is a spec-driven development process where AI agent panels replace human gate approvals at every phase. The human provides initial requirements and goals, then re-enters only at the end to review demos and the audit trail. The AI may ask for async clarifications but never blocks on them.
| Traditional SDD | AVSDD |
|---|---|
| Human approves each phase | 5-agent panel approves each phase |
| Gates block until human returns | Gates run autonomously and resolve |
| Wireframes optional | Visualizer agent generates wireframes at every spec phase |
| Business intent informal | North Star Document locked at Phase 0, traced throughout |
| Human is the quality bar | Agents embody PM, Architect, QA, Security, and CX perspectives |
The North Star is the locked source of business intent. It is created before any spec work begins and cannot be modified by agents — only by human async clarification.
NORTH STAR DOCUMENT
───────────────────
Problem Statement: [1 sentence — what pain currently exists]
Success State: [1 sentence — what the world looks like when done]
Measurable Success Criteria:
SC-1: [quantifiable outcome — not a feature, an observable result]
SC-2: [quantifiable outcome]
SC-3: [quantifiable outcome]
Out of Scope: [explicit anti-goals — what we will NOT solve]
Primary Beneficiary: [who benefits and how they'll know it worked]
Every agent panel member receives the North Star at every gate. A phase that cannot draw a line from its artifacts to the North Star success criteria fails PM review.
Five agents form the review panel at each phase gate. Every agent receives the same artifacts simultaneously. Verdicts are revealed synchronously (all-at-once) to prevent anchoring bias.
| Persona | Core Question | Rejects When |
|---|---|---|
| PM — Alex | Does this deliver the stated success criteria? | Artifacts don't trace to North Star SC; traceability gaps |
| Architect — Vera | Is the technical approach sound and traceable? | Design won't scale, orphaned components, intent drift |
| QA — Jordan | Is this testable and verifiable? | No acceptance criteria or untestable claims |
| SEC — Morgan | Does this introduce unacceptable risk? | Auth, data, or attack surface gaps |
| CX — Casey | Does this serve the end user well? | UX gaps, accessibility issues, user journey blind spots |
Rotating Dissent: At each gate, one panel member takes the Dissent obligation — they must raise at least one substantive challenge beyond their primary review, even if they'd otherwise PASS. This is not a separate seat but an obligation layered on top of the designated member's primary review. Rotation:
| Gate | Primary Dissent |
|---|---|
| Requirements | Vera (Architect) |
| Design | Morgan (SEC) |
| Tasks | Jordan (QA) |
| Demo | Casey (CX) |
Synchronized Verdict Reveal: All verdicts are written independently before any are shared. This prevents groupthink and anchoring.
Verdict Format:
[PERSONA] — [PASS | FAIL | CONDITIONAL]
Rationale: [2-3 sentences]
Evidence: [specific artifact reference]
Conditions (if CONDITIONAL): [exactly what must change, numbered list]
Conditional Expiry: A CONDITIONAL verdict must be resolved within 2 iterations of the phase. If unresolved after 2 attempts, it auto-escalates to FAIL.
Deadlock Resolution: If 3+ agents vote FAIL, the phase returns to rework. If 2 agents FAIL and 3 PASS, the 2 FAIL conditions must be addressed before proceeding. Unanimous PASS required to gate-advance.
At every spec phase (Requirements, Design, Tasks), a Visualizer Agent runs in parallel with the panel gate and produces visual artifacts for human review.
Requirements Phase — UI Wireframes (ASCII):
┌─────────────────────────────────────────┐
│ DASHBOARD [Profile] │
├─────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────────────────┐ │
│ │ Sidebar │ │ Main Content Area │ │
│ │ │ │ │ │
│ │ [Nav 1] │ │ [Card] [Card] │ │
│ │ [Nav 2] │ │ │ │
│ │ [Nav 3] │ │ [Table / List] │ │
│ └──────────┘ └──────────────────────┘ │
└─────────────────────────────────────────┘
Design Phase — Process Flow (Mermaid):
flowchart TD
A[User Action] --> B{Auth Check}
B -->|Valid| C[Load Data]
B -->|Invalid| D[Redirect Login]
C --> E[Transform]
E --> F[Render View]
Design Phase — Sequence Diagram (Mermaid):
sequenceDiagram
participant U as User
participant API as API Layer
participant DB as Database
U->>API: POST /resource
API->>DB: INSERT query
DB-->>API: Row ID
API-->>U: 201 Created
Tasks Phase — Dependency Map (Mermaid):
graph LR
T1[Setup DB Schema] --> T3[Build API Endpoints]
T2[Setup Auth] --> T3
T3 --> T4[Build UI Components]
T4 --> T5[E2E Tests]
The PM (Alex) maintains a living traceability matrix throughout all phases, tracing every artifact back to a North Star success criterion. Vera (Architect) provides a second pass on intent drift from a technical angle.
| Artifact | Type | Traces To | SC Coverage |
|------------------|-------------|-----------|-------------|
| FR-001 Login req | Requirement | SC-1 | ✓ |
| Component: Auth | Design | FR-001 | ✓ |
| TASK-1.3 OAuth | Task | Component:Auth | ✓ |
| Test TC-12 | Test | TASK-1.3 | ✓ |
The PM runs a delta check at each gate:
- Scope creep: artifacts that trace to nothing in the North Star → flag for removal
- Intent drift: artifacts that used to trace correctly but no longer do → FAIL
- Gap detection: success criteria with no corresponding artifacts → CONDITIONAL
When agents encounter ambiguity they cannot resolve, they surface a clarification request. The process does not block — it continues with the best reasonable assumption documented, and the human addresses the clarification asynchronously.
CLARIFICATION REQUEST
─────────────────────
Raised by: [Persona]
Phase: [Phase Name]
Question: [Specific question]
Assumed Answer: [What we'll proceed with if no response]
Impact if Assumption Wrong: [What changes]
Deadline for Input: [Phase 4 start / before implementation begins]
Who runs it: Primary AI agent (no panel gate — human initiates this). Human input: Initial requirements, goals, context. Output: Locked North Star Document.
This is the only phase where human input is actively consumed. The AI drafts the North Star from the human's requirements, then presents it for one-time human confirmation before locking.
# North Star lives here
touch avsdd/north-star.md
touch avsdd/traceability.md # PM initializes this
touch avsdd/clarifications.md # Async Q&A logWho runs it: AI generates requirements → Visualizer generates wireframes → Panel gates.
Deliverables:
spec/{id}/requirements.md— functional requirements, user stories, acceptance criteriaspec/{id}/requirements-wireframes.md— ASCII wireframes for all primary UI statesspec/{id}/panel-gates/requirements-gate.md— 5 agent verdicts
Panel focus at this gate:
- PM (Alex): Do requirements trace to every North Star success criterion? Is traceability matrix populated?
- Architect (Vera): Are requirements technically feasible and well-structured? [Dissent rotation]
- QA (Jordan): Does every requirement have testable acceptance criteria?
- SEC (Morgan): Are auth, input validation, and data protection requirements present?
- CX (Casey): Do requirements reflect the end user's real needs?
Who runs it: AI generates design → Visualizer generates diagrams → Panel gates.
Deliverables:
spec/{id}/design.md— architecture, data model, API contracts, component designspec/{id}/design-diagrams.md— Mermaid flowcharts + sequence diagramsspec/{id}/panel-gates/design-gate.md— 5 agent verdicts
Panel focus at this gate:
- PM (Alex): Does the design make the measurable outcomes achievable? All components traced?
- Architect (Vera): Is the architecture sound, scalable, and free of orphaned components?
- QA (Jordan): Is the design testable? Are error states and edge cases designed?
- SEC (Morgan): Are threat surfaces addressed? Auth flow, data flow, input validation? [Dissent rotation]
- CX (Casey): Does the design support a good user experience?
Who runs it: AI generates tasks → Visualizer generates dependency map → Panel gates.
Deliverables:
spec/{id}/tasks.md— task breakdown with IDs, estimates, dependencies, acceptance criteriaspec/{id}/tasks-dependency-map.md— Mermaid dependency graphspec/{id}/panel-gates/tasks-gate.md— 5 agent verdicts
Panel focus at this gate:
- PM (Alex): Is the task list scoped to deliver the success criteria — no more, no less?
- Architect (Vera): Does every task trace to a design component (nothing orphaned)?
- QA (Jordan): Are test tasks included alongside implementation tasks? [Dissent rotation]
- SEC (Morgan): Are security hardening tasks present (not afterthoughts)?
- CX (Casey): Are user-facing quality tasks included?
Who runs it: AI implements following TDD. No panel gate — this phase is execution.
Approach:
- Follow task order from Phase 3
- Write tests before implementation (TDD: Red → Green → Refactor)
- Update task status after each task completes
- Log non-obvious decisions to
spec/{id}/decisions.md - If a blocker or ambiguity arises → file a clarification request (non-blocking)
No human gate. Implementation proceeds until complete. The demo in Phase 5 is where quality is verified.
Who runs it: AI generates demo artifacts → Panel verifies against North Star.
Deliverables:
demos/{id}/demo.md— structured demo showing each success criteriondemos/{id}/verification.md— panel verdict against North Star
Panel focus at this gate — every SC verified:
INTENT VERIFICATION
───────────────────
SC-1: [success criterion text]
Demo shows: [what artifact proves this]
Verified by: [QA test result / measurement]
Result: PASS / FAIL + evidence
SC-2: ...
The panel does not ask "is it built?" — it asks "does it prove the North Star was reached?"
After Phase 5 PASS: the human reviews the demo artifacts + audit trail and may redirect, accept, or request a follow-up iteration.
project/
├── CLAUDE.md # AI context (AVSDD rules)
├── avsdd/
│ ├── PROCESS.md # Full process guide
│ ├── north-star.md # Locked business intent (Phase 0)
│ ├── traceability.md # PM traceability matrix (living doc)
│ ├── clarifications.md # Async human Q&A log
│ ├── panel-gate-template.md # Verdict format reference
│ └── personas/
│ ├── PM.md # Alex — Product Manager
│ ├── ARCHITECT.md # Vera — Software Architect
│ ├── QA.md # Jordan — QA Engineer
│ ├── SEC.md # Morgan — Security Engineer
│ └── CX.md # Casey — CX Advocate
├── spec/
│ ├── WORKFLOW.md # This process guide
│ ├── .current-spec # Active spec pointer
│ └── {id}-{name}/
│ ├── README.md # Phase status dashboard
│ ├── requirements.md # Phase 1 requirements
│ ├── requirements-wireframes.md # Visualizer: ASCII wireframes
│ ├── design.md # Phase 2 design
│ ├── design-diagrams.md # Visualizer: Mermaid diagrams
│ ├── tasks.md # Phase 3 tasks
│ ├── tasks-dependency-map.md # Visualizer: dependency graph
│ ├── decisions.md # Phase 4 decision log
│ └── panel-gates/
│ ├── requirements-gate.md # Phase 1 panel verdicts
│ ├── design-gate.md # Phase 2 panel verdicts
│ └── tasks-gate.md # Phase 3 panel verdicts
└── demos/
└── {id}/
├── demo.md # Phase 5 demo artifacts
└── verification.md # Phase 5 panel verification
# Copy the avsdd/ folder into your project root
cp -r path/to/avsdd/ your-project/avsdd/
# Create the spec and demo directories
mkdir -p spec demosThe avsdd/ folder ships with all templates pre-populated (north-star, traceability, clarifications, panel-gate-template, and all 5 persona files).
mkdir -p spec/001-feature-name/panel-gates
mkdir -p demos/001
# Initialize spec README
cat > spec/001-feature-name/README.md << 'EOF'
# Spec 001: [Feature Name]
| Phase | Status | Gate Result |
|-------|--------|-------------|
| Requirements | Pending | - |
| Design | Pending | - |
| Tasks | Pending | - |
| Implementation | Pending | - |
| Demo & Verify | Pending | - |
**North Star Alignment:** Traces to SC-1, SC-2
**Current Blockers:** None
EOF
echo "001-feature-name" > spec/.current-speccat > CLAUDE.md << 'EOF'
# CLAUDE.md — AI Assistant Context
## Development Process: AVSDD
This project uses Autonomous Agent-Verified Spec-Driven Development (AVSDD).
See SETUP_SPEC_DRIVEN_DEVELOPMENT.md for the full process.
### Phase Gate Rules
- CANNOT proceed to Design without Requirements panel PASS
- CANNOT proceed to Tasks without Design panel PASS
- CANNOT proceed to Implementation without Tasks panel PASS
- Phase 4 (Implementation) has no gate — builds until complete
- Phase 5 (Demo) panel verifies against North Star success criteria only
### Business Intent
- North Star: avsdd/north-star.md (LOCKED after Phase 0)
- Traceability: avsdd/traceability.md (PM updates at every gate)
- Clarifications: avsdd/clarifications.md (async, non-blocking)
### Session Start Checklist
1. Read avsdd/north-star.md — know the success criteria
2. Read spec/.current-spec — find active spec
3. Read spec/{id}/README.md — find current phase
4. Read avsdd/traceability.md — check for gaps
5. Check avsdd/clarifications.md — any pending human responses?
### Agent Panel Trigger
When a phase is complete and needs gate review, say:
"Run the agent panel gate for [phase] of spec [id]"
The panel will:
1. Run 5 agents (PM, Architect, QA, SEC, CX) in parallel
2. Each writes their verdict independently
3. Verdicts are revealed simultaneously
4. Resolve any CONDITIONALs or FAILs before proceeding
### Visualizer Trigger
When a spec phase is drafted, say:
"Run the Visualizer for [requirements/design/tasks] of spec [id]"
### AVSDD Rules
- NEVER skip a panel gate
- NEVER modify the North Star without explicit human instruction
- ALWAYS update the traceability matrix after each phase
- File clarification requests rather than blocking
- Log all non-obvious implementation decisions to decisions.md
## Project Context
- **Tech Stack**: [Add your stack here]
- **Spec Directory**: spec/
- **Active Spec**: See spec/.current-spec
EOF# Requirements: [Feature Name]
**Spec ID**: {id}
**Status**: Draft
**Updated**: [DATE]
**North Star Alignment**: SC-1, SC-2 (list which SCs this addresses)
---
## 1. Problem Statement
### Current Situation
[What currently exists or doesn't exist]
### Pain Points
- [Pain point 1]
- [Pain point 2]
### Desired Outcome
[What should exist after this is implemented]
---
## 2. User Stories
### Story 1
**As a** [user type] **I want** [goal] **so that** [reason]
**Acceptance Criteria** (must be testable):
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
---
## 3. Functional Requirements
### FR-001: [Name]
**Priority**: P0 / P1 / P2
**Traces to**: SC-X
**Description**: [Detail]
**Acceptance Criteria**:
- [ ] [Testable criterion]
---
## 4. Non-Functional Requirements
### Performance
- [ ] [Requirement with measurable target]
### Security
- [ ] [Auth, data protection, input validation]
### Accessibility
- [ ] [WCAG level or specific requirement]
---
## 5. Out of Scope
[What this spec explicitly does NOT cover — ties to North Star "Out of Scope"]
---
## 6. Dependencies
- [ ] [Dependency 1 with owner]
---
## 7. Open Clarifications
[Any questions filed to avsdd/clarifications.md]# Design: [Feature Name]
**Spec ID**: {id}
**Status**: Draft
**Updated**: [DATE]
---
## 1. Architecture Overview
### System Context
[Where this fits — diagram or prose]
### Component Diagram
[ASCII or description — Mermaid version in design-diagrams.md]
---
## 2. Technical Decisions
### TD-001: [Decision]
**Decision**: [What]
**Rationale**: [Why — ties back to which requirement]
**Alternatives**: [What else was considered]
**Trade-offs**: [Honest pros/cons]
---
## 3. Data Model
```typescript
interface [ModelName] {
id: string;
// ...
}POST /api/[endpoint]
Request: { ... }
Response: { ... }
[Approach]
[Encryption, storage, retention]
[Sanitization strategy]
[What new attack surface this introduces and how it's mitigated]
| Error | Cause | Handling |
|---|---|---|
| [error] | [cause] | [response] |
- [What will be unit tested]
- [What will be integration tested]
- [Full user flow tests]
### Tasks Template (`spec/{id}/tasks.md`)
```markdown
# Tasks: [Feature Name]
**Spec ID**: {id}
**Status**: Draft
**Updated**: [DATE]
---
## Task Breakdown
### TASK-{id}.1: [Task Name]
**Type**: Feature / Setup / Test / Security
**Priority**: P0 / P1 / P2
**Traces to**: [Design component or requirement]
**Status**: Pending
**Implementation steps**:
- [ ] [Step 1]
- [ ] [Step 2]
**Test tasks** (required alongside every implementation task):
- [ ] Unit test written for [component]
- [ ] Integration test written for [flow]
**Acceptance Criteria**:
- [ ] [Testable criterion 1]
**Dependencies**: None / TASK-{id}.N
---
## Progress
| Total | Complete | In Progress | Pending |
|-------|----------|-------------|---------|
| N | 0 | 0 | N |
---
## Risk Register
### Risk 1: [Description]
**Likelihood**: H / M / L
**Impact**: H / M / L
**Mitigation**: [How we handle it if it hits]
AVSDD uses TDD during Phase 4 implementation. Tests are not a Phase 4 afterthought — they are scoped in Phase 3 tasks.
- Red: Write the failing test first (based on task acceptance criteria)
- Green: Write minimal implementation to make it pass
- Refactor: Clean up without breaking tests
# Install Playwright
npm init playwright@latest
# Directory structure
mkdir -p tests/{unit,integration,e2e}
# Playwright config
cat > playwright.config.ts << 'EOF'
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests/e2e',
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry',
},
projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
webServer: {
command: 'npm run dev',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
EOF{
"scripts": {
"test": "playwright test",
"test:ui": "playwright test --ui",
"test:coverage": "nyc npm test"
}
}- Unit tests: 80%+ coverage
- Critical paths: 100% coverage
- E2E: all Phase 3 acceptance criteria covered
"Here are my requirements: [requirements]. Draft the North Star Document and confirm with me before locking."
"Create spec 002 for [feature name]. Begin with Phase 1 requirements and run the Visualizer."
"Run the agent panel gate for the requirements phase of spec 001."
"Run the Visualizer for the design phase of spec 001."
"I've answered the clarifications in avsdd/clarifications.md. Update assumptions and continue."
"Check the traceability matrix and show me which success criteria have gaps."
| Symbol | Meaning |
|---|---|
| PASS | All 5 agents passed — proceed to next phase |
| FAIL | Return to rework — address specific failures |
| CONDITIONAL | 1-2 conditions to resolve — max 2 attempts before auto-FAIL |
| Persona | Name | Primary Lens |
|---|---|---|
| PM | Alex | Value delivery vs. North Star + traceability |
| Architect | Vera | Technical soundness, scalability, intent drift |
| QA | Jordan | Testability and coverage |
| SEC | Morgan | Risk surface |
| CX | Casey | End-user experience and accessibility |
| File | Purpose | Modified When |
|---|---|---|
avsdd/north-star.md |
Business intent | Phase 0 only (locked) |
avsdd/traceability.md |
Artifact → SC links | Every gate |
avsdd/clarifications.md |
Async Q&A | Any phase |
spec/.current-spec |
Active spec ID | On spec change |
spec/{id}/panel-gates/ |
Gate verdicts | After each gate |
demos/{id}/verification.md |
Phase 5 North Star check | Phase 5 |
→ File a clarification request in avsdd/clarifications.md
→ Document the assumed answer and continue
→ Human resolves before Phase 4 begins
→ PM CONDITIONAL will surface this → Add missing requirements or prune orphaned artifacts → Rerun gate after matrix is clean
→ Auto-escalates to FAIL → Rework the phase with a different approach → PM or Architect may need to re-examine scope vs. North Star
cat avsdd/north-star.md # Reload intent
cat spec/.current-spec # Find active spec
cat spec/{id}/README.md # Check phase status
cat avsdd/clarifications.md # Check open questionsThe core discipline: every artifact must trace to the North Star. Every gate re-asks "are we still pointed at the right destination?"