ai-qakit 1.0.0

package/templates/.claude/README.md

@@ -0,0 +1,428 @@
+# Claude Code Configuration
+
+AI-assisted development toolkit for Claude Code with multi-agent workflows, specialized skills, development commands, and automation hooks.
+
+## Quick Start
+
+```bash
+# 1. Copy to your project
+cp -r ai-devkit/.claude your-project/
+
+# 2. Initialize (deep analysis with 7 agents)
+/devkit:config:init-backend
+
+# 3. Use commands
+/devkit:backend:create-api CRUD for users
+/devkit:spec:implement Add authentication feature
+/devkit:review:code Check for issues
+```
+
+## Structure
+
+```
+.claude/
+├── commands/                       # Slash commands
+│   ├── devkit/                    # AI DevKit commands
+│   │   ├── config/                # Configuration
+│   │   ├── docs/                  # Documentation
+│   │   ├── review/                # Code review
+│   │   ├── spec/                  # Spec-Driven Development
+│   │   ├── spec-lite/             # Lightweight workflow
+│   │   ├── backend/               # Backend commands
+│   │   ├── frontend/              # Frontend commands
+│   │   ├── skill/                 # Skill management
+│   │   ├── fix/                   # Bug fixing
+│   │   └── ...                    # Core commands (ask, scout, solve, etc.)
+│   ├── update-changelog.md        # Project-level commands
+│   └── update-readme.md
+│
+├── agents/                         # Specialized agents
+│
+├── skills/                         # Knowledge modules
+│
+├── doc-templates/                  # Documentation templates
+│
+├── workflows/                      # Development workflows
+│
+├── hooks/                          # Automation hooks
+│
+└── settings.local.json            # Local settings (hooks config)
+```
+
+## Commands
+
+### Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:help` | List all devkit commands with descriptions |
+| `/devkit:ask [question]` | Smart assistant (routes to best approach) |
+| `/devkit:scout` | Codebase exploration |
+
+### Configuration & Setup
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:config:bootstrap` | Bootstrap project configuration |
+| `/devkit:config:init-backend` | Initialize backend commands based on `/devkit:docs:init` output |
+| `/devkit:config:init-frontend` | Initialize frontend project configuration |
+
+### Code Generation
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:create-test [file]` | Generate tests (99% coverage target) |
+| `/devkit:frontend:create-api-integration [resource]` | API integration layer (hooks, services, types) |
+| `/devkit:frontend:create-component [desc]` | React components |
+| `/devkit:frontend:create-form [desc]` | Form components with validation |
+| `/devkit:frontend:create-page [desc]` | Page components |
+| `/devkit:frontend:create-storybook [component]` | Storybook stories for components |
+| `/devkit:frontend:create-table [desc]` | Data table with sorting/filtering/pagination |
+| `/devkit:backend:create-api [desc]` | API endpoints (REST or GraphQL) |
+| `/devkit:backend:create-schema [desc]` | Database models |
+| `/devkit:backend:create-migration [desc]` | Database migrations |
+
+### API Design
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:backend:design-rest-api [version]` | REST API with OpenAPI spec |
+| `/devkit:backend:design-graphql-api [approach]` | GraphQL with schema/resolvers |
+
+### Multi-Agent Workflows
+
+| Command | Description | Agents | Skills |
+|---------|-------------|--------|--------|
+| `/devkit:spec:task [task]` | Create a new task specification | - | - |
+| `/devkit:spec:brainstorm [task-id]` | Brainstorm feature requirements | brainstormer | - |
+| `/devkit:spec:capture-requirement [task-id]` | Analyze requirements and generate knowledge artifacts | - | - |
+| `/devkit:spec:deep-capture-requirement [task-id]` | Promax version with extensive codebase analysis | - | - |
+| `/devkit:spec:update-requirement [task-id] [changes]` | Update existing requirements with new content | - | - |
+| `/devkit:spec:plan [task-id]` | Research and create implementation plan | planner | planning, research |
+| `/devkit:spec:update-plan [task-id] [desc]` | Update existing plan with new requirements or modifications | - | - |
+| `/devkit:spec:implement [task-id]` | Implement from specification | coder, tattletale | planning, backend-dev |
+| `/devkit:spec:test [task-id]` | Create comprehensive tests | tester | testing |
+| `/devkit:spec:cook [task-id]` | Step-by-step feature implementation | - | - |
+| `/devkit:refactor [file]` | Code simplification | code-simplifier, tattletale | code-review |
+| `/devkit:solve [problem]` | Multi-technique problem solving | cunningham | problem-solving |
+
+### Spec Lite (Small Tasks)
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:spec-lite:task [task-id] [desc]` | Create lightweight task with requirements.md |
+| `/devkit:spec-lite:plan [task-id]` | Quick planning (auto-detects stack, finds reusable resources) |
+| `/devkit:spec-lite:update-plan [task-id] [desc]` | Update existing lite plan with new requirements (max 4 phases) |
+| `/devkit:spec-lite:do [task-id]` | Implement all phases, batch code review after all files created |
+| `/devkit:spec-lite:test [task-id]` | Create tests with 100% coverage |
+
+### Quality & Security
+
+| Command | Description | Agents | Skills |
+|---------|-------------|--------|--------|
+| `/devkit:review:code [scope]` | Code review with quality analysis | code-reviewer, tattletale | code-review |
+| `/devkit:review:codebase` | Full codebase review | tattletale, typescript-pro | code-review |
+| `/devkit:fix [issue]` | Fix identified issues | - | - |
+| `/devkit:fix:fast [issue]` | Quick fix for common issues | - | - |
+| `/devkit:fix:hard [issue]` | Complex issue resolution | - | - |
+
+### Research & Analysis
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:analyze [target]` | Comprehensive code analysis (quality, security, performance, architecture) |
+| `/devkit:research [topic]` | Deep research with reports |
+
+### Skill Management
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:skill:add [skill]` | Add new skill to project | - | - |
+| `/devkit:skill:create [name]` | Create new skill template | - | - |
+| `/devkit:skill:optimize [skill]` | Optimize existing skill | - | - |
+
+### Documentation
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:docs:capture-knowledge [entry]` | Generate docs with diagrams | docs-manager | docs-discovery |
+| `/devkit:docs:init` | Initialize doc structure | docs-manager | - |
+| `/devkit:docs:update` | Update existing docs | docs-manager | - |
+| `/devkit:docs:summarize` | Summarize code/docs | docs-manager | - |
+
+### Debugging & Problem Solving
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:debug [issue]` | Systematic 7-step debugging |
+| `/devkit:solve [problem]` | Multi-technique problem solving (5 techniques) |
+
+### Specification (Full)
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:spec:task [task]` | Create a new task specification |
+| `/devkit:spec:brainstorm [task-id]` | Brainstorm feature requirements |
+| `/devkit:spec:capture-requirement [task-id]` | Analyze requirements and generate knowledge artifacts |
+| `/devkit:spec:deep-capture-requirement [task-id]` | Promax version with extensive codebase analysis |
+| `/devkit:spec:update-requirement [task-id] [changes]` | Update existing requirements with new content |
+| `/devkit:spec:plan [task-id]` | Research and create implementation plan |
+| `/devkit:spec:update-plan [task-id] [desc]` | Update existing plan with new requirements or modifications |
+| `/devkit:spec:implement [task-id]` | Implement from specification (testing via `/devkit:spec:test`) |
+| `/devkit:spec:test [task-id]` | Create comprehensive tests with 100% coverage |
+| `/devkit:spec:cook [task-id]` | Step-by-step feature implementation |
+
+### Specification Lite (Small Tasks)
+
+Lightweight workflow for small tasks - no research, max 4 phases, token-efficient.
+
+| Command | Description |
+|---------|-------------|
+| `/devkit:spec-lite:task [task-id] [desc]` | Create lightweight task with requirements.md |
+| `/devkit:spec-lite:plan [task-id]` | Quick planning (auto-detects stack, finds reusable resources) |
+| `/devkit:spec-lite:update-plan [task-id] [desc]` | Update existing lite plan with new requirements (max 4 phases) |
+| `/devkit:spec-lite:do [task-id]` | Implement all phases, batch code review after all files created |
+| `/devkit:spec-lite:test [task-id]` | Create tests with 100% coverage |
+
+**Key Features:**
+- **Simplified structure**: Just `requirements.md` and `plan.md` (no reports/subfolders)
+- **Resource reuse**: Scout finds existing utils/services/patterns to reuse - prevents duplicates
+- **Auto-detect stack**: Automatically detects platform and API approach
+- **Batch code review**: Reviews ALL files at once after implementation complete (not one-by-one)
+- **Separate testing**: Testing handled via `/devkit:spec-lite:test` for focused coverage
+- **Active task tracking**: Maintains `.claude/active-task` for session continuity
+
+## Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `brainstormer` | Requirements gathering and brainstorming |
+| `claude-optimizer` | CLAUDE.md optimization |
+| `code-reviewer` | Code review and quality analysis |
+| `code-simplifier` | Code refactoring and cleanup |
+| `coder` | Feature implementation with verification |
+| `context-manager` | Context and memory management |
+| `cunningham` | Problem-solving specialist |
+| `database-admin` | Database administration and optimization |
+| `debugger` | Systematic debugging and issue resolution |
+| `docs-manager` | Documentation management |
+| `performance-engineer` | Performance optimization and bottleneck analysis |
+| `planner` | Research-backed planning and analysis |
+| `project-manager` | Project oversight and coordination |
+| `quality-engineer` | Testing strategies and edge case detection |
+| `readme-writer` | README generation |
+| `researcher` | Deep research with source analysis |
+| `scout` | Fast parallel codebase exploration |
+| `security-agent` | Security vulnerability analysis |
+| `storage-path-convention` | Storage path conventions and standards |
+| `tattletale-reporter` | Code verification and issue detection |
+| `tester` | Test execution and validation |
+| `typescript-pro` | TypeScript best practices |
+| `ui-ux-designer` | UI/UX design and wireframing |
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| **Core Development** | |
+| `backend-development` | Backend patterns, security, APIs, testing |
+| `frontend-development` | Frontend patterns and best practices |
+| `typescript-pro` | Advanced TypeScript type system |
+| `javascript-pro` | Modern ES2015+ JavaScript |
+| `python-pro` | Python best practices and patterns |
+| **Specialized** | |
+| `ai-multimodal` | Multimodal AI with Google Gemini API |
+| `api-design-principles` | REST/GraphQL API design patterns |
+| `chrome-devtools` | Browser automation and analysis |
+| `databases` | Database patterns and optimization |
+| `document-skills` | Document processing (PDF, DOCX, PPTX, XLSX) |
+| `infra-engineer` | Infrastructure and DevOps |
+| `mobile-development` | Mobile app development |
+| **Quality & Process** | |
+| `code-review` | AI & human review practices |
+| `debugging` | 4-phase systematic debugging |
+| `planning` | Technical solution planning |
+| `problem-solving` | 5 techniques for complex problems |
+| `research` | Systematic research methodology |
+| `sequential-thinking` | Structured multi-step problem solving |
+| `testing` | Comprehensive testing strategies |
+| **Documentation & Tools** | |
+| `docs-discovery` | Documentation discovery patterns |
+| `docs-seeker` | Documentation via llms.txt and context7 |
+| `repomix` | Repository packaging for AI analysis |
+| `command-development` | Command creation patterns |
+
+*27+ specialized skills available covering UI/UX, security, performance, and domain-specific expertise*
+
+## Documentation Templates
+
+| Template | Description |
+|----------|-------------|
+| `code-standards.md` | Coding standards and best practices template |
+| `codebase-summary.md` | Comprehensive codebase overview template |
+| `development-rules.md` | Senior developer engineering best practices |
+| `project-overview-pdr.md` | Project overview in PDR (Project Design Review) format |
+| `project-roadmap.md` | Project roadmap and feature planning template |
+| `system-architecture.md` | System architecture documentation template |
+| `technical-documents.md` | Technical documents index and organization template |
+
+These templates are used by documentation commands (e.g., `/docs:init`, `/docs:update`) to generate consistent, comprehensive project documentation.
+
+## Workflows
+
+| Workflow | Description |
+|----------|-------------|
+| `primary-workflow` | Main development workflow |
+| `development-rules` | Development rules and standards |
+| `documentation-management` | Documentation management workflow |
+| `orchestration-protocol` | Multi-agent orchestration |
+
+## Hooks
+
+Automation hooks that enhance Claude Code behavior. Configured in `settings.local.json`.
+
+| Hook | Event | Description |
+|------|-------|-------------|
+| `executable_force-agent-skills-eval.sh` | UserPromptSubmit | Enforces delegation-first workflow: evaluates agents → skills → manual |
+| `dev-rules-reminder.cjs` | UserPromptSubmit | Injects development rules, modularization guidelines, and catalog commands |
+| `scout-block.cjs` | PreToolUse (Bash\|Glob\|Grep\|Read\|Edit\|Write) | Blocks access to directories in `.scoutignore` |
+
+### Force Agent/Skills Evaluation Hook
+
+Triggered on every user prompt. Injects a mandatory delegation sequence reminder:
+1. **Evaluate Agents** - Scan available subagent_types for matches
+2. **Evaluate Skills** - If no agent fits, scan available skills
+3. **Activate** - Use Task tool or Skill tool based on evaluation
+4. **Implement** - Proceed only after delegation decision
+
+Key rules enforced:
+- Max 3 concurrent agents per wave
+- Each task must be self-contained (no inter-task dependencies)
+- Sub-agents inherit skill awareness
+
+### Dev Rules Reminder Hook
+
+Non-blocking hook triggered on every user prompt (debounced). Injects:
+- Links to development rules workflow file
+- Markdown file organization reminders (plans/, docs/)
+- Catalog generation commands for skills and commands
+- YAGNI, KISS, DRY principle enforcement
+- Modularization guidelines (kebab-case naming, check existing modules)
+
+Automatically skips injection if recently reminded (checks last 150 lines of transcript).
+
+### Scout Block Hook
+
+**Blocking** hook triggered before file and bash operations. Prevents access to:
+- Directories listed in `.claude/.scoutignore` (node_modules, __pycache__, .git, dist, build by default)
+- Bash commands that access blocked directories (cd, ls, cat, etc.)
+
+**Allows**: Build commands (npm build, pnpm build, yarn build, npm run build)
+
+Cross-platform support: Windows (PowerShell), Unix (Bash), WSL.
+
+Configure blocked patterns by editing `.claude/.scoutignore`.
+
+## How Init Works
+
+### `/config:init-backend`
+
+Simplified 7-phase workflow:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    INITIALIZATION FLOW                       │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 1: Run /docs:init (generate project documentation)   │
+│  Phase 2: Extract project config from generated docs        │
+│  Phase 3: Copy backend commands to root folder              │
+│  Phase 4: Clean up API-specific commands (REST/GraphQL)     │
+│  Phase 5: Customize commands for project stack              │
+│  Phase 6: Display final summary                             │
+│  Phase 7: Validation & feedback                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## What Gets Generated
+
+After running `/config:init-backend`:
+
+| Output | Description |
+|--------|-------------|
+| `./docs/*.md` | Project documentation (via `/docs:init`) |
+| Customized commands | Backend commands adapted to project conventions |
+
+## Smart Command Adaptation
+
+After initialization, all commands reference `./docs/` and use YOUR project's:
+- Actual API type and conventions
+- Real endpoints and patterns
+- Existing authentication approach
+- Current ORM and schema patterns
+
+## Troubleshooting
+
+**Commands not following project patterns:**
+- Run `/devkit:docs:init` to regenerate documentation
+- Run `/devkit:config:init-backend` to re-customize commands
+
+**Wrong API type detected:**
+- Check `./docs/codebase-summary.md` for detected API type
+- Re-run initialization if needed
+
+---
+
+## Setup Scripts
+
+The `setup/` directory contains automated installation scripts for Claude Code plugins and MCP servers.
+
+### Quick Install
+
+```bash
+# macOS/Linux - Install all plugins and MCP servers
+./setup/setup.sh
+
+# Windows PowerShell
+.\setup\setup.ps1
+```
+
+### What Gets Installed
+
+| Component | Description |
+|-----------|-------------|
+| **claude-mem** | Persistent memory compression system across sessions |
+| **ccusage** | Usage tracking and cost analysis CLI |
+| **context7** | Up-to-date library documentation (MCP) |
+| **sequential-thinking** | Structured problem-solving (MCP) |
+
+### Script Options
+
+```bash
+# Install specific components
+./setup/setup.sh --plugins    # Plugins only (claude-mem, ccusage)
+./setup/setup.sh --mcp        # MCP servers only (context7, sequential-thinking)
+
+# Diagnostics and troubleshooting
+./setup/setup.sh --status     # Check status of all components
+./setup/setup.sh --diagnose   # Run diagnostics on all components
+./setup/setup.sh --fix        # Auto-fix issues in all components
+```
+
+### Directory Structure
+
+```
+setup/
+├── setup.sh                    # Main entry point (macOS/Linux)
+├── setup.ps1                   # Main entry point (Windows)
+└── dependencies/
+    ├── setup-claude-mem.sh/.ps1      # Persistent memory plugin
+    ├── setup-ccusage.sh/.ps1         # Usage tracking CLI
+    └── setup-mcp-servers.sh/.ps1     # MCP servers installer
+```
+
+### After Installation
+
+1. Start a new Claude Code session to activate the plugins
+2. Use `mem-search` skill to search past sessions
+3. Run `bunx ccusage@latest` to track usage and costs
+4. context7 and sequential-thinking are available as MCP tools