Web Project Plan

Skill that concretizes a new web project through an interview and generates project files.

Audience: Developers. Use technical terms directly. Scope: Web projects only. Goal: By end of session, agent context file + required docs/ structure exist as real files.

Which context file to generate depends on the user's AI tool (see Phase 4-3): CLAUDE.md for Claude Code, AGENTS.md for Codex/Copilot/Gemini, etc.

Directory Structure

README.md
AGENTS.md or CLAUDE.md # Agent context file (see Phase 4-3 for which one)
docs/
  INDEX.md             # Document map
  QUICK_REF.md         # Commands & env vars cheatsheet
  ROADMAP.md           # MVP scope + backlog
  references/          # Tech references (generated by this skill)
    UI.md
    AUTH.md
    DB.md
    ...

Session Flow

Phase 1 — Project Identity

1. Project name / working title?

>

2. One-line description? (What it does, for whom, what problem it solves)

>

3. Primary users? → Personal tool / Public product / Internal tool

>

4. Web project type? → SPA / SSR (SEO matters) / SSG (static content) / Not sure yet

>

5. Existing stack or boilerplate?

>

6. Package manager? → pnpm / npm / yarn / bun / Not sure yet

Phase 2 — Feature Scoping

Only present questions relevant to Phase 1 answers.

[Data Persistence]

A. Need a database?
   → Yes — What data?
   → No

[Auth & Permissions]

B. Login / accounts?
   → Yes → Social / Email / Both
   → No

   (If Yes) B-1. User data visibility?
   → Private / Partially public / Fully public

   (If Yes) B-2. Role separation?
   → None (single user type)
   → Yes → Which roles? (admin / user / guest, etc.)

[Social / Sharing]

C. Can users view other users' content? (feed, board, etc.)
   → Yes / No

[Search]

D. Search feature?
   → No
   → Yes → What data to search?
            Real-time suggestions needed? (Yes / No)
            Data scale? (Small → PostgreSQL FTS / Large → Algolia · Meilisearch)

[Payments]

E. Payments?
   → No / one-time / subscription / per-feature

[AI]

F. AI features needed?
   → Yes → What kind? (generation / analysis / recommendations / summarization)
            Streaming responses needed? (Yes / No)
   → No

[External APIs]

G. External service integrations?
   → Yes → Which ones?
   → No

[Files / Media]

H. File upload / storage needed?
   → Yes → What files? (images / documents / video)
            Per-user private or public?
   → No

[Notifications]

I. Notifications? (push / email / SMS)
   → Yes → What triggers?
   → No

[Realtime]

J. Real-time sync or collaboration needed?
   → Yes / No

[i18n]

K. Multi-language support?
   → No
   → Yes → How many languages? / From v1 or later?

Phase 3 — Design & UI

Only present relevant questions.

[References & Assets] — Always ask

L. Design reference? (Figma / reference site / none)

M. Brand assets? (colors, logo, fonts) → Yes / No

[Rendering & SEO] — Always ask if Public product

N. SEO requirements?
   → None
   → OG tags + sitemap level
   → Content SEO — search visibility matters (SSR/SSG strategy needed)

[Theme] — Always ask

O. Dark mode support?
   → Yes / No

[Screen Structure] — Always ask

P. Number of screens?
   → ~3 / 4~10 / 10+

   Reusable components? → Yes / No

P-1. Layout approach?
   → Responsive (mobile-first)
   → Fixed width (dashboard, admin, etc.)
   → Both

   (If responsive) P-2. Primary usage context?
   → Mobile-first / Desktop-first / Equal

   (If responsive) P-3. Layout changes at breakpoints?
   □ Navigation (e.g., desktop sidebar → mobile bottom tab bar or hamburger)
   □ Grid/card layout (e.g., 3 cols → 1 col)
   □ Table → card-based restructure
   □ Form layout changes
   □ No changes (scale only)

   (If responsive) P-4. Touch interactions needed?
   → Yes (swipe, tap target sizing, etc.) / No

[Interactions] — Always ask

Q. Interaction requirements?
   □ Drag and drop
   □ Animations / transitions
   □ Charts / data visualization
   □ None

Phase 4 — Stack & MVP Scope

#### 4-1. Stack Proposal

Propose stack based on Phase 1–3 answers. If existing stack provided, align with it. Only add rows relevant to feature answers.

Framework selection guide (based on Phase 1 answers):

• SSR/SSG needed + React → Next.js 15 (App Router)
• SSR/SSG needed + Vue → Nuxt 3
• SPA + React → Vite + React
• SPA + Vue → Vite + Vue
• Static content focused → Astro
• Not sure → Default to Next.js 15 (most versatile)

## Proposed Stack

