--- name: initialize description: Initialize ÆtherLight in a new repository. Sets up folder structure, Git workflow, configuration files, and development standards. --- # Initialize ÆtherLight Skill ## What This Skill Does Sets up ÆtherLight in a new repository: - Creates standardized folder structure - Configures Git workflow and branches - Sets up configuration files - Establishes development patterns - Integrates with VS Code\/Cursor ## When Claude Should Use This Use this skill when the user: - Says "set up ÆtherLight" or "initialize the project" - Starts a new repository - Wants to add ÆtherLight to existing project - Mentions project setup or initialization - References Issue #6 (initialization process) ## Initialization Process ### 1. Assess Current State ```bash # Check if repo exists git status 2>\/dev\/null || git init # Check for existing structure ls -la # Check for existing CLAUDE.md or cursor files if [ -f "CLAUDE.md" ]; then echo "⚠️ Existing CLAUDE.md found - will enhance, not replace" cp CLAUDE.md CLAUDE.md.backup.$(date +%Y%m%d_%H%M%S) fi if [ -f ".claude\/CLAUDE.md" ]; then echo "⚠️ Existing .claude\/CLAUDE.md found - will merge" cp .claude\/CLAUDE.md .claude\/CLAUDE.md.backup.$(date +%Y%m%d_%H%M%S) fi # Comprehensive project analysis echo "🔍 Analyzing project type..." # Framework detection [ -f "package.json" ] && { echo "Node.js project detected" grep -q '"react"' package.json && echo " → React framework" grep -q '"vue"' package.json && echo " → Vue framework" grep -q '"@angular\/core"' package.json && echo " → Angular framework" grep -q '"express"' package.json && echo " → Express backend" grep -q '"next"' package.json && echo " → Next.js framework" } [ -f "Cargo.toml" ] && echo "Rust project detected" [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && echo "Python project detected" [ -f "go.mod" ] && echo "Go project detected" [ -f "pom.xml" ] && echo "Java\/Maven project detected" [ -f "build.gradle" ] && echo "Java\/Gradle project detected" # Build system detection [ -f "Makefile" ] && echo "Make build system detected" [ -f "webpack.config.js" ] && echo "Webpack bundler detected" [ -f "vite.config.js" ] && echo "Vite bundler detected" [ -f "rollup.config.js" ] && echo "Rollup bundler detected" ``` ### 2. Create ÆtherLight Structure ```bash # Core directories mkdir -p .claude\/skills mkdir -p .claude\/commands mkdir -p .aetherlight\/patterns mkdir -p sprints mkdir -p docs\/patterns mkdir -p docs\/architecture mkdir -p analysis mkdir -p tasks # Development directories (based on project type) mkdir -p src mkdir -p tests mkdir -p scripts # Initialize pattern library echo "Creating pattern library templates..." mkdir -p .aetherlight\/patterns\/auth mkdir -p .aetherlight\/patterns\/database mkdir -p .aetherlight\/patterns\/api mkdir -p .aetherlight\/patterns\/ui ``` ### 3. Initialize Configuration Files #### Handling Existing CLAUDE.md ```bash # Function to merge or create CLAUDE.md create_or_enhance_claude_md() { if [ -f "CLAUDE.md" ] || [ -f ".claude\/CLAUDE.md" ]; then echo "📝 Enhancing existing CLAUDE.md with ÆtherLight integration..." # Extract existing content sections existing_content=$(cat CLAUDE.md 2>\/dev\/null || cat .claude\/CLAUDE.md 2>\/dev\/null) # Create enhanced version preserving user content cat > .claude\/CLAUDE.md.enhanced << 'EOF' # Project Instructions for Claude - ÆtherLight Enhanced ## ÆtherLight Integration - Voice commands available via backtick (`) - Sprint management in `\/sprints\/` directory - Pattern library in `.aetherlight\/patterns\/` - Code analysis via `\/code-analyze` command - Automated workflows via skills ## Original Project Instructions [EXISTING_CONTENT] ## ÆtherLight Development Standards ### Git Workflow (Enforced) 1. All work in feature branches 2. PRs required for master 3. Semantic commit messages 4. Code review before merge 5. Protected code policy applies after release ### Available Commands - `\/initialize` - Set up project structure - `\/sprint-plan` - Create sprint with branches - `\/code-analyze` - Analyze codebase - `\/publish` - Automated release ### Code Protection Rules - Released code is PROTECTED - Refactor-only modifications allowed - New features as extensions only EOF # Replace placeholder with existing content sed -i "s|\[EXISTING_CONTENT\]|$existing_content|" .claude\/CLAUDE.md.enhanced # Move enhanced version into place mv .claude\/CLAUDE.md.enhanced .claude\/CLAUDE.md else echo "📝 Creating new CLAUDE.md with ÆtherLight standards..." create_new_claude_md fi } # Function for new CLAUDE.md create_new_claude_md() { cat > .claude\/CLAUDE.md << 'EOF' # Project Instructions for Claude ## Project Overview [Project description - filled from user input] ## ÆtherLight Features - Voice-to-code transcription (backtick key) - Sprint management with Git workflow - Pattern matching to prevent hallucinations - Automated code analysis - Enforced development standards ## Development Standards ### Git Workflow 1. All work in feature branches 2. PRs required for master 3. Semantic commit messages 4. Code review before merge ### Code Standards - TypeScript\/JavaScript: ESLint + Prettier - Tests required for new features - Documentation for public APIs - No console.log in production ## Available Commands - `\/initialize` - Set up project - `\/sprint-plan` - Plan and create sprint - `\/code-analyze` - Analyze codebase - `\/publish` - Release new version ## Project-Specific Rules [Customized based on user requirements] EOF } ``` #### `.claude\/settings.json` ```json { "version": "1.0.0", "workflow": { "requirePR": true, "protectedBranch": "master", "requireReview": true, "semanticCommits": true }, "analysis": { "schedule": "weekly", "autoFix": false, "blockOnCritical": true }, "sprint": { "duration": "2 weeks", "ceremonies": ["planning", "standup", "review", "retro"] } } ``` #### `.claude\/settings.local.json` ```json { "permissions": { "allowFileCreation": true, "allowFileModification": true, "allowGitOperations": true, "allowTerminalCommands": true }, "features": { "voiceIntegration": true, "sprintManagement": true, "codeAnalysis": true, "patternLibrary": true } } ``` #### `.aetherlight\/config.json` ```json { "project_initialized": true, "initialization_date": "[TIMESTAMP]", "ai_assistant_integration": { "claude_md": true, "commands": true, "skills": true, "patterns": true }, "project_metadata": { "type": "[DETECTED_TYPE]", "frameworks": "[DETECTED_FRAMEWORKS]", "language": "[PRIMARY_LANGUAGE]" } } ``` #### Command Files Create `.claude\/commands\/sprint-status.md`: ```markdown --- name: sprint-status description: Display current sprint progress and task status --- # Sprint Status Command Show the current sprint's tasks and their completion status. ## Usage Read the latest sprint file from `sprints\/` directory and display: - Sprint name and duration - Task list with status indicators - Completion percentage - Blocked tasks - Next actions ## Implementation 1. Find the most recent SPRINT_*.toml file 2. Parse the TOML structure 3. Display tasks grouped by phase 4. Show progress bars for each phase 5. Highlight blocked or at-risk items ``` Create `.claude\/commands\/update-task.md`: ```markdown --- name: update-task description: Update task status in the current sprint --- # Update Task Command Modify a task's status in the active sprint TOML file. ## Usage `\/update-task [task-id] [status]` Status options: - pending - in_progress - completed - blocked ## Implementation 1. Read current sprint TOML 2. Find task by ID 3. Update status field 4. Write back to TOML 5. Commit change with semantic message ``` Create `.claude\/commands\/view-patterns.md`: ```markdown --- name: view-patterns description: Browse and search the pattern library --- # View Patterns Command Browse available code patterns and templates. ## Usage `\/view-patterns [category]` Categories: - auth (authentication patterns) - database (data access patterns) - api (API endpoint patterns) - ui (UI component patterns) ## Implementation 1. List patterns in `.aetherlight\/patterns\/` 2. Show pattern description and usage 3. Provide copy-paste ready code 4. Include best practices notes ``` ### 4. Set Up Git Workflow #### Initialize Branches ```bash # Ensure on master git checkout -b master 2>\/dev\/null || git checkout master # Create development branches git checkout -b develop git push -u origin develop # Create initial feature branch git checkout -b feature\/initial-setup ``` #### Configure Git Hooks Create `.githooks\/pre-commit`: ```bash #!\/bin\/bash # Run tests before commit npm test || exit 1 # Run linter npm run lint || exit 1 # Check for sensitive data grep -r "password\|secret\|api_key" --exclude-dir=.git . && { echo "Potential secrets found!" exit 1 } ``` ### 5. Initialize Pattern Library Create pattern templates in `.aetherlight\/patterns\/`: #### Authentication Pattern `.aetherlight\/patterns\/auth\/jwt-auth.md`: ```markdown --- name: JWT Authentication category: auth tags: [jwt, authentication, security] --- # JWT Authentication Pattern ## When to Use - Stateless authentication - API authentication - Multi-service architectures ## Implementation \`\`\`typescript \/\/ Token generation function generateToken(user: User): string { return jwt.sign( { id: user.id, email: user.email }, process.env.JWT_SECRET, { expiresIn: '24h' } ); } \/\/ Token verification middleware function verifyToken(req, res, next) { const token = req.headers['authorization']?.split(' ')[1]; if (!token) return res.status(401).json({ error: 'No token provided' }); jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => { if (err) return res.status(403).json({ error: 'Invalid token' }); req.user = decoded; next(); }); } \`\`\` ## Best Practices - Store secrets in environment variables - Use refresh tokens for long sessions - Implement token rotation - Add rate limiting ``` #### Database Pattern `.aetherlight\/patterns\/database\/repository.md`: ```markdown --- name: Repository Pattern category: database tags: [repository, data-access, clean-architecture] --- # Repository Pattern ## When to Use - Abstracting data access logic - Testing with mock data - Switching between databases ## Implementation \`\`\`typescript interface IUserRepository { findById(id: string): Promise; findByEmail(email: string): Promise; create(data: CreateUserDto): Promise; update(id: string, data: UpdateUserDto): Promise; delete(id: string): Promise; } class UserRepository implements IUserRepository { async findById(id: string): Promise { return await db.user.findUnique({ where: { id } }); } async create(data: CreateUserDto): Promise { return await db.user.create({ data }); } \/\/ ... other methods } \`\`\` ## Best Practices - Keep repositories focused on single entities - Use DTOs for data transfer - Implement proper error handling - Add transaction support ``` #### API Pattern `.aetherlight\/patterns\/api\/rest-controller.md`: ```markdown --- name: RESTful Controller category: api tags: [rest, api, controller] --- # RESTful Controller Pattern ## When to Use - Building REST APIs - CRUD operations - Resource-based endpoints ## Implementation \`\`\`typescript class UserController { constructor(private userService: UserService) {} async getAll(req: Request, res: Response) { try { const users = await this.userService.findAll(); return res.json(users); } catch (error) { return res.status(500).json({ error: error.message }); } } async getOne(req: Request, res: Response) { try { const user = await this.userService.findById(req.params.id); if (!user) return res.status(404).json({ error: 'User not found' }); return res.json(user); } catch (error) { return res.status(500).json({ error: error.message }); } } \/\/ POST, PUT, DELETE methods... } \`\`\` ## Best Practices - Use proper HTTP status codes - Implement pagination for lists - Add request validation - Include error details in development only ``` ### 6. Create Initial Sprint Generate `sprints\/SPRINT_INITIAL.toml`: ```toml [sprint] name = "Initial Setup Sprint" type = "setup" goals = [ "Repository structure", "Development environment", "CI\/CD pipeline", "Documentation" ] [[phases]] id = 1 name = "Foundation" tasks = [ "Create folder structure", "Set up Git workflow", "Configure linting", "Write README" ] [[phases]] id = 2 name = "Integration" tasks = [ "VS Code configuration", "Install ÆtherLight extension", "Configure voice commands", "Test workflow" ] ``` ### 6. VS Code\/Cursor Integration #### `.vscode\/settings.json` ```json { "aetherlight.enabled": true, "aetherlight.features": { "voice": true, "sprint": true, "codeAnalysis": true, "autoUpdate": true }, "editor.formatOnSave": true, "files.exclude": { "**\/.git": true, "**\/node_modules": true, "**\/dist": true } } ``` #### `.vscode\/extensions.json` ```json { "recommendations": [ "aetherlight.aetherlight", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode" ] } ``` ### 7. Documentation Templates #### `README.md` ```markdown # [Project Name] > Powered by ÆtherLight 🚀 ## Overview [Project description] ## Setup \`\`\`bash # Clone repository git clone [repo-url] # Install dependencies npm install # Install ÆtherLight globally npm install -g aetherlight@latest # Open in VS Code\/Cursor code . \`\`\` ## Development Workflow ### Starting Work 1. Pull latest: `git pull origin develop` 2. Create branch: `git checkout -b feature\/[name]` 3. Open ÆtherLight: Press backtick (`) 4. Voice command: "Start working on [feature]" ### Committing - Use semantic commits: `feat:`, `fix:`, `docs:`, etc. - ÆtherLight handles commit messages ### Code Analysis - Voice: "Analyze my code" - Command: `\/code-analyze` ### Sprint Planning - Voice: "Plan next sprint" - Command: `\/sprint-plan` ## Project Structure \`\`\` . ├── .claude\/ # ÆtherLight configuration ├── sprints\/ # Sprint definitions ├── src\/ # Source code ├── tests\/ # Test files ├── docs\/ # Documentation └── analysis\/ # Code analysis reports \`\`\` ``` ### 8. Protection Rules #### `PROTECTED.md` ```markdown # Protected Code Policy ## What Cannot Be Changed (After Release) ### Core Functions - Function signatures in published APIs - Database schemas without migration - Authentication logic - Payment processing ### How to Modify Protected Code 1. **Refactoring Only** - Create `refactor\/[name]` branch - Maintain exact same interface - All tests must pass - Requires 2 reviews 2. **Bug Fixes** - Create `fix\/[issue]` branch - Minimal change principle - Add regression test - Document in CHANGELOG 3. **New Features** - New code only (don't modify existing) - Create `feature\/[name]` branch - Extend, don't replace ## Enforcement Protected files are marked with: \`\`\`typescript \/** * @protected * @since v1.0.0 * Modification requires refactor branch and review *\/ \`\`\` ``` ### 9. User Onboarding #### Interactive Setup ```typescript \/\/ The skill prompts for: const projectConfig = { name: await ask("Project name?"), type: await ask("Project type? (web\/api\/desktop\/library)"), language: await ask("Primary language? (ts\/js\/python\/rust)"), team: await ask("Team size? (solo\/small\/large)"), workflow: await ask("Workflow preference? (agile\/kanban\/custom)") }; \/\/ Customizes setup based on answers ``` ### 10. Validation #### Ensure Setup Complete ```bash # Check all required files exist required_files=( ".claude\/CLAUDE.md" ".claude\/settings.json" "README.md" ".gitignore" "sprints\/SPRINT_INITIAL.toml" ) for file in "${required_files[@]}"; do [ -f "$file" ] || echo "Missing: $file" done # Verify Git setup git remote -v || echo "No remote configured" git branch --list || echo "No branches created" # Test ÆtherLight aetherlight --version || echo "ÆtherLight not installed" ``` ## Success Criteria Initialization succeeds when: - [ ] All directories created - [ ] Configuration files in place - [ ] Git workflow configured - [ ] VS Code integrated - [ ] Initial sprint created - [ ] Documentation complete - [ ] User can start development ## Next Steps After initialization: 1. Run `\/sprint-plan` to plan first real sprint 2. Run `\/code-analyze` to baseline code quality 3. Create first feature branch 4. Start development with voice commands