name: project-init
description: Universal project initialization and assessment. Works for new Greenfield projects OR existing codebases. Establishes clean architecture, standards, and CLAUDE.md. Use at the start of any project or when onboarding to an existing codebase.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Project Initialization

Universal setup for new projects OR assessment of existing codebases.

Workflow

1. DETECT   → Identify project type and current state
2. ASSESS   → Evaluate architecture, patterns, issues
3. PLAN     → Define or document standards
4. SETUP    → Create CLAUDE.md and structure
5. VERIFY   → Confirm ready for development

Phase 1: Detection

First, analyze the project:

Questions to answer:
- Is this Greenfield or existing?
- What framework? (React, Flutter, Node, etc.)
- What database? (Supabase, Firebase, etc.)
- What state management?
- What testing framework?
- What deployment target?

Detection Commands

# Check for framework indicators
ls package.json pubspec.yaml requirements.txt Cargo.toml go.mod

# Check dependencies
cat package.json | grep -E "react|next|vue"
cat pubspec.yaml | grep -E "flutter|dart"

Phase 2: Assessment

For Existing Codebases

Analyze current state:

Architecture Assessment:
□ Folder structure - Is it feature-first or layer-first?
□ State management - What pattern? Is it consistent?
□ Data layer - Repository pattern? Direct API calls?
□ Testing - What coverage? What frameworks?
□ Code quality - Linting? Type safety?
□ Dependencies - Up to date? Security issues?

Generate Architecture Report

Create ARCHITECTURE.md:

# Architecture Assessment

## Current State
- Framework: [detected]
- Structure: [feature-first / layer-first / mixed]
- State: [provider / bloc / redux / etc.]
- Issues: [list issues found]

## Recommendations
- [Priority 1 fixes]
- [Priority 2 improvements]
- [Nice to have]

Phase 3: Standards Definition

Create CLAUDE.md

Every project MUST have a CLAUDE.md in the root:

# Project Name

## Tech Stack
- Framework: React/Flutter
- Database: Supabase
- State: [state management]
- Testing: [test framework]

## Architecture

### Folder Structure
[Define or document current structure]

### Patterns
- Repository pattern for data access
- [State management pattern]
- Feature-first organization

### Naming Conventions
- Components: PascalCase
- Files: kebab-case
- Functions: camelCase
- Constants: SCREAMING_SNAKE_CASE

## Code Standards

### Do
- Use typed interfaces/models
- Handle all error cases
- Write tests for new features
- Use semantic commit messages

### Don't
- Direct API calls in UI
- Hardcoded values
- Skip error handling
- Mix business logic in views

## Commands
- `npm run dev` / `flutter run`
- `npm test` / `flutter test`
- `npm run build` / `flutter build`

Phase 4: Structure Setup

React Project Structure

src/
├── app/                    # App entry, routing
├── features/               # Feature modules
│   └── auth/
│       ├── components/     # Feature UI
│       ├── hooks/          # Feature hooks
│       ├── services/       # API calls
│       └── types/          # TypeScript types
├── shared/
│   ├── components/         # Reusable UI
│   ├── hooks/              # Shared hooks
│   ├── lib/                # Utilities
│   └── types/              # Shared types
└── test/                   # Test utilities

Flutter Project Structure

lib/
├── app/                    # App config, routing
├── core/                   # Constants, utils, themes
├── features/               # Feature modules
│   └── auth/
│       ├── data/           # Repositories, models
│       ├── domain/         # Entities, use cases
│       └── presentation/   # Screens, widgets
├── shared/
│   ├── widgets/            # Reusable widgets
│   └── services/           # Shared services
└── main.dart

Phase 5: Verification

Checklist

□ CLAUDE.md exists and is complete
□ Folder structure follows standard
□ Linting configured and passing
□ Tests can run
□ Build succeeds
□ README is accurate

For Greenfield Projects

Quick setup:

# React + Supabase
npx create-next-app@latest my-app --typescript
cd my-app
npm install @supabase/supabase-js

# Flutter + Supabase
flutter create my_app
cd my_app
flutter pub add supabase_flutter

Then run this skill to establish standards.

For Existing Projects

1. Run detection
2. Generate architecture assessment
3. Create improvement plan
4. Establish CLAUDE.md
5. Begin incremental cleanup with /architecture-cleanup

Output

After running this skill, every project has:
- CLAUDE.md - AI instructions and standards
- ARCHITECTURE.md - Current state documentation (for existing)
- Clear folder structure
- Defined patterns and conventions