ai-qakit 1.0.0

package/templates/.cursor/commands/devkit/docs/capture-knowledge.md

@@ -0,0 +1,252 @@
+# Capture Knowledge
+
+Analyze code from an entry point and generate comprehensive documentation.
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Validate the entry point exists
+2. Show analysis scope and depth
+3. Present documentation outline
+4. Ask for confirmation before generating files
+
+## Ask for Clarification
+
+If anything is unclear, **ask the user**:
+- "What is the exact file path or function name for the entry point?"
+- "What is the primary goal of capturing this knowledge?"
+- "Are there specific areas to focus on or exclude?"
+- "What level of detail do you need (overview vs deep dive)?"
+- "Should I include visual diagrams?"
+
+---
+
+## Step 1: Gather Context
+
+**Collect from user:**
+- Entry point (file, folder, function, API)
+- Why this entry point matters (feature, bug, investigation)
+- Relevant requirements/design docs
+- Desired depth or focus areas
+
+## Step 2: Validate Entry Point
+
+**Determine entry point type:**
+- File: `src/services/auth.ts`
+- Folder: `src/modules/payments/`
+- Function: `calculateTotalPrice`
+- API Endpoint: `POST /api/users`
+
+**Verify existence:**
+```bash
+ls -la [entry-point]
+```
+
+**If not found:**
+- Suggest likely alternatives
+- Ask for clarification
+
+## Step 3: Present Analysis Scope
+
+```
+═══════════════════════════════════════════════
+📋 KNOWLEDGE CAPTURE PLAN
+═══════════════════════════════════════════════
+
+Entry Point: [path/name]
+Type: [File / Folder / Function / API]
+
+Analysis Scope:
+├── Primary file(s)
+├── Direct dependencies (depth 1)
+├── Nested dependencies (depth 2-3)
+└── External integrations
+
+Focus Areas:
+├── Business logic
+├── Data flow
+├── Error handling
+└── Performance considerations
+
+Output: docs/knowledge/[name].md
+
+Proceed with analysis? (Y/n)
+═══════════════════════════════════════════════
+```
+
+## Step 4: Collect Source Context
+
+**For files/modules:**
+- Read primary file and summarize purpose
+- Identify exports and key patterns
+- Extract essential code snippets
+
+**For folders:**
+- List structure
+- Highlight key modules
+- Map relationships
+
+**For functions/APIs:**
+- Capture signature and parameters
+- Document return values
+- Note error handling
+
+## Step 5: Analyze Dependencies
+
+**Build dependency tree (up to depth 3):**
+```
+entry-point
+├── direct-import-1
+│   ├── nested-import-1
+│   └── nested-import-2
+├── direct-import-2
+└── direct-import-3
+```
+
+**Categorize:**
+- Internal imports
+- External packages
+- External services
+- Generated code
+
+## Step 6: Synthesize Explanation
+
+**Document:**
+- Purpose and high-level behavior
+- Core logic and key components
+- Execution flow
+- Error handling approach
+- Performance considerations
+- Security notes
+- Potential improvements
+
+## Step 7: Create Documentation
+
+**Output file:** `docs/knowledge/[entry-point-name].md`
+
+```markdown
+# [Entry Point Name]
+
+## Overview
+
+[Purpose and high-level description]
+
+## Implementation Details
+
+### Core Logic
+
+[Explanation of main functionality]
+
+### Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| [name] | [description] |
+
+### Execution Flow
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Dependencies
+
+### Internal
+
+| Module | Purpose |
+|--------|---------|
+| [path] | [description] |
+
+### External
+
+| Package | Usage |
+|---------|-------|
+| [name] | [description] |
+
+## Visual Diagrams
+
+### Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C{Decision}
+    C -->|Yes| D[Action 1]
+    C -->|No| E[Action 2]
+```
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant A as Client
+    participant B as Server
+    A->>B: Request
+    B-->>A: Response
+```
+
+## Additional Insights
+
+### Edge Cases
+
+- [Edge case 1]
+- [Edge case 2]
+
+### Potential Improvements
+
+- [Improvement 1]
+- [Improvement 2]
+
+### Known Issues
+
+- [Issue 1]
+
+## Metadata
+
+- **Analysis date:** [date]
+- **Entry point:** [path]
+- **Files analyzed:** [count]
+- **Dependencies:** [count]
+```
+
+## Step 8: Resolve Open Questions
+
+**IMPORTANT:** Before completing, ALL open questions MUST be resolved.
+
+1. **Check for open questions** discovered during analysis
+2. **If questions exist:**
+   - Ask user about each question using multiple-choice format
+   - Present recommendation: `**Recommended:** Option X - <reason>`
+   - Update the documentation file with answers
+   - Add clarifications to relevant sections
+3. **Resolution loop:**
+   - Pick most critical question
+   - Ask with clear options
+   - Update docs/knowledge/[name].md with answer
+   - Remove from open list
+4. **Only proceed to summary when ALL questions are resolved**
+
+## Step 9: Summary
+
+```
+═══════════════════════════════════════════════
+✅ KNOWLEDGE CAPTURED
+═══════════════════════════════════════════════
+
+File Created: docs/knowledge/[name].md
+
+Contents:
+├── Overview
+├── Implementation Details
+├── Dependencies ([count])
+├── Visual Diagrams ([count])
+└── Additional Insights
+
+Questions Resolved: [count] during session
+
+Related Entry Points to Explore:
+├── [suggestion 1]
+└── [suggestion 2]
+═══════════════════════════════════════════════
+```

