@aicgen/aicgen 1.0.0-beta.1

package/planning/PHASE1-COMPLETE.md

@@ -0,0 +1,211 @@
+# Phase 1: Foundation & Schema - COMPLETE ✅
+
+## What We Built
+
+Phase 1 establishes the core data structures and detection system for aicgen's profile-based configuration generation.
+
+### 1. Domain Models (`src/domain/`)
+
+#### `project-fingerprint.ts`
+Complete project detection schema with:
+- **Language detection** with confidence scoring
+- **Framework detection** (Next.js, NestJS, Django, etc.)
+- **Database detection** (PostgreSQL, MySQL, MongoDB, etc.)
+- **Package manager** detection
+- **Project structure** analysis (tests, CI, Docker, monorepo)
+- **Existing configs** detection (AI assistants, linters, formatters)
+- **Project size** estimation (team size, complexity, file count)
+
+#### `profile.ts`
+Profile schema supporting:
+- **Instruction levels**: basic, standard, expert, full, custom
+- **Architecture types**: microservices, modular-monolith, refactor, etc.
+- **Guideline includes** with section extraction
+- **Output configs** for generated files
+- **Defaults** for testing, linting, formatting, CI/CD
+
+### 2. Core Logic (`src/core/`)
+
+#### `project-scanner.ts`
+Comprehensive project scanner that:
+- Detects language with confidence scoring
+- Identifies frameworks and databases
+- Analyzes project structure
+- Estimates team size from codebase
+- Finds existing AI assistant configs
+- Counts code files intelligently
+
+#### `recommender.ts`
+Intelligent recommendation engine that:
+- Recommends instruction level based on project size/maturity
+- Recommends architecture based on team size/structure
+- Provides reasoning for each recommendation
+- Includes detailed descriptions for user display
+
+#### `profile-loader.ts`
+Profile file loader with:
+- YAML profile parsing
+- Profile caching for performance
+- Profile validation
+- Fallback profile loading
+- Profile listing/discovery
+
+### 3. Example Usage (`src/examples/`)
+
+#### `phase1-demo.ts`
+Demonstrates the complete Phase 1 flow:
+1. Scan project → get fingerprint
+2. Get recommendations → instruction level + architecture
+3. Create profile selection
+4. Load profile (will work in Phase 2)
+
+## How to Test
+
+Run the demo:
+```bash
+bun run src/examples/phase1-demo.ts
+```
+
+You should see:
+- Project fingerprint details
+- Recommended instruction level with reasoning
+- Recommended architecture with reasoning
+- Profile selection
+- Error loading profile (expected - profiles created in Phase 2)
+
+## Profile Selection Matrix
+
+The system supports a matrix of profiles:
+
+```
+Assistant × Language × Instruction Level × Architecture = Profile
+
+Examples:
+- claude-code × typescript × standard × modular-monolith
+- copilot × python × expert × microservices
+- antigravity × javascript × basic × refactor
+```
+
+## Instruction Levels
+
+| Level | Lines | Team Size | Use Case |
+|-------|-------|-----------|----------|
+| **Basic** | ~200 | 1 | Scripts, POCs, learning |
+| **Standard** | ~500 | 1-5 | MVP, small production apps |
+| **Expert** | ~1000 | 5-20 | Scaling products, large teams |
+| **Full** | ~2000+ | 20+ | Enterprise, complex systems |
+| **Custom** | Variable | Any | Specific needs |
+
+## Architecture Recommendations
+
+| Architecture | Complexity | Best For |
+|--------------|------------|----------|
+| **Modular Monolith** | Medium | Most projects (default) |
+| **Microservices** | High | Large teams, clear boundaries |
+| **Refactor** | Medium | Legacy codebases |
+| **Custom** | Variable | Specific patterns |
+
+## Recommendation Logic
+
+### Instruction Level
+- `fileCount < 10` + `teamSize = 1` → **Basic**
+- `fileCount > 50` OR `teamSize >= 5` → **Standard**
+- `fileCount > 200` OR `teamSize >= 15` → **Expert**
+- Has tests + CI → **Standard** minimum
+- Empty project → **Basic**
+
+### Architecture
+- Monorepo + large team (10+) → **Microservices**
+- Multiple modules → **Modular Monolith**
+- Large codebase without tests → **Refactor**
+- Backend + large team → **Microservices**
+- Default → **Modular Monolith**
+
+## What's Next: Phase 2
+
+Phase 2 will create:
+
+1. **Profile YAML files** (`profiles/`)
+   - `claude-code/typescript-standard-modular-monolith.yml`
+   - `copilot/python-expert-microservices.yml`
+   - etc.
+
+2. **Template system** (`templates/`)
+   - Handlebars templates for instructions.md
+   - Templates for each AI assistant
+   - CI/CD templates
+   - Docker templates
+
+3. **Template renderer**
+   - Parse templates with project context
+   - Generate final config files
+   - Atomic file writes
+
+4. **First working profile**
+   - Claude Code + TypeScript + Standard + Modular Monolith
+   - Test end-to-end generation
+
+## Files Created
+
+```
+src/
+├── domain/
+│   ├── project-fingerprint.ts  ✅ Complete type definitions
+│   ├── profile.ts              ✅ Complete profile schema
+│   └── index.ts                ✅ Barrel export
+├── core/
+│   ├── project-scanner.ts      ✅ Comprehensive scanner
+│   ├── recommender.ts          ✅ Smart recommendations
+│   ├── profile-loader.ts       ✅ YAML profile loader
+│   └── index.ts                ✅ Barrel export
+└── examples/
+    └── phase1-demo.ts          ✅ Usage demonstration
+```
+
+## Success Criteria ✅
+
+- [x] ProjectFingerprint schema with all detection fields
+- [x] Profile schema with instruction levels & architecture
+- [x] Project scanner detects language, framework, database
+- [x] Recommender suggests appropriate level & architecture
+- [x] Profile loader can parse YAML files
+- [x] All components use strict TypeScript
+- [x] No `any` types, proper error handling
+- [x] Example demonstrates full flow
+
+## Architecture Decisions
+
+1. **Separate domain models from implementation**
+   - `domain/` contains pure TypeScript interfaces
+   - `core/` contains business logic
+   - Clean separation enables testing
+
+2. **Confidence-based language detection**
+   - Multiple signals (tsconfig.json, package.json, etc.)
+   - Scored detection, not binary
+   - Supports polyglot projects
+
+3. **Smart recommendations with reasoning**
+   - Not just "pick one"
+   - Explain WHY each choice makes sense
+   - Users can override with context
+
+4. **Profile caching**
+   - YAML parsing is expensive
+   - Cache loaded profiles
+   - Clear cache method for testing
+
+5. **Extensible architecture detection**
+   - Easy to add new architecture types
+   - Each type has clear description
+   - Complexity rating helps users decide
+
+## Ready for Phase 2!
+
+Phase 1 provides the foundation. Phase 2 will bring it to life with actual profile files and templates.
+
+**Next command:**
+```bash
+# After Phase 2, you'll be able to run:
+aicgen init --assistant claude-code --language typescript
+```

package/planning/PHASE2-COMPLETE.md

@@ -0,0 +1,350 @@
+# Phase 2: Template System - COMPLETE ✅
+
+## What We Built
+
+Phase 2 creates the template rendering engine and first complete profile with templates.
+
+### 1. Template System (`src/services/template-renderer.ts`)
+
+Complete Handlebars-based template engine with:
+- Template loading from files
+- Template rendering with context
+- Custom helpers (uppercase, lowercase, capitalize, formatDate, join, eq, ne, gt, etc.)
+- Boolean logic helpers (and, or, not)
+
+### 2. File Writer Enhanced (`src/utils/file.ts`)
+
+Added batch atomic writes:
+- `writeFiles()` function for multiple files
+- Atomic writes (temp file + rename pattern)
+- Rollback on failure (cleans up temp files)
+- Directory creation
+
+### 3. Config Generator (`src/services/config-generator.ts`)
+
+Orchestration service that:
+- Scans project → gets fingerprint
+- Loads profile
+- Renders all templates
+- Writes files atomically
+- Supports dry-run mode
+- Evaluates conditions (!structure.hasCI, !structure.hasDocker)
+
+### 4. First Complete Profile
+
+**`profiles/claude-code/typescript-standard-modular-monolith.yml`**
+
+Complete profile with:
+- Meta information (name, version, description)
+- Detection rules (when to suggest this profile)
+- Instruction level config (guidelines to include, rules)
+- Architecture config (structure, rules, focus areas)
+- Output configs (which templates to render)
+- Defaults (testing, linting, formatting, database, CI/CD)
+
+### 5. Handlebars Templates
+
+**Claude Code templates:**
+
+1. **`instructions.md.hbs`** (~200 lines)
+   - Project overview
+   - Architecture description & structure
+   - Code guidelines & principles
+   - TypeScript specifics
+   - Error handling patterns
+   - Testing strategy
+   - Development workflow
+   - Environment configuration
+   - Logging patterns
+   - Deployment guidelines
+
+2. **`config.yml.hbs`**
+   - Project metadata
+   - Profile info
+   - Defaults configuration
+
+3. **`decisions.md.hbs`**
+   - Architecture Decision Records (ADRs)
+   - Initial decisions documented
+   - Template for adding new ADRs
+
+## File Structure Created
+
+```
+profiles/
+└── claude-code/
+    └── typescript-standard-modular-monolith.yml
+
+templates/
+└── claude-code/
+    ├── instructions.md.hbs
+    ├── config.yml.hbs
+    └── decisions.md.hbs
+
+src/
+├── models/
+│   ├── project.ts              (enhanced)
+│   └── profile.ts              (enhanced)
+├── services/
+│   ├── project-scanner.ts      (new)
+│   ├── recommender.ts          (new)
+│   ├── profile-loader.ts       (new)
+│   ├── template-renderer.ts    (new)
+│   └── config-generator.ts     (new)
+└── utils/
+    └── file.ts                  (enhanced with writeFiles)
+
+examples/
+├── phase1-demo.ts
+└── phase2-demo.ts              (new)
+```
+
+## How It Works
+
+### Generation Flow
+
+```
+1. Scan Project
+   ↓
+2. Get Fingerprint (language, framework, size, etc.)
+   ↓
+3. Get Recommendations (instruction level, architecture)
+   ↓
+4. Load Profile (YAML file)
+   ↓
+5. Render Templates (Handlebars with context)
+   ↓
+6. Write Files Atomically
+```
+
+### Template Context
+
+Every template receives:
+
+```typescript
+{
+  project: ProjectFingerprint,  // Detected project info
+  profile: ProfileConfig,        // Selected profile
+  timestamp: Date               // Generation time
+}
+```
+
+### Handlebars Helpers
+
+Available in all templates:
+
+```handlebars
+{{uppercase "hello"}}           → HELLO
+{{lowercase "WORLD"}}           → world
+{{capitalize "typescript"}}     → Typescript
+{{formatDate timestamp}}        → 2025-12-06
+
+{{#if (eq project.language.primary "typescript")}}
+  TypeScript detected!
+{{/if}}
+
+{{#if (gt project.projectSize.fileCount 100)}}
+  Large codebase
+{{/if}}
+
+{{#if (and project.structure.hasTests project.structure.hasCI)}}
+  Well-configured project
+{{/if}}
+```
+
+## Testing Phase 2
+
+Run the demo:
+
+```bash
+bun run examples/phase2-demo.ts
+```
+
+Expected output:
+```
+=== Phase 2: Template System & Generation Demo ===
+
+Step 1: Getting recommendations...
+
+Project Analysis:
+  Name: aicgen
+  Language: typescript
+  Framework: None
+  Team Size: ~3 developers
+  File Count: 42
+
+Recommended Configuration:
+  Instruction Level: standard
+  - Code style, testing, CI/CD, basic architecture
+  - Best for: Startup MVPs, small production apps, 1-5 developers
+  Architecture: modular-monolith
+  - Single deployment with clear module boundaries
+  - Complexity: Medium
+
+Step 2: Generating configuration files...
+
+Selected Profile:
+  claude-code + typescript + standard + modular-monolith
+
+Generating (dry run)...
+
+✅ Dry run successful!
+
+Files that would be generated:
+  ✓ .claude/instructions.md
+  ✓ .claude/config.yml
+  ✓ .claude/decisions.md
+```
+
+## Generated Files Preview
+
+### .claude/instructions.md
+
+Complete development guide including:
+- Project overview with detected tech stack
+- Modular monolith architecture description
+- Code guidelines (TypeScript specific)
+- Testing strategy
+- Development workflow
+- Environment & deployment
+- Warnings if no tests/CI/Docker detected
+
+### .claude/config.yml
+
+Project configuration:
+```yaml
+project:
+  name: "your-project"
+  language: "typescript"
+  framework: "Next.js"
+
+profile:
+  level: "standard"
+  architecture: "modular-monolith"
+
+defaults:
+  runtime: "node:20-alpine"
+  testing:
+    framework: "vitest"
+    coverage: 80
+```
+
+### .claude/decisions.md
+
+Architecture Decision Records:
+- ADR-001: Architecture choice
+- ADR-002: Testing strategy
+- ADR-003: Code quality tools
+- Template for adding new ADRs
+
+## Key Features
+
+✅ **Conditional Generation**
+- Only generate CI if not exists: `condition: "!structure.hasCI"`
+- Only generate Docker if not exists: `condition: "!structure.hasDocker"`
+- Optional files: `optional: true`
+
+✅ **Context-Aware Templates**
+```handlebars
+{{#if project.database}}
+- **Database:** {{project.database.type}}
+{{/if}}
+
+{{#if (not project.structure.hasTests)}}
+⚠️ **No tests detected** - Priority!
+{{/if}}
+```
+
+✅ **Atomic Writes**
+- All files written atomically
+- Rollback on failure
+- No partial state
+
+✅ **Dry Run Support**
+- See what would be generated
+- No files written
+- Validate templates
+
+## Architecture Decisions
+
+1. **Handlebars over other engines**
+   - Simple, powerful, widely used
+   - Good TypeScript support
+   - Extensible with helpers
+   - No code execution (safe)
+
+2. **Atomic batch writes**
+   - Write all to .tmp first
+   - Rename all at once
+   - Rollback on any failure
+   - Prevents partial state
+
+3. **Template context structure**
+   - `project` - what was detected
+   - `profile` - what was selected
+   - `timestamp` - when generated
+   - Simple, predictable
+
+4. **Condition evaluation**
+   - Simple string conditions
+   - Evaluated in generator
+   - Can extend easily
+   - Type-safe
+
+5. **Profile as single source of truth**
+   - YAML defines everything
+   - Templates referenced, not embedded
+   - Easy to add new profiles
+   - Versioned separately
+
+## What's Next: Phase 3
+
+Phase 3 will add the interactive CLI wizard:
+
+1. **Interactive prompts** (Inquirer.js)
+   - Select AI assistant
+   - Choose instruction level
+   - Choose architecture
+   - Configure options
+
+2. **Pretty terminal output** (Chalk + Ora)
+   - Colored output
+   - Progress spinners
+   - Success/error indicators
+
+3. **CLI commands**
+   - `aicgen init` - Interactive wizard
+   - `aicgen init --profile claude-code` - Skip assistant selection
+   - `aicgen init --level expert` - Skip level selection
+
+4. **Validation & confirmation**
+   - Show what will be generated
+   - Confirm before writing
+   - Handle existing files
+
+## Success Criteria ✅
+
+- [x] Template renderer with Handlebars
+- [x] Custom helpers for common operations
+- [x] Batch atomic file writes
+- [x] Config generator orchestration
+- [x] First complete profile (Claude Code + TypeScript)
+- [x] Three templates (instructions, config, decisions)
+- [x] Dry-run support
+- [x] Conditional generation
+- [x] Context-aware templates
+- [x] Demo showing end-to-end flow
+
+## Ready for Phase 3!
+
+**Next command:**
+```bash
+# After Phase 3, you'll be able to run:
+aicgen init
+```
+
+And get an interactive wizard that:
+1. Scans your project
+2. Recommends instruction level & architecture
+3. Lets you customize
+4. Generates all config files