@aicgen/aicgen 1.0.0-beta.1

package/planning/DYNAMIC-GUIDELINES-DESIGN.md

@@ -0,0 +1,265 @@
+# Dynamic Guidelines System Design
+
+## Problem
+
+Current system embeds all guidelines at build time. Users can't:
+- Add new guidelines without rebuilding
+- Update existing guidelines
+- Contribute custom guidelines
+- Download community guidelines
+
+## Proposed Solution: Hybrid System
+
+### Architecture
+
+```
+Priority (highest to lowest):
+1. ~/.aicgen/guidelines/     (user custom)
+2. ~/.aicgen/cache/latest/   (downloaded updates)
+3. Embedded data             (bundled fallback)
+```
+
+### Directory Structure
+
+```
+~/.aicgen/
+├── config.yml                    # User config
+├── guidelines/                   # User custom guidelines
+│   ├── custom-mappings.yml      # User-added mappings
+│   └── custom/
+│       ├── my-react-guide.md
+│       └── my-nextjs-guide.md
+│
+└── cache/
+    └── latest/                   # Downloaded official updates
+        ├── guideline-mappings.yml
+        └── guidelines/*.md
+```
+
+### Implementation Plan
+
+#### 1. Data Source Layer (`src/services/data-source.ts`)
+
+```typescript
+interface DataSource {
+  getMappings(): Promise<Record<string, GuidelineMapping>>;
+  getGuideline(path: string): Promise<string>;
+}
+
+class EmbeddedDataSource implements DataSource {
+  // Uses EMBEDDED_DATA (current implementation)
+}
+
+class FileSystemDataSource implements DataSource {
+  constructor(private basePath: string) {}
+  // Reads from filesystem
+}
+
+class HybridDataSource implements DataSource {
+  constructor(
+    private userPath: string,      // ~/.aicgen/guidelines
+    private cachePath: string,     // ~/.aicgen/cache/latest
+    private embedded: DataSource   // Fallback
+  ) {}
+
+  async getMappings() {
+    // Merge: user > cache > embedded
+  }
+
+  async getGuideline(path: string) {
+    // Try: user > cache > embedded
+  }
+}
+```
+
+#### 2. Updated GuidelineLoader
+
+```typescript
+export class GuidelineLoader {
+  private dataSource: DataSource;
+
+  constructor(dataSource?: DataSource) {
+    this.dataSource = dataSource || this.createDefaultDataSource();
+  }
+
+  private createDefaultDataSource(): DataSource {
+    const userDir = join(homedir(), '.aicgen', 'guidelines');
+    const cacheDir = join(homedir(), '.aicgen', 'cache', 'latest');
+
+    return new HybridDataSource(
+      userDir,
+      cacheDir,
+      new EmbeddedDataSource()
+    );
+  }
+
+  // Rest of implementation uses dataSource
+}
+```
+
+#### 3. New Commands
+
+```bash
+# Update official guidelines from GitHub
+aicgen update
+
+# Add custom guideline
+aicgen add-guideline <path> --category <cat> --language <lang>
+
+# List all available guidelines
+aicgen list-guidelines [--source user|cache|embedded|all]
+
+# Remove guideline
+aicgen remove-guideline <id>
+
+# Reset to embedded (clear cache and user)
+aicgen reset-guidelines
+```
+
+### Update Command Flow
+
+```typescript
+// src/commands/update.ts
+export async function updateCommand() {
+  const spinner = ora('Checking for updates...').start();
+
+  // 1. Fetch latest from GitHub
+  const latest = await fetchLatestGuidelines();
+
+  // 2. Compare versions
+  const currentVersion = getEmbeddedVersion();
+  if (latest.version <= currentVersion) {
+    spinner.succeed('Already up to date');
+    return;
+  }
+
+  // 3. Download and extract
+  const cachePath = join(homedir(), '.aicgen', 'cache', 'latest');
+  await downloadAndExtract(latest.url, cachePath);
+
+  spinner.succeed(`Updated to v${latest.version}`);
+  console.log(chalk.cyan(`\n📦 New guidelines available:`));
+  latest.changes.forEach(change => {
+    console.log(`   ${chalk.gray('•')} ${change}`);
+  });
+}
+```
+
+### Custom Guideline Format
+
+```yaml
+# ~/.aicgen/guidelines/custom-mappings.yml
+my-react-hooks:
+  path: custom/react-hooks-guide.md
+  category: Best Practices
+  languages: [typescript, javascript]
+  levels: [standard, expert, full]
+  architectures: [layered, modular-monolith]
+  tags: [react, hooks, frontend]
+
+my-nextjs-patterns:
+  path: custom/nextjs-patterns.md
+  category: Architecture
+  languages: [typescript]
+  levels: [expert, full]
+  tags: [nextjs, react, ssr]
+```
+
+## Benefits
+
+### For Users
+- ✅ Add custom guidelines without rebuild
+- ✅ Update official guidelines via `aicgen update`
+- ✅ Works offline (embedded fallback)
+- ✅ Customize for their tech stack
+
+### For Maintainers
+- ✅ Push guideline updates without new releases
+- ✅ Faster iteration on guidelines
+- ✅ Community contributions easier
+
+### For Teams
+- ✅ Share team-specific guidelines
+- ✅ Enforce company standards
+- ✅ Version control custom guidelines
+
+## Migration Path
+
+### Phase 1: Keep Current System
+- No breaking changes
+- Embedded data still works
+
+### Phase 2: Add Hybrid Support
+- Implement data source layer
+- Add filesystem loading
+- Merge logic for multiple sources
+
+### Phase 3: Add Update Command
+- GitHub integration
+- Version checking
+- Download and cache
+
+### Phase 4: Add Custom Guidelines
+- CLI commands for adding/removing
+- Validation and linting
+- Documentation
+
+## Implementation Checklist
+
+- [ ] Create `DataSource` interface
+- [ ] Implement `EmbeddedDataSource`
+- [ ] Implement `FileSystemDataSource`
+- [ ] Implement `HybridDataSource`
+- [ ] Update `GuidelineLoader` to use data sources
+- [ ] Create `~/.aicgen/` directory structure
+- [ ] Implement `update` command
+- [ ] Implement `add-guideline` command
+- [ ] Implement `list-guidelines` command
+- [ ] Add version tracking
+- [ ] GitHub integration for updates
+- [ ] Validation for custom guidelines
+- [ ] Documentation and examples
+
+## Alternative: Remote-First Approach
+
+If internet is always available:
+
+```typescript
+// Fetch from CDN/GitHub on every run (with cache)
+const guidelines = await fetch('https://cdn.aicgen.dev/guidelines/latest.json');
+```
+
+**Pros**: Always latest
+**Cons**: Requires internet, slower startup
+
+**Verdict**: Hybrid approach is better - works offline, updates when available.
+
+---
+
+## Questions for Implementation
+
+1. **Should we implement this now or later?**
+   - Now: Full flexibility from day 1
+   - Later: Ship faster, add when needed
+
+2. **Update frequency?**
+   - Manual: `aicgen update` when user wants
+   - Auto-check: Check on init, download in background
+   - Both: Auto-check + manual command
+
+3. **Custom guideline validation?**
+   - Strict: Must match schema, linting required
+   - Loose: Any markdown file works
+   - Medium: Basic validation, warnings for issues
+
+4. **Storage location?**
+   - `~/.aicgen/` (Unix-style)
+   - Platform-specific config dirs
+   - Both with fallback
+
+5. **Versioning?**
+   - Semantic versioning (1.0.0)
+   - Date-based (2025-12-08)
+   - Git commit hash
+
+My recommendation: **Implement Phase 1-2 now** (hybrid system), **Phase 3-4 later** (update commands).