package/templates/.cursor/commands/devkit/docs/init.md

@@ -0,0 +1,153 @@
+---
+description: Initialize project documentation structure from templates
+---
+
+# Docs: Init
+
+Initialize documentation structure using `.cursor/doc-templates/` as the source of truth.
+
+## Usage
+
+`@docs/init [project-type]`
+
+## Templates Reference
+
+All documentation MUST strictly follow these templates located in `.cursor/doc-templates/`:
+
+| Template | Output | Purpose |
+|----------|--------|---------|
+| `project-overview-pdr.md` | `docs/project-overview-pdr.md` | Product Development Requirements |
+| `codebase-summary.md` | `docs/codebase-summary.md` | Technical overview & stats |
+| `code-standards.md` | `docs/code-standards.md` | Project-specific coding conventions |
+| `system-architecture.md` | `docs/system-architecture.md` | System design & architecture |
+| `technical-documents.md` | `docs/technical-documents.md` | C4 diagrams, deployment, setup |
+| `development-rules.md` | `docs/development-rules.md` | Development workflow rules |
+
+## Generated Structure
+
+```
+docs/
+├── project-overview-pdr.md   # From template - fill all {{PLACEHOLDER}}
+├── codebase-summary.md       # From template - fill all {{PLACEHOLDER}}
+├── code-standards.md         # From template - fill all {{PLACEHOLDER}}
+├── system-architecture.md    # From template - fill all {{PLACEHOLDER}}
+├── technical-documents.md    # From template - fill all {{PLACEHOLDER}}
+└── development-rules.md      # From template - fill all {{PLACEHOLDER}}
+```
+
+## Process
+
+### Step 1: Read Templates
+
+Read ALL template files from `.cursor/doc-templates/`:
+- Understand the `{{PLACEHOLDER}}` syntax
+- Note the `<!-- AI GUIDANCE: -->` comments for customization hints
+- Identify sections that can be deleted if not applicable
+
+### Step 2: Analyze Codebase
+
+Scan the project to detect:
+- **Project Type**: Web app, API, library, CLI, monorepo
+- **Tech Stack**: Languages, frameworks, databases, cloud services
+- **Structure**: Directory layout, module organization
+- **Dependencies**: Key packages and integrations
+- **Patterns**: Architecture patterns, coding conventions
+
+### Step 3: Generate Documentation
+
+For each template:
+
+1. **Copy template structure exactly** - Preserve all sections
+2. **Replace ALL `{{PLACEHOLDER}}` values** with detected/analyzed content
+3. **Remove inapplicable sections** - Delete sections marked optional if not relevant
+4. **Keep AI GUIDANCE comments** for future reference (or remove after filling)
+
+### Step 4: Fill Missing Information
+
+If information cannot be detected:
+- Mark with `// TODO:` for manual completion
+- Add placeholder text describing what's needed
+- Never leave empty `{{PLACEHOLDER}}` values
+
+### Step 5: Cross-Reference
+
+Ensure all documents link correctly:
+- Update Related Documentation sections
+- Verify internal links between docs
+- Check file paths are correct
+
+## Template Placeholder Rules
+
+### MUST Replace
+
+All `{{PLACEHOLDER}}` values must be replaced with actual content:
+
+```markdown
+# Before
+**Project Name**: {{PROJECT_NAME}}
+**Version**: {{VERSION}}
+
+# After
+**Project Name**: MyApp
+**Version**: 1.0.0
+```
+
+### Section Removal
+
+Remove entire sections if not applicable (marked in AI GUIDANCE):
+
+```markdown
+<!-- AI GUIDANCE: Remove this section if project has no database -->
+## Database Schema
+...
+```
+
+### TODO Markers
+
+Use for information that needs manual input:
+
+```markdown
+## External Systems
+
+// TODO: List external services and integrations
+| System | Purpose | Integration Details |
+|--------|---------|---------------------|
+| ... | ... | ... |
+```
+
+## Output
+
+```
+✅ DOCS INITIALIZED FROM TEMPLATES
+════════════════════════════════════════
+
+📁 docs/
+├── ✅ project-overview-pdr.md (from template)
+├── ✅ codebase-summary.md (from template)
+├── ✅ code-standards.md (from template)
+├── ✅ system-architecture.md (from template)
+├── ✅ technical-documents.md (from template)
+└── ✅ development-rules.md (from template)
+
+PLACEHOLDERS FILLED: 142/150
+TODO MARKERS: 8 (require manual input)
+
+NEXT STEPS:
+1. Review generated docs for accuracy
+2. Fill remaining TODO markers
+3. Add project-specific diagrams
+4. Run @docs/update after code changes
+════════════════════════════════════════
+```
+
+## Validation Checklist
+
+Before completing:
+
+- [ ] All `{{PLACEHOLDER}}` replaced with actual values
+- [ ] No empty sections (remove or add TODO)
+- [ ] Tech stack correctly identified
+- [ ] Architecture patterns documented
+- [ ] C4 diagrams creation done base on project context.
+- [ ] Related Documentation links are valid
+- [ ] Development setup steps are complete

package/templates/.cursor/commands/devkit/docs/summarize.md

@@ -0,0 +1,82 @@
+---
+description: Generate concise summaries of code, files, or features
+---
+
+# Docs: Summarize
+
+Generate concise summaries for code, files, or features.
+
+## Usage
+
+`@docs/summarize [target] [format]`
+
+## Targets
+
+| Target | Example |
+|--------|---------|
+| File | `@docs/summarize src/auth/service.ts` |
+| Directory | `@docs/summarize src/auth/` |
+| Feature | `@docs/summarize "authentication flow"` |
+| PR/Diff | `@docs/summarize --diff` |
+
+## Formats
+
+- `brief` - One paragraph (default)
+- `detailed` - Full breakdown
+- `bullet` - Bullet points
+- `technical` - For developers
+- `stakeholder` - For non-technical audience
+
+## Process
+
+1. **Read** - Analyze target code
+2. **Extract** - Key functionality and patterns
+3. **Summarize** - Generate concise summary
+4. **Format** - Apply requested format
+
+## Output Examples
+
+### Brief Format
+```
+The AuthService handles user authentication via JWT tokens,
+supporting email/password and OAuth providers. It manages
+session lifecycle, token refresh, and password reset flows.
+```
+
+### Bullet Format
+```
+## auth/service.ts
+
+**Purpose:** User authentication and session management
+
+**Key Functions:**
+• login() - Authenticate with credentials
+• verifyToken() - Validate JWT token
+• refreshToken() - Generate new access token
+• logout() - Invalidate session
+
+**Dependencies:**
+• jwt-library for token handling
+• bcrypt for password hashing
+• redis for session storage
+```
+
+### Technical Format
+```
+## Technical Summary
+
+**Module:** AuthService
+**Pattern:** Repository + Service layer
+**Auth Flow:** JWT with refresh tokens
+
+**Security:**
+- Passwords: bcrypt (12 rounds)
+- Tokens: RS256, 15min expiry
+- Sessions: Redis with TTL
+
+**API Surface:**
+- POST /auth/login
+- POST /auth/refresh
+- POST /auth/logout
+- GET /auth/me
+```

package/templates/.cursor/commands/devkit/docs/update.md

@@ -0,0 +1,174 @@
+---
+description: Update project documentation based on codebase changes
+---
+
+# Docs: Update
+
+Analyze codebase and update documentation to reflect current state, strictly following `.claude/doc-templates/` structure.
+
+## Usage
+
+`@docs/update [focus-area]`
+
+## Templates Reference
+
+All updates MUST maintain the template structure from `.claude/doc-templates/`:
+
+| Template | Doc File | Sections to Update |
+|----------|----------|-------------------|
+| `project-overview-pdr.md` | `docs/project-overview-pdr.md` | Features, Requirements, Roadmap |
+| `codebase-summary.md` | `docs/codebase-summary.md` | Stats, Components, Dependencies |
+| `code-standards.md` | `docs/code-standards.md` | Conventions, Patterns |
+| `system-architecture.md` | `docs/system-architecture.md` | Components, Data Flow, APIs |
+| `technical-documents.md` | `docs/technical-documents.md` | C4 Diagrams, Deployment, Setup |
+| `development-rules.md` | `docs/development-rules.md` | Rules, Checklists |
+
+## Focus Areas
+
+| Area | Updates | Files |
+|------|---------|-------|
+| `api` | Endpoints, schemas, auth | `codebase-summary.md`, `technical-documents.md` |
+| `architecture` | Components, data flow, diagrams | `system-architecture.md`, `technical-documents.md` |
+| `setup` | Prerequisites, scripts, env vars | `technical-documents.md`, `codebase-summary.md` |
+| `standards` | Conventions, patterns, rules | `code-standards.md`, `development-rules.md` |
+| `all` | Everything | All documentation files |
+
+## Process
+
+### Step 1: Read Current Documentation
+
+Load existing docs from `docs/` directory:
+- Check which template sections exist
+- Identify filled vs TODO sections
+- Note any custom additions outside template
+
+### Step 2: Analyze Codebase Changes
+
+Detect changes since last update:
+- **New Files**: Components, services, utilities
+- **Modified Files**: API changes, new functions
+- **Dependencies**: Added/removed packages
+- **Configuration**: Env vars, build settings
+- **Tests**: Coverage changes
+
+### Step 3: Compare Against Templates
+
+For each template section:
+
+1. **Check completeness** - Are all required fields filled?
+2. **Verify accuracy** - Does content match current code?
+3. **Identify gaps** - What's missing or outdated?
+
+### Step 4: Update Documentation
+
+Apply changes while preserving template structure:
+
+```markdown
+# Template Structure MUST Be Preserved
+
+## Section from Template
+| Field | Previous Value | Updated Value |
+|-------|----------------|---------------|
+| {{TECH_STACK}} | React 17 | React 18 |
+| {{DATABASE}} | PostgreSQL 13 | PostgreSQL 15 |
+```
+
+### Step 5: Update Metadata
+
+Update revision information in each file:
+
+```markdown
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.1.0 | 2025-01-15 | AI | Added new API endpoints |
+| 1.0.0 | 2025-01-01 | AI | Initial documentation |
+```
+
+## Update Rules
+
+### MUST Preserve
+
+- Template section structure
+- Section ordering from template
+- Table formats and headers
+- Cross-reference links
+
+### MUST Update
+
+- Version numbers and dates
+- Statistics (file counts, line counts)
+- Dependency versions
+- API endpoint lists
+- Component descriptions
+
+### MUST NOT
+
+- Remove template sections (mark as N/A if not applicable)
+- Change section headings
+- Add unstructured content
+- Leave `{{PLACEHOLDER}}` unfilled
+
+### TODO Handling
+
+For sections that need manual input:
+
+```markdown
+## C4 Diagrams
+
+// TODO: Update System Context diagram with new external service
+// TODO: Add new component to Container diagram
+
+### Current Diagrams
+[existing content]
+```
+
+## Output
+
+```
+📝 DOCS UPDATED (TEMPLATE-COMPLIANT)
+════════════════════════════════════════
+
+CHANGES DETECTED:
+• 5 new API endpoints
+• 2 dependency updates
+• 1 new component
+• 3 config changes
+
+UPDATED FILES:
+✅ codebase-summary.md
+   ├── Quick Stats: Updated file counts
+   ├── Tech Stack: React 17 → 18
+   └── Core Components: Added PaymentService
+
+✅ technical-documents.md
+   ├── System Containers: Added Redis cache
+   └── Development Setup: New env variables
+
+✅ code-standards.md
+   └── Conventions: Added new patterns
+
+⏭️ system-architecture.md (no changes needed)
+⏭️ project-overview-pdr.md (no changes needed)
+
+NEW TODO MARKERS: 2
+• C4 diagram update required
+• New external system documentation
+
+TEMPLATE COMPLIANCE: ✅ 100%
+════════════════════════════════════════
+```
+
+## Validation Checklist
+
+After update:
+
+- [ ] All sections maintain template structure
+- [ ] No orphaned `{{PLACEHOLDER}}` values
+- [ ] Version/date updated in Revision History
+- [ ] Statistics reflect current codebase
+- [ ] Links between docs are valid
+- [ ] TODO markers added for manual tasks
+- [ ] No content outside template sections
+- [ ] C4 diagrams creation done base on project context.

