ai-qakit 1.0.0

package/templates/.claude/commands/devkit/ask.md

@@ -0,0 +1,269 @@
+---
+description: "Ask questions, get help, solve problems: /ask [your question]"
+allowed-tools: Read, Grep, Write, Edit, WebSearch, AskUserQuestion, Skill
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Ask
+
+Smart assistant that routes your question to the appropriate problem-solving approach.
+
+## Usage
+
+`/devkit:ask [your question or problem]`
+
+## Context
+
+- Question: $ARGUMENTS
+- This command intelligently applies the right skill(s) based on your question type
+- Current development workflows, system constraints, scale requirements, and business context will be considered:
+- Primary workflow: `./.claude/workflows/primary-workflow.md`
+- Development rules: `./.claude/workflows/development-rules.md`
+- Orchestration protocols: `./.claude/workflows/orchestration-protocol.md`
+- Documentation management: `./.claude/workflows/documentation-management.md`
+
+**Project Documentation:**
+```
+./docs
+├── project-overview-pdr.md
+├── code-standards.md
+├── codebase-summary.md
+├── design-guidelines.md
+├── deployment-guide.md
+├── system-architecture.md
+├── project-roadmap.md
+└── technical-documents.md
+```
+---
+
+## Your Role
+You are a Senior Systems Architect providing expert consultation and architectural guidance. You focus on high-level design, strategic decisions, and architectural patterns rather than implementation details. You orchestrate four specialized architectural advisors:
+1. **Systems Designer** – evaluates system boundaries, interfaces, and component interactions.
+2. **Technology Strategist** – recommends technology stacks, frameworks, and architectural patterns.
+3. **Scalability Consultant** – assesses performance, reliability, and growth considerations.
+4. **Risk Analyst** – identifies potential issues, trade-offs, and mitigation strategies.
+You operate by the holy trinity of software engineering: **YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every solution you propose must honor these principles.
+
+## Process
+1. **Problem Understanding**: Analyze the technical question and gather architectural context.
+   - If the architecture context doesn't contain the necessary information, use [`SlashCommand(/scout)`](`./.claude/commands/scout.md`) to scout the codebase again.
+2. **Expert Consultation**:
+   - Systems Designer: Define system boundaries, data flows, and component relationships
+   - Technology Strategist: Evaluate technology choices, patterns, and industry best practices
+   - Scalability Consultant: Assess non-functional requirements and scalability implications
+   - Risk Analyst: Identify architectural risks, dependencies, and decision trade-offs
+3. **Architecture Synthesis**: Combine insights to provide comprehensive architectural guidance.
+4. **Strategic Validation**: Ensure recommendations align with business goals and technical constraints.
+
+## Step 1: Classify the Question
+
+Analyze the question and classify into one or more categories:
+
+| Question Type | Indicators | Primary Skill |
+|---------------|------------|---------------|
+| **Research** | "what is", "how does X work", "best practices for", "compare X vs Y", "latest trends in" | `research` |
+| **Problem/Debugging** | "stuck on", "can't figure out", "why isn't X working", "error with", "how to fix" | `problem-solving` |
+| **Complex Analysis** | Multi-step problem, unclear scope, needs breakdown, "design", "architect", "plan" | `sequential-thinking` |
+| **Quick Answer** | Simple factual question, single-step solution | Direct answer |
+
+**Multiple skills may apply.** For example:
+- "How to fix authentication in NestJS" → `problem-solving` + `research`
+- "Design a scalable payment system" → `sequential-thinking` + `research`
+- "Why does my code keep failing at scale" → `problem-solving` + `sequential-thinking`
+
+---
+
+## Step 2: Apply Appropriate Skill(s)
+
+### For Research Questions
+
+Activate `.claude/skills/research/SKILL.md`:
+
+1. Define research scope
+2. Gather information (web search, docs, code examples)
+3. Analyze and synthesize findings
+4. Provide actionable recommendations
+
+**Output format:**
+```
+📚 RESEARCH FINDINGS
+─────────────────────
+[Concise summary of findings]
+
+Key Points:
+• [Point 1]
+• [Point 2]
+• [Point 3]
+
+Recommendations:
+1. [Action 1]
+2. [Action 2]
+
+Sources: [List relevant sources]
+```
+
+### For Problem-Solving Questions
+
+Activate `.claude/skills/problem-solving/SKILL.md`:
+
+1. Identify the stuck-type (complexity spiral, innovation block, assumption constraint, etc.)
+2. Apply the matching technique:
+   - **Complexity spiraling** → Simplification Cascades
+   - **Innovation block** → Collision-Zone Thinking
+   - **Recurring patterns** → Meta-Pattern Recognition
+   - **Forced solution** → Inversion Exercise
+   - **Scale uncertainty** → Scale Game
+   - **Unsure** → When Stuck dispatch
+
+**Output format:**
+```
+🔧 PROBLEM ANALYSIS
+─────────────────────
+Stuck-Type: [identified type]
+Technique: [applied technique]
+
+Analysis:
+[Systematic breakdown]
+
+Solution:
+[Actionable steps]
+
+Why This Works:
+[Brief explanation]
+```
+
+### For Complex/Multi-Step Questions
+
+Activate `.claude/skills/sequential-thinking/SKILL.md`:
+
+1. Start with loose estimate of steps needed
+2. Structure each thought building on previous
+3. Apply dynamic adjustment (expand/contract/revise/branch)
+4. Generate and verify hypotheses
+5. Complete only when confident
+
+**Output format:**
+```
+🧠 SEQUENTIAL ANALYSIS
+─────────────────────
+Thought 1/N: [Initial analysis]
+...
+Thought N/N [FINAL]: [Conclusion]
+
+Summary:
+[Key takeaways and recommendations]
+```
+
+### For Quick/Simple Questions
+
+Answer directly without invoking skills:
+
+```
+💡 ANSWER
+─────────────────────
+[Direct, concise answer]
+
+[Code example if applicable]
+```
+
+---
+
+## Step 3: Combine Skills When Needed
+
+For questions requiring multiple approaches:
+
+### Research + Problem-Solving
+```
+1. Research the problem space first
+2. Apply problem-solving techniques with research context
+3. Validate solution against researched best practices
+```
+
+### Research + Sequential Thinking
+```
+1. Use sequential thinking to break down the problem
+2. Research each component as needed
+3. Synthesize into cohesive recommendation
+```
+
+### Problem-Solving + Sequential Thinking
+```
+1. Identify stuck-type
+2. Use sequential thinking to work through the technique
+3. Apply revisions as new insights emerge
+```
+
+### All Three (Complex Technical Problems)
+```
+1. Sequential thinking to scope the problem
+2. Research relevant technologies/patterns
+3. Problem-solving techniques when stuck
+4. Iterate until solution verified
+```
+
+---
+
+## Step 4: Deliver Response
+
+Structure your response based on question complexity:
+
+### Simple Questions
+- Direct answer
+- Code example if relevant
+- One-liner explanation
+
+### Moderate Questions
+- Brief context
+- Solution with explanation
+- Relevant code/commands
+- Next steps if applicable
+
+### Complex Questions
+- Problem breakdown
+- Step-by-step analysis
+- Multiple options with trade-offs
+- Recommended approach with rationale
+- Implementation guidance
+
+---
+
+## Examples
+
+**Research:**
+```
+/ask What are the best practices for API rate limiting in 2024?
+```
+
+**Problem-Solving:**
+```
+/ask I'm stuck - my code has 5 different ways to handle errors and it keeps growing
+```
+
+**Complex Analysis:**
+```
+/ask Design a notification system that can handle 1M users
+```
+
+**Quick Answer:**
+```
+/ask How do I create a new branch in git?
+```
+
+**Combined:**
+```
+/ask My authentication keeps breaking at scale - how should I redesign it?
+```
+
+---
+
+## Begin Now
+
+1. Read the question: `$ARGUMENTS`
+2. Classify the question type(s)
+3. Activate appropriate skill(s)
+4. Provide structured response
+5. Include actionable next steps if applicable
+
+If the question is unclear, ask for clarification before proceeding.
+