package/planning/ENTERPRISE-UX-COMPLETE.md

@@ -0,0 +1,281 @@
+# Enterprise UX Implementation Complete ✅
+
+## What Was Implemented
+
+### 1. Box Formatting Utility (`src/utils/formatting.ts`)
+
+**Functions:**
+- `drawBox()` - Draw bordered boxes with titles and padding
+- `drawSeparator()` - Horizontal separators
+- `drawTable()` - Full bordered tables with headers
+- `createSummaryBox()` - Formatted key-value summary boxes
+- `createMetricsBox()` - Metrics display with custom styling
+- `padLeft()`, `padRight()`, `center()` - Text alignment helpers
+
+**Example:**
+```
+╭──────────────────────────────── 📁 Project Detection ─────────────────────────────────╮
+│                                                                                        │
+│  Name:          my-project                                                            │
+│  Language:      typescript                                                            │
+│                                                                                        │
+╰────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+### 2. Wizard State Management (`src/utils/wizard-state.ts`)
+
+**Features:**
+- Full state tracking for wizard flow
+- History management for back navigation
+- Step validation and conditional skipping
+- Helper functions for back navigation
+
+**Key Classes/Functions:**
+- `WizardStateManager` - Manages wizard state and navigation
+- `addBackOption()` - Adds "← Back" to choice lists
+- `isBackSelected()` - Checks if back was selected
+- Constants: `BACK_OPTION`, `BACK_VALUE`
+
+### 3. Complete Wizard Refactor (`src/commands/init.ts`)
+
+**Implemented:**
+- ✅ State-based wizard flow
+- ✅ Back navigation on every prompt
+- ✅ Box-formatted output
+- ✅ Summary preview before generation
+- ✅ Profile metrics in level descriptions
+- ✅ Smart navigation (skip steps based on setup type)
+
+**Flow:**
+1. Project Detection → Box-formatted display
+2. Language Selection → Confirm detected or select
+3. Project Type → With back option
+4. AI Assistant → With back option
+5. Setup Type (Quick/Custom) → With back option
+6. Architecture → With back option
+7. Level → **Shows metrics in description!**
+8. Guidelines (if custom) → With back option
+9. **Summary Preview** → Box-formatted with back option
+10. Generation → Progress indicators
+
+### 4. Smart Guideline Selector (`src/commands/guideline-selector.ts`)
+
+**Features:**
+- ✅ Category-child synchronization
+- ✅ Back navigation support
+- ✅ Clear instructions
+- ✅ Selection summary
+
+**Behavior:**
+- Check category → All children checked
+- Uncheck category → Can still select individual children
+- Shows "Selected X of Y guidelines" summary
+
+### 5. Enhanced Banner Display
+
+**Updates:**
+- ✅ Redesigned ASCII art to match SVG
+- ✅ Shows on main CLI entry (not just init)
+- ✅ Navigation instructions displayed
+- ✅ Professional formatting
+
+## Visual Examples
+
+### Main CLI Banner
+```
+        ◉                              ╭──────────╮
+       ◉  ╲                           │ ─────    │
+      ◉    ╲   ──►   ◆   ─►   │ ────     │
+     ◉      ╱                      │ ─────    │
+    ◉      ╱                       │ ────     │
+   ◉                                  ╰──────────╯
+                                            ✓
+           aicgen ─ AI Config Generator
+           v0.1.0 · MIT License
+
+   Navigation:
+   ↑↓ arrows    - Navigate options
+   Space        - Select/deselect (checkboxes)
+   Enter        - Confirm selection
+   Ctrl+C       - Cancel anytime
+```
+
+### Level Selection with Metrics
+```
+? Instruction detail level?
+  ← Back
+  ────────────────────────────────────────
+❯ Basic - Essential guidelines for quick projects
+  (12 guidelines, 1 hook, 1 agent, ~30 KB)
+
+  Standard - Production-ready practices
+  (28 guidelines, 3 hooks, 2 agents, ~70 KB)
+
+  Expert - Advanced patterns for scaling
+  (45 guidelines, 4 hooks, 3 agents, ~110 KB)
+
+  Full - Everything - all guidelines
+  (57 guidelines, 4 hooks, 3 agents, ~140 KB)
+```
+
+### Summary Preview
+```
+╭─────────────────────── 📋 Configuration Summary ───────────────────────╮
+│                                                                        │
+│  Assistant:      Claude Code                                          │
+│  Language:       TypeScript                                           │
+│  Project Type:   Web Application                                      │
+│  Architecture:   Modular Monolith                                     │
+│  Level:          Standard                                             │
+│                                                                        │
+╰────────────────────────────────────────────────────────────────────────╯
+
+╭────────────────────── 📊 Configuration Preview ───────────────────────╮
+│                                                                        │
+│  • 28 guidelines                                                      │
+│  • 3 hooks                                                            │
+│  • 2 sub-agents                                                       │
+│  • ~70 KB estimated size                                              │
+│                                                                        │
+╰────────────────────────────────────────────────────────────────────────╯
+
+? Proceed with generation?
+❯ Yes, generate configuration
+  ← Back (modify settings)
+  Cancel
+```
+
+### Guideline Selection
+```
+📚 Select Guidelines
+
+💡 Tip: Uncheck a category to uncheck all items in that category
+Use Space to toggle, Enter to confirm
+
+? Select guidelines to include:
+  ← Back to previous step
+  ──────────────────────────────────────────────────
+  ◉ Language (8 guidelines)
+    ◉ TypeScript basics
+    ◉ TypeScript advanced types
+    ◉ TypeScript decorators
+    ...
+
+  ◉ Architecture (5 guidelines)
+    ◉ Layered architecture patterns
+    ◉ Modular monolith structure
+    ...
+
+  ◯ Testing (3 guidelines)
+    ◯ Unit testing standards
+    ◯ Integration testing
+    ◯ E2E testing
+
+✓ Selected 28 of 57 guidelines
+```
+
+## Files Created
+
+1. `src/utils/formatting.ts` - Box formatting utilities
+2. `src/utils/wizard-state.ts` - Wizard state management
+3. `src/commands/guideline-selector.ts` - Smart guideline selector
+4. `src/commands/init-old-backup.ts` - Backup of old init.ts
+5. `ENTERPRISE-UX-COMPLETE.md` - This file
+
+## Files Modified
+
+1. `src/commands/init.ts` - Complete refactor with enterprise UX
+2. `src/utils/banner.ts` - Redesigned ASCII art
+3. `src/index.ts` - Added banner to main CLI
+
+## TypeScript Compilation
+
+✅ All code compiles successfully
+```bash
+npx tsc --noEmit
+# No errors
+```
+
+## Testing
+
+To test the enterprise UX:
+
+```bash
+# Build binary
+bun run build:binary:windows
+
+# Run init wizard
+./aicgen.exe init
+
+# Or just run main CLI to see banner
+./aicgen.exe
+```
+
+## User Experience Improvements
+
+### Before
+- No back navigation (had to Ctrl+C and restart)
+- No metrics preview (guessing what each level includes)
+- No summary (can't review before generating)
+- Simple text output
+- Category selection didn't affect children
+- No banner on main CLI
+
+### After
+- ✅ Back navigation on every step
+- ✅ Real-time metrics in level descriptions
+- ✅ Box-formatted summary with preview
+- ✅ Professional box formatting throughout
+- ✅ Smart category-child sync
+- ✅ Beautiful banner on main CLI
+- ✅ Clear navigation instructions
+- ✅ State management for robust flow
+
+## Architecture Decisions
+
+### State Management Pattern
+Used explicit WizardStateManager class instead of inline state for:
+- Better testability
+- Clear state transitions
+- Easier debugging
+- Type safety
+
+### Back Navigation Implementation
+Used "← Back" option in prompts instead of global listener because:
+- More intuitive for users
+- Works with all terminal types
+- Consistent with prompt flow
+- Easier to implement
+
+### Box Formatting
+Used custom utility instead of library because:
+- Full control over styling
+- No external dependencies
+- Optimized for our color scheme
+- Custom functions for our use cases
+
+## What Users Get
+
+1. **Professional First Impression** - Beautiful banner and formatting
+2. **Confidence** - See exactly what they're getting (metrics)
+3. **Control** - Back navigation, review before generation
+4. **Clarity** - Box formatting makes information easy to scan
+5. **Efficiency** - Smart category selection, skip unnecessary steps
+6. **Guidance** - Clear instructions at every step
+
+## Next Steps (Optional Enhancements)
+
+1. **Loading Animations** - Better progress indicators with sub-tasks
+2. **Error Recovery** - Graceful error handling with recovery options
+3. **Keyboard Shortcuts** - Advanced navigation (Ctrl+B for back, etc.)
+4. **Theme Support** - User-configurable color schemes
+5. **Saved Preferences** - Remember last selections
+6. **Interactive Preview** - Show example generated files
+7. **Validation Hints** - Real-time feedback on selections
+
+---
+
+**Status**: ✅ Complete and production-ready
+**Date**: 2025-12-08
+**Version**: 0.1.0
+**Impact**: Enterprise-grade CLI experience

package/planning/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,20 @@
+# Dynamic Guidelines Implementation Plan
+
+See DYNAMIC-GUIDELINES-DESIGN.md for full details.
+
+## Quick Summary
+
+**Storage:**
+- Official: GitHub repo `aicgen/guidelines`
+- Cache: `~/.aicgen/cache/official/`
+- User custom: `~/.aicgen/data/`
+- Embedded: Binary fallback
+
+**Commands:**
+- `aicgen update` - Download latest from GitHub
+- `aicgen add-guideline` - Interactive guideline creator
+- Auto-check on `aicgen init`
+
+**Priority:** User data > Official cache > Embedded
+
+Ready to implement!