Web project plan

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):

Q5 Answer	File generated
Claude Code	CLAUDE.md
Codex / Copilot / Gemini	AGENTS.md
Cursor	AGENTS.md + .cursorrules suggested
None / not sure	Present the options and recommend

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

Answer	Generated Document
A: DB needed	docs/references/DB.md
B: Auth needed	docs/references/AUTH.md
B-2: Roles needed	docs/references/AUTH.md — add RBAC section
C: Social/feed	docs/references/AUTH.md + docs/references/DB.md
D: Search — PostgreSQL FTS	docs/references/DB.md — add search strategy section
D: Search — external (Algolia, etc.)	docs/references/API.md — add Search section
E: Payments	docs/references/BILLING.md
F: AI features	docs/references/AI_SYSTEMS.md
G: External APIs	docs/references/API.md
H: Storage	docs/references/ARCHITECTURE.md — Storage section
I: Notifications	docs/references/ARCHITECTURE.md — Notifications section
J: Realtime	docs/references/ARCHITECTURE.md — Realtime section
K: i18n	docs/references/ARCHITECTURE.md — i18n section
Any of L~Q	docs/references/UI.md
P-1: Responsive	docs/references/UI.md — Breakpoints & layout changes section
N: SEO needed	docs/references/UI.md — SEO section
CI/CD needed	docs/references/ARCHITECTURE.md — CI/CD section
AI coding tool = Claude Code	CLAUDE.md + docs/references/prompts/
AI coding tool = other/none	AGENTS.md + docs/references/prompts/ (if AI features exist)

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.