package/templates/.cursor/commands/devkit/fix.md

@@ -0,0 +1,24 @@
+---
+description: Analyze fix the issue
+argument-hint: [issue-description]
+---
+
+# Fix
+
+Use subagents to plan and fix issues via the Orchestration Protocol.
+
+## Usage
+`@fix [issue-description]`
+
+## Workflow
+1) Use `planner` (`./.cursor/rules/planner.mdc`) rule and `researcher` (`./.cursor/rules/researcher.mdc`) rule to create an implementation plan with TODO tasks in `./.cursor/issues/`.
+2) Main agent implements the plan step by step.
+3) Use `tester` (`./.cursor/rules/tester.mdc`) rule to run tests; ensure they pass, then report back.
+4) If issues or failed tests arise, use `debugger` (`./.cursor/rules/debugger.mdc`) rule to find root causes, then main agent fixes all of them.
+5) Repeat until all tests pass or no further issues remain.
+6) Delegate to `code-reviewer` (`./.cursor/rules/code-reviewer.mdc`) rule for review; if critical issues are found, main agent improves code and re-tests.
+7) Report back to user with a brief summary of changes and outcomes.
+
+Notes:
+- For frontend/UI issues, start the browser, reproduce, and gather DevTools console/network errors before choosing approaches.
+