claude-code-starter 0.4.1 → 0.6.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { execSync, spawn } from "child_process";
 import fs3 from "fs";
 import path3 from "path";
 import { fileURLToPath } from "url";
@@ -535,7 +536,6 @@ import path2 from "path";
 function generateArtifacts(projectInfo) {
   const artifacts = [];
   const { techStack, rootDir } = projectInfo;
-  artifacts.push(generateClaudeMd(projectInfo));
   artifacts.push(generateSettings(techStack));
   artifacts.push(...generateSkills(techStack));
   artifacts.push(...generateAgents(techStack));
@@ -562,7 +562,7 @@ function writeArtifacts(artifacts, rootDir, force) {
     fs2.mkdirSync(dir, { recursive: true });
     const exists = fs2.existsSync(fullPath);
     if (exists && !force) {
-      const shouldPreserve = artifact.path.includes("state/task.md") || artifact.path === ".claude/CLAUDE.md";
+      const shouldPreserve = artifact.path.includes("state/task.md");
       if (shouldPreserve) {
         skipped.push(artifact.path);
         continue;
@@ -577,202 +577,6 @@ function writeArtifacts(artifacts, rootDir, force) {
   }
   return { created, updated, skipped };
 }
-function generateClaudeMd(projectInfo) {
-  const { techStack, name, description } = projectInfo;
-  const sections = [];
-  sections.push(`# ${name}`);
-  sections.push("");
-  if (description) {
-    sections.push(`> ${description}`);
-    sections.push("");
-  }
-  sections.push("## Start Here");
-  sections.push("");
-  sections.push("Check `.claude/state/task.md` for your current task.");
-  sections.push("");
-  sections.push("## Tech Stack");
-  sections.push("");
-  if (techStack.primaryLanguage) {
-    sections.push(`- **Language**: ${formatLanguage(techStack.primaryLanguage)}`);
-  }
-  if (techStack.primaryFramework) {
-    sections.push(`- **Framework**: ${formatFramework(techStack.primaryFramework)}`);
-  }
-  if (techStack.packageManager) {
-    sections.push(`- **Package Manager**: ${techStack.packageManager}`);
-  }
-  if (techStack.testingFramework) {
-    sections.push(`- **Testing**: ${techStack.testingFramework}`);
-  }
-  if (techStack.linter) {
-    sections.push(`- **Linter**: ${techStack.linter}`);
-  }
-  sections.push("");
-  sections.push("## Commands");
-  sections.push("");
-  sections.push("| Command | Purpose |");
-  sections.push("|---------|---------|");
-  sections.push("| `/task <desc>` | Start or switch to a new task |");
-  sections.push("| `/status` | Show current task state |");
-  sections.push("| `/done` | Mark current task complete |");
-  sections.push("| `/analyze <area>` | Deep-dive into specific code |");
-  sections.push("| `/code-review` | Review changes for quality and security |");
-  sections.push("");
-  sections.push("## Common Operations");
-  sections.push("");
-  sections.push("```bash");
-  sections.push(getCommonCommands(techStack));
-  sections.push("```");
-  sections.push("");
-  sections.push("## Rules");
-  sections.push("");
-  sections.push("1. **State First** - Always read `.claude/state/task.md` when resuming");
-  sections.push("2. **One Task** - Focus on one thing at a time");
-  sections.push("3. **Test Before Done** - Run tests before marking complete");
-  sections.push("4. **Update State** - Keep task.md current as you work");
-  sections.push("5. **Match Patterns** - Follow existing code conventions");
-  sections.push("6. **TDD Workflow** - Write failing tests first, then implement");
-  sections.push("");
-  sections.push("## Quality Gates");
-  sections.push("");
-  sections.push("Enforced constraints for code quality:");
-  sections.push("");
-  sections.push("| Constraint | Limit | Action |");
-  sections.push("|------------|-------|--------|");
-  sections.push("| Lines per function | 20 max | Decompose immediately |");
-  sections.push("| Parameters per function | 3 max | Use options object |");
-  sections.push("| Lines per file | 200 max | Split by responsibility |");
-  sections.push("| Test coverage | 80% min | Add tests before merge |");
-  sections.push("");
-  sections.push("## Skills");
-  sections.push("");
-  sections.push("Reference these for specialized workflows:");
-  const skills = getSkillsForStack(techStack);
-  for (const skill of skills) {
-    sections.push(`- \`.claude/skills/${skill.name}.md\` - ${skill.description}`);
-  }
-  sections.push("");
-  const agents = getAgentsForStack(techStack);
-  if (agents.length > 0) {
-    sections.push("## Agents");
-    sections.push("");
-    sections.push("Specialized agents available:");
-    for (const agent of agents) {
-      sections.push(`- \`${agent.name}\` - ${agent.description}`);
-    }
-    sections.push("");
-  }
-  sections.push("## File References");
-  sections.push("");
-  sections.push("Use `path/to/file.ts:123` format when referencing code.");
-  sections.push("");
-  return {
-    type: "claude-md",
-    path: ".claude/CLAUDE.md",
-    content: sections.join("\n"),
-    isNew: true
-  };
-}
-function getCommonCommands(stack) {
-  const commands = [];
-  switch (stack.packageManager) {
-    case "bun":
-      commands.push("# Install dependencies");
-      commands.push("bun install");
-      commands.push("");
-      commands.push("# Run development server");
-      commands.push("bun dev");
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("bun test");
-      commands.push("");
-      commands.push("# Build");
-      commands.push("bun run build");
-      break;
-    case "pnpm":
-      commands.push("# Install dependencies");
-      commands.push("pnpm install");
-      commands.push("");
-      commands.push("# Run development server");
-      commands.push("pnpm dev");
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("pnpm test");
-      break;
-    case "yarn":
-      commands.push("# Install dependencies");
-      commands.push("yarn");
-      commands.push("");
-      commands.push("# Run development server");
-      commands.push("yarn dev");
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("yarn test");
-      break;
-    case "npm":
-      commands.push("# Install dependencies");
-      commands.push("npm install");
-      commands.push("");
-      commands.push("# Run development server");
-      commands.push("npm run dev");
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("npm test");
-      break;
-    case "pip":
-    case "poetry":
-      commands.push("# Install dependencies");
-      commands.push(
-        stack.packageManager === "poetry" ? "poetry install" : "pip install -r requirements.txt"
-      );
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("pytest");
-      commands.push("");
-      commands.push("# Run server");
-      commands.push("uvicorn main:app --reload");
-      break;
-    case "cargo":
-      commands.push("# Build");
-      commands.push("cargo build");
-      commands.push("");
-      commands.push("# Run tests");
-      commands.push("cargo test");
-      commands.push("");
-      commands.push("# Run");
-      commands.push("cargo run");
-      break;
-    case "go":
-      commands.push("# Run tests");
-      commands.push("go test ./...");
-      commands.push("");
-      commands.push("# Build");
-      commands.push("go build");
-      commands.push("");
-      commands.push("# Run");
-      commands.push("go run .");
-      break;
-    default:
-      commands.push("# No package manager detected");
-      commands.push("# Add your common commands here");
-  }
-  if (stack.linter) {
-    commands.push("");
-    commands.push("# Lint");
-    switch (stack.linter) {
-      case "eslint":
-        commands.push(`${stack.packageManager === "bun" ? "bun" : "npx"} eslint .`);
-        break;
-      case "biome":
-        commands.push(`${stack.packageManager === "bun" ? "bun" : "npx"} biome check .`);
-        break;
-      case "ruff":
-        commands.push("ruff check .");
-        break;
-    }
-  }
-  return commands.join("\n");
-}
 function generateSettings(stack) {
   const permissions = ["Read(**)", "Edit(**)", "Write(.claude/**)", "Bash(git:*)"];
   const pkgManagers = ["npm", "yarn", "pnpm", "bun", "npx"];
@@ -845,51 +649,6 @@ function generateSettings(stack) {
     isNew: true
   };
 }
-function getSkillsForStack(stack) {
-  const skills = [
-    // Core methodology skills
-    { name: "pattern-discovery", description: "Finding codebase patterns" },
-    { name: "systematic-debugging", description: "Debugging approach" },
-    { name: "testing-methodology", description: "Testing strategy" },
-    // Process discipline skills
-    { name: "iterative-development", description: "TDD loops until tests pass" },
-    { name: "commit-hygiene", description: "Atomic commits and PR size limits" },
-    { name: "code-deduplication", description: "Prevent semantic code duplication" },
-    { name: "simplicity-rules", description: "Code complexity constraints" },
-    { name: "security", description: "Security patterns and secrets management" }
-  ];
-  if (stack.frameworks.includes("nextjs")) {
-    skills.push({ name: "nextjs-patterns", description: "Next.js App Router patterns" });
-  }
-  if (stack.frameworks.includes("react") || stack.frameworks.includes("nextjs")) {
-    skills.push({ name: "react-components", description: "React component patterns" });
-  }
-  if (stack.frameworks.includes("fastapi")) {
-    skills.push({ name: "fastapi-patterns", description: "FastAPI endpoint patterns" });
-  }
-  if (stack.frameworks.includes("nestjs")) {
-    skills.push({ name: "nestjs-patterns", description: "NestJS module patterns" });
-  }
-  if (stack.frameworks.includes("prisma") || stack.frameworks.includes("drizzle")) {
-    skills.push({ name: "database-patterns", description: "Database and ORM patterns" });
-  }
-  if (stack.frameworks.includes("swiftui")) {
-    skills.push({ name: "swiftui-patterns", description: "SwiftUI declarative UI patterns" });
-  }
-  if (stack.frameworks.includes("uikit")) {
-    skills.push({ name: "uikit-patterns", description: "UIKit view controller patterns" });
-  }
-  if (stack.frameworks.includes("vapor")) {
-    skills.push({ name: "vapor-patterns", description: "Vapor server-side Swift patterns" });
-  }
-  if (stack.frameworks.includes("jetpack-compose")) {
-    skills.push({ name: "compose-patterns", description: "Jetpack Compose UI patterns" });
-  }
-  if (stack.frameworks.includes("android-views")) {
-    skills.push({ name: "android-views-patterns", description: "Android XML views patterns" });
-  }
-  return skills;
-}
 function generateSkills(stack) {
   const artifacts = [];
   artifacts.push(generatePatternDiscoverySkill());
@@ -3303,16 +3062,6 @@ Before PR merge:
     isNew: true
   };
 }
-function getAgentsForStack(stack) {
-  const agents = [
-    { name: "code-reviewer", description: "Reviews code for quality and security" },
-    { name: "test-writer", description: "Generates tests for code" }
-  ];
-  if (stack.hasDocker) {
-    agents.push({ name: "docker-helper", description: "Helps with Docker and containerization" });
-  }
-  return agents;
-}
 function generateAgents(stack) {
   const artifacts = [];
   artifacts.push(generateCodeReviewerAgent(stack));
@@ -3827,90 +3576,331 @@ Provide:
     isNew: true
   };
 }
-function formatLanguage(lang) {
-  const names = {
-    typescript: "TypeScript",
-    javascript: "JavaScript",
-    python: "Python",
-    go: "Go",
-    rust: "Rust",
-    java: "Java",
-    ruby: "Ruby",
-    csharp: "C#",
-    swift: "Swift",
-    kotlin: "Kotlin",
-    php: "PHP",
-    cpp: "C++"
-  };
-  return names[lang] || lang;
+
+// src/prompt.ts
+function getAnalysisPrompt(projectInfo) {
+  const context = buildContextSection(projectInfo);
+  return `${ANALYSIS_PROMPT}
+
+---
+
+## Pre-detected Context
+
+The static analyzer has already detected the following about this project.
+Use this as a starting point - verify and expand on it during your analysis.
+
+${context}
+
+---
+
+## Execute Now
+
+1. Read this entire prompt to understand all phases
+2. Execute Phase 1 completely - read files, analyze code, gather all data
+3. Execute Phase 2 - generate the CLAUDE.md using only discovered information
+4. Execute Phase 3 - verify quality before writing
+5. Use the Write tool to create \`.claude/CLAUDE.md\` with the final content
+6. Output a brief summary of what was generated and any gaps found
+
+Do NOT output the full CLAUDE.md to stdout. Write it to disk using the Write tool.`;
 }
-function formatFramework(fw) {
-  const names = {
-    // JavaScript/TypeScript Frontend
-    nextjs: "Next.js",
-    react: "React",
-    vue: "Vue.js",
-    nuxt: "Nuxt",
-    svelte: "Svelte",
-    sveltekit: "SvelteKit",
-    angular: "Angular",
-    astro: "Astro",
-    remix: "Remix",
-    gatsby: "Gatsby",
-    solid: "Solid.js",
-    // JavaScript/TypeScript Backend
-    express: "Express",
-    nestjs: "NestJS",
-    fastify: "Fastify",
-    hono: "Hono",
-    elysia: "Elysia",
-    koa: "Koa",
-    // Python
-    fastapi: "FastAPI",
-    django: "Django",
-    flask: "Flask",
-    starlette: "Starlette",
-    // Go
-    gin: "Gin",
-    echo: "Echo",
-    fiber: "Fiber",
-    // Rust
-    actix: "Actix",
-    axum: "Axum",
-    rocket: "Rocket",
-    // Ruby
-    rails: "Rails",
-    sinatra: "Sinatra",
-    // Java/Kotlin
-    spring: "Spring",
-    quarkus: "Quarkus",
-    // Android
-    "jetpack-compose": "Jetpack Compose",
-    "android-views": "Android Views",
-    room: "Room",
-    hilt: "Hilt",
-    "ktor-android": "Ktor",
-    // Swift/iOS
-    swiftui: "SwiftUI",
-    uikit: "UIKit",
-    vapor: "Vapor",
-    swiftdata: "SwiftData",
-    combine: "Combine",
-    // CSS/UI
-    tailwind: "Tailwind CSS",
-    shadcn: "shadcn/ui",
-    chakra: "Chakra UI",
-    mui: "Material UI",
-    // Database/ORM
-    prisma: "Prisma",
-    drizzle: "Drizzle",
-    typeorm: "TypeORM",
-    sequelize: "Sequelize",
-    mongoose: "Mongoose",
-    sqlalchemy: "SQLAlchemy"
-  };
-  return names[fw] || fw;
+function buildContextSection(projectInfo) {
+  const { name, description, techStack, fileCount } = projectInfo;
+  const lines = [];
+  lines.push(`- **Project Name**: ${name}`);
+  if (description) {
+    lines.push(`- **Description**: ${description}`);
+  }
+  lines.push(`- **Source Files**: ${fileCount}`);
+  if (techStack.primaryLanguage) {
+    lines.push(`- **Primary Language**: ${techStack.primaryLanguage}`);
+  }
+  if (techStack.languages.length > 1) {
+    lines.push(
+      `- **Other Languages**: ${techStack.languages.filter((l) => l !== techStack.primaryLanguage).join(", ")}`
+    );
+  }
+  if (techStack.primaryFramework) {
+    lines.push(`- **Primary Framework**: ${techStack.primaryFramework}`);
+  }
+  if (techStack.frameworks.length > 1) {
+    lines.push(
+      `- **Other Frameworks**: ${techStack.frameworks.filter((f) => f !== techStack.primaryFramework).join(", ")}`
+    );
+  }
+  if (techStack.packageManager) {
+    lines.push(`- **Package Manager**: ${techStack.packageManager}`);
+  }
+  if (techStack.testingFramework) {
+    lines.push(`- **Testing Framework**: ${techStack.testingFramework}`);
+  }
+  if (techStack.linter) {
+    lines.push(`- **Linter**: ${techStack.linter}`);
+  }
+  if (techStack.formatter) {
+    lines.push(`- **Formatter**: ${techStack.formatter}`);
+  }
+  if (techStack.bundler) {
+    lines.push(`- **Bundler**: ${techStack.bundler}`);
+  }
+  if (techStack.isMonorepo) {
+    lines.push("- **Monorepo**: yes");
+  }
+  if (techStack.hasDocker) {
+    lines.push("- **Docker**: yes");
+  }
+  if (techStack.hasCICD && techStack.cicdPlatform) {
+    lines.push(`- **CI/CD**: ${techStack.cicdPlatform}`);
+  }
+  return lines.join("\n");
 }
+var ANALYSIS_PROMPT = `You are a senior software architect performing a comprehensive codebase analysis.
+Your goal is to generate a professional \`.claude/CLAUDE.md\` file that gives Claude
+complete context to work effectively in this project.
+
+**This is NOT a generic template.** Every section must contain information specific to THIS
+project, discovered through actual file reading and analysis. If you cannot determine
+something, omit that section entirely - do not fill in generic boilerplate.
+
+---
+
+## Phase 1: Discovery (Read Before You Write)
+
+Perform these analysis steps IN ORDER. Do not skip any step. Do not start writing
+the CLAUDE.md until all discovery is complete.
+
+### 1.1 Project Identity
+
+- Read \`package.json\`, \`pyproject.toml\`, \`Cargo.toml\`, \`go.mod\`, \`Gemfile\`, or equivalent
+- Extract: project name, version, description, author, license
+- Read \`README.md\` if it exists - extract the project's purpose in one sentence
+- Check for a \`docs/\` folder and scan for architecture docs
+
+### 1.2 Directory Structure Map
+
+- List the top-level directories and their purposes
+- Identify the source code root (\`src/\`, \`lib/\`, \`app/\`, \`pkg/\`, etc.)
+- Identify test directories (\`tests/\`, \`__tests__/\`, \`spec/\`, \`test/\`, etc.)
+- Identify configuration directories (\`.github/\`, \`.vscode/\`, \`config/\`, etc.)
+- Note any monorepo structure (\`packages/\`, \`apps/\`, \`services/\`)
+- Map the directory tree to a max depth of 3 levels (excluding \`node_modules\`, \`.git\`, \`dist\`, \`build\`, \`__pycache__\`, \`.next\`, \`target\`)
+
+### 1.3 Tech Stack Deep Scan
+
+Go beyond just detecting names. For each technology found, note HOW it is used:
+
+- **Languages**: Primary and secondary. Check config files for strictness settings
+- **Frameworks**: Read the main entry point to confirm framework usage patterns
+- **Package Manager**: Check lock files
+- **Database**: Check for ORM configs, connection strings in env examples, database drivers
+- **Authentication**: Look for auth libraries, auth middleware, session configs
+- **API Layer**: REST routes, GraphQL schemas, tRPC routers, gRPC proto files
+- **State Management**: Redux, Zustand, Pinia, Context API patterns
+- **Styling**: CSS modules, Tailwind config, styled-components, Sass
+- **Build Tools**: Check build configs
+- **CI/CD**: Read workflow files
+- **Infrastructure**: Docker, Terraform, Kubernetes manifests
+
+### 1.4 Architecture Pattern Recognition
+
+Read 5-10 key source files to identify:
+
+- **Architecture Style**: MVC, Clean Architecture, Hexagonal, Microservices, Monolith, Serverless
+- **Code Organization**: Feature-based, Layer-based, Domain-based
+- **Dependency Injection**: How dependencies are wired
+- **Data Flow**: How data moves through the application
+- **Error Handling Pattern**: How errors are caught, transformed, and reported
+- **API Pattern**: RESTful conventions, GraphQL resolvers, RPC style
+
+### 1.5 Entry Points & Key Files
+
+Identify and read these critical files:
+
+- **Application Entry**: main.ts, index.ts, app.ts, server.ts, main.py, app.py, main.go, main.rs
+- **Route/API Definitions**: Where routes/endpoints are registered
+- **Configuration**: Environment loading, app config
+- **Database Schema**: Models, migrations, schema definitions
+- **Middleware Chain**: Authentication, logging, error handling
+- **Type Definitions**: Shared types, interfaces, schemas
+- **Constants**: Shared constants, status codes, error codes
+
+### 1.6 Code Conventions (Read Actual Code)
+
+Read at least 3-5 source files and document the ACTUAL patterns used:
+
+- **Naming**: camelCase vs snake_case, file naming, component naming
+- **Imports**: Absolute vs relative, import ordering, barrel exports
+- **Exports**: Default vs named exports, re-export patterns
+- **Function Style**: Arrow functions vs function declarations, async/await patterns
+- **Error Handling**: try/catch style, Result types, error-first callbacks
+- **Type Annotations**: Explicit vs inferred, interface vs type
+- **File Structure**: How individual files are organized
+
+### 1.7 Development Workflow
+
+- **Scripts**: Read all scripts from package.json or equivalent
+- **Environment Variables**: Read \`.env.example\`, \`.env.sample\`, or \`.env.template\` - list ALL required variables
+- **Pre-commit Hooks**: Check \`.husky/\`, \`.lefthook.yml\`, lint-staged config
+- **Code Quality**: Linter/formatter rules and config
+- **Testing Setup**: Test config files, test utilities, fixtures, mocks
+- **Database Operations**: Migrations, seed data, reset commands
+
+### 1.8 Domain Knowledge
+
+- **Business Entities**: Core domain objects (User, Order, Product, etc.)
+- **Key Workflows**: Main user flows
+- **External Integrations**: Third-party APIs, webhooks, payment gateways
+- **Background Jobs**: Queue systems, cron jobs, scheduled tasks
+
+---
+
+## Phase 2: Generate the CLAUDE.md
+
+Using ONLY information discovered in Phase 1, generate the \`.claude/CLAUDE.md\` file.
+Every section must contain PROJECT-SPECIFIC content. Skip sections that don't apply.
+
+### Output Structure
+
+The CLAUDE.md MUST follow this structure:
+
+\`\`\`markdown
+# {Project Name}
+
+> {One-line description from README or package.json}
+
+## Overview
+
+{2-3 sentences: what this project does, who it's for, core value proposition.
+Written for an AI assistant that needs to understand PURPOSE to make good decisions.}
+
+## Architecture
+
+{Describe the actual architecture pattern found}
+
+### Directory Structure
+
+\\\`\\\`\\\`
+{Actual directory tree, depth 3, with annotations}
+\\\`\\\`\\\`
+
+### Data Flow
+
+{How a typical request flows through the system}
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| \`path/to/file\` | What it does |
+
+## Tech Stack
+
+| Category | Technology | Notes |
+|----------|-----------|-------|
+| Language | X | Config details |
+| Framework | Y | How it's used |
+
+## Development Setup
+
+### Prerequisites
+
+{Exact versions and tools needed}
+
+### Getting Started
+
+\\\`\\\`\\\`bash
+{Actual commands to get running}
+\\\`\\\`\\\`
+
+### Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| \`VAR_NAME\` | What it's for | \`example_value\` |
+
+## Common Commands
+
+\\\`\\\`\\\`bash
+{Actual commands from package.json scripts or equivalent}
+\\\`\\\`\\\`
+
+## Code Conventions
+
+### Naming
+
+{ACTUAL naming patterns found}
+
+### Patterns to Follow
+
+{3-5 patterns with file references as examples}
+
+### Anti-Patterns to Avoid
+
+{What NOT to do based on codebase conventions}
+
+## Testing
+
+### Running Tests
+
+\\\`\\\`\\\`bash
+{actual test commands}
+\\\`\\\`\\\`
+
+### Writing Tests
+
+{Testing patterns, utilities, fixtures available}
+
+## Domain Knowledge
+
+### Core Entities
+
+{Main domain objects and relationships}
+
+### Key Workflows
+
+{3-5 most important workflows}
+
+## Gotchas & Important Notes
+
+{3-10 non-obvious things about this project that would trip up a newcomer}
+
+## Rules
+
+1. **Read before writing** - Understand existing patterns before adding code
+2. **Match conventions** - Follow the patterns documented above
+3. **Test everything** - Write tests, run existing tests after changes
+4. {project-specific rules discovered during analysis}
+\`\`\`
+
+---
+
+## Phase 3: Quality Checklist
+
+Before writing the CLAUDE.md, verify:
+
+- [ ] Every section contains PROJECT-SPECIFIC information (not generic boilerplate)
+- [ ] File paths referenced actually exist in the project
+- [ ] Commands listed are verified from package.json scripts or equivalent
+- [ ] Code conventions were observed from ACTUAL source files
+- [ ] The "Gotchas" section contains genuinely useful, non-obvious information
+- [ ] An AI reading this CLAUDE.md could add a new feature following existing patterns
+- [ ] Sections without real content have been omitted entirely
+
+---
+
+## Important Guidelines
+
+1. **Be specific, not generic.** "Uses React with hooks" is useless. "Uses React 18 with Server Components via Next.js App Router, client components in src/components/client/ with 'use client' directive" is useful.
+
+2. **Reference real files.** Every pattern should reference an actual file as an example. Use \`path/to/file.ts:lineNumber\` format.
+
+3. **Prioritize actionable information.** Focus on what helps an AI write correct code: where to put new code, what patterns to follow, what to avoid, how to test.
+
+4. **Skip empty sections.** Only include sections with real content.
+
+5. **Keep it maintainable.** Don't include metrics that go stale quickly.
+
+6. **Respect existing CLAUDE.md.** If one exists, read it first and preserve manually-added sections.`;
 
 // src/cli.ts
 var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
@@ -3947,13 +3937,16 @@ ${pc.bold("OPTIONS")}
 
 ${pc.bold("WHAT IT DOES")}
   1. Analyzes your repository's tech stack
-  2. Detects frameworks, languages, and tools
+  2. Launches Claude CLI to deeply analyze your codebase
   3. Generates tailored Claude Code configurations:
-     - CLAUDE.md with project-specific instructions
+     - CLAUDE.md with project-specific instructions (via Claude analysis)
      - Skills for your frameworks (Next.js, FastAPI, etc.)
      - Agents for code review and testing
      - Rules matching your code style
 
+${pc.bold("REQUIREMENTS")}
+  Claude CLI must be installed: https://claude.ai/download
+
 ${pc.bold("MORE INFO")}
   https://github.com/cassmtnr/claude-code-starter
 `);
@@ -3969,10 +3962,10 @@ function showTechStack(projectInfo, verbose) {
   console.log(pc.bold("Tech Stack"));
   console.log();
   if (techStack.primaryLanguage) {
-    console.log(`  ${pc.bold("Language:")} ${formatLanguage2(techStack.primaryLanguage)}`);
+    console.log(`  ${pc.bold("Language:")} ${formatLanguage(techStack.primaryLanguage)}`);
   }
   if (techStack.primaryFramework) {
-    console.log(`  ${pc.bold("Framework:")} ${formatFramework2(techStack.primaryFramework)}`);
+    console.log(`  ${pc.bold("Framework:")} ${formatFramework(techStack.primaryFramework)}`);
   }
   if (techStack.packageManager) {
     console.log(`  ${pc.bold("Package Manager:")} ${techStack.packageManager}`);
@@ -4105,8 +4098,8 @@ ${projectInfo.name}${projectInfo.description ? ` - ${projectInfo.description}` :
 
 New project - setting up from scratch.
 
-${preferences?.framework ? `**Framework:** ${formatFramework2(preferences.framework)}` : ""}
-${preferences?.primaryLanguage ? `**Language:** ${formatLanguage2(preferences.primaryLanguage)}` : ""}
+${preferences?.framework ? `**Framework:** ${formatFramework(preferences.framework)}` : ""}
+${preferences?.primaryLanguage ? `**Language:** ${formatLanguage(preferences.primaryLanguage)}` : ""}
 
 ## Next Steps
 
@@ -4121,7 +4114,7 @@ ${preferences?.primaryLanguage ? `**Language:** ${formatLanguage2(preferences.pr
   }
   fs3.writeFileSync(taskPath, content);
 }
-function formatLanguage2(lang) {
+function formatLanguage(lang) {
   const names = {
     typescript: "TypeScript",
     javascript: "JavaScript",
@@ -4138,7 +4131,7 @@ function formatLanguage2(lang) {
   };
   return names[lang] || lang;
 }
-function formatFramework2(fw) {
+function formatFramework(fw) {
   const names = {
     nextjs: "Next.js",
     react: "React",
@@ -4184,6 +4177,53 @@ function formatFramework2(fw) {
   };
   return names[fw] || fw;
 }
+function checkClaudeCli() {
+  try {
+    execSync("claude --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runClaudeAnalysis(projectDir, projectInfo) {
+  return new Promise((resolve) => {
+    const prompt = getAnalysisPrompt(projectInfo);
+    console.log(pc.cyan("Launching Claude for deep project analysis..."));
+    console.log(pc.gray("Claude will read your codebase and generate a comprehensive CLAUDE.md"));
+    console.log();
+    const child = spawn(
+      "claude",
+      [
+        "-p",
+        prompt,
+        "--allowedTools",
+        "Read",
+        "Glob",
+        "Grep",
+        `Write(.claude/**)`,
+        `Edit(.claude/**)`
+      ],
+      {
+        cwd: projectDir,
+        stdio: ["ignore", "inherit", "inherit"]
+      }
+    );
+    child.on("error", (err) => {
+      console.error(pc.red(`Failed to launch Claude CLI: ${err.message}`));
+      resolve(false);
+    });
+    child.on("close", (code) => {
+      if (code === 0) {
+        console.log();
+        console.log(pc.green("Claude analysis complete!"));
+        resolve(true);
+      } else {
+        console.error(pc.red(`Claude exited with code ${code}`));
+        resolve(false);
+      }
+    });
+  });
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
@@ -4232,7 +4272,12 @@ async function main() {
     }
     console.log();
   }
-  console.log(pc.gray("Generating configuration..."));
+  if (!checkClaudeCli()) {
+    console.error(pc.red("Claude CLI is required but not found."));
+    console.error(pc.gray("Install it from: https://claude.ai/download"));
+    process.exit(1);
+  }
+  console.log(pc.gray("Generating supporting configuration..."));
   console.log();
   const result = generateArtifacts(projectInfo);
   const { created, updated, skipped } = writeArtifacts(result.artifacts, projectDir, args.force);
@@ -4256,10 +4301,17 @@ async function main() {
   }
   console.log();
   createTaskFile(projectInfo, preferences);
-  const totalFiles = created.length + updated.length;
+  const success = await runClaudeAnalysis(projectDir, projectInfo);
+  if (!success) {
+    console.error(pc.red("Claude analysis failed. Please try again."));
+    process.exit(1);
+  }
+  const totalFiles = created.length + updated.length + 1;
+  console.log();
   console.log(pc.green(`Done! (${totalFiles} files)`));
   console.log();
   console.log(pc.bold("Generated for your stack:"));
+  console.log(pc.cyan("  CLAUDE.md (deep analysis by Claude)"));
   const skills = result.artifacts.filter((a) => a.type === "skill");
   const agents = result.artifacts.filter((a) => a.type === "agent");
   const rules = result.artifacts.filter((a) => a.type === "rule");
@@ -4279,26 +4331,29 @@ async function main() {
   console.log();
   console.log(`${pc.cyan("Next step:")} Run ${pc.bold("claude")} to start working!`);
   console.log();
-  if (!projectInfo.isExisting) {
-    console.log(pc.gray("Tip: Use /task to define your first task"));
-  } else {
-    console.log(pc.gray("Tip: Use /analyze to explore specific areas of your codebase"));
-  }
+  console.log(
+    pc.gray("Your CLAUDE.md was generated by deep analysis - review it with: cat .claude/CLAUDE.md")
+  );
+}
+var isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(pc.red("Error:"), err.message);
+    if (process.env.DEBUG) {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  });
 }
-main().catch((err) => {
-  console.error(pc.red("Error:"), err.message);
-  if (process.env.DEBUG) {
-    console.error(err.stack);
-  }
-  process.exit(1);
-});
 export {
+  checkClaudeCli,
   createTaskFile,
-  formatFramework2 as formatFramework,
-  formatLanguage2 as formatLanguage,
+  formatFramework,
+  formatLanguage,
   getVersion,
   parseArgs,
   promptNewProject,
+  runClaudeAnalysis,
   showBanner,
   showHelp,
   showTechStack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-starter",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "A lightweight starter kit for AI-assisted development with Claude Code",
   "keywords": [
     "claude",