Auto Webdev

Autonomous Web Development Protocol

An autonomous development loop inspired by Karpathy's Autoresearch. The human writes one file (requirements.md), then walks away. The agent scaffolds the project, implements features one by one, evaluates each against a build pipeline, keeps or reverts, and never stops until every feature is done or skipped.

When to use

Use when:

• User provides a website requirements document (or enough detail to generate one)
• The goal is end-to-end autonomous implementation — scaffold through deploy
• Multiple features need to be built sequentially with objective quality validation

Do NOT use when:

• Modifying a small feature in an existing project (just edit directly)
• Answering questions or giving advice (no build loop needed)
• The project has no build pipeline to validate against

Three-layer architecture

auto-webdev defines Layer 1 only. Layer 2 is resolved by composing sub-skills declared in requirements.md. Layer 3 comes from the LLM's training data.

The requirements.md specification

This is the human's only input — analogous to Autoresearch's program.md. Place it at the project root.

# Project Name

## Meta

| Key | Value |
|-----|-------|
| type | saas / landing / dashboard / e-commerce / blog / interactive / portfolio / docs |
| framework | next.js |
| styling | tailwind-v4 |
| design | dark-glass / apple-light / custom |
| deploy | railway / vercel / static / none |

## Capabilities

- [ ] realtime
- [ ] auth
- [ ] database
- [ ] email
- [ ] pdf
- [ ] 3d-webgl
- [ ] payment
- [ ] file-upload
- [ ] i18n

## Routes

| Route | Purpose | Access |
|-------|---------|--------|
| `/` | Landing page | public |
| `/dashboard` | Main dashboard | auth |
| `/admin` | Admin panel | admin |

## Data model

### User
- id: string (uuid)
- email: string
- name: string
- role: "user" | "admin"
- createdAt: Date

### Project
- id: string (uuid)
- title: string
- ownerId: string → User
- status: "draft" | "active" | "archived"

## Features

1. 用户注册与登录 — email/password auth with session management
2. Dashboard 概览 — stats cards, recent activity feed
3. 项目 CRUD — create, read, update, delete with form validation
4. 实时通知 — WebSocket push for project status changes
5. 数据导出 — export project list as CSV/PDF
6. 管理后台 — user management, system settings

## Constraints

- Mobile-first responsive design
- Lighthouse performance ≥ 90
- Support: Chrome, Safari, Firefox (latest 2 versions)
- Language: zh-CN primary, en fallback

Sections Data model and Constraints are optional. All others are required.

Capability → Skill mapping

Capabilities without a matching sub-skill are implemented using Layer 3 (LLM knowledge). No explicit skill file is needed — the agent applies standard patterns for auth, database, email, payment, etc.

The autonomous loop

Like Autoresearch, the agent enters a deterministic loop and never pauses to ask the user for confirmation. The user may be asleep. The build pipeline is the only judge.

Phase 0: Scaffold

1. Read and parse requirements.md — extract Meta, Capabilities, Routes, Features
2. Initialize project via the framework sub-skill (e.g. @nextjs-app-scaffold)
3. Install all dependencies declared by Capabilities
4. Apply design system via the design sub-skill (select variant from Meta)
5. Create directory skeleton: routes, components, lib, types
6. Generate type definitions from Data model section
7. git init && git add -A && git commit -m "scaffold: initial project structure"
8. Gate: tsc --noEmit && next build must pass
9. Log to progress.tsv

Phase 1: Feature loop

The core cycle — analogous to Autoresearch's LOOP FOREVER.

FOR each feature in requirements.md → Features (priority order):

  1. ANALYZE
     - What does this feature depend on?
     - If a dependency was crashed/skipped and not yet recovered → mark DEFERRED, skip
     - Identify files to create/modify

  2. PLAN
     - List every file that will be touched
     - If feature is too large for one commit, break into sub-steps internally
       (but still commit as one unit)

  3. IMPLEMENT
     - Write the code

  4. EVALUATE
     - Run: tsc --noEmit && next build
     - IF pass → git add -A && git commit -m "feat: <feature-name>"
                 → log status=keep in progress.tsv
     - IF fail → attempt fix (up to 3 retries)
     - IF 3 retries exhausted → git checkout .
                                 → log status=crash in progress.tsv
                                 → SKIP this feature

  5. NEXT feature

