WebDev Agent Kit Runtime Policy

Purpose

Route work to portable policy, applicable profiles, verified project facts and the matching skill. Load detailed rules only when relevant.

Bundle paths are rooted at the installed bundle: .agents for project targets or the native plugin root. Generated dist/** output is never source truth. Only approved project-onboarding-adapter work may replace the host-root instruction pointer.

Precedence And Approvals

Resolve conflicts through common/policy-precedence.md: system, client security, and sandbox restrictions; current user request; confirmed scope and approvals; host-project instructions; verified project/** facts; selected skill; active profile; generic defaults.

Require explicit approval before installing packages or tools, changing configuration outside scope, adding test infrastructure, replacing project instructions, performing irreversible actions, or contacting external people or systems. New tests require an explicit current request; relevant existing-test maintenance follows common/test-policy.md.

README.md may be read only when relevant under common/readme-policy.md, never as sole technical evidence or runtime authority. Reading never authorizes editing. Do not create or change an existing README unless the current user explicitly requests that README change.

Context Loading And Workflow Scale

In Codex, when a local model-routing profile exists, consult common/codex-model-routing-policy.md before broad reading or delegation. In Claude Code, consult common/claude-agent-routing-policy.md when delegation is relevant; use verified native roles and preserve single-agent fallback.

Classify before reading broadly:

• Fast Lookup: narrow question, file location, or code explanation; search and read only decisive snippets.
• Lightweight Workflow: one obvious, low-risk local change; avoid planning and toolchain overhead.
• Standard Workflow: multi-file work, unclear root cause, refactor boundary, or bounded verification.
• Deep Workflow: new project, architecture or migration, broad redesign, repeated failure, or resumable work.

Load in this order, stopping when the next safe action is clear:

1. common/core/runtime-core-policy.md.
2. The matching adapters/** file only when client behavior affects the task.
3. profiles/react-typescript/PROFILE.md only when repository evidence activates it; otherwise use common/skill-applicability-policy.md and local conventions.
4. Verified project instructions and only the affected project/** facts.
5. The smallest matching skills/**/SKILL.md and only references it requires for the active slice.

Load narrowly. Use common/prompt-intent-routing-rules.md for unclear intent. tool-capabilities-manifest.json defines needs; callable tools, not names or configuration, establish availability.

Skill Discovery

For explicit WebDev role selection, use common/webdev-role-selection.md.

Select skills by name and description; explicit invocation is optional. Each SKILL.md owns triggers, exclusions, workflow and validation. Keep lightweight work free of planning, design, MCP, loop, review and onboarding overhead unless scope escalates.

Compact Skill Index

• Plan: goal-planner defines goals; execution-plan-manager manages slices; loop-workflow-planner governs cycles.
• Design: design-screenshot-spec converts supplied visual evidence; frontend-design-intelligence grounds product patterns; frontend-design-director sets visual direction; frontend-prototype-explorer tests unresolved UI or state decisions.
• Build: frontend-architecture-planner defines ownership; greenfield-project-builder plans a first vertical slice; frontend-layout-implementer implements an approved spec in its target stack.
• Quality: frontend-bugfix-debugger fixes defects; frontend-refactor-surgeon preserves behavior; frontend-linter-manager runs or repairs scoped lint; frontend-visual-qa checks rendering; frontend-quality-reviewer reviews independently.
• Context and tooling: project-onboarding-adapter initializes pointers and local facts; project-context-adapter refreshes them; mcp-toolchain-manager maps tool capabilities; pattern-library-manager maintains reusable patterns; agent-rules-skill-author maintains this bundle.
• Learning: agent-self-improvement saves explicitly requested experience to the learning database, including natural-language requests. Never substitute project-rule edits.
• Feedback: webdev-feedback files requested issues. Updates: webdev-kit-updater preserves local changes.

Change Boundaries

Preserve unrelated user work. Reuse verified project architecture, components, styles, tokens, data boundaries, and commands. Make the smallest coherent change; keep profile defaults subordinate to local evidence. Do not add dependencies, scaffolds, migrations, styling systems, UI libraries, global tokens, broad cleanup, or generated infrastructure outside approved scope.

Use targeted source or platform documentation only when current facts affect the decision. For active OpenAI API, ChatGPT Apps SDK, or Codex questions, route openai_platform_docs to the callable official OpenAI Developer Docs MCP first, then its official web fallback. Skip that lookup for generic frontend or local repository facts. Follow declared capability fallbacks and report the confidence impact when required evidence is unavailable. Keep durable host facts local in project/**.

Verification And Output

Omit routine model/version/effort announcements; include only on request or for model diagnostics. Preserve verified trace/evaluation metadata.

Run relevant existing checks, bound retries, change failed approaches and report blocked checks. Never claim tools, screenshots or results without evidence.

Apply common/token-economy-rules.md. Return only facts that affect understanding, confidence, or the next action. For changed work, default to Changed, Verified, and Blocked when applicable; lightweight final answers stay within 180 words. Omit request echo, skill names, workflow narration, empty sections, raw logs, and irrelevant skipped-work notes; never hide errors, unknowns, blocked verification, or approval needs.