heymegabyte/agent-skills / 07-quality-and-verification
quality-and-verification
Unverified5-level verification pyramid: static→unit→Playwright E2E (homepage-first, 6bp)→AI visual→post-deploy. 8-check quality gate. Multi-agent testing (functional/security/a11y/performance). Playwright v1.56+ AI agents (Planner/Generator/Healer, v1.63 current). WCAG 2.2 AA via axe-core v4.13. Percy+Chromatic visual regression. ADA Title II 2027/2028 deadlines.
spec-driven-development.md
View on GitHub---
name: "spec-driven-development"
description: "Spec-first autonomous development loop. Every feature starts with acceptance criteria that become tests. Progress persists across context compaction. AI cannot stop until all criteria pass on production."
updated: "2026-04-23"
---
# Spec-Driven Development
## The Problem
AI builds the happy path and stops. Features ship incomplete. Recommendations get listed but not implemented.
## The Fix: Spec → Test → Build → Verify Loop
### Phase 1: Generate Spec (BEFORE any code)
For every feature/project, generate `SPEC.md`:
```markdown
# Feature: [name]
## Acceptance Criteria
- [ ] AC1: [specific, testable criterion]
- [ ] AC2: ...
- [ ] ACN: ...
## E2E Tests (auto-generated from criteria)
- test_ac1.spec.ts: [what it verifies]
- test_ac2.spec.ts: ...
## Pages Affected
- /path1: [what changes]
## Recommendations Queue
- [ ] R1: [improvement discovered during build]
- [ ] R2: ...
```
Each acceptance criterion MUST be:
- Observable on production (not just in code)
- Testable via Playwright against `PROD_URL`
- Completable in under 1 minute of test execution
### Phase 2: Write Failing Tests FIRST
For every acceptance criterion, write the Playwright test BEFORE implementing. Test must fail (red). Then implement until it passes (green). Then refactor.
```typescript
// test_ac1.spec.ts — written BEFORE implementation
test('AC1: donation form accepts Stripe payment', async ({ page }) => {
await page.goto(`${PROD_URL}/donate`);
await page.fill('[data-testid="amount"]', '25');
await page.click('[data-testid="donate-button"]');
await expect(page.locator('[data-testid="success-message"]')).toBeVisible();
});
```
### Phase 3: Build in Slices
- Each acceptance criterion = one vertical slice
- Implement → deploy → run that test → pass → next criterion
- Never implement AC2 before AC1's test passes on production
### Phase 4: Recommendations Loop
- After all ACs pass, ask: "What else can I improve?"
- Every recommendation → new AC → new test → implement → verify
- Loop until zero recommendations
### Phase 5: Progress Persistence
Write progress to `progress.md` in project root:
```markdown
# Progress
## Completed
- [x] AC1: donation form (test: PASS, deployed: 2026-04-20)
- [x] AC2: email receipt (test: PASS, deployed: 2026-04-20)
## In Progress
- [ ] AC3: mobile responsive (test: FAIL, blocking: viewport overflow at 375px)
## Recommendations Queue
- [ ] R1: add loading skeleton during Stripe checkout
## Blocked
- (none)
```
This file survives context compaction. Any new session reads it and picks up where the last left off.
## The Ralph Loop (Autonomous Execution)
For full-app builds, use the autonomous loop:
1. Generate `feature-requirements.md` with ALL features as acceptance criteria
2. Generate `progress.md` (all unchecked)
3. Loop:
- Read `progress.md` → find next unchecked AC
- Write failing test for that AC
- Implement until test passes on production
- Screenshot → GPT Image 2 vision critique → fix if needed
- Mark AC complete in `progress.md`
- Git commit with AC reference
- If context getting full → save progress → spawn fresh agent to continue
- Repeat until all ACs checked
4. Run recommendations loop (skill 14)
5. **Done when** — all ACs pass + all recommendations implemented or rejected + GPT Image 2 vision says zero issues
## Context Exhaustion Prevention
When context exceeds 60%:
1. Save current progress to `progress.md`
2. Commit all work
3. Spawn a new agent with: "Read progress.md and SPEC.md. Continue from where the last agent left off. Implement the next unchecked acceptance criterion."
This gives infinite effective context — each agent gets a fresh window but continues the same spec.
## Test Organization
```
tests/
├── e2e/
│ ├── homepage.spec.ts (~1 min, runs first always)
│ ├── navigation.spec.ts (~1 min)
│ ├── contact-form.spec.ts (~1 min)
│ ├── donation-flow.spec.ts (~1 min)
│ ├── auth-flow.spec.ts (~1 min)
│ ├── search.spec.ts (~1 min)
│ └── visual-regression.spec.ts (~1 min, screenshots + GPT Image 2 vision)
├── unit/
│ └── (vitest files)
└── playwright.config.ts
```
- Each E2E file: ~1 minute, tests one feature, runs against `PROD_URL`, parallel-safe
- Total test suite: should complete in under 5 minutes with parallelization
## Stagehand Integration
- Use raw Playwright for predictable elements (`data-testid`, role, text)
- Use Stagehand `act()/extract()/observe()` for:
- Dynamic content that changes between deploys
- Natural language assertions ("verify the page looks professional")
- Complex multi-step flows where selectors are fragile
```typescript
import { Stagehand } from '@browserbasehq/stagehand';
// Prefer raw Playwright
await page.click('[data-testid="submit"]');
// Fallback to Stagehand for dynamic content
const stagehand = new Stagehand({ page });
await stagehand.act('click the primary call-to-action button');
const price = await stagehand.extract('the displayed price');
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |