ai-qakit 1.0.0

package/templates/.claude/rules/index.md

@@ -0,0 +1,77 @@
+# Development Rules
+
+> **Senior Developer Engineering Best Practices**
+> This document defines coding standards and best practices that apply across all programming languages and platforms.
+
+---
+
+## Module Index
+
+This guide is organized into focused modules for easier navigation:
+
+| # | Module | Topics |
+|---|--------|--------|
+| 1 | [Core Principles](./01-core-principles.md) | YAGNI, KISS, DRY, SOLID |
+| 2 | [Naming & Constants](./02-naming-and-constants.md) | Naming conventions, magic values, consistency |
+| 3 | [Function Design](./03-function-design.md) | Size, parameters, utils, types, return values |
+| 4 | [Error Handling](./04-error-handling.md) | Errors, logging, security |
+| 5 | [Testing](./05-testing.md) | Test pyramid, best practices, naming |
+| 6 | [Code Quality](./06-code-quality.md) | Documentation, formatting, code review |
+| 7 | [Architecture](./07-architecture.md) | Organization, dependencies, module boundaries |
+| 8 | [Performance & Security](./08-performance-security.md) | Optimization, OWASP, secure coding |
+
+---
+
+## Quick Reference - The 15 Clean Code Rules
+
+1. **Meaningful Names** - Names should tell a story and be searchable
+2. **Single Responsibility** - Functions/classes do ONE thing well
+3. **Keep Functions Small** - Under 30 lines, fit on screen
+4. **Comments Explain Why** - Not what (code shows what)
+5. **DRY** - Extract repeated logic, don't copy-paste
+6. **Proper Error Handling** - Fail safe, use custom errors
+7. **Clear Formatting** - Auto-format on save
+8. **Keep Classes Small** - Under 200 lines
+9. **Strong Types** - Be explicit, avoid `any`
+10. **Minimal Dependencies** - Each is a maintenance burden
+11. **Consistent Patterns** - Same style everywhere
+12. **Testable Code** - TDD, dependency injection
+13. **Clear Return Values** - Explicit types, avoid null
+14. **KISS** - Simple beats clever
+15. **Self-Documenting Code** - Read it aloud
+
+---
+
+## Pre-Commit Checklist
+
+Before committing code, verify:
+
+- [ ] No magic numbers or strings - all values in constants
+- [ ] Descriptive variable and function names
+- [ ] Functions follow single responsibility principle
+- [ ] Proper error handling with meaningful messages
+- [ ] Sensitive data not logged or exposed
+- [ ] Tests written and passing
+- [ ] No code duplication - utils extracted
+- [ ] Code is readable without excessive comments
+- [ ] Security considerations addressed
+- [ ] Performance implications considered
+- [ ] Types are explicit (no `any`)
+- [ ] Dependencies are minimal and justified
+
+---
+
+## Sources & Further Reading
+
+- [15 Clean Code Rules - Dev.to](https://dev.to/hadil/15-delightful-clean-code-rules-that-will-make-your-code-sparkle-30g7)
+- [Clean Code Principles - Caltech](https://pg-p.ctme.caltech.edu/blog/coding/clean-code-principles)
+- [Software Engineering Best Practices 2025](https://zencoder.ai/blog/software-engineering-best-practices)
+- [SOLID, DRY, KISS Principles](https://scalastic.io/en/solid-dry-kiss/)
+- [Naming Conventions Guide](https://www.theserverside.com/feature/A-guide-to-common-variable-naming-conventions)
+- [Error Handling & Logging Checklist](https://www.iansresearch.com/resources/all-blogs/post/security-blog/2023/08/17/error-handling-and-logging-checklist)
+- [Logging Best Practices](https://betterstack.com/community/guides/logging/logging-best-practices/)
+- [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
+- [Unit Testing Best Practices - IBM](https://www.ibm.com/think/insights/unit-testing-best-practices)
+- [Code Documentation Best Practices](https://blog.codacy.com/code-documentation)
+- [SQL Query Optimization - DataCamp](https://www.datacamp.com/blog/sql-query-optimization)
+- [Clean Code by Robert C. Martin](https://www.freecodecamp.org/news/how-to-write-clean-code/)

package/templates/.claude/scripts/README.md

@@ -0,0 +1,153 @@
+# Claude Code Scripts
+
+Centralized utility scripts for Claude Code skills.
+
+## Installation
+
+Install required dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+## resolve_env.py
+
+Centralized environment variable resolver that follows Claude Code's hierarchy.
+
+### Priority Order (Highest to Lowest)
+
+1. **process.env** - Runtime environment variables (HIGHEST)
+2. **PROJECT/.claude/skills/\<skill\>/.env** - Project skill-specific
+3. **PROJECT/.claude/skills/.env** - Project shared across skills
+4. **PROJECT/.claude/.env** - Project global defaults
+5. **~/.claude/skills/\<skill\>/.env** - User skill-specific
+6. **~/.claude/skills/.env** - User shared across skills
+7. **~/.claude/.env** - User global defaults (LOWEST)
+
+### CLI Usage
+
+```bash
+# Resolve a variable for a specific skill
+python ~/.claude/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal
+
+# With verbose output
+python ~/.claude/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal --verbose
+
+# Find all locations where variable is defined
+python ~/.claude/scripts/resolve_env.py GEMINI_API_KEY --find-all
+
+# Show hierarchy for a skill
+python ~/.claude/scripts/resolve_env.py --show-hierarchy --skill ai-multimodal
+
+# Export format for shell sourcing
+eval $(python ~/.claude/scripts/resolve_env.py GEMINI_API_KEY --export)
+```
+
+### Python API Usage
+
+```python
+# Add to sys.path if needed
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path.home() / '.claude' / 'scripts'))
+
+from resolve_env import resolve_env, find_all, show_hierarchy
+
+# Simple resolution
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
+
+# With default value
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal', default='fallback-key')
+
+# With verbose output
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal', verbose=True)
+
+# Find all locations
+locations = find_all('GEMINI_API_KEY', skill='ai-multimodal')
+for description, value, path in locations:
+    print(f"{description}: {value}")
+
+# Show hierarchy
+show_hierarchy(skill='ai-multimodal')
+```
+
+### Integration Pattern
+
+Skills should use this script instead of implementing their own resolution logic:
+
+```python
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+
+# Import centralized resolver
+sys.path.insert(0, str(Path.home() / '.claude' / 'scripts'))
+from resolve_env import resolve_env
+
+# Resolve API key
+api_key = resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
+
+if not api_key:
+    print("Error: GEMINI_API_KEY not found")
+    print("Run: python ~/.claude/scripts/resolve_env.py --show-hierarchy --skill ai-multimodal")
+    sys.exit(1)
+
+# Use api_key...
+```
+
+### Benefits
+
+- **Consistent**: All skills use the same resolution logic
+- **Maintainable**: Single source of truth for hierarchy
+- **Debuggable**: Built-in verbose mode and find-all functionality
+- **Flexible**: Supports both project-local and user-global configs
+- **Clear**: Shows exactly where each value comes from
+
+### Testing
+
+```bash
+# Test without any config files
+python ~/.claude/scripts/resolve_env.py TEST_VAR --verbose
+
+# Test with environment variable
+export TEST_VAR=from-runtime
+python ~/.claude/scripts/resolve_env.py TEST_VAR --verbose
+
+# Test with skill context
+python ~/.claude/scripts/resolve_env.py GEMINI_API_KEY --skill ai-multimodal --find-all
+```
+
+## generate_catalogs.py
+
+Generate YAML catalogs from command and skill data files. Outputs to stdout by default for easy consumption by Claude.
+
+### Usage
+
+```bash
+# Generate skills catalog (outputs to stdout)
+python .claude/scripts/generate_catalogs.py --skills
+
+# Generate commands catalog (outputs to stdout)
+python .claude/scripts/generate_catalogs.py --commands
+
+# Generate both catalogs (outputs to stdout)
+python .claude/scripts/generate_catalogs.py
+
+# Write to file instead of stdout
+python .claude/scripts/generate_catalogs.py --skills --output guide/SKILLS.yaml
+
+# View help
+python .claude/scripts/generate_catalogs.py --help
+```
+
+### Input Files
+
+Located in the same directory as the script:
+- `commands_data.yaml` - Source data for commands
+- `skills_data.yaml` - Source data for skills
+
+### Output
+
+By default, outputs YAML to stdout. Use `--output PATH` to write to a file instead.
+
+**Note:** The script can be run from any directory - it resolves input files relative to the script location.

package/templates/.claude/scripts/commands_data.yaml

@@ -0,0 +1,336 @@
+- argument_hint: ''
+  category: devkit
+  description: Comprehensive code analysis across quality, security, performance,
+    and architecture domains
+  name: devkit:analyze
+  path: devkit/analyze.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: 'Ask questions, get help, solve problems: /ask [your question]'
+  name: devkit:ask
+  path: devkit/ask.md
+  power_level: 0
+- argument_hint:
+  - endpoint-description
+  category: devkit
+  description: Generate API endpoint following project patterns (REST or GraphQL)
+  name: devkit:backend:create-api
+  path: devkit/backend/create-api.md
+  power_level: 0
+- argument_hint:
+  - migration-description
+  category: devkit
+  description: Generate database migration
+  name: devkit:backend:create-migration
+  path: devkit/backend/create-migration.md
+  power_level: 0
+- argument_hint:
+  - model-description
+  category: devkit
+  description: Generate database schema/model definition
+  name: devkit:backend:create-schema
+  path: devkit/backend/create-schema.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:backend:design-graphql-api
+  path: devkit/backend/design-graphql-api.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:backend:design-rest-api
+  path: devkit/backend/design-rest-api.md
+  power_level: 0
+- argument_hint:
+  - user-requirements
+  category: devkit
+  description: Bootstrap a new project step by step
+  name: devkit:config:bootstrap
+  path: devkit/config/bootstrap.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: Initialize backend project commands based on generated documentation
+  name: devkit:config:init-backend
+  path: devkit/config/init-backend.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: 'Initialize frontend project with ultrathink methodology (maximum detail):
+    /init-frontend [optional-context]'
+  name: devkit:config:init-frontend
+  path: devkit/config/init-frontend.md
+  power_level: 0
+- argument_hint:
+  - file-path
+  category: devkit
+  description: Generate tests to achieve 99% coverage for a file
+  name: devkit:create-test
+  path: devkit/create-test.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:debug
+  path: devkit/debug.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:docs:capture-knowledge
+  path: devkit/docs/capture-knowledge.md
+  power_level: 0
+- argument_hint:
+  - project-type
+  category: devkit
+  description: Initialize project documentation structure from templates
+  name: devkit:docs:init
+  path: devkit/docs/init.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:docs:summarize
+  path: devkit/docs/summarize.md
+  power_level: 0
+- argument_hint:
+  - focus-area
+  category: devkit
+  description: Update project documentation based on codebase changes
+  name: devkit:docs:update
+  path: devkit/docs/update.md
+  power_level: 0
+- argument_hint:
+  - issues
+  category: devkit
+  description: Analyze and fix small issues [FAST]
+  name: devkit:fix:fast
+  path: devkit/fix/fast.md
+  power_level: 0
+- argument_hint:
+  - issues
+  category: devkit
+  description: Use subagents to plan and fix hard issues
+  name: devkit:fix:hard
+  path: devkit/fix/hard.md
+  power_level: 0
+- argument_hint:
+  - issues
+  category: devkit
+  description: Analyze and fix small issues
+  name: devkit:fix
+  path: devkit/fix.md
+  power_level: 0
+- argument_hint:
+  - api-endpoint-or-resource
+  category: devkit
+  description: Generate API integration layer (hooks, services, types) following project
+    patterns
+  name: devkit:frontend:create-api-integration
+  path: devkit/frontend/create-api-integration.md
+  power_level: 0
+- argument_hint:
+  - component-description
+  category: devkit
+  description: Generate React component following project patterns
+  name: devkit:frontend:create-component
+  path: devkit/frontend/create-component.md
+  power_level: 0
+- argument_hint:
+  - form-description
+  category: devkit
+  description: Generate form component with validation following project patterns
+  name: devkit:frontend:create-form
+  path: devkit/frontend/create-form.md
+  power_level: 0
+- argument_hint:
+  - page-description
+  category: devkit
+  description: Generate page/route component following project patterns
+  name: devkit:frontend:create-page
+  path: devkit/frontend/create-page.md
+  power_level: 0
+- argument_hint:
+  - component-name-or-path
+  category: devkit
+  description: Generate Storybook stories for components following project patterns
+  name: devkit:frontend:create-storybook
+  path: devkit/frontend/create-storybook.md
+  power_level: 0
+- argument_hint:
+  - table-description
+  category: devkit
+  description: Generate data table component with sorting, filtering, and pagination
+  name: devkit:frontend:create-table
+  path: devkit/frontend/create-table.md
+  power_level: 0
+- argument_hint:
+  - category|command|task description
+  category: devkit
+  description: AI-DevKit usage guide - just type naturally
+  name: devkit:help
+  path: devkit/help.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:refactor
+  path: devkit/refactor.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:research
+  path: devkit/research.md
+  power_level: 0
+- argument_hint:
+  - file-path | folder-path | "code-snippet" | --task task-id | --changed
+  category: devkit
+  description: Review code against development rules and fix violations
+  name: devkit:review:code
+  path: devkit/review/code.md
+  power_level: 0
+- argument_hint:
+  - tasks-or-prompt
+  category: devkit
+  description: Scan & analyze the codebase.
+  name: devkit:review:codebase
+  path: devkit/review/codebase.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:scout
+  path: devkit/scout.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:skill:add
+  path: devkit/skill/add.md
+  power_level: 0
+- argument_hint:
+  - prompt-or-llms-or-github-url
+  category: devkit
+  description: Create a new agent skill
+  name: devkit:skill:create
+  path: devkit/skill/create.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:skill:optimize
+  path: devkit/skill/optimize.md
+  power_level: 0
+- argument_hint:
+  - problem-description
+  category: devkit
+  description: Complex problem solving with multiple techniques
+  name: devkit:solve
+  path: devkit/solve.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:spec:brainstorm
+  path: devkit/spec/brainstorm.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Capture requirements for a task from existing requirement files
+  name: devkit:spec:capture-requirement
+  path: devkit/spec/capture-requirement.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Implement a feature [step by step]
+  name: devkit:spec:cook
+  path: devkit/spec/cook.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Deeply analyze existing requirements, research best practices, and
+    generate knowledge artifacts
+  name: devkit:spec:deep-capture-requirement
+  path: devkit/spec/deep-capture-requirement.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Start coding an existing task (use /spec:test for testing)
+  name: devkit:spec:implement
+  path: devkit/spec/implement.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Research, analyze, and create an implementation plan
+  name: devkit:spec:plan
+  path: devkit/spec/plan.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Create a new task folder structure
+  name: devkit:spec:task
+  path: devkit/spec/task.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Create comprehensive tests with 100% code coverage for an existing
+    task
+  name: devkit:spec:test
+  path: devkit/spec/test.md
+  power_level: 0
+- argument_hint: '[task-id] [description of changes]'
+  category: devkit
+  description: Update an existing implementation plan with new requirements or modifications
+  name: devkit:spec:update-plan
+  path: devkit/spec/update-plan.md
+  power_level: 0
+- argument_hint: '[task-id] [new requirement or changes]'
+  category: devkit
+  description: Update existing task requirements with new content or changes
+  name: devkit:spec:update-requirement
+  path: devkit/spec/update-requirement.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Implement all phases of a lite task (use /spec:test for testing)
+  name: devkit:spec-lite:do
+  path: devkit/spec-lite/do.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Create a quick implementation plan (no research, max 4 phases)
+  name: devkit:spec-lite:plan
+  path: devkit/spec-lite/plan.md
+  power_level: 0
+- argument_hint: ''
+  category: devkit
+  description: ''
+  name: devkit:spec-lite:task
+  path: devkit/spec-lite/task.md
+  power_level: 0
+- argument_hint:
+  - task-id
+  category: devkit
+  description: Run tests and achieve 100% coverage for a lite task, file-by-file
+  name: devkit:spec-lite:test
+  path: devkit/spec-lite/test.md
+  power_level: 0
+- argument_hint: '[task-id] [description of changes]'
+  category: devkit
+  description: Update an existing lite plan with new requirements or modifications
+  name: devkit:spec-lite:update-plan
+  path: devkit/spec-lite/update-plan.md
+  power_level: 0