# Auto Webdev

> Autonomous website development protocol inspired by Karpathy's Autoresearch. Given a requirements.md, the agent scaffolds, implements features one by one, evaluates via build pipeline (tsc + lint + build), keeps or reverts, and tracks progress — fully autonomously until all features are done. Use when the user provides a website requirements document and wants autonomous end-to-end implementation without step-by-step guidance.

- Skill: `ph13917403910/auto-webdev` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ph13917403910/auto-webdev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ph13917403910/auto-webdev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: PH13917403910 (https://skillmd.com/u/ph13917403910)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ph13917403910/auto-webdev

---


# Autonomous Web Development Protocol

An autonomous development loop inspired by [Karpathy's Autoresearch](https://github.com/karpathy/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

| Layer | Name | Scope | Mutability |
|-------|------|-------|------------|
| 1 | **Protocol** (this skill) | requirements.md spec, autonomous loop, quality gates, progress tracking, rollback rules | Stable — rarely changes |
| 2 | **Capabilities** (sub-skills) | Scaffolding, design systems, realtime, auth, deploy, etc. | Extensible — composed per project |
| 3 | **Domain Knowledge** (LLM) | SaaS patterns, e-commerce flows, dashboards, landing pages, content sites | Implicit — no explicit encoding needed |

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.

```markdown
# 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

| requirements.md declaration | Sub-skill | Notes |
|-----------------------------|-----------|-------|
| framework: next.js | `@nextjs-app-scaffold` | Project init, directory structure, custom server |
| design: dark-glass | `@dark-glass-ui` (Variant A) | Dark glassmorphism tokens + components |
| design: apple-light | `@dark-glass-ui` (Variant B) | Light variant — swap color tokens |
| capability: realtime | `@realtime-state-sync` | Socket.io three-layer architecture |
| deploy: railway | `@railway-docker-deploy` | Multi-stage Dockerfile + Railway CLI |
| type: interactive | `@interactive-workshop-site` | Stage-driven FSM patterns |

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.

| Gate | When | Pass condition | On failure |
|------|------|----------------|------------|
| `tsc --noEmit` | After every feature | 0 type errors | Fix (≤3 retries), then revert |
| `next build` | After every feature | exit 0 | Fix (≤3 retries), then revert |
| Route reachability | Phase 2 | All declared routes render | Fix wiring |
| Lighthouse perf | Phase 3 (if constraint) | Score ≥ declared threshold | Optimize |
| `docker build` | Phase 4 (if applicable) | exit 0 | Fix Dockerfile |

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

| Aspect | Autoresearch | auto-webdev |
|--------|-------------|-------------|
| Human input | `program.md` | `requirements.md` |
| Editable scope | Single file (`train.py`) | Per-feature multi-file scope |
| Evaluation metric | `val_bpb` (single number) | `tsc` + `build` (binary pass/fail) |
| Iteration unit | One experiment (~5 min) | One feature |
| Keep condition | `val_bpb` decreased | All quality gates pass |
| Revert mechanism | `git reset` | `git checkout .` |
| Progress log | `results.tsv` | `progress.tsv` |
| Stop condition | Never (manual interrupt) | All features done |
| Composition | None (single domain) | Dynamic sub-skill composition |

## 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

| Scenario | Action |
|----------|--------|
| Build failure (tsc or next build) | Parse error output → fix → re-evaluate (≤3 retries) |
| 3 retries exhausted | `git checkout .` → log `crash` → continue to next feature |
| Runtime error (doesn't break build) | Defer to Phase 2 (Integration) |
| Dependency feature crashed/skipped | Mark current feature `deferred` → retry in Phase 2 |
| npm install failure | Retry with `--legacy-peer-deps`, or find alternative package |
| Sub-skill not found | Fall back to Layer 3 (LLM knowledge) |

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