NEVER STOP until all features are attempted (keep / crash / skip / deferred).

Critical rule: Do not ask the user whether to continue. Do not pause between features. The loop runs to completion autonomously.

Phase 2: Integration

After all features are attempted:

1. Route reachability — verify every declared route renders without error
2. Cross-feature wiring — navigation links, shared state, data flow between features
3. Retry deferred/crashed features — dependencies may now be satisfied
4. git add -A && git commit -m "integration: cross-feature wiring"
5. Log to progress.tsv

Phase 3: Polish

1. Responsive check (if Constraints specify mobile-first)
2. Accessibility baseline — keyboard navigation, aria labels, focus management
3. Performance — dynamic imports, image optimization, code splitting
4. git add -A && git commit -m "polish: responsive + a11y + perf"
5. Log to progress.tsv

Phase 4: Deploy

1. Compose deployment config via the deploy sub-skill (e.g. @railway-docker-deploy)
2. Generate Dockerfile, .dockerignore, .railwayignore (or platform equivalent)
3. Gate: docker build . must pass (if applicable)
4. git add -A && git commit -m "deploy: containerization ready"
5. Log to progress.tsv
6. Print final progress summary

Quality gates

Analogous to Autoresearch's val_bpb — an objective, automated metric that decides keep vs. revert.

The first two gates are hard gates — equivalent to val_bpb in Autoresearch. Every feature must pass both before it can be committed. Failure after 3 retries triggers a full revert (git checkout .).

progress.tsv format

Analogous to Autoresearch's results.tsv. Tab-separated values at the project root.

phase	feature	commit	status	description
scaffold	-	a1b2c3d	pass	initial project structure
feature	用户注册	b2c3d4e	keep	email/password auth with JWT
feature	Dashboard	c3d4e5f	keep	stats cards + recent activity
feature	项目CRUD	d4e5f6g	crash	circular dependency after 3 retries
feature	实时通知	-	deferred	depends on crashed 项目CRUD
feature	数据导出	e5f6g7h	keep	CSV + PDF export
feature	管理后台	f6g7h8i	keep	user management + settings
feature	项目CRUD	g7h8i9j	keep	retry in integration phase - fixed
feature	实时通知	h8i9j0k	keep	retry in integration phase - dependency resolved
integration	-	i9j0k1l	pass	navigation wiring + retried crashed features
polish	-	j0k1l2m	pass	responsive + a11y + dynamic imports
deploy	-	k1l2m3n	pass	Dockerfile + entrypoint ready

Valid status values: pass | keep | discard | crash | deferred | skip

Autoresearch comparison

Feature decomposition guide

Each feature in requirements.md should map to one commit. Guidelines for decomposition:

• Atomic: A feature either fully passes quality gates or is fully reverted. No partial commits.
• Self-contained: Ideally, each feature adds value independently. Avoid features that are meaningless without another.
• Right-sized: If a feature requires more than ~10 files, consider splitting it in requirements.md. Within the loop, the agent may internally break implementation into sub-steps but still commits as one unit.
• Dependency-ordered: If feature B depends on feature A, list A first. The agent respects this ordering and defers features whose dependencies are unsatisfied.

When analyzing a feature, the agent should identify:

1. New files to create (pages, components, lib modules)
2. Existing files to modify (layout, navigation, types, data)
3. New dependencies to install (npm install ...)
4. Type definitions to add or extend

Error handling

The agent never stops on error. Every error has a resolution path that keeps the loop moving forward.

Checklist

• requirements.md read and parsed — Meta, Capabilities, Routes, Features extracted
• Project scaffolded via framework sub-skill, initial build passes
• All Features attempted — each is keep / crash / skip / deferred
• Integration phase — all routes reachable, deferred features retried
• Polish phase — responsive + a11y + performance
• Deploy phase — deployment config generated, docker build passes
• progress.tsv records every phase and feature outcome
• Git log is clean — one commit per feature, descriptive messages