forgedev 1.2.0 → 1.3.0

package/docs/05-universal-scaffolder-vision.md

@@ -1,452 +0,0 @@
-# Project Init → Universal AI-First Project Scaffolder
-## Vision: Describe what you're building. Get the right stack, scaffold, AND Claude Code infrastructure.
-
----
-
-## The Idea
-
-Today: `npx create-next-init my-app` → always Next.js.
-
-Tomorrow: `npx create-init my-app` → asks what you're building → recommends
-the right stack → scaffolds it → ships with Claude Code infrastructure
-(CLAUDE.md, hooks, agents, skills) tailored to THAT stack.
-
-The user describes their service. The tool figures out the rest.
-
----
-
-## How It Would Work
-
-```
-$ npx create-init my-app
-
-🚀 Welcome to Project Init!
-
-What are you building?
-
-  1. Web app (SPA / SSR / static site)
-  2. API / backend service
-  3. Full-stack app (frontend + backend)
-  4. Mobile app (iOS / Android / cross-platform)
-  5. CLI tool / developer utility
-  6. AI/ML service
-  7. Desktop app
-  8. Chrome / browser extension
-  9. Microservice / serverless function
-  10. Let me describe it (free text → AI recommends)
-
-> 10
-
-Describe what you're building:
-> A SaaS platform for managing compliance questionnaires with AI-powered
-  auto-responses, role-based access, and PDF report generation
-
-🤖 Based on your description, I recommend:
-
-  Frontend:  Next.js 16 (App Router) + TypeScript + Tailwind + Shadcn/ui
-  Backend:   FastAPI (Python) + SQLAlchemy 2.0 + Pydantic v2
-  Database:  PostgreSQL + pgvector (for AI embeddings)
-  Auth:      NextAuth.js (frontend) + JWT (backend)
-  AI:        Gemini API via structured output
-  Testing:   Vitest (unit) + Playwright (E2E) + Pytest (backend)
-  CI/CD:     GitHub Actions
-  Infra:     Docker Compose (dev) + Cloud Run (prod)
-
-Include Claude Code infrastructure?
-  ✓ CLAUDE.md (tailored to this stack)
-  ✓ Hooks (lint, typecheck, protected files)
-  ✓ Skills (frontend, backend, testing, security, AI prompts)
-  ✓ Agents (code-quality, security, spec-validator, production-readiness)
-  ✓ Commands (audit-spec, audit-wiring, pre-pr)
-
-Proceed? (y/n)
-```
-
----
-
-## Architecture
-
-### The Stack Decision Engine
-
-The core of this tool isn't templates — it's a **decision tree** that maps
-what you're building to what you should build it with.
-
-```
-User Input (what they're building)
-        ↓
-Classifier (service type + requirements)
-        ↓
-Stack Recommender (best-fit tech for each layer)
-        ↓
-Template Composer (assembles from modular pieces)
-        ↓
-Claude Code Configurator (generates .claude/ for that stack)
-        ↓
-Scaffold Output (ready-to-run project)
-```
-
-### Service Type → Stack Mapping
-
-| Service Type | Frontend | Backend | Database | Testing | Notes |
-|-------------|----------|---------|----------|---------|-------|
-| Static site / blog | Astro or Next.js (SSG) | — | — | Playwright | Simplest option |
-| SPA (client-heavy) | React + Vite / Next.js | — or API route | — | Vitest + Playwright | |
-| SSR web app | Next.js (App Router) | Next.js API routes | PostgreSQL / SQLite | Vitest + Playwright | Monolith |
-| API service (Python) | — | FastAPI + SQLAlchemy | PostgreSQL | Pytest | |
-| API service (Node) | — | Hono / Express / NestJS | PostgreSQL | Vitest | |
-| API service (Go) | — | Gin / Echo / Chi | PostgreSQL | Go test | |
-| API service (Rust) | — | Axum / Actix | PostgreSQL | cargo test | |
-| Full-stack (JS monolith) | Next.js | Next.js API / tRPC | PostgreSQL (Prisma) | Vitest + Playwright | T3-style |
-| Full-stack (polyglot) | Next.js / React + Vite | FastAPI / Go / Rust | PostgreSQL | Per-language + Playwright | Separate repos or monorepo |
-| Mobile (cross-platform) | React Native (Expo) | — or API | SQLite / Supabase | Detox / Maestro | |
-| Mobile (native iOS) | SwiftUI | — or API | CoreData / CloudKit | XCTest | |
-| Mobile (native Android) | Jetpack Compose | — or API | Room / Firebase | Espresso | |
-| CLI tool (Node) | — | — | — | Vitest | |
-| CLI tool (Python) | — | — | — | Pytest | |
-| CLI tool (Go) | — | — | — | Go test | Best for cross-platform CLI |
-| CLI tool (Rust) | — | — | — | cargo test | Best for performance CLI |
-| AI/ML service | Streamlit / Gradio / Next.js | FastAPI + LangChain / custom | PostgreSQL + pgvector | Pytest + golden datasets | |
-| Desktop app | Tauri (Rust + web) or Electron | — | SQLite | Playwright | Tauri preferred (smaller) |
-| Browser extension | HTML/CSS/JS or React | — | chrome.storage | Playwright | Manifest V3 |
-| Microservice / Lambda | — | Language of choice | DynamoDB / PostgreSQL | Per-language | Serverless framework |
-
-### Modifier Questions (Refine the Recommendation)
-
-After picking the service type, the tool asks refinement questions:
-
-```
-Do you need real-time features (websockets, live updates)?
-  → Adds Socket.io / WebSocket layer
-
-Do you need AI/LLM integration?
-  → Adds AI service layer, prompt patterns, vector DB
-
-Do you need authentication?
-  → Adds auth layer (NextAuth, Clerk, Supabase Auth, etc.)
-
-Do you need file uploads / storage?
-  → Adds S3/Cloud Storage integration
-
-Do you need payment processing?
-  → Adds Stripe integration
-
-What's your deployment target?
-  → Docker, Vercel, AWS, GCP, self-hosted
-  → Generates appropriate config
-
-Monorepo or separate repos?
-  → Turborepo / Nx for monorepo, separate Git repos otherwise
-```
-
-### The Claude Code Configurator
-
-This is the differentiator. For EVERY stack combination, the tool generates:
-
-**1. CLAUDE.md** — tailored to the actual tech:
-```markdown
-# [Project Name]
-
-## WHAT
-- [Exact stack the tool selected]
-- [Folder structure it created]
-
-## HOW
-- Lint: [actual lint command for this stack]
-- Type check: [actual type check command]
-- Test: [actual test command]
-- Build: [actual build command]
-
-## RULES
-- [Stack-specific conventions]
-```
-
-**2. Hooks** — using the actual commands:
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "Write|Edit|MultiEdit",
-      "hooks": [{"type": "command", "command": "[actual lint command for file type]"}]
-    }],
-    "Stop": [{
-      "hooks": [{"type": "command", "command": "[actual validation script for this stack]"}]
-    }]
-  }
-}
-```
-
-**3. Skills** — for the specific frameworks:
-```
-.claude/skills/
-  nextjs/SKILL.md        ← if Next.js was selected
-  fastapi/SKILL.md       ← if FastAPI was selected
-  playwright/SKILL.md    ← if Playwright was selected
-  prisma/SKILL.md        ← if Prisma was selected
-  etc.
-```
-
-**4. Agents** — with stack-aware checklists:
-```
-.claude/agents/
-  code-quality-reviewer.md    ← checks for THIS stack's patterns
-  security-reviewer.md        ← checks for THIS stack's vulnerabilities
-  spec-validator.md           ← generic (works for any stack)
-  production-readiness.md     ← checks for THIS stack's deploy concerns
-```
-
-**5. Commands** — with the right audit paths:
-```
-.claude/commands/
-  verify-all.md
-  audit-spec.md
-  pre-pr.md
-```
-
----
-
-## Modular Template Architecture
-
-Instead of one monolithic template per stack, use composable modules:
-
-```
-templates/
-├── base/                     # Every project gets this
-│   ├── .gitignore
-│   ├── README.md.template
-│   ├── .claude/
-│   │   ├── commands/         # Universal commands
-│   │   └── agents/           # Universal agents
-│   └── docs/
-│       └── plans/            # Empty plans directory
-│
-├── frontend/
-│   ├── nextjs/               # Next.js 16 template
-│   ├── react-vite/           # React + Vite template
-│   ├── astro/                # Astro template
-│   ├── expo/                 # React Native / Expo template
-│   └── _shared/              # Shared frontend pieces
-│       ├── tailwind/
-│       ├── shadcn/
-│       └── .claude/skills/frontend/
-│
-├── backend/
-│   ├── fastapi/              # FastAPI template
-│   ├── hono/                 # Hono template
-│   ├── nestjs/               # NestJS template
-│   ├── gin/                  # Go + Gin template
-│   ├── axum/                 # Rust + Axum template
-│   ├── spring-boot/          # Java Spring Boot template
-│   └── _shared/
-│       └── .claude/skills/backend/
-│
-├── database/
-│   ├── prisma-postgres/
-│   ├── sqlalchemy-postgres/
-│   ├── drizzle-postgres/
-│   └── mongodb/
-│
-├── auth/
-│   ├── nextauth/
-│   ├── clerk/
-│   ├── supabase-auth/
-│   └── jwt-custom/
-│
-├── ai/
-│   ├── gemini/
-│   ├── openai/
-│   ├── anthropic/
-│   └── _shared/
-│       └── .claude/skills/ai-integration/
-│
-├── testing/
-│   ├── vitest/
-│   ├── playwright/
-│   ├── cypress/
-│   ├── pytest/
-│   ├── go-test/
-│   └── cargo-test/
-│
-├── infra/
-│   ├── docker-compose/
-│   ├── github-actions/
-│   ├── vercel/
-│   ├── cloud-run/
-│   └── serverless/
-│
-└── claude-code/              # Claude Code infrastructure modules
-    ├── hooks/
-    │   ├── typescript.json    # Hooks for TS projects
-    │   ├── python.json        # Hooks for Python projects
-    │   ├── go.json            # Hooks for Go projects
-    │   ├── rust.json          # Hooks for Rust projects
-    │   └── polyglot.json      # Hooks for multi-language projects
-    ├── skills/
-    │   ├── nextjs/SKILL.md
-    │   ├── fastapi/SKILL.md
-    │   ├── playwright/SKILL.md
-    │   ├── prisma/SKILL.md
-    │   ├── security-web/SKILL.md
-    │   ├── security-api/SKILL.md
-    │   └── ai-prompts/SKILL.md
-    └── agents/
-        ├── code-quality/
-        │   ├── typescript.md
-        │   ├── python.md
-        │   ├── go.md
-        │   └── rust.md
-        ├── security/
-        │   ├── web-app.md
-        │   ├── api-service.md
-        │   └── full-stack.md
-        └── universal/
-            ├── spec-validator.md
-            └── production-readiness.md
-```
-
-The scaffold engine composes: `base + frontend/nextjs + backend/fastapi + database/sqlalchemy-postgres + auth/nextauth + testing/playwright + testing/pytest + infra/docker-compose + claude-code/hooks/polyglot + claude-code/skills/nextjs + claude-code/skills/fastapi + ...`
-
----
-
-## Free-Text → AI Recommendation (Option 10)
-
-When the user describes what they're building in free text, use Claude's API
-to classify and recommend:
-
-```javascript
-const response = await anthropic.messages.create({
-  model: "claude-sonnet-4-20250514",
-  system: `You are a senior software architect. Given a project description,
-recommend the optimal tech stack. Return ONLY valid JSON.`,
-  messages: [{
-    role: "user",
-    content: `Project description: "${userDescription}"
-
-Return JSON:
-{
-  "service_type": "web_app|api_service|full_stack|mobile|cli|ai_service|desktop|extension|microservice",
-  "frontend": { "framework": "...", "language": "...", "styling": "...", "ui_library": "..." } | null,
-  "backend": { "framework": "...", "language": "...", "orm": "..." } | null,
-  "database": { "type": "...", "extras": ["pgvector", "redis", ...] } | null,
-  "auth": "nextauth|clerk|supabase|jwt|none",
-  "ai": { "provider": "...", "needs_embeddings": bool, "needs_structured_output": bool } | null,
-  "testing": { "unit": "...", "e2e": "...", "backend": "..." },
-  "deployment": "vercel|docker|cloud_run|serverless|self_hosted",
-  "extras": ["websockets", "file_uploads", "payments", "email", ...],
-  "reasoning": "Brief explanation of why this stack fits"
-}`
-  }]
-});
-```
-
----
-
-## Implementation Roadmap
-
-### Phase 1: Core CLI + Decision Engine (Week 1-2)
-- Interactive CLI with Inquirer.js
-- Service type selection (10 options)
-- Stack mapping (hardcoded decision tree, no AI yet)
-- Base template generation (project structure, configs, README)
-
-### Phase 2: First 3 Stack Templates (Week 3-4)
-- Next.js full-stack (what next-init already does, enhanced)
-- FastAPI backend service
-- React + Vite SPA
-- Each ships with Claude Code infrastructure
-
-### Phase 3: Claude Code Infrastructure Generation (Week 5-6)
-- Dynamic CLAUDE.md generation based on selected stack
-- Hook generation with actual commands for the stack
-- Skill generation for selected frameworks
-- Agent generation with stack-specific checklists
-
-### Phase 4: AI Recommendation (Week 7-8)
-- Free-text description → Claude API → stack recommendation
-- User confirms or adjusts recommendation
-- Template composition from modular pieces
-
-### Phase 5: Expand Stack Coverage (Ongoing)
-- Go + Gin backend
-- Rust + Axum backend
-- React Native / Expo mobile
-- Tauri desktop
-- Browser extensions
-- Community-contributed templates
-
-### Phase 6: Plugin Ecosystem (Future)
-- Community templates via GitHub repos
-- `create-init plugin add [github-url]`
-- Template marketplace
-
----
-
-## What Makes This Different From Existing Tools
-
-| Tool | What It Does | What's Missing |
-|------|-------------|----------------|
-| create-next-app | Scaffolds Next.js only | No stack choice, no AI infra |
-| create-vite | Scaffolds Vite projects | Frontend only, no AI infra |
-| Yeoman | Language-agnostic scaffolding | No AI recommendation, no Claude Code |
-| Blueprint | Multi-language scaffolding | No AI recommendation, no Claude Code |
-| LobeHub scaffolding skill | 70+ project types | It's a Claude Code skill, not a standalone CLI |
-| **create-init (this)** | **AI-recommended stack + Claude Code infra** | **Nothing. That's the point.** |
-
-The unique value: you describe what you're building, get the right stack
-recommended, and ship with the full AI-assisted development infrastructure
-(hooks, agents, skills, commands) already configured for THAT stack.
-
-No one else is doing: service description → stack recommendation → scaffold
-→ AI development infrastructure — in one tool.
-
----
-
-## Naming Options
-
-| Name | Command | Available? |
-|------|---------|-----------|
-| create-init | `npx create-init my-app` | Check npm registry |
-| create-scaffold | `npx create-scaffold my-app` | Check npm registry |
-| create-project-ai | `npx create-project-ai my-app` | Check npm registry |
-| create-stack | `npx create-stack my-app` | Check npm registry |
-| project-init | `npx project-init my-app` | Check npm registry |
-
----
-
-## The Prompt to Start Building This
-
-Use this with Claude Code to begin:
-
-```
-I'm evolving my existing next-init repo (https://github.com/babaphemy/next-init)
-into a universal project scaffolding CLI.
-
-Read the current codebase thoroughly. Then:
-
-1. Plan the architecture for a modular template system that supports:
-   - Multiple frontend frameworks (Next.js, React+Vite, Astro, Expo)
-   - Multiple backend frameworks (FastAPI, Hono, NestJS, Go/Gin, Rust/Axum)
-   - Multiple databases (PostgreSQL+Prisma, PostgreSQL+SQLAlchemy, MongoDB)
-   - Composable features (auth, AI, payments, file uploads, websockets)
-   - Claude Code infrastructure generation (.claude/ directory) for any stack
-
-2. The CLI should:
-   - Ask what the user is building (10 service types + free text)
-   - Recommend the optimal stack based on service type
-   - Let the user adjust the recommendation
-   - Compose the project from modular template pieces
-   - Generate Claude Code infrastructure (CLAUDE.md, hooks, skills, agents)
-     tailored to the selected stack
-
-3. Start by refactoring the existing setup.js into:
-   - A service type selector
-   - A stack recommender
-   - A template composer
-   - A Claude Code configurator
-
-Keep the existing Next.js template as the first module.
-Build the architecture so adding new stack templates is straightforward.
-Do NOT implement all stacks yet — just the architecture and Next.js.
-
-Save your plan to docs/plans/universal-scaffolder-plan.md.
-DO NOT write code until I approve the plan.
-```