package/templates/.claude/commands/devkit/backend/create-api.md

@@ -0,0 +1,220 @@
+---
+description: Generate API endpoint following project patterns (REST or GraphQL)
+argument-hint: [endpoint-description]
+allowed-tools: Read, Grep, Write, Edit, AskUserQuestion
+---
+
+<!--
+Usage: /create-api [endpoint-description]
+Requires: API framework configured (NestJS/Express/FastAPI/etc.)
+Example: /create-api "GET endpoint for user profile"
+Example: /create-api "POST endpoint to create products"
+Example: /create-api "GraphQL mutations for order management"
+-->
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create API Endpoint
+
+Generate API endpoint based on description.
+
+## Input Validation
+
+### Validate Endpoint Description ($ARGUMENTS)
+
+If $ARGUMENTS not provided:
+  Use AskUserQuestion to ask for endpoint description:
+  - question: "What API endpoint should I generate? Describe the operation, resource, and purpose."
+  - header: "API Endpoint"
+  - options:
+    - I'll describe the endpoint
+
+If $ARGUMENTS provided:
+  Proceed with API generation for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show API design plan
+2. List all files that will be created/modified
+3. Present the endpoint structure and components
+4. Ask for confirmation before writing any files
+5. Never generate API code without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What fields should the request/response include?"
+- "Does this endpoint require authentication? What roles can access it?"
+- "Should this support pagination, filtering, or sorting?"
+- "What validation rules apply to the input fields?"
+- "Are there any business rules I should know about?"
+- "Should this be a single endpoint or full CRUD?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- **API Type**: REST or GraphQL
+- Framework (NestJS, Express, FastAPI, Apollo, etc.)
+- API structure (controller/resolver paths)
+- DTO/validation patterns
+- Authentication patterns
+- Documentation (OpenAPI/Swagger or GraphQL Playground)
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Determine API Type
+
+Based on CLAUDE.md API Type field:
+
+**If REST API** → Follow REST conventions below
+**If GraphQL** → Follow GraphQL conventions below
+**If Hybrid** → Ask which approach for this endpoint
+
+## Step 3: Parse Request
+
+Analyze "$ARGUMENTS" to determine:
+- Resource name
+- Operations needed (CRUD, single endpoint, etc.)
+- Request/response fields
+- Relationships
+
+---
+
+## REST API Generation
+
+### REST Conventions
+
+| Action | Method | Endpoint | Status |
+|--------|--------|----------|--------|
+| List | GET | /api/v1/{resources} | 200 |
+| Get | GET | /api/v1/{resources}/:id | 200, 404 |
+| Create | POST | /api/v1/{resources} | 201, 400 |
+| Update | PUT/PATCH | /api/v1/{resources}/:id | 200, 404 |
+| Delete | DELETE | /api/v1/{resources}/:id | 204, 404 |
+
+### Generate REST Components
+
+**Controller:**
+- Route decorators with HTTP methods
+- Request validation decorators
+- Authentication guards (if pattern exists)
+- Swagger/OpenAPI decorators (if pattern exists)
+- Response type hints
+
+**Service:**
+- Business logic methods
+- Repository/database calls
+- Error handling with proper HTTP exceptions
+- Transaction handling (if pattern exists)
+
+**DTOs:**
+- CreateDto with validation decorators
+- UpdateDto (partial)
+- ResponseDto
+- QueryDto for filters/pagination
+
+---
+
+## GraphQL API Generation
+
+### GraphQL Conventions
+
+**Types:**
+```graphql
+type Resource { ... }
+input CreateResourceInput { ... }
+input UpdateResourceInput { ... }
+type ResourceConnection { edges, pageInfo, totalCount }
+```
+
+**Operations:**
+```graphql
+type Query {
+  resource(id: ID!): Resource
+  resources(first: Int, after: String): ResourceConnection!
+}
+
+type Mutation {
+  createResource(input: CreateResourceInput!): Resource!
+  updateResource(id: ID!, input: UpdateResourceInput!): Resource!
+  deleteResource(id: ID!): Boolean!
+}
+```
+
+### Generate GraphQL Components
+
+**Schema (if schema-first):**
+- Type definitions
+- Input types
+- Query/Mutation extensions
+
+**Resolver:**
+- Query resolvers with DataLoader
+- Mutation resolvers with validation
+- Field resolvers for relationships
+- Authorization decorators
+
+**Types (if code-first):**
+- ObjectType classes
+- InputType classes
+- Args classes
+
+---
+
+## Step 4: Review Existing Patterns
+
+Find and analyze existing API files to detect:
+- Naming conventions
+- Decorator/annotation patterns
+- Validation approach
+- Error handling patterns
+- Response formatting
+- Authentication/authorization patterns
+
+## Step 5: Generate Components
+
+Create all required files following detected patterns from Step 4.
+
+## Step 6: Show Generated Files
+
+Display:
+1. All file paths to create/modify
+2. Full content for each file
+3. Registration steps (module imports, schema stitching, route registration)
+
+## Step 7: Test Examples
+
+**For REST:**
+```bash
+curl -X [METHOD] http://localhost:[PORT]/api/v1/[resource] \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '[example body]'
+```
+
+**For GraphQL:**
+```graphql
+query {
+  resources(first: 10) {
+    edges { node { id name } }
+  }
+}
+
+mutation {
+  createResource(input: { name: "test" }) {
+    id
+    name
+  }
+}
+```
+
+Generate API now for: $ARGUMENTS

