ai-qakit 1.0.0

package/templates/.claude/statusline.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+# Custom Claude Code statusline
+# Theme: minimal | Colors: true | Features: git, model, devkit
+
+input=$(cat)
+
+# ---- color helpers (force colors for Claude Code) ----
+use_color=1
+[ -n "$NO_COLOR" ] && use_color=0
+
+rst() { if [ "$use_color" -eq 1 ]; then printf '\033[0m'; fi; }
+
+# ---- modern sleek colors ----
+model_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;147m'; fi; }  # light purple
+devkit_version_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;214m'; fi; } # orange
+git_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;150m'; fi; }
+update_color() { if [ "$use_color" -eq 1 ]; then printf '\033[38;5;208m'; fi; } # bright orange
+
+# ---- detect jq ----
+HAS_JQ=0
+command -v jq >/dev/null 2>&1 && HAS_JQ=1
+
+# ---- extract data ----
+if [ "$HAS_JQ" -eq 1 ]; then
+  model_name=$(echo "$input" | jq -r '.model.display_name // "Claude"' 2>/dev/null)
+else
+  model_name=$(echo "$input" | grep -o '"display_name"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)"$/\1/')
+  [ -z "$model_name" ] && model_name="Claude"
+fi
+
+# ---- git ----
+git_branch=""
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  git_branch=$(git branch --show-current 2>/dev/null || git rev-parse --short HEAD 2>/dev/null)
+fi
+
+# ---- time helpers ----
+to_epoch() {
+  local ts="$1"
+  if command -v gdate >/dev/null 2>&1; then gdate -d "$ts" +%s 2>/dev/null && return; fi
+  date -u -j -f "%Y-%m-%dT%H:%M:%S%z" "${ts/Z/+0000}" +%s 2>/dev/null && return
+  python3 - "$ts" <<'PY' 2>/dev/null
+import sys, datetime
+s=sys.argv[1].replace('Z','+00:00')
+print(int(datetime.datetime.fromisoformat(s).timestamp()))
+PY
+}
+
+# ---- ensure ccusage is installed ----
+if ! command -v ccusage >/dev/null 2>&1; then
+  # Install ccusage silently in background if npm is available
+  if command -v npm >/dev/null 2>&1; then
+    npm install -g ccusage >/dev/null 2>&1 &
+  fi
+fi
+
+# ---- get plan usage from ccusage ----
+session_reset="" session_pct=0 session_cost=""
+if command -v ccusage >/dev/null 2>&1 && [ "$HAS_JQ" -eq 1 ]; then
+  blocks_output=""
+  if command -v timeout >/dev/null 2>&1; then
+    blocks_output=$(timeout 3s ccusage blocks --json 2>/dev/null)
+  elif command -v gtimeout >/dev/null 2>&1; then
+    blocks_output=$(gtimeout 3s ccusage blocks --json 2>/dev/null)
+  else
+    blocks_output=$(ccusage blocks --json 2>/dev/null)
+  fi
+
+  if [ -n "$blocks_output" ]; then
+    active_block=$(echo "$blocks_output" | jq -c '.blocks[] | select(.isActive == true)' 2>/dev/null | head -n1)
+    if [ -n "$active_block" ]; then
+      # Session timing
+      end_time_str=$(echo "$active_block" | jq -r '.endTime // empty')
+      start_time_str=$(echo "$active_block" | jq -r '.startTime // empty')
+      block_cost=$(echo "$active_block" | jq -r '.costUSD // empty')
+      block_tokens=$(echo "$active_block" | jq -r '.totalTokens // 0')
+
+      if [ -n "$end_time_str" ] && [ -n "$start_time_str" ]; then
+        now_sec=$(date +%s)
+        end_sec=$(to_epoch "$end_time_str")
+        remaining=$((end_sec - now_sec))
+
+        if [ "$remaining" -gt 0 ]; then
+          rh=$((remaining / 3600))
+          rm=$(((remaining % 3600) / 60))
+          session_reset="${rh}h ${rm}m"
+        else
+          session_reset="expired"
+        fi
+      fi
+    fi
+  fi
+fi
+
+# ---- version check (cached, once per hour) ----
+update_available=""
+if [ -n "$AI_DEVKIT_VERSION" ]; then
+  CACHE_FILE="/tmp/.ai-devkit-version-cache"
+  CACHE_MAX_AGE=3600  # 1 hour in seconds
+
+  # Check if cache exists and is fresh
+  check_cache() {
+    if [ -f "$CACHE_FILE" ]; then
+      cache_age=$(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0)))
+      [ "$cache_age" -lt "$CACHE_MAX_AGE" ] && return 0
+    fi
+    return 1
+  }
+
+  # Fetch latest version (background, non-blocking)
+  fetch_latest() {
+    # Use gtimeout (macOS with coreutils) or timeout (Linux), fallback to no timeout
+    timeout_cmd=""
+    command -v gtimeout >/dev/null 2>&1 && timeout_cmd="gtimeout 5"
+    command -v timeout >/dev/null 2>&1 && timeout_cmd="timeout 5"
+    ($timeout_cmd npm view @enouvo/ai-devkit version 2>/dev/null > "$CACHE_FILE.tmp" && mv "$CACHE_FILE.tmp" "$CACHE_FILE") &
+  }
+
+  if check_cache; then
+    latest_version=$(cat "$CACHE_FILE" 2>/dev/null | tr -d '[:space:]')
+  else
+    fetch_latest
+    latest_version=""
+  fi
+
+  # Compare versions if we have latest
+  if [ -n "$latest_version" ] && [ "$latest_version" != "$AI_DEVKIT_VERSION" ]; then
+    # Simple version comparison (assumes semver)
+    if [ "$(printf '%s\n' "$AI_DEVKIT_VERSION" "$latest_version" | sort -V | tail -n1)" = "$latest_version" ]; then
+      update_available=" $(update_color)(New version available!)$(rst)"
+    fi
+  fi
+fi
+
+# ---- render: git, model, devkit ----
+if [ -n "$git_branch" ]; then
+  printf '  🌿 %s%s%s' "$(git_color)" "$git_branch" "$(rst)"
+fi
+printf '  🤖 %s%s%s' "$(model_color)" "$model_name" "$(rst)"
+if [ -n "$AI_DEVKIT_VERSION" ]; then
+  printf '  🧰 %sDevKit v%s%s%s' "$(devkit_version_color)" "$AI_DEVKIT_VERSION" "$(rst)" "$update_available"
+fi
+
+# ---- check if model is Claude (not GPT or Gemini) ----
+is_claude_model=1
+model_lower=$(echo "$model_name" | tr '[:upper:]' '[:lower:]')
+case "$model_lower" in
+  *gpt*|*gemini*) is_claude_model=0 ;;
+esac
+
+# ---- render Line 2: session usage (Claude models only) ----
+has_usage=0
+
+# Session info from ccusage (only for Claude models)
+if [ "$is_claude_model" -eq 1 ] && [ -n "$session_reset" ]; then
+  [ "$has_usage" -eq 0 ] && printf '\n    ' && has_usage=1
+  printf '⏱️  Resets in %s%s%s' \
+    "$(label_color)" "$session_reset" "$(rst)"
+fi
+
+printf '\n'

package/templates/.claude/workflows/api-testing-workflow.md

@@ -0,0 +1,36 @@
+# API Testing Workflow
+
+## Overview
+Comprehensive workflow for API testing.
+
+## Workflow Steps
+
+### 1. Analyze API
+- Review API specification
+- Identify endpoints
+- Map authentication
+- Note dependencies
+
+### 2. Design Tests
+- Create test cases per endpoint
+- Cover CRUD operations
+- Include validation tests
+- Plan auth tests
+
+### 3. Implement Tests
+- Write API tests
+- Set up test data
+- Configure environments
+- Add assertions
+
+### 4. Execute Tests
+- Run against target environment
+- Validate responses
+- Check performance
+- Log results
+
+### 5. Contract Testing
+- Define contracts
+- Verify provider
+- Test consumer
+- Publish to broker

package/templates/.claude/workflows/bug-investigation-workflow.md

@@ -0,0 +1,42 @@
+# Bug Investigation Workflow
+
+## Overview
+Systematic approach to investigating and resolving bugs.
+
+## Workflow Steps
+
+### 1. Gather Information
+- Read bug report
+- Collect logs and screenshots
+- Identify affected version/environment
+- Note reproduction steps
+
+### 2. Reproduce the Bug
+- Follow reported steps
+- Try variations
+- Document exact reproduction
+- Note frequency
+
+### 3. Isolate the Problem
+- Identify affected component
+- Check recent changes
+- Review related code
+- Narrow down scope
+
+### 4. Root Cause Analysis
+- Apply 5 Whys technique
+- Trace code execution
+- Check data flow
+- Identify root cause
+
+### 5. Document Findings
+- Write investigation report
+- Suggest fixes
+- Identify prevention measures
+- Update bug ticket
+
+### 6. Verify Fix
+- Test the fix
+- Check for regressions
+- Verify in all environments
+- Close bug ticket

package/templates/.claude/workflows/development-rules.md

@@ -0,0 +1,366 @@
+# Development Rules
+
+<!--
+AI TEMPLATE INSTRUCTIONS:
+- Replace all {{PLACEHOLDER}} values with project-specific content
+- Delete sections not applicable to the project
+- Link to existing coding standards documents where available
+- Remove this instruction block after customization
+-->
+
+> **Core Principles**: YAGNI (You Aren't Gonna Need It) · KISS (Keep It Simple, Stupid) · DRY (Don't Repeat Yourself)
+
+---
+
+## Quick Reference
+
+| Rule | Guideline |
+|------|-----------|
+| **File Size** | < {{MAX_FILE_LINES}} lines (target: {{TARGET_FILE_LINES}}) |
+| **Function Size** | < {{MAX_FUNCTION_LINES}} lines |
+| **Nesting Depth** | Max {{MAX_NESTING_DEPTH}} levels |
+| **Parameters** | Max {{MAX_PARAMS}} per function |
+| **Commit Style** | {{COMMIT_STYLE}} |
+
+---
+
+## 1. Code Organization
+
+### File Size Management
+
+<!--
+AI GUIDANCE: Adjust limits based on project complexity.
+Typical ranges: 200-300 target, 500 max.
+-->
+
+- **Target**: Keep files under {{TARGET_FILE_LINES}} lines
+- **Hard Limit**: {{MAX_FILE_LINES}} lines (must refactor if exceeded)
+- **Exception**: Auto-generated files (clearly marked)
+
+**When files grow too large:**
+1. Extract utility functions to `{{UTILS_PATH}}/`
+2. Split into focused components/modules
+3. Use composition over inheritance
+4. Create dedicated service classes for business logic
+
+### File Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| **Source Files** | {{FILE_NAMING_CONVENTION}} | `{{FILE_EXAMPLE}}` |
+| **Test Files** | Match source + `.test`/`.spec` | `{{TEST_FILE_EXAMPLE}}` |
+| **Constants** | `*.constants.{{EXT}}` | `app.constants.ts` |
+| **Types** | `*.types.{{EXT}}` | `user.types.ts` |
+
+---
+
+## 2. Code Quality Standards
+
+### Constants - No Magic Numbers/Strings
+
+<!--
+AI GUIDANCE: Always enforce this rule.
+Magic values make code hard to maintain and understand.
+-->
+
+```{{PRIMARY_LANGUAGE}}
+// ❌ Bad - Magic numbers and strings
+if (user.age >= 18) { ... }
+if (status === 'active') { ... }
+setTimeout(callback, 3600000);
+
+// ✅ Good - Named constants
+// {{CONSTANTS_PATH}}
+export const MINIMUM_ADULT_AGE = 18;
+export const USER_STATUS = {
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  PENDING: 'pending',
+} as const;
+export const ONE_HOUR_MS = 60 * 60 * 1000;
+
+// Usage
+if (user.age >= MINIMUM_ADULT_AGE) { ... }
+if (status === USER_STATUS.ACTIVE) { ... }
+setTimeout(callback, ONE_HOUR_MS);
+```
+
+### Utility Functions - Promote Reusability
+
+```{{PRIMARY_LANGUAGE}}
+// ❌ Bad - Duplicated logic
+// file1.{{EXT}}
+const fullName = `${user.firstName} ${user.lastName}`.trim();
+// file2.{{EXT}}
+const displayName = `${person.firstName} ${person.lastName}`.trim();
+
+// ✅ Good - Utility function
+// {{UTILS_PATH}}/string.utils.{{EXT}}
+export function formatFullName(firstName: string, lastName: string): string {
+  return `${firstName} ${lastName}`.trim();
+}
+```
+
+### Naming Conventions
+
+```{{PRIMARY_LANGUAGE}}
+// ❌ Bad - Abbreviated/unclear names
+const usr = getUser();
+const btn = document.getElementById('submit');
+const idx = items.findIndex(i => i.id === targetId);
+const val = calculateTotal();
+const cb = () => console.log('done');
+
+// ✅ Good - Descriptive names
+const currentUser = getUser();
+const submitButton = document.getElementById('submit');
+const targetIndex = items.findIndex(item => item.id === targetId);
+const totalAmount = calculateTotal();
+const onCompleteCallback = () => console.log('done');
+```
+
+### Error Handling
+
+```{{PRIMARY_LANGUAGE}}
+// ✅ Always use try-catch for fallible operations
+try {
+  const result = await riskyOperation();
+  return result;
+} catch (error) {
+  logger.error('Operation failed', { error, context });
+  throw new {{ERROR_CLASS}}('User-friendly message');
+}
+```
+
+---
+
+## 3. Task Management
+
+<!--
+AI GUIDANCE: Include if project uses task-based development.
+Adjust folder structure to match project conventions.
+-->
+
+### Task Folder Structure
+
+```
+{{TASKS_PATH}}/{TASK-ID}/
+├── README.md           # Task overview
+├── requirements.md     # Requirements document
+├── plan/
+│   └── plan.md         # Implementation plan
+└── reports/            # All reports
+    └── {description}-{YYMMDD}.md
+```
+
+**Rules:**
+- Use existing task folders - never create duplicates
+- All reports go in `{{TASKS_PATH}}/{TASK-ID}/reports/`
+- Report naming: `{description}-{YYMMDD}.md`
+
+---
+
+## 4. Git Workflow
+
+### Commit Messages
+
+<!--
+AI GUIDANCE: Use Conventional Commits format.
+Adjust types based on project needs.
+-->
+
+```
+{{COMMIT_TYPE}}({{SCOPE}}): {{DESCRIPTION}}
+
+# Types
+feat:     New feature (minor version bump)
+fix:      Bug fix (patch version bump)
+docs:     Documentation only
+style:    Formatting, no code change
+refactor: Code restructuring
+test:     Adding/updating tests
+chore:    Maintenance tasks
+perf:     Performance improvements
+
+# Examples
+feat(auth): add OAuth2 login support
+fix(api): handle null response from payment gateway
+docs(readme): update installation instructions
+refactor(user): extract validation logic to separate module
+```
+
+### Pre-Commit Checklist
+
+- [ ] Code compiles without errors
+- [ ] Linting passes (`{{LINT_COMMAND}}`)
+- [ ] No syntax errors
+- [ ] No hardcoded secrets or credentials
+- [ ] Meaningful commit message
+
+### Pre-Push Checklist
+
+- [ ] All tests pass (`{{TEST_COMMAND}}`)
+- [ ] No failing tests ignored
+- [ ] No `.env` files or secrets committed
+- [ ] Branch is up to date with {{DEFAULT_BRANCH}}
+
+---
+
+## 5. Security Rules
+
+### Never Commit
+
+<!--
+AI GUIDANCE: Always enforce these rules strictly.
+-->
+
+| Type | Examples |
+|------|----------|
+| **Secrets** | API keys, tokens, passwords |
+| **Environment Files** | `.env`, `.env.local`, `.env.production` |
+| **Credentials** | Database connection strings, SSH keys |
+| **Personal Data** | PII, user data exports |
+
+### Required Practices
+
+- Use environment variables for all secrets
+- Add sensitive patterns to `.gitignore`
+- Use secret scanning in CI/CD
+- Rotate credentials if accidentally committed
+
+---
+
+## 6. Testing Requirements
+
+### Coverage Targets
+
+| Type | Minimum |
+|------|---------|
+| **Unit Tests** | {{UNIT_COVERAGE}}% |
+| **Integration Tests** | {{INTEGRATION_COVERAGE}}% |
+| **Overall** | {{OVERALL_COVERAGE}}% |
+
+### Testing Rules
+
+- Write tests for new features before merging
+- Never skip failing tests to pass CI
+- Mock external dependencies
+- Test error scenarios, not just happy paths
+- Run full test suite before push
+
+---
+
+## 7. Code Review Standards
+
+### Before Requesting Review
+
+- [ ] Self-reviewed changes
+- [ ] Tests added/updated
+- [ ] Documentation updated (if needed)
+- [ ] No commented-out code
+- [ ] No TODO without ticket reference
+
+### Review Focus Areas
+
+| Priority | Focus |
+|----------|-------|
+| **High** | Security vulnerabilities, data handling |
+| **High** | Logic correctness, edge cases |
+| **Medium** | Performance implications |
+| **Medium** | Code readability, maintainability |
+| **Low** | Style consistency (if not auto-formatted) |
+
+---
+
+## 8. Documentation Rules
+
+### When to Update Docs
+
+- [ ] New feature implemented
+- [ ] API endpoint added/changed
+- [ ] Configuration changed
+- [ ] Breaking changes introduced
+- [ ] Bug fix with user impact
+
+### Documentation Locations
+
+| Type | Location |
+|------|----------|
+| **API Reference** | `{{API_DOCS_PATH}}` |
+| **Architecture** | `{{ARCHITECTURE_DOCS_PATH}}` |
+| **User Guide** | `{{USER_DOCS_PATH}}` |
+| **Code Standards** | `{{STANDARDS_PATH}}` |
+
+---
+
+## 9. Implementation Rules
+
+### Do
+
+- Follow established architectural patterns
+- Handle edge cases and error scenarios
+- Write clean, readable, maintainable code
+- Update existing files directly (no "enhanced" copies)
+- Implement real code (no mocks/simulations in production)
+
+### Don't
+
+- Over-engineer solutions (YAGNI)
+- Create duplicate functionality
+- Ignore existing patterns in codebase
+- Skip error handling
+- Leave debug code in production
+
+---
+
+## 10. Tool Usage
+
+<!--
+AI GUIDANCE: Include relevant tools for the project.
+Remove or add based on project stack.
+-->
+
+### CLI Tools
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| **{{TOOL_1}}** | `{{TOOL_1_CMD}}` | {{TOOL_1_PURPOSE}} |
+| **{{TOOL_2}}** | `{{TOOL_2_CMD}}` | {{TOOL_2_PURPOSE}} |
+| **{{TOOL_3}}** | `{{TOOL_3_CMD}}` | {{TOOL_3_PURPOSE}} |
+
+### Debugging
+
+```bash
+# {{DEBUG_TOOL_1}}
+{{DEBUG_COMMAND_1}}
+
+# {{DEBUG_TOOL_2}}
+{{DEBUG_COMMAND_2}}
+```
+
+---
+
+## Related Documentation
+
+- [Code Standards]({{CODE_STANDARDS_PATH}}) - Detailed coding conventions
+- [System Architecture]({{ARCHITECTURE_PATH}}) - Architecture decisions
+- [Testing Guide]({{TESTING_GUIDE_PATH}}) - Testing strategies
+
+---
+
+## Enforcement
+
+### Automated
+
+| Check | Stage | Command |
+|-------|-------|---------|
+| **Linting** | Pre-commit | `{{LINT_COMMAND}}` |
+| **Type Check** | Pre-commit | `{{TYPE_CHECK_COMMAND}}` |
+| **Tests** | Pre-push | `{{TEST_COMMAND}}` |
+| **Security Scan** | CI | `{{SECURITY_SCAN_COMMAND}}` |
+
+### Manual
+
+- Code review required for all PRs
+- Architecture review for significant changes
+- Security review for auth/data handling changes