project-research

name	project-research
description	Use when starting a new project, kicking off a codebase, or when the user needs to define project scope, tech stack, design language, and coding standards before writing code. Gathers requirements through structured interviews, researches documentation and best practices, and produces CLAUDE.md and PLAN.md.

Project Research

Overview

Structured project kickoff that gathers everything an AI agent needs before writing a single line of code. Conducts interviews one question at a time, researches documentation and best practices automatically, establishes guardrails to prevent code rot, and compiles CLAUDE.md + PLAN.md.

Do NOT write any code, scaffold any project, or invoke any implementation skill until all phases are complete and the user has approved the final CLAUDE.md and PLAN.md. No exceptions.

Progressive Saving (Crash Protection)

After EVERY user answer, immediately update `PLAN.md.draft` (and `CLAUDE.md.draft` when relevant) with the new information. Do not wait until the end of a phase. Every single answer gets saved before asking the next question. This is not optional.

• Each draft file includes a header comment showing current phase and last question answered
• If PLAN.md.draft or CLAUDE.md.draft exists at session start, read it and ask the user if they want to resume
• On resume, skip answered questions and continue from where it left off
• Phase 9 (Compile) promotes drafts to final files after user approval, then deletes the drafts
• Most answers go to PLAN.md.draft. Only update CLAUDE.md.draft when the answer produces an actionable rule for ongoing development (code style rules, guardrails, architecture boundaries, commands, gotchas).

See output-templates.md for draft format details.

Checklist

You MUST create a task for each phase and complete them in order:

1. Project Vision Interview - understand what, why, who, scope, audit existing code if any
2. Tech Stack Discovery - identify technologies, auto-research docs + best practices
3. Data Model & Entity Design - core entities, relationships, data flow
4. User Flow + Stories Interview - validate plan against real user journeys and edge cases
5. Goals + Coding Style Interview - development preferences and standards
6. Design Language Interview - visual style, colors, typography, animations
7. Project Guardrails & AI Working Agreement - rules to keep the project clean over time
8. Holistic Review Interview - AI-driven questions about non-obvious gaps
9. Compile Outputs - generate/merge CLAUDE.md and PLAN.md, get user approval

Process Flow

digraph project_research {
    rankdir=TB;
    "Phase 1: Project Vision" [shape=box];
    "Phase 2: Tech Stack + Research" [shape=box];
    "Phase 3: Data Model" [shape=box];
    "Phase 4: User Flows" [shape=box];
    "Phase 5: Coding Style" [shape=box];
    "Phase 6: Design Language" [shape=box];
    "Phase 7: Guardrails" [shape=box];
    "Phase 8: Holistic Review" [shape=box];
    "Phase 9: Compile" [shape=box];
    "User approves?" [shape=diamond];
    "Done" [shape=doublecircle];

    "Phase 1: Project Vision" -> "Phase 2: Tech Stack + Research";
    "Phase 2: Tech Stack + Research" -> "Phase 3: Data Model";
    "Phase 3: Data Model" -> "Phase 4: User Flows";
    "Phase 4: User Flows" -> "Phase 5: Coding Style";
    "Phase 5: Coding Style" -> "Phase 6: Design Language";
    "Phase 6: Design Language" -> "Phase 7: Guardrails";
    "Phase 7: Guardrails" -> "Phase 8: Holistic Review";
    "Phase 8: Holistic Review" -> "Phase 9: Compile";
    "Phase 9: Compile" -> "User approves?";
    "User approves?" -> "Done" [label="yes"];
    "User approves?" -> "Phase 9: Compile" [label="no, revise"];
}

Interview Rules

• One question at a time - never batch multiple questions
• Always propose options - use AskUserQuestion with options for EVERY question, even open-ended ones — propose your best guesses as options to reduce mental burden (user can always pick "Other" for free text)
• Use multiSelect - when choices aren't mutually exclusive (e.g., "which guardrails?", "which platforms?"), set multiSelect: true
• Be opinionated - suggest a recommended default as the first option with "(Recommended)" suffix, let user override
• Summarize between phases - confirm understanding before moving on
• Adapt follow-ups - let answers guide the next question naturally
• Skip irrelevant topics - a CLI tool doesn't need design language questions about color palettes
• "Other" is always available - users can always provide custom text, so keep options to the 2-4 most likely choices
• Save after every answer - after each user answer, update PLAN.md.draft (and CLAUDE.md.draft when it's an actionable rule) before asking the next question

Phase Details

See interview-questions.md for detailed question banks per phase.

Phase 1: Project Vision Interview

Understand the big picture. Cover: what you're building, problem it solves, target user, platform (web/mobile/desktop/CLI/API), scope (MVP vs production), solo vs team, existing code/designs, timeline.

Capture raw input: When the user first describes their idea, save their exact words verbatim into PLAN.md.draft under "Original Vision > Raw user input". This preserves the original intent as a source of truth even if the project evolves.

If existing code exists: Before interviewing, automatically audit the codebase:

1. Read the directory structure (top 2-3 levels)
2. Check for existing CLAUDE.md, README, package.json, or config files
3. Identify existing patterns (testing framework, linting, folder structure)
4. Summarize findings to the user and use them to inform all subsequent phases

End condition: You can describe the project in 2-3 sentences and know the platform, scope, and audience.

Phase 2: Tech Stack Discovery + Auto-Research

First interview about tech choices (frontend, backend, database, auth, key libraries, deployment target, constraints).

Then for EACH technology identified, automatically research using BOTH Context7 and web search — focus on the latest docs:

1. Context7: resolve-library-id → query-docs for each technology. Get up-to-date API references, patterns, and code examples.
2. llms.txt: WebFetch → {official-site}/llms.txt (e.g. react.dev/llms.txt). Extract key reference links if it exists.
3. Latest official docs: WebSearch → "{technology} official documentation {current year}". Get docs homepage URL. Prioritize current-year results.
4. Best practices: WebSearch → "{technology} best practices {current year}". Summarize top 3-5 recommendations.
5. Common pitfalls: WebSearch → "{technology} common mistakes to avoid {current year}". Note top issues.

Present findings to user after each technology.

Post-research reconciliation: After researching ALL technologies, review the stack as a whole. Ask follow-up questions if:

• Two technologies don't play well together (e.g., incompatible versions, known integration pain)
• Research revealed a better alternative than what was originally chosen
• A best-practices guide strongly recommends a different approach for their use case
• A technology is outdated, deprecated, or has a clearly superior successor
• The stack has redundant tools that overlap in purpose

Be honest: "Based on my research, I'd actually recommend X instead of Y because [specific finding]. Want to reconsider?"

End condition: Complete tech stack list with documentation links and best practices for each. All technologies validated as working well together.

Phase 3: Data Model & Entity Design

Understand the data that flows through the system. This phase bridges the gap between "what tech" and "how users interact."

Cover:

• Core entities (Users, Posts, Orders, etc.) and their attributes
• Relationships between entities (1:1, 1:many, many:many)
• What's mutable vs. immutable
• What needs to be indexed, searchable, or filterable
• Audit/history requirements (do you need to track who changed what?)
• Data lifecycle (creation, updates, archival, deletion)
• Seeding/migration strategy for initial data
• External data sources or integrations that feed into the model

End condition: You can draw a rough entity-relationship diagram and describe how data flows through the system.

Phase 4: User Flow + Stories Interview

Validate the plan against real user journeys. Moved early because understanding flows informs coding style, design, and guardrails decisions.

1. Ask user to walk through the 3 most important user flows step by step
2. For each flow, ask about: first-use/onboarding, error states, empty states, loading states, edge cases
3. Generate 3-5 user stories: "As a [user], I want to [action] so that [benefit]"
4. For each story, think about: happy path, error path, edge cases (first time, no data, too much data)
5. Check: does the current tech plan and data model support every flow? Flag gaps.

End condition: Core user flows validated against the technical plan and data model.

Phase 5: Goals + Coding Style Interview

Cover: coding paradigm (functional/OOP/mixed), file organization, naming conventions, testing philosophy, error handling, state management, logging, comment philosophy, import organization, max file length.

End condition: You can write a "Coding Standards" section for CLAUDE.md.

Phase 6: Design Language Interview + Research

Cover: overall aesthetic, reference apps for inspiration, color palette, dark/light mode, accent colors, typography, spacing philosophy, animation philosophy, icon style, border/shadow treatment, responsive needs.

After the user names reference apps/sites, automatically research:

1. WebSearch → "{app name} UI design system" or "{app name} design language" - find their design docs if public
2. WebSearch → "{app name} {product type} UI inspiration" - find Dribbble/Behance examples of similar products
3. WebSearch → "best {product type} UI design {current year}" - find current design trends for this product category
4. If user mentions a specific aesthetic (e.g., "glassmorphism", "brutalist", "neumorphism"), search for examples and reference implementations

Present findings with links so the user can review visual references.

Skip this phase entirely for CLI tools, APIs, or libraries without UI.

End condition: You can write a "Design Language" section for CLAUDE.md with concrete references.

Phase 7: Project Guardrails & AI Working Agreement

Establish rules that prevent AI-assisted coding from creating a mess over time. This phase produces the constraints that keep the codebase healthy across dozens of AI sessions.

Interview topics:

1. Code size limits - max file length, max function length, when to split
2. Architecture boundaries - module boundaries, import rules, dependency direction (e.g., "UI never imports from API layer directly")
3. Testing requirements - what must be tested, what level of coverage, when can tests be skipped
4. Dependency governance - when can new packages be added, prefer stdlib, approval process
5. Refactoring triggers - concrete thresholds (e.g., "if a file exceeds 300 lines, refactor before adding more")
6. Anti-patterns - patterns explicitly forbidden in this project
7. Tech debt tracking - how to flag and prioritize debt
8. CLAUDE.md maintenance - when and how to update CLAUDE.md as the project evolves
9. Code review checkpoints - when should AI pause for human review vs. proceed
10. Integration & external services - third-party APIs, webhooks, OAuth providers, rate limits
11. Environment & secrets - env var management, secrets handling, dev vs staging vs prod config

End condition: You can write a "Guardrails" section for CLAUDE.md with concrete, enforceable rules.

Phase 8: Holistic Review Interview

YOU think critically about what's missing. Review everything gathered in phases 1-7 and ask about non-obvious concerns. Only ask about topics NOT already covered.

Consider: auth model, data migration, offline/sync, accessibility, i18n, performance budgets, security (OWASP), monitoring/error tracking, CI/CD, versioning, API versioning, rate limiting, backup/DR, legal/compliance, third-party dependencies, browser/OS support.

End condition: No significant architectural gaps remain.

Phase 9: Compile Outputs

The Split Principle: CLAUDE.md is loaded every session — keep it under 80 lines, only actionable rules. Everything else goes in PLAN.md. For each line in CLAUDE.md ask: "Would removing this cause Claude to make mistakes?" If not, move it to PLAN.md.

Before presenting the final files, review them against these standards. The files must be EXCELLENT — not bloated, not boring, not redundant. They are the foundation of the entire project.

Both files must be:

• Zero duplicates — if something is in CLAUDE.md, don't repeat it in PLAN.md (reference it instead)
• Zero fluff — every sentence must earn its place. No filler paragraphs, no restating the obvious
• Scannable — bullet points over prose, tables over lists where data is structured, headers that let you jump to what you need
• Specific — "Use Zustand for client state" not "Consider using a state management library"
• Actionable — every line should help someone build the project, not just describe it

CLAUDE.md must be:

• Under 80 lines — ruthlessly prune
• A cheat sheet you'd tape to your monitor — only what you need every single session
• Free of any research, reasoning, or background context

PLAN.md must be:

• A document so clear that a new developer (or AI) could pick it up cold and start building
• Organized so you can find any decision instantly — not a wall of text
• The raw user input preserved verbatim so intent is never lost
• Research condensed to actionable takeaways — not raw search results dumped in

CLAUDE.md (lean cheat sheet — under 80 lines):

1. Read existing CLAUDE.md if present
2. Preserve existing content that's still relevant
3. Include ONLY: project identity (1 line), commands, code style rules (non-obvious only), architecture rules (no "why"), guardrails, environment config, gotchas
4. Do NOT include: research, documentation links, best practices, data model details, user flows, design specs, decision reasoning — these go in PLAN.md

PLAN.md (comprehensive but tight project document):

• Original user input (verbatim from Phase 1)
• Project goal and vision
• Tech stack with documentation references and best practices research (condensed to key takeaways)
• Data model (entities, relationships, rules)
• User stories and flows
• Design language specs
• Architecture decisions WITH reasoning
• External integrations
• Phase-by-phase implementation plan
• Testing strategy
• Known risks and mitigations
• Open questions

See output-templates.md for the exact file templates.

Present both files to the user for review before writing them.