ai-qakit 1.0.0

package/templates/.cursor/rules/debugger.mdc

@@ -0,0 +1,108 @@
+---
+description: Debugging specialist for systematic issue resolution
+globs:
+  - "**/*"
+---
+
+# Debugger
+
+Systematic debugging specialist for issue resolution.
+
+## Debugging Process
+
+### Phase 1: Reproduce
+1. Understand the issue clearly
+2. Get exact error messages
+3. Reproduce consistently
+4. Document steps to reproduce
+
+### Phase 2: Isolate
+1. Identify affected code path
+2. Check recent changes
+3. Narrow down to specific component
+4. Create minimal reproduction
+
+### Phase 3: Diagnose
+1. Read error messages carefully
+2. Check stack traces
+3. Add strategic logging
+4. Use debugger breakpoints
+5. Check state at each step
+
+### Phase 4: Fix
+1. Understand root cause (not symptoms)
+2. Consider side effects
+3. Implement fix
+4. Verify fix works
+
+### Phase 5: Verify
+1. Run original reproduction
+2. Run related tests
+3. Check for regressions
+4. Remove debug logging
+
+## Common Issues
+
+### Runtime Errors
+- Check null/undefined values
+- Verify type coercion
+- Check array bounds
+- Verify object properties
+
+### Logic Errors
+- Trace data flow
+- Check conditionals
+- Verify loop conditions
+- Check state mutations
+
+### Async Issues
+- Check promise chains
+- Verify await usage
+- Check race conditions
+- Verify cleanup
+
+### Performance Issues
+- Profile execution
+- Check N+1 queries
+- Verify caching
+- Check memory leaks
+
+## Debugging Tools
+
+**JavaScript/TypeScript:**
+- Browser DevTools
+- console.log/table/trace
+- debugger statement
+- Node.js inspector
+
+**Python:**
+- pdb/ipdb
+- print debugging
+- logging module
+- pytest --pdb
+
+## Output Format
+
+```
+ISSUE: [description]
+
+REPRODUCTION:
+1. [step 1]
+2. [step 2]
+
+ROOT CAUSE:
+[explanation]
+
+FIX:
+[what was changed]
+
+VERIFICATION:
+[how it was tested]
+```
+
+## Avoid
+
+- Fixing symptoms, not causes
+- Changing code without understanding
+- Removing error handling
+- Ignoring related issues

package/templates/.cursor/rules/development-rules.mdc

@@ -0,0 +1,208 @@
+---
+description: Development rules and coding best practices - MUST FOLLOW
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+# Development Rules
+
+**CRITICAL:** Follow these rules in ALL circumstances. NON-NEGOTIABLE.
+
+## 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
+
+## Core Principles
+
+- **YAGNI** - Only implement when actually needed
+- **KISS** - If you can't explain to a junior, it's too complex
+- **DRY** - Copy-paste is a code smell
+- **SOLID** - Single responsibility, open/closed, Liskov, interface segregation, dependency inversion
+
+## File Standards
+
+- **Naming**: kebab-case with meaningful names
+- **Size**: Keep under 200 lines, split large files
+- **Structure**: One component/class per file
+
+## Constants - No Magic Numbers/Strings
+
+```typescript
+// BAD
+if (user.age >= 18) { ... }
+if (status === 'active') { ... }
+setTimeout(cb, 3600000);
+
+// GOOD
+export const MINIMUM_ADULT_AGE = 18;
+export const USER_STATUS = { ACTIVE: 'active' } as const;
+export const ONE_HOUR_MS = 60 * 60 * 1000;
+```
+
+## Naming Conventions
+
+```typescript
+// BAD - Shorthand
+const usr, btn, idx, val, arr, cb, e, d, t, n
+
+// GOOD - Descriptive
+const currentUser, submitButton, targetIndex, totalAmount
+const activeUsers, onCompleteCallback, authenticationError
+```
+
+- Functions: Use verbs (`calculateTotal`, `fetchUserData`)
+- Booleans: `is/has/can/should` prefixes (`isActive`, `hasPermission`)
+- Constants: `SCREAMING_SNAKE_CASE`
+
+## Function Design
+
+- Maximum 3 parameters; use objects for more
+- Avoid deep nesting (max 2-3 levels)
+- Return early with guard clauses
+- Each function fits on screen
+
+```typescript
+// BAD - Deep nesting
+function process(order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.paymentValid) { /* ... */ }
+    }
+  }
+}
+
+// GOOD - Guard clauses
+function process(order) {
+  if (!order) return;
+  if (order.items.length === 0) return;
+  if (!order.paymentValid) return;
+  // process...
+}
+```
+
+## Utility Functions
+
+```typescript
+// BAD - Duplicated logic
+const fullName = `${user.firstName} ${user.lastName}`.trim();
+
+// GOOD - Utility function
+// utils/string-utils.ts
+export function formatFullName(firstName: string, lastName: string): string {
+  return `${firstName} ${lastName}`.trim();
+}
+```
+
+## Error Handling
+
+- Always "fail safe" - never "fail open"
+- Create custom error classes
+- Use optional chaining: `obj?.value ?? defaultValue`
+- Never expose stack traces to users
+- Log with context: userId, requestId, timestamp
+
+## Security
+
+- Validate and sanitize ALL user input
+- Use parameterized queries (prevent SQL injection)
+- Encode output (prevent XSS)
+- Never commit secrets
+
+## Testing
+
+- AAA pattern: Arrange, Act, Assert
+- Test pyramid: 70% unit, 20% integration, 10% E2E
+- Don't use mocks just to pass tests
+- Pass dependencies as parameters
+
+## Pre-Commit Checklist
+
+- [ ] No magic numbers/strings
+- [ ] Descriptive names
+- [ ] Single responsibility functions
+- [ ] Proper error handling
+- [ ] No sensitive data logged
+- [ ] Tests passing
+- [ ] Types explicit (no `any`)
+
+## Mandatory Code Review Process
+
+**After completing any implementation, ALWAYS perform code review:**
+
+### Review Checklist
+
+For each file created/modified, verify:
+
+1. **Core Principles**
+   - [ ] YAGNI - No unnecessary features
+   - [ ] KISS - Simple, understandable code
+   - [ ] DRY - No duplicated logic
+   - [ ] SOLID - Proper design principles
+
+2. **Naming & Constants**
+   - [ ] Meaningful, descriptive names
+   - [ ] No magic numbers/strings
+   - [ ] Constants properly defined
+
+3. **Function Design**
+   - [ ] Functions under 30 lines
+   - [ ] Max 3 parameters
+   - [ ] Single responsibility
+   - [ ] Guard clauses used
+
+4. **Error Handling**
+   - [ ] Proper try-catch usage
+   - [ ] No silent failures
+   - [ ] Custom error classes where needed
+
+5. **Code Quality**
+   - [ ] Self-documenting code
+   - [ ] Comments explain "why", not "what"
+   - [ ] Consistent formatting
+
+6. **Security**
+   - [ ] Input validation at boundaries
+   - [ ] No exposed secrets
+   - [ ] Parameterized queries
+
+### Fix Until Compliant
+
+- Review each file against ALL rules above
+- Fix ALL violations found
+- Re-review after fixes
+- **Do NOT proceed until code is fully compliant**
+
+### Severity Levels
+
+- 🔴 **Critical**: Security, data loss risks - FIX IMMEDIATELY
+- 🟠 **Major**: Bugs, maintainability - FIX BEFORE COMMIT
+- 🟡 **Minor**: Style, best practices - FIX WHEN POSSIBLE
+
+## Communication
+
+When unclear, ask:
+- "What's the goal?"
+- "Should I modify existing X or create new Y?"
+- "Would you prefer approach A or B?"
+
+## Important
+
+- NEVER propose changes to code you haven't read
+- Avoid over-engineering - only make requested changes
+- Delete unused code completely - no `// removed` comments
+- Read `./docs/*.md` for project context

package/templates/.cursor/rules/docs-manager.mdc

@@ -0,0 +1,121 @@
+---
+description: Documentation manager for maintaining project documentation
+globs:
+  - "**/*.md"
+  - "**/docs/**"
+  - "**/README*"
+---
+
+# Docs Manager
+
+Documentation manager for maintaining accurate project documentation.
+
+## Responsibilities
+
+1. **Accuracy** - Keep docs in sync with code
+2. **Completeness** - Cover all important aspects
+3. **Clarity** - Write for the audience
+4. **Organization** - Logical structure
+
+## Documentation Types
+
+### README.md
+- Project overview
+- Quick start guide
+- Installation steps
+- Basic usage
+
+### API Documentation
+- Endpoint descriptions
+- Request/response formats
+- Authentication
+- Error codes
+
+### Architecture Docs
+- System overview
+- Component diagrams
+- Data flow
+- Technology choices
+
+### Developer Guides
+- Setup instructions
+- Coding conventions
+- Testing guidelines
+- Deployment process
+
+## Documentation Structure
+
+```
+docs/
+├── project-overview-pdr.md    # Project overview (PDR format)
+├── codebase-summary.md        # Codebase overview
+├── code-standards.md          # Coding standards
+├── system-architecture.md     # System architecture (C4 model)
+├── technical-documents.md     # Technical docs index
+├── development-rules.md       # Development rules & best practices
+├── design-guidelines.md       # Design guidelines
+└── deployment-guide.md        # Deployment instructions
+```
+
+## Documentation Templates
+
+Use templates from `.cursor/doc-templates/`:
+- `project-overview-pdr.md` - Project overview template
+- `codebase-summary.md` - Codebase summary template
+- `code-standards.md` - Coding standards template
+- `system-architecture.md` - Architecture template (C4)
+- `technical-documents.md` - Technical docs template
+- `development-rules.md` - Development rules template
+
+## Writing Standards
+
+**Style:**
+- Clear, concise language
+- Active voice
+- Short paragraphs
+- Code examples
+
+**Format:**
+- Consistent headers
+- Proper markdown
+- Table of contents for long docs
+- Cross-references
+
+**Content:**
+- Keep up to date
+- Include examples
+- Explain "why" not just "what"
+- Document edge cases
+
+## Update Triggers
+
+Update docs when:
+- [ ] New features added
+- [ ] APIs changed
+- [ ] Configuration changed
+- [ ] Dependencies updated
+- [ ] Architecture modified
+
+## Quality Checklist
+
+- [ ] Accurate and current
+- [ ] Code examples work
+- [ ] Links are valid
+- [ ] No typos
+- [ ] Proper formatting
+- [ ] Clear for target audience
+
+## Codebase Analysis
+
+Use `repomix` to generate codebase summary:
+```bash
+# Copy .repomixignore first
+cp .cursor/.repomixignore ./
+
+# Generate codebase compaction
+repomix
+
+# Output: repomix-output.xml → use for docs/codebase-summary.md
+```
+
+Use `@scout` command to search for files needed to complete tasks.

package/templates/.cursor/rules/docs-seeker/docs-seeker.mdc

@@ -0,0 +1,57 @@
+---
+description: Script-first documentation discovery; use to find technical docs (topic-specific, library-wide, or repo-based) and recommend agent distribution using llms.txt. Cursor-compatible (no skill activation needed).
+globs:
+  - "**/*"
+---
+
+# Docs-Seeker (Cursor)
+
+Use scripts to classify queries, fetch context7 llms.txt, and analyze results before manual URL work.
+
+## Primary Workflow (always in this order)
+```bash
+# 1) Detect query type (topic-specific vs general)
+node .cursor/rules/docs-seeker/scripts/detect-topic.js "<user query>"
+
+# 2) Fetch documentation (constructs URLs, handles fallbacks)
+node .cursor/rules/docs-seeker/scripts/fetch-docs.js "<user query>"
+
+# 3) Analyze llms.txt (if multiple URLs)
+cat llms.txt | node .cursor/rules/docs-seeker/scripts/analyze-llms-txt.js -
+```
+
+Scripts handle URL construction, fallback chains, and error handling automatically.
+
+## Execution Principles
+- Scripts first; avoid manual URL construction.
+- Zero-token overhead: scripts run without loading context.
+- Automatic fallback: topic → general → error.
+- Progressive disclosure: load workflows/references only when needed.
+- Agent distribution: follow analyze script recommendations.
+
+## Scripts
+- `detect-topic.js` — classify query; returns `{topic, library, isTopicSpecific}`.
+- `fetch-docs.js` — build context7 URLs; fallback topic→general; outputs llms.txt or error.
+- `analyze-llms-txt.js` — categorize URLs (critical/important/supplementary) and suggest agent distribution.
+
+## Quick Start
+- Topic query: `node .cursor/rules/docs-seeker/scripts/detect-topic.js "<query>"` → `fetch-docs` → read 1-3 URLs directly.
+- General query: detect-topic (`isTopicSpecific: false`) → `fetch-docs` → `analyze-llms-txt` → deploy agents per distribution.
+
+## Workflows (details in `workflows/`)
+- `topic-search.md` — fastest path for feature/component queries.
+- `library-search.md` — comprehensive library docs search.
+- `repo-analysis.md` — fallback when llms.txt unavailable.
+
+## References (in `references/`)
+- `context7-patterns.md` — URL patterns and mappings.
+- `errors.md` — error handling and fallback chain.
+- `advanced.md` — edge cases (multi-language, versions, plugins, conflicts, rate limits).
+
+## Environment
+Scripts load `.env` in order: `process.env` > `.cursor/rules/docs-seeker/.env` > `.cursor/rules/.env`. See `.env.example` in the rule if needed.
+
+## Output Notes
+- Use script recommendations for parallel agents based on URL count.
+- Keep tokens low; prefer topic URLs first, then general, then repo analysis.
+- Cite sources and note fallbacks taken. Include unresolved gaps if docs are missing.

package/templates/.cursor/rules/docs-seeker/references/advanced.md

@@ -0,0 +1,80 @@
+# Advanced Scenarios & Edge Cases
+
+## Multi-Language Documentation
+
+**Challenge:** Docs in multiple languages
+
+**Approach:**
+1. Identify target language from user
+2. Search for language-specific llms.txt
+   - `llms-es.txt`, `llms-ja.txt`
+3. Fallback to English if not found
+4. Note language limitations in report
+
+## Version-Specific Documentation
+
+**Latest (default):**
+- Use base llms.txt URL
+- No version specifier needed
+
+**Specific version:**
+```
+WebSearch: "[library] v[version] llms.txt"
+Check paths:
+- /v2/llms.txt
+- /docs/v2/llms.txt
+- /{version}/llms.txt
+
+For repos:
+git checkout v[version] or tags/[version]
+```
+
+## Framework with Plugins
+
+**Challenge:** Core framework + 50 plugins
+
+**Strategy:**
+1. Focus on core framework first
+2. Ask user which plugins needed
+3. Launch targeted search for specific plugins
+4. Note available plugins in report
+5. Don't document everything upfront
+
+## Documentation Under Construction
+
+**Signs:**
+- New release with incomplete docs
+- Many "Coming soon" pages
+- GitHub issues requesting docs
+
+**Approach:**
+1. Note status upfront in report
+2. Combine available docs + repo analysis
+3. Check tests/ and examples/ directories
+4. Clearly mark "inferred from code"
+5. Link to GitHub issues for updates
+
+## Conflicting Information
+
+**When sources disagree:**
+1. Identify primary official source
+2. Note version differences
+3. Present both approaches with context
+4. Recommend official/latest
+5. Explain why conflict exists
+
+**Priority order:**
+1. Official docs (latest version)
+2. Official docs (versioned)
+3. GitHub README
+4. Community tutorials
+5. Stack Overflow
+
+## Rate Limiting
+
+**If hitting API limits:**
+- Use CONTEXT7_API_KEY from .env
+- Implement exponential backoff
+- Cache results in session
+- Batch requests where possible
+

package/templates/.cursor/rules/docs-seeker/references/context7-patterns.md

@@ -0,0 +1,69 @@
+# context7.com URL Patterns
+
+## Topic-Specific URLs (Priority #1)
+
+**Pattern:** `https://context7.com/{path}/llms.txt?topic={keyword}`
+
+**When to use:** User asks about specific feature/component
+
+**Examples:**
+```
+shadcn/ui date picker
+→ https://context7.com/shadcn-ui/ui/llms.txt?topic=date
+
+Next.js caching
+→ https://context7.com/vercel/next.js/llms.txt?topic=cache
+
+Better Auth OAuth
+→ https://context7.com/better-auth/better-auth/llms.txt?topic=oauth
+
+FFmpeg compression
+→ https://context7.com/websites/ffmpeg_doxygen_8_0/llms.txt?topic=compress
+```
+
+**Benefits:** Returns ONLY relevant docs, 10x faster, minimal tokens
+
+## General Library URLs (Priority #2)
+
+**GitHub repos:** `https://context7.com/{org}/{repo}/llms.txt`
+
+**Websites:** `https://context7.com/websites/{normalized-path}/llms.txt`
+
+## Known Repository Mappings
+
+```
+next.js → vercel/next.js
+nextjs → vercel/next.js
+astro → withastro/astro
+remix → remix-run/remix
+shadcn → shadcn-ui/ui
+shadcn/ui → shadcn-ui/ui
+better-auth → better-auth/better-auth
+```
+
+## Official Site Fallbacks
+
+Use ONLY if context7.com unavailable:
+```
+Astro: https://docs.astro.build/llms.txt
+Next.js: https://nextjs.org/llms.txt
+Remix: https://remix.run/llms.txt
+SvelteKit: https://kit.svelte.dev/llms.txt
+```
+
+## Topic Keyword Normalization
+
+**Rules:**
+- Lowercase
+- Remove special chars
+- Use first word for multi-word topics
+- Max 20 chars
+
+**Examples:**
+```
+"date picker" → "date"
+"OAuth" → "oauth"
+"Server-Side" → "server"
+"caching strategies" → "caching"
+```
+

package/templates/.cursor/rules/docs-seeker/references/errors.md

@@ -0,0 +1,69 @@
+# Error Handling & Fallback Strategies
+
+## Error Codes
+
+**404 Not Found**
+- Topic-specific URL not available
+- Library not on context7.com
+- llms.txt doesn't exist
+
+**Timeout**
+- Network issues
+- Large repository clone
+- Slow API response
+
+**Invalid Response**
+- Malformed llms.txt
+- Empty content
+- Invalid URLs
+
+## Fallback Chain
+
+### For Topic-Specific Queries
+
+```
+1. Try topic-specific URL
+   https://context7.com/{library}/llms.txt?topic={keyword}
+   ↓ 404
+2. Try general library URL
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+3. WebSearch for llms.txt
+   "[library] llms.txt site:[official domain]"
+   ↓ Not found
+4. Repository analysis
+   Use Repomix on GitHub repo
+```
+
+### For General Library Queries
+
+```
+1. Try context7.com
+   https://context7.com/{library}/llms.txt
+   ↓ 404
+2. WebSearch for llms.txt
+   "[library] llms.txt"
+   ↓ Not found
+3. Repository analysis
+   Clone + Repomix
+   ↓ No repo
+4. Research agents
+   Deploy multiple Researcher agents
+```
+
+## Timeout Handling
+
+**Set limits:**
+- WebFetch: 60s
+- Repository clone: 5min
+- Repomix: 10min
+
+**Fail fast:** Don't retry failed methods
+
+## Empty Results
+
+**If llms.txt has 0 URLs:**
+→ Note in report  
+→ Try repository analysis  
+→ Check official website manually
+