webdev-agent-kit

---

Table of Contents

• Table of Contents
• Who This Kit Is For
• What Changes After Installation
• Supported Clients
• Quick Start
• Adapting the Kit to a Project
• Smart Context Cache and Token Savings
• Verifying the Installation
• Practical Scenarios
  • A Small CSS Change
  • Fixing a Frontend Bug
  • Building an Interface from Screenshots
• Core Skills
• Architecture
• Project Validation
• Contributing
• License

Who This Kit Is For

WebDev Agent Kit is an open-source set of local rules. You continue using your usual Codex, Claude Code, or Cursor client while connecting it to a shared standard for working with projects.

WebDev Agent Kit is intended for frontend developers and teams that use AI coding agents in React and Next.js projects and want to:

• preserve the existing architecture and local conventions;
• keep small tasks small;
• avoid broad rewrites and unapproved dependencies;
• receive verification proportional to the change;
• use the same baseline rules across different coding agents;
• see actual results and blockers instead of confident assumptions.

The stack profile supports React, Next.js, TypeScript, and CSS Modules, Redux, TanStack, and Axios when they are already used in the project. General planning, review, visual verification, and tooling workflows can apply more broadly, but the kit does not transfer React rules to another stack by analogy.

What Changes After Installation

The agent receives a local decision-making system that:

• classifies the task and selects the minimum necessary workflow;
• reads only the context needed for the next safe action;
• prefers facts from source files, configuration, and CI over general recommendations;
• asks for permission before installing packages, changing infrastructure, or taking other actions outside the task;
• performs the minimum meaningful verification of the changed area;
• separates related failures from existing ones and reports unavailable checks honestly.

The kit does not guarantee error-free model behavior. It makes expected behavior, boundaries, and result verification explicit and testable.

Supported Clients

Download the package for your client from the latest GitHub Release:

Client	Contract	Download
Codex	Project bundle	Codex bundle
Claude Code	Native plugin via local marketplace	Claude Code bundle
Cursor	Project bundle + native rule	Cursor bundle
VS Code — Codex	Codex contract alias	VS Code Codex bundle
VS Code — Claude	Claude Code contract alias	VS Code Claude bundle

The same release includes a checksum for each archive in SHA256SUMS. The stable and versioned names for the same target contain identical bytes.

Quick Start

Installation instructions are available for all supported clients:

• Codex
• Claude Code
• Cursor
• VS Code Codex
• VS Code Claude Code

Video guides are available only for:

• Cursor — text and video guide
• VS Code Codex — text and video guide

All materials are collected in the documentation index. The installation guide index and MCP guide are also available separately.

Adapting the Kit to a Project

For Codex and Cursor targets, after installation open the project root in the coding agent and send this request once:

Adapt this .agents kit to my project and create AGENTS.md in the root

Claude Code targets use the native plugin installed through the local marketplace; the .agents adaptation flow in this section applies only to Codex and Cursor.

The onboarding process detects the active client, project structure, framework, routes, styling system, verification commands, and available tool capabilities. It then creates or updates the local .agents/project/** profiles and path indexes for the detected stack, architecture, styles, verification, design references, client, and tool capabilities.

React and Next.js projects receive stack-specific path indexes. Other frontend stacks receive a bounded profile that records the detected boundary and keeps only applicable framework-neutral workflows.

Onboarding keeps the native instruction pointer small and does not overwrite existing project instructions without permission. It does not create application source files or automatically install packages, MCP servers, frameworks, or other tools.

For the best adaptation result:

1. Add the repository-aware prompt from the custom instructions to the personal or user instructions of your coding client. Keep local project instructions enabled: the user prompt supplements them and requires the agent to discover and follow the repository's own rules.
2. Ask the agent to inspect tool capabilities in the current session and confirm recommended MCP servers or equivalent native tools. Configuration alone does not prove that a server is available: the capability must be callable or previously verified for the project.

Recommended integrations depend on the project and active task:

Capability	Recommended provider	When it is useful
Current framework and library documentation	Context7 MCP	Questions about React, Next.js, TypeScript, packages, CLIs, and build tools
Visual evidence from the rendered interface	Browser or Playwright MCP	Opening a local application, checking responsive states, and capturing screenshots
Next.js runtime diagnostics	Next DevTools MCP	Only for compatible Next.js projects

The kit continues to work without MCP servers. Native file tools and targeted shell commands support onboarding, planning, source changes, code review, and existing lint, typecheck, build, or test commands. Official web documentation can replace documentation MCPs. Without a callable browser provider, rendered visual QA, viewport checks, and screenshot evidence are unavailable; the agent can perform only source review and must report lower confidence. Without Next DevTools MCP, Next.js runtime verification is unavailable, but normal source and project-command work remains possible. Missing optional tools should be reported honestly and skipped or replaced with a fallback, not installed automatically.

Detailed instructions for recommended MCPs and verification prompts are in the MCP guide.

Smart Context Cache and Token Savings

The context cache is a set of verified project profiles and path indexes, not a build cache or model-response cache. Onboarding creates the initial context, and subsequent tasks consult the relevant overlays before searching the repository broadly. The agent receives direct paths to known routes, components, styles, patterns, verification commands, and tool capabilities.

When project facts change, the context workflow updates only the affected profiles and indexes. For example, after changing routes, components, styles, verification commands, documentation variants, or tool capabilities, use:

Update the project context after this layout change.

Token use is reduced by selecting the minimum necessary workflow, starting from cached paths, searching narrowly, loading only the relevant skill and required references, and stopping after enough evidence is available for the next safe action. Reports remain evidence-based and omit irrelevant logs, repeated output, and process narration while preserving commands, errors, check results, risks, and blockers.

For long-running or resumable work, compact summaries preserve the goal, constraints, acceptance criteria, decisions, affected files and checks, results, blockers, and the exact next step. Optional loop memory organizes persistent progress as Tried, Verified, and Open, so another session can continue without reconstructing the context again.

Cached facts remain local and never override current source files, configuration, CI, or actual verification results. Stale facts must be updated. The kit does not promise a fixed token-savings percentage; it reduces waste by avoiding unnecessary context and repeated repository scans.

Economical GPT Subagents And Review Handoffs

Full Codex onboarding configures missing project-local roles for bounded lookup, implementation, complex reasoning and independent review. Models and reasoning efforts come from the actual client catalog, not hardcoded production IDs. Version 1.1.0 also previews and applies a narrow supported native subagent activation field when needed. The primary model, global configuration, MCP, trust and security settings remain unchanged.

No separate setup command or second confirmation is needed. Existing working bindings remain unchanged; facts-only/no-model-change requests and Plan Mode exclude model setup and canaries. A written TOML is only configured: refresh the client and verify the actual child model, effort and permissions. Missing runtime evidence retains the ordinary single-agent workflow. Named-role and direct model/effort dispatch are verified separately for the actual client surface. See the GPT routing guide for commands and diagnosis.

For justified delegated work, compact task packets preserve criteria, interfaces, owned files and retry budgets. Exact review packages cover all task commits or an explicitly scoped working-tree snapshot; repeat review focuses on fixes and their consequences. These artifacts stay local and do not burden small edits. The design notes explain what was adapted from Superpowers and which heavier workflows were deliberately excluded.

Verifying the Installation

Use this read-only smoke prompt:

Verify the WebDev Agent Kit installation.
Do not change source code.
Show the detected client, stack, available capabilities,
local rules, and unavailable checks.

The response should contain facts about the detected target, confirmed stack, available tool capabilities, local overlays, and verification limits. A missing