package/templates/.claude/commands/devkit/backend/create-migration.md

@@ -0,0 +1,130 @@
+---
+description: Generate database migration
+argument-hint: [migration-description]
+allowed-tools: Read, Grep, Bash(test:*, ls, cat), Write, Edit, AskUserQuestion
+---
+
+<!--
+Usage: /create-migration [migration-description]
+Requires: Migration tool configured (Prisma/TypeORM/Alembic/etc.)
+Example: /create-migration "add email index to users table"
+Example: /create-migration "create products table"
+Example: /create-migration "add foreign key from posts to users"
+-->
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create Database Migration
+
+Generate a migration based on description.
+
+## Input Validation
+
+### Validate Migration Description ($ARGUMENTS)
+
+If $ARGUMENTS not provided:
+  Use AskUserQuestion to ask for migration description:
+  - question: "What database changes should this migration make?"
+  - header: "Migration Description"
+  - options:
+    - I'll describe the migration
+
+If $ARGUMENTS provided:
+  Proceed with migration generation for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show migration plan
+2. Display the schema changes that will be made
+3. Show the migration file content before creating
+4. Ask for confirmation before writing files
+5. Never create migrations without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What data type should [field] be? (e.g., varchar length, decimal precision)"
+- "Should [field] be nullable or have a default value?"
+- "Is this a breaking change that needs data migration?"
+- "Should I add an index on [field] for query performance?"
+- "What's the foreign key relationship with [table]?"
+- "Should this include a rollback strategy for existing data?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Migration tool (Prisma, TypeORM, Alembic, etc.)
+- Migration directory
+- Naming conventions
+- Migration commands
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Analyze Request
+
+Parse "$ARGUMENTS" to determine:
+- Migration type (create table, add column, modify, drop)
+- Table/entity name
+- Column definitions with types
+- Constraints (unique, not null, foreign keys)
+- Indexes needed
+
+## Step 3: Check Current Schema
+
+Read current schema/models to understand:
+- Existing tables and relationships
+- Column naming conventions
+- Type patterns used
+- Timestamp columns pattern
+
+## Step 4: Review Existing Migrations
+
+Check existing migrations for:
+- Naming pattern
+- File structure
+- Up/down migration style
+- Rollback patterns
+
+## Step 5: Generate Migration
+
+Create migration file following detected patterns:
+
+**Include:**
+- Properly named migration file
+- Up migration (apply changes)
+- Down migration (rollback changes)
+- Appropriate indexes
+- Foreign key constraints
+- Timestamps (created_at, updated_at) if table creation
+
+**Migration naming convention:**
+Follow project pattern, typically:
+- `YYYYMMDDHHMMSS_description`
+- `001_description`
+- `create_[table]`
+- `add_[column]_to_[table]`
+
+## Step 6: Show Migration
+
+Display:
+1. Migration file path
+2. Full migration content
+3. SQL that will be executed (if applicable)
+
+## Step 7: Provide Commands
+
+Show commands to:
+- Run migration: `[detected migrate command]`
+- Rollback migration: `[detected rollback command]`
+- Check migration status: `[detected status command]`
+
+Generate migration now for: $ARGUMENTS