| Area          | Choice                      | Why  |
|---------------|-----------------------------|------|
| Pkg Manager   | pnpm                        | ...  | ← Phase 1-6 answer
| Frontend      | Next.js 15 (App Router)     | ...  | ← guide above
| Styling       | Tailwind v4 + shadcn/ui     | ...  |
| Auth          | Supabase Auth               | ...  | ← if B = Yes
| DB            | Supabase (PostgreSQL)       | ...  | ← if A = Yes
| ORM           | Drizzle ORM                 | ...  | ← if A = Yes
| Search        | PG FTS / Algolia            | ...  | ← if D = Yes
| AI            | Anthropic / OpenAI          | ...  | ← if F = Yes
| Storage       | Supabase Storage / S3       | ...  | ← if H = Yes
| Notifications | Resend / FCM                | ...  | ← if I = Yes
| Payments      | Stripe / Toss Payments      | ...  | ← if E = Yes
| i18n          | next-intl                   | ...  | ← if K = Yes
| Testing       | Vitest + Playwright         | ...  | always
| Deploy        | Vercel                      | ...  |

"Anything you'd like to change?" — Confirm or revise, then finalize stack.

#### 4-2. MVP Scope Cut

Show the full feature list from Phase 2–3:

"Separate into must-have for v1 vs. can-wait for later. If unsure, I'll propose."

• v1 (Must) → docs/ROADMAP.md confirmed section
• v2+ (Later) → docs/ROADMAP.md backlog section

#### 4-3. Deploy & Dev Environment

1. Deploy platform? (Vercel / Railway / AWS / other)
2. CI/CD pipeline? (GitHub Actions / other / none)
3. Testing strategy?
   → Unit only / Unit + E2E / none
   → E2E tool: Playwright / Cypress
4. Monorepo vs single repo?
5. AI coding tool? (Claude Code / Codex / Cursor / Copilot / Gemini / none)

Agent context file generation (based on Q5 answer):

Content is the same regardless of filename — only the filename changes to match what each agent reads. Write the file following references/AGENTS_MD_GUIDE.md.

>

If the user doesn't specify an AI tool, or says "not sure": Present a short recommendation like this:

>

"Which AI coding tool will you use? This decides the context filename: - Claude Code → CLAUDE.md - Codex / Copilot / Gemini → AGENTS.md - Not sure / multiple → I'll generate AGENTS.md (most widely supported) - None → I'll still generate AGENTS.md — useful if you adopt one later"

>

Then proceed with their choice. Don't silently pick one.

Internal Mapping Table

Always generated: README.md, agent context file (per Phase 4-3), docs/INDEX.md, docs/QUICK_REF.md, docs/ROADMAP.md, docs/references/README.md

Document Writing Rules

All generated docs/references/*.md follow this section order:

## Purpose
## Current State
## Current Rules
## [Topic-specific core sections]
## Related Docs

File naming:

• Reference docs: uppercase topic — AUTH.md, DB.md, UI.md
• Session records: date-based — SESSION-SUMMARY-2026-04-06.md
• Filenames in English, body text in user's language

Agent context file principles

When writing CLAUDE.md / AGENTS.md, apply these principles (adapted from Karpathy's coding guidelines):

1. Surface, don't assume — include only what the agent would get wrong without knowing. Skip generic advice ("write clean code"). Prefer concrete prohibitions ("Never modify src/components/ui/").
2. Minimum content — respect Length Guidelines in references/AGENTS_MD_GUIDE.md (Simple 30-50 / Standard 60-100 / Complex 100-150). When over budget, delegate details to docs/references/*.md and link.
3. Trace every line to a Phase 1-3 answer — no speculative future-proofing, no sections for features the user didn't request. If a line can't point back to an interview answer, cut it.
4. Verifiable, not aspirational — Commands must actually run. "Do Not" rules must be checkable. Replace "follow best practices" with "Server components by default, 'use client' only when needed".

#### Required block in generated file

Append this section verbatim at the end of the generated CLAUDE.md / AGENTS.md. Counts toward length budget (~7 lines):

## Coding Principles
- Surface assumptions; ask when unclear, don't pick silently.
- Minimum code only — no speculative features, abstractions, or "flexibility" that wasn't requested.
- Surgical changes — every changed line must trace to the request; don't refactor unrelated code.
- Define verifiable success before coding (test, command, or expected output).
- For multi-step tasks, state a brief plan with verify steps before executing.

Final Output

## Document Structure

[Always generated]
README.md
CLAUDE.md or AGENTS.md   ← depends on AI tool (Phase 4-3)
docs/
  INDEX.md
  QUICK_REF.md
  ROADMAP.md
  references/
    README.md

[Added for this project]
docs/references/AUTH.md         ← Login + RBAC
docs/references/DB.md           ← Data persistence + search strategy
docs/references/BILLING.md      ← Subscription payments
docs/references/AI_SYSTEMS.md   ← AI features
docs/references/UI.md           ← Screen specs + dark mode + SEO
docs/references/ARCHITECTURE.md ← Storage, notifications, realtime, i18n, CI/CD

[Omitted]
docs/references/API.md ... (one-line reason each)

Generate files with this structure?

If YES, generate in this order:

1. Agent context file — Read references/AGENTS_MD_GUIDE.md, then write CLAUDE.md or AGENTS.md per Phase 4-3, applying the "Agent context file principles" in Document Writing Rules.
2. README.md — Project overview + confirmed stack + local run instructions
3. docs/INDEX.md — Links to all active docs + one-line descriptions
4. docs/ROADMAP.md — Based on MVP scope cut results
5. Remaining docs/references/*.md — Follow section template above

Tone

Direct, technical conversational style. Present phase by phase, one at a time. Respond in the user's language.