ai-qakit 1.0.0

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

@@ -0,0 +1,424 @@
+---
+description: Capture and document knowledge from code entry points with visual diagrams
+argument-hint: [entry-point] | [file-path] | [function-name] | [api-endpoint]
+allowed-tools: Read, Grep, Bash, Write, Edit, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /docs:capture-knowledge [entry-point]
+Example: /docs:capture-knowledge src/services/auth.service.ts
+Example: /docs:capture-knowledge "handleUserLogin function"
+Example: /docs:capture-knowledge "/api/v1/users"
+-->
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Capture Knowledge
+
+Analyze code from any entry point and generate comprehensive documentation with visual diagrams.
+
+## Use Cases
+
+- **Onboarding** - Help new developers understand complex systems
+- **Documentation** - Generate comprehensive system documentation
+- **Debugging** - Understand complete execution flows
+- **Refactoring** - Get full context before making changes
+- **Knowledge Base** - Create searchable documentation
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the entry point and show analysis plan
+2. Present findings and documentation structure
+3. Show the knowledge document outline before creating
+4. Ask for confirmation before writing files
+5. Never create documentation without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What is the specific entry point you want to analyze?"
+- "What's the purpose of this analysis? (onboarding, debugging, refactoring)"
+- "How deep should I go? (surface level, detailed, exhaustive)"
+- "Are there any areas I should focus on or skip?"
+- "Should I include external dependencies in the analysis?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+---
+
+## Step 1: Gather Context
+
+Use AskUserQuestion to collect:
+
+**Question 1: Entry Point**
+- question: "What is the entry point you want to analyze?"
+- header: "Entry Point"
+- options:
+  - File (e.g., src/services/auth.ts)
+  - Folder (e.g., src/modules/payments/)
+  - Function (e.g., calculateTotalPrice)
+  - API Endpoint (e.g., POST /api/users)
+  - Other (I'll specify)
+
+**Question 2: Purpose**
+- question: "Why are you capturing this knowledge?"
+- header: "Purpose"
+- options:
+  - Onboarding (Understanding the system)
+  - Documentation (Creating/updating docs)
+  - Debugging (Investigating an issue)
+  - Refactoring (Planning changes)
+  - Knowledge transfer (Team sharing)
+
+**Question 3: Depth**
+- question: "How deep should the analysis go?"
+- header: "Depth"
+- options:
+  - Surface (Overview, main components)
+  - Standard (Core logic, direct dependencies)
+  - Deep (Full dependency tree, edge cases)
+  - Exhaustive (Everything, including internals)
+
+**Question 4: Focus Areas**
+- question: "Any specific areas to focus on?"
+- header: "Focus"
+- multiSelect: true
+- options:
+  - Business logic
+  - Data flow
+  - Error handling
+  - Performance
+  - Security
+  - Dependencies
+
+If user provides entry point directly via $ARGUMENTS, parse it and proceed.
+
+## Step 2: Validate Entry Point
+
+Based on the entry point type:
+
+**For Files:**
+```bash
+ls -la [file-path]
+```
+- Confirm file exists
+- Identify language and framework
+
+**For Folders:**
+```bash
+find [folder-path] -type f -name "*.ts" -o -name "*.js" -o -name "*.py" | head -20
+```
+- List structure and key files
+
+**For Functions:**
+```bash
+grep -rn "function [name]\|const [name]\|def [name]\|public [name]" src/ --include="*.ts" --include="*.js" --include="*.py"
+```
+- Find function definition
+- Handle multiple matches by asking user
+
+**For API Endpoints:**
+```bash
+grep -rn "@Get\|@Post\|@app.route\|router\." src/ | grep -i "[endpoint]"
+```
+- Locate route handler
+
+**If not found:**
+- Suggest alternatives with fuzzy matching
+- Ask user to clarify
+
+## Step 3: Collect Source Context
+
+Read the primary file/module and extract:
+
+1. **Purpose** - What does this code do?
+2. **Exports** - What does it expose?
+3. **Key Patterns** - Design patterns, conventions used
+4. **Signature** - For functions: parameters, return types, generics
+5. **Error Handling** - How errors are managed
+6. **Essential Snippets** - Key code sections (avoid large dumps)
+
+**For Folders:**
+- List directory structure
+- Identify entry points and main modules
+- Note configuration files
+
+**For Functions/APIs:**
+- Capture full signature
+- Document parameters with types
+- Note return values and errors
+- Extract docstrings/comments
+
+## Step 4: Analyze Dependencies
+
+Build dependency graph up to depth 3:
+
+```bash
+# Find imports in the file
+grep -E "^import|^from|require\(" [file-path]
+```
+
+**Track:**
+- Internal imports (project code)
+- External packages (node_modules, pip packages)
+- Services (databases, APIs, queues)
+- Generated code (to potentially exclude)
+
+**Categorize:**
+| Category | Examples |
+|----------|----------|
+| Direct imports | ./utils, ../services |
+| Framework | @nestjs, express, fastapi |
+| Database | prisma, typeorm, sqlalchemy |
+| External APIs | axios calls, fetch |
+| Utils | lodash, moment, uuid |
+
+**Avoid loops:** Track visited nodes during traversal.
+
+## Step 5: Synthesize Explanation
+
+Draft comprehensive analysis:
+
+### Overview
+- Purpose and responsibility
+- Language, framework, patterns
+- High-level behavior description
+
+### Implementation Details
+- Core logic walkthrough
+- Key algorithms or business rules
+- State management approach
+- Data transformations
+
+### Execution Flow
+- Entry → Processing → Output
+- Conditional branches
+- Async/await patterns
+- Event handlers
+
+### Quality Considerations
+- **Error Handling:** How failures are managed
+- **Performance:** Potential bottlenecks, optimizations
+- **Security:** Input validation, auth checks
+- **Testing:** Existing tests, coverage gaps
+
+### Risks & Improvements
+- Technical debt identified
+- Potential bugs or edge cases
+- Suggested refactoring opportunities
+
+## Step 6: Create Documentation
+
+**Normalize name to kebab-case:**
+- `calculateTotalPrice` → `calculate-total-price`
+- `src/services/auth.ts` → `auth-service`
+- `POST /api/users` → `post-api-users`
+
+**Create documentation file:**
+
+Path: `docs/knowledge-{name}.md`
+
+**Documentation Template:**
+
+```markdown
+# Knowledge: [Entry Point Name]
+
+> Auto-generated knowledge capture for [entry point]
+> Generated: [date]
+
+## Overview
+
+[Purpose and high-level description]
+
+## Entry Point
+
+- **Type:** [File / Folder / Function / API]
+- **Path:** `[path]`
+- **Language:** [language]
+- **Framework:** [framework]
+
+## Implementation Details
+
+### Core Logic
+
+[Detailed explanation of how it works]
+
+### Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| [name] | [description] |
+
+### Execution Flow
+
+```mermaid
+flowchart TD
+    A[Entry] --> B{Condition}
+    B -->|Yes| C[Process]
+    B -->|No| D[Skip]
+    C --> E[Output]
+    D --> E
+```
+
+## Dependencies
+
+### Internal
+
+| Module | Purpose |
+|--------|---------|
+| [path] | [description] |
+
+### External
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| [name] | [version] | [description] |
+
+### Dependency Graph
+
+```mermaid
+graph LR
+    A[Entry Point] --> B[Service A]
+    A --> C[Service B]
+    B --> D[Database]
+    C --> E[External API]
+```
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Handler
+    participant Service
+    participant Database
+    
+    Client->>Handler: Request
+    Handler->>Service: Process
+    Service->>Database: Query
+    Database-->>Service: Result
+    Service-->>Handler: Response
+    Handler-->>Client: Result
+```
+
+## Quality Analysis
+
+### Error Handling
+[How errors are handled]
+
+### Performance Considerations
+[Bottlenecks, optimizations]
+
+### Security Notes
+[Auth, validation, vulnerabilities]
+
+## Risks & Technical Debt
+
+- [ ] [Risk or debt item 1]
+- [ ] [Risk or debt item 2]
+
+## Suggested Improvements
+
+1. [Improvement 1]
+2. [Improvement 2]
+
+## Related Knowledge
+
+- [Link to related knowledge docs]
+
+## Metadata
+
+| Property | Value |
+|----------|-------|
+| Analyzed | [timestamp] |
+| Depth | [depth level] |
+| Files Touched | [count] |
+| Analysis Duration | [time] |
+
+## Next Steps
+
+- [ ] Review this documentation
+- [ ] Address identified risks
+- [ ] Capture related entry points
+```
+
+**Write the file** using Write tool with actual findings.
+
+## Step 7: Resolve Open Questions
+
+**IMPORTANT:** Before completing, ALL open questions MUST be resolved.
+
+1. **Check for open questions** discovered during analysis
+2. **If questions exist:**
+   - Use `AskUserQuestion` tool to ask user about each question
+   - Present options when applicable with recommendation
+   - Update the documentation file with answers
+   - Add clarifications to relevant sections
+   - Repeat until no open questions remain
+
+3. **Resolution loop:**
+   ```
+   WHILE open_questions.length > 0:
+     - Pick the most critical question
+     - Use AskUserQuestion with clear options
+     - Update docs/knowledge-[name].md with answer
+     - Remove question from open list
+   ```
+
+4. **Only proceed to summary when ALL questions are resolved**
+
+## Step 8: Review & Next Actions
+
+Display summary:
+
+```
+════════════════════════════════════════════════════════════════════
+                    📚 KNOWLEDGE CAPTURED SUCCESSFULLY
+════════════════════════════════════════════════════════════════════
+
+📄 Documentation Created:
+   docs/knowledge-[name].md
+
+📊 Analysis Summary:
+   - Entry Point: [type] - [path]
+   - Files Analyzed: [count]
+   - Dependencies Found: [count]
+   - Depth: [level]
+
+🔍 Key Insights:
+   • [Insight 1]
+   • [Insight 2]
+   • [Insight 3]
+
+✅ Questions Resolved: [count] questions answered during session
+
+🔗 Suggested Next Captures:
+   • /capture-knowledge [related-entry-1]
+   • /capture-knowledge [related-entry-2]
+
+💡 Review the generated documentation for accuracy!
+════════════════════════════════════════════════════════════════════
+```
+
+Use AskUserQuestion:
+- question: "Would you like to capture knowledge for any related entry points?"
+- header: "Continue?"
+- options:
+  - Yes, capture [suggested entry point 1]
+  - Yes, capture [suggested entry point 2]
+  - No, I'm done for now
+
+If user selects "Yes", repeat the process for the selected entry point.
+
+---
+
+## Begin Now
+
+If entry point provided via $ARGUMENTS, start with Step 2 (Validate).
+Otherwise, start with Step 1 (Gather Context) to collect information.
+
+Ready to capture knowledge. What entry point would you like to analyze?
+

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

@@ -0,0 +1,203 @@
+---
+description: Initialize project documentation structure from templates
+argument-hint: [project-type]
+allowed-tools: Read, Write, MultiEdit, Bash, LS, Glob, Grep, WebSearch, WebFetch, Task, AskUserQuestion, Skill
+---
+
+# Docs: Init
+
+Initialize documentation structure using `.claude/doc-templates/` as the source of truth.
+
+## Usage
+
+`@docs/init [project-type]`
+
+## Templates Reference
+
+All documentation MUST strictly follow these templates located in `.claude/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 // TODO:
+└── development-rules.md      # From template - fill all {{PLACEHOLDER}}
+```
+
+---
+
+## Execution Strategy (Token-Optimized)
+
+**CRITICAL**: Follow this exact order to minimize token consumption.
+
+### Phase 1: Setup
+1. Copy `.claude/.repomixignore` to project root (if exists)
+2. Run `repomix` to generate `./repomix-output.xml`
+
+### Phase 2: Batch Context Loading (Read ALL at once)
+
+Read all files in a SINGLE parallel batch BEFORE writing any documentation:
+
+**Templates** (read all 6 in parallel):
+- `.claude/doc-templates/project-overview-pdr.md`
+- `.claude/doc-templates/codebase-summary.md`
+- `.claude/doc-templates/code-standards.md`
+- `.claude/doc-templates/system-architecture.md`
+- `.claude/doc-templates/technical-documents.md`
+- `.claude/doc-templates/development-rules.md`
+
+**Source files** (read in same batch):
+- `./repomix-output.xml` (codebase compaction)
+- `./package.json` (project metadata)
+- `./README.md` (existing content to update)
+- `./.env.example` or similar config files (if exists)
+
+### Phase 3: 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
+
+### Phase 4: Generate Documentation
+
+For each template, strictly follow this process:
+
+1. **Copy template structure exactly** - Preserve all sections
+2. **Replace ALL `{{PLACEHOLDER}}` values** with detected/analyzed content
+3. **Fill ALL `// TODO:` markers** with project-specific information
+4. **Remove inapplicable sections** - Delete sections marked optional if not relevant
+5. **Keep AI GUIDANCE comments** for future reference (or remove after filling)
+
+Write docs in this order:
+1. `docs/codebase-summary.md` (from repomix output)
+2. `docs/project-overview-pdr.md`
+3. `docs/code-standards.md`
+4. `docs/system-architecture.md`
+5. `docs/technical-documents.md`
+6. `docs/development-rules.md`
+7. `docs/design-guidelines.md` (if applicable)
+8. Update `README.md` (keep under 300 lines)
+
+**IMPORTANT**: Do NOT re-read any files during this phase. Use only the context loaded in Phase 2.
+
+---
+
+## 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
+```
+
+### MUST Fill
+
+All `// TODO:` markers must be filled with project-specific content:
+
+```markdown
+# Before
+// TODO: Describe main type of users
+
+# After
+- Admin users: System administrators with full access
+- Regular users: Standard application users
+```
+
+### 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 for Manual Input
+
+Use for information that cannot be auto-detected:
+
+```markdown
+## External Systems
+
+// TODO: List external services and integrations
+| System | Purpose | Integration Details |
+|--------|---------|---------------------|
+| ... | ... | ... |
+```
+
+---
+
+## Delegation
+
+Use `docs-manager` agent to analyze the codebase and execute the above strategy.
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+---
+
+## 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
+- [ ] All `// TODO:` filled or marked for manual completion
+- [ ] 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
+
+**IMPORTANT**: Do not start implementing until planning is complete.

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

@@ -0,0 +1,33 @@
+---
+description: Analyze the codebase and update documentation
+argument-hint: [focused-topics] [should-scan-codebase]
+allowed-tools: Read, Write, MultiEdit, Bash, LS, Glob, Grep, WebSearch, WebFetch, Task, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /docs:summarize [focused-topics] [should-scan-codebase]
+Requires: Existing docs/codebase-summary.md
+Example: /docs:summarize
+Example: /docs:summarize "authentication API" false
+Example: /docs:summarize "all" true
+-->
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+Use `docs-manager` agent to analyze the codebase based on `docs/codebase-summary.md` and respond with a summary report.
+
+## Arguments:
+$1: Focused topics (default: all)
+$2: Should scan codebase (`Boolean`, default: `false`)
+
+## Focused Topics:
+<focused_topics>$1</focused_topics>
+
+## Should Scan Codebase:
+<should_scan_codebase>$2</should_scan_codebase>
+
+## Important:
+- Use `.claude/doc-templates/` directory as the source of truth for documentation.
+- Do not scan the entire codebase unless the user explicitly requests it.
+
+**IMPORTANT**: **Do not** start implementing.