ai-qakit 1.0.0

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

@@ -0,0 +1,312 @@
+---
+description: Fast parallel codebase search for files
+argument-hint: [user-prompt] [scale] [task-id]
+allowed-tools: Task, TodoWrite, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /scout [search-description] [scale] [task-id]
+Requires: Task tool for spawning Explore agents
+Example: /scout "find authentication logic" 3
+Example: /scout "locate API endpoints for user management" 5 ABC-123
+Example: /scout "search for database models" 1
+Note: Scale defaults to 3 (1=quick, 3=standard, 5=comprehensive)
+Note: If task-id provided, saves report to ./.claude/tasks/[task-id]/reports/
+-->
+
+# Scout - Fast Parallel Codebase Search
+
+**Report Protocol**: Follow CLAUDE.md "Sub-Agent Report Generation" protocol before spawning scout subagents.
+
+Search the codebase for files needed to complete a task using fast, token-efficient Explore agents running in parallel.
+
+## Purpose
+
+When you need to quickly find files related to a specific feature, function, or concept, scout launches multiple specialized agents that search different parts of the codebase simultaneously.
+
+---
+
+## Input Validation
+
+### Validate USER_PROMPT ($1)
+
+If $1 not provided:
+  Use AskUserQuestion to ask what to search for:
+  - question: "What should I search for in the codebase?"
+  - header: "Search Target"
+  - options:
+    - I'll describe what I'm looking for
+
+If $1 provided:
+  Use the provided search description
+
+### Validate SCALE ($2)
+
+Default SCALE to 3 if not provided.
+
+If $2 provided:
+  Validate $2 is a number between 1 and 10:
+  - If valid: Use $2 as SCALE
+  - If invalid: Show error and default to 3
+
+**Scale Guide:**
+- 1 = Quick single-agent search (fast, targeted)
+- 2-3 = Standard parallel search (balanced)
+- 4-5 = Comprehensive deep search (thorough)
+- 6-10 = Exhaustive search (maximum coverage)
+
+---
+
+## Variables
+
+- **USER_PROMPT**: $1 (what to search for)
+- **SCALE**: $2 (defaults to 3, must be 1-10)
+- **TASK_ID**: $3 (optional, if provided saves to task directory)
+- **REPORT_OUTPUT_DIR**: `./.claude/tasks/[task-id]/reports/` (if task-id provided)
+
+---
+
+## Workflow
+
+### Step 1: Analyze Search Request
+
+Analyze the user's search request and determine:
+1. **Search Type**: Feature, function, component, pattern, API, config, etc.
+2. **Likely Locations**: Which directories/files might contain what user is looking for
+3. **Search Strategy**: How to divide the search across agents
+
+### Step 2: Divide Search Territory
+
+Based on SCALE, divide the codebase into search zones:
+
+**For SCALE = 1** (Single agent):
+- Search most likely location only
+- Example: If searching for "auth", focus on `src/auth/` or `auth/`
+
+**For SCALE = 2-3** (Standard):
+- Divide into 2-3 logical zones
+- Example zones:
+  - Agent 1: Core source code (`src/`, `lib/`)
+  - Agent 2: Configuration and setup (`config/`, root files)
+  - Agent 3: Tests and documentation (`test/`, `docs/`)
+
+**For SCALE = 4-5** (Comprehensive):
+- Divide into 4-5 specialized zones
+- Example zones:
+  - Agent 1: Controllers/Routes
+  - Agent 2: Services/Business Logic
+  - Agent 3: Models/Schemas
+  - Agent 4: Utils/Helpers
+  - Agent 5: Config/Infrastructure
+
+**For SCALE = 6-10** (Exhaustive):
+- Maximum coverage with specialized agents
+- Each agent focuses on specific patterns or file types
+
+### Step 3: Launch Explore Agents in Parallel
+
+**IMPORTANT**: Launch all agents in parallel using a single message with multiple Task tool calls.
+
+For each agent, provide:
+
+```markdown
+Agent #[N] - Search [zone description]
+
+**Search Task**: Find files related to: [USER_PROMPT]
+
+**Search Zone**: [Specific directories or patterns for this agent]
+
+**Search Methods**:
+1. Use Glob to find files by patterns (e.g., `**/*auth*.ts`, `**/controllers/*.js`)
+2. Use Grep to search file contents for keywords (e.g., "authentication", "login", "JWT")
+3. Use Read to examine promising files
+
+**Instructions**:
+- Focus on [specific aspect related to USER_PROMPT]
+- List all relevant files found with brief descriptions
+- Note key functions, classes, or patterns discovered
+- Include file paths and line numbers for important code
+- Use a timeout of 3 minutes for your search
+- If timeout occurs, report partial results
+
+**Report Format**:
+Files Found:
+- [file-path] - [what it contains]
+- [file-path] - [what it contains]
+
+Key Findings:
+- [Important discovery 1]
+- [Important discovery 2]
+```
+
+### Step 4: Collect and Synthesize Results
+
+After all agents complete (or timeout):
+
+1. **Collect Results**: Gather findings from all agents
+2. **Deduplicate**: Remove duplicate file mentions
+3. **Prioritize**: Rank files by relevance to search request
+4. **Categorize**: Group files by purpose (implementation, tests, config, docs)
+
+### Step 5: Generate Scout Report
+
+```
+════════════════════════════════════════════════════════════════════
+                    🔍 SCOUT REPORT
+════════════════════════════════════════════════════════════════════
+
+SEARCH QUERY: [USER_PROMPT]
+SEARCH SCALE: [SCALE] ([agents] agents deployed)
+SEARCH TIME:  [duration]
+
+────────────────────────────────────────────────────────────────────
+                    PRIMARY FINDINGS
+────────────────────────────────────────────────────────────────────
+
+HIGH RELEVANCE:
+📄 [file-path] - [description]
+📄 [file-path] - [description]
+
+MODERATE RELEVANCE:
+📄 [file-path] - [description]
+📄 [file-path] - [description]
+
+────────────────────────────────────────────────────────────────────
+                    FILES BY CATEGORY
+────────────────────────────────────────────────────────────────────
+
+IMPLEMENTATION:
+• [file-path] - [what it does]
+• [file-path] - [what it does]
+
+TESTS:
+• [file-path] - [what it tests]
+
+CONFIGURATION:
+• [file-path] - [what it configures]
+
+DOCUMENTATION:
+• [file-path] - [what it documents]
+
+────────────────────────────────────────────────────────────────────
+                    KEY INSIGHTS
+────────────────────────────────────────────────────────────────────
+
+• [Insight about how feature is implemented]
+• [Insight about patterns used]
+• [Insight about dependencies]
+
+────────────────────────────────────────────────────────────────────
+                    UNRESOLVED QUESTIONS
+────────────────────────────────────────────────────────────────────
+
+• [Question 1 that search couldn't answer]
+• [Question 2 requiring deeper investigation]
+
+════════════════════════════════════════════════════════════════════
+
+TOTAL FILES FOUND: [count]
+SEARCH COVERAGE:  [percentage or description]
+```
+
+### Step 6: Save Report (Optional)
+
+If TASK_ID ($3) is provided:
+1. Verify `./.claude/tasks/$3/` directory exists
+2. Create `./.claude/tasks/$3/reports/` directory if needed
+3. Save report as `./.claude/tasks/$3/reports/YYYYMMDD-HHmm-scout-report.md`
+
+If no task-id, display report in conversation only.
+
+---
+
+## Error Handling
+
+### Agent Timeout
+- If an agent times out (>3 minutes), include its partial results
+- Note which zones were not fully searched
+- Suggest re-running with different SCALE or more specific query
+
+### No Results Found
+```
+No files found matching: [USER_PROMPT]
+
+Suggestions:
+• Try broader search terms
+• Check if feature exists in this codebase
+• Verify correct spelling and terminology
+• Try different search scale (current: [SCALE])
+```
+
+### Agent Failures
+- If agents fail to launch or crash, report the error
+- Provide partial results from successful agents
+- Suggest troubleshooting steps
+
+---
+
+## Usage Examples
+
+### Example 1: Quick Search (SCALE=1)
+```
+/scout "authentication middleware" 1
+
+Deploys 1 agent to quickly find auth middleware files.
+Best for: Known location, simple search
+```
+
+### Example 2: Standard Search (SCALE=3)
+```
+/scout "user profile API endpoints" 3
+
+Deploys 3 agents to search controllers, services, and tests.
+Best for: Common features, moderate uncertainty
+```
+
+### Example 3: Comprehensive Search (SCALE=5)
+```
+/scout "payment processing logic" 5
+
+Deploys 5 agents for thorough search across all layers.
+Best for: Complex features, uncertain location
+```
+
+---
+
+## Tips for Effective Scouting
+
+**Good Search Queries**:
+- "authentication logic" ✓
+- "API endpoints for user management" ✓
+- "database migrations for products table" ✓
+- "error handling utilities" ✓
+
+**Poor Search Queries**:
+- "code" ✗ (too vague)
+- "everything" ✗ (too broad)
+- "file.ts" ✗ (use Read tool instead)
+
+**When to Use Scout**:
+- Starting work on unfamiliar codebase areas
+- Finding all files related to a feature
+- Understanding code organization patterns
+- Locating integration points between systems
+
+**When NOT to Use Scout**:
+- You know exact file paths (use Read instead)
+- Searching for specific text/code (use Grep instead)
+- Finding files by pattern (use Glob instead)
+
+---
+
+## Begin Now
+
+1. Validate USER_PROMPT ($1) - what to search for
+2. Validate SCALE ($2) - how many agents (default: 3)
+3. Check TASK_ID ($3) - optional, for saving report to task directory
+4. Analyze search request and divide territory
+5. Launch SCALE number of Explore agents in parallel
+6. Collect results and generate scout report
+7. If task-id provided, save to `./.claude/tasks/[task-id]/reports/`
+
+Ready to scout the codebase. What should I search for?

package/templates/.claude/commands/devkit/skill/add.md

@@ -0,0 +1,29 @@
+---
+description: Add new reference files or scripts to a skill
+argument-hint: [skill-name] [reference-or-script-prompt]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+$1: skill name (required, default: "")
+$2: reference or script prompt (required, default: "")
+If $1 or $2 is not provided, use `AskUserQuestion` tool to ask the user to provide it.
+
+## Your mission
+Add new reference files or scripts to a skill at `.claude/skills/$1` directory.
+
+## Requirements
+<reference-or-script-prompt>
+$2
+</reference-or-script-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.

package/templates/.claude/commands/devkit/skill/create.md

@@ -0,0 +1,22 @@
+---
+description: Create a new agent skill
+argument-hint: [prompt-or-llms-or-github-url]
+---
+
+Ultrathink.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Your mission
+Create a new skill in `.claude/skills/` directory.
+
+## Requirements
+<user-prompt>$ARGUMENTS</user-prompt>
+
+## Rules of Skill Creation:
+Base on the requirements:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- If you're given an URL, it's documentation page, use `Explore` subagent to explore every internal link and report back to main agent, don't skip any link.
+- If you receive a lot of URLs, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you receive a lot of files, use multiple `Explore` subagents to explore them in parallel, then report back to main agent.
+- If you're given a Github URL, use [`repomix`](https://repomix.com/guide/usage) command to summarize ([install it](https://repomix.com/guide/installation) if needed) and spawn multiple `Explore` subagents to explore it in parallel, then report back to main agent.

package/templates/.claude/commands/devkit/skill/optimize.md

@@ -0,0 +1,34 @@
+---
+description: Optimize an existing agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to optimize an existing skill in `./.claude/skills/${SKILL}` directory. 
+When you finish, use `AskUserQuestion` tool to ask user to review your plan:
+- If the user approve: Write down a plan follow "Output Requirements", then use `AskUserQuestion` tool to ask user if they want to start implementing.
+- If the user reject: Revise the plan or use `AskUserQuestion` tool to ask more questions to clarify more about the user's request (ask one question at the time), then repeat the review process.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>
+
+## Output Requirements
+An output implementation plan must also follow the progressive disclosure structure:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- `SKILL.md` is always short and concise, straight to the point, treat it as a quick reference guide.
+- Create a directory `./.claude/plans/{date}-plan-name` (date format from `$TASK_DATE_FORMAT`).
+- Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+- For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+**IMPORTANT:**
+- Skills are not documentation, they are practical instructions for Claude Code to use the tools, packages, plugins or APIs to achieve the tasks.
+- Each skill teaches Claude how to perform a specific development task, not what a tool does.
+- Claude Code can activate multiple skills automatically to achieve the user's request.