Project Init
Overview
This skill transforms a project idea into a fully scoped, documented project blueprint through structured discovery, research, and user collaboration. The output is a project directory containing comprehensive documentation that serves as the source of truth for implementation.
Workflow
The workflow has two major stages: Discovery (understanding what to build) and Initialization (creating the project documentation). Complete Discovery fully before moving to Initialization.
Stage 1: Discovery
Step 1: Gather Project Details
Begin by understanding the project at a high level. Ask the user to describe:
- What the project is (purpose, problem it solves, target users)
- Core features and functionality
- Tech stack preferences (languages, frameworks, databases, infrastructure)
- Project-type-specific details:
- Web apps: pages/routes needed, authentication, data models
- CLI tools: example commands/usage, input/output formats
- APIs: endpoints, data schemas, integrations
- Mobile apps: screens, navigation flow, platform targets
- Libraries/SDKs: public API surface, target consumers
- Games: mechanics, platforms, networking model
Use the
tool to gather this information. Start with broad questions, then drill into specifics based on answers. Do not overwhelm — ask 1-3 focused questions per round.
Step 2: Research
Conduct online research using the
tool to investigate:
- Similar projects — find existing implementations, open-source examples, and established patterns for this type of project
- Technical best practices — architecture patterns, library choices, common pitfalls for the chosen tech stack
- Trade-offs — evaluate alternative approaches discovered during research
- Implementation details — specific APIs, protocols, or techniques the project will need
Synthesize findings internally. Identify anything the user may have missed, potential risks, and areas needing clarification.
Step 3: Self-Reflection
Before proceeding to the interview, pause and reason through:
- Connections between user requirements and research findings
- Gaps in the current understanding
- Architectural implications of the stated requirements
- Potential scope risks or technical challenges
- Questions where the answer is NOT obvious from prior context
Step 4: Interview
Use the
tool to clarify anything unresolved from Steps 1-3. Topics may include:
- Technical implementation choices surfaced by research
- UI/UX decisions (for visual projects)
- Concerns or trade-offs discovered during research
- Feature prioritization (MVP vs. nice-to-have)
- Design preferences and constraints
- Integration requirements
- Deployment and infrastructure needs
Rules for the interview:
- Do NOT ask questions whose answers are obvious from previous responses or research
- Do NOT ask about preferences already documented in
references/user-preferences.md
- Continue interviewing until confident that the project is fully understood
- Each round should surface genuinely new information
Read
references/user-preferences.md
for standing preferences that apply to all projects (monorepo structure, Docker, Makefiles, Bash scripts). Apply these automatically without asking.
Stage 2: Initialization
Proceed only after reaching full confidence in the project understanding. Initialization creates the project directory and documentation files — nothing else.
Step 1: Create Project Directory
bash
mkdir -p <project-name>/docs
Create only the project root and
directory. Do NOT run any framework initializers, package managers, or scaffolding tools — those are roadmap tasks.
Step 2: Create SPEC.md
Write
<project-name>/docs/SPEC.md
containing:
- Project Overview — name, purpose, problem statement, target users
- Architecture — high-level system design, component diagram (ASCII/Mermaid), data flow
- Tech Stack — languages, frameworks, databases, infrastructure with rationale for each choice
- Project Structure — directory layout following monorepo conventions (see
references/user-preferences.md
- Core Modules — description of each major module/component, its responsibilities, and interfaces
- Data Models — key entities, schemas, relationships
- API Surface — endpoints, contracts, or public interfaces (as applicable)
- External Integrations — third-party services, APIs, dependencies
- Key Decisions — architectural decisions made during discovery with rationale
Step 3: Create STYLES.md (Conditional)
Only create this file for projects with a visual/frontend component (web apps, mobile apps, desktop apps, games with UI).
Write
<project-name>/docs/STYLES.md
containing a concise styling specification for a modern, professional, Apple-esque design:
- Design Philosophy — clean, minimal, purposeful, premium feel
- Color Palette — primary, secondary, accent, semantic colors (success/warning/error/info), neutral scale, dark mode variants
- Typography — font families (system stack or specific), size scale, weight scale, line heights
- Spacing & Layout — spacing scale, grid system, breakpoints, max-widths, container padding
- Component Styling — buttons, inputs, cards, modals, navigation patterns, hover/focus/active states
- Motion & Animation — transition durations, easing curves, animation principles
- Iconography — icon style, library recommendation, sizing
- Shadows & Elevation — shadow scale, usage guidelines
- Border Radius — radius scale and usage
Base recommendations on modern design trends: clean whitespace, subtle depth through shadows, refined color palettes, smooth micro-interactions.
Step 4: Create ROADMAP.md
Read
references/roadmap-format.md
for the canonical format, phase structure, and action item template.
Write
<project-name>/docs/ROADMAP.md
following these rules:
Header:
# <project-name> Development Roadmap
followed by
Phases (in order):
-
Phase 1: Project Setup — Infrastructure, tooling, project scaffolding. Must include tasks for:
- Running framework initializers (e.g.,
npx create-next-app@latest
- Monorepo directory structure creation
- Makefile with standard targets (, , , , plus project-specific targets)
- Docker and docker-compose setup
- CI/CD pipeline configuration
- Linting, formatting, pre-commit hooks
- For frontend apps: global styles setup, shared component library scaffold, page stubs with "X Page Coming Soon" text
- Environment configuration templates
-
Phase 2: Research (optional) — Only include for complex projects requiring deep technical investigation before implementation. Each task produces a deliverable in
. Skip for straightforward projects.
-
Phase 3: MVP (or Phase 2 if Research is skipped) — Core features required for initial launch. Break into logical subsections with numbered action items.
-
Phase 4: Nice to Have (or Phase 3) — Features, polish, and production hardening that elevate the project beyond MVP.
-
Phase 5: Future (or Phase 4) — High-level directions, not scoped tasks. Uses the Description/Features/Rationale format instead of Description/Requirements/Implementation Notes.
Action item format for Phases 1-4: Each item gets exactly 3 subsections:
- Description: What and why
- Requirements: checklist of concrete deliverables
- Implementation Notes: Technical guidance, references, trade-offs
Action item format for Future phase: Each item gets exactly 3 subsections:
- Description: What this direction is about
- Features: Potential features and capabilities
- Rationale: Why this direction is worth pursuing
Number action items as
(e.g.,
,
,
,
). Give each item a descriptive title after the number (e.g.,
### 1.1 Monorepo Structure and Tooling
).
Action items should be granular enough to be individually actionable but broad enough to avoid excessive fragmentation. Target 3-8 action items per phase for most projects.