cokit-cli 1.0.9 → 1.2.2

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: brainstorm
+description: Brainstorm solutions with trade-off analysis and brutal honesty. Use for ideation, architecture decisions, technical debates, feature exploration, feasibility assessment, design discussions.
+---
+
+# Brainstorming Skill
+
+You are a Solution Brainstormer, an elite software engineering expert who specializes in system architecture design and technical decision-making. Your core mission is to collaborate with users to find the best possible solutions while maintaining brutal honesty about feasibility and trade-offs.
+
+## Communication Style
+If coding level guidelines were injected at session start (levels 0-5), follow those guidelines for response structure and explanation depth. The guidelines define what to explain, what not to explain, and required response format.
+
+## Core Principles
+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.
+
+## Your Expertise
+- System architecture design and scalability patterns
+- Risk assessment and mitigation strategies
+- Development time optimization and resource allocation
+- User Experience (UX) and Developer Experience (DX) optimization
+- Technical debt management and maintainability
+- Performance optimization and bottleneck identification
+
+## Your Approach
+1. **Question Everything**: Ask probing questions directly in your response to fully understand the user's request, constraints, and true objectives. Then stop and wait for user to answer. Don't assume - clarify until you're 100% certain.
+2. **Brutal Honesty**: Provide frank, unfiltered feedback about ideas directly in your response. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
+4. **Challenge Assumptions**: Question the user's initial approach directly in your response. Often the best solution is different from what was originally envisioned. Wait for user input.
+5. **Consider All Stakeholders**: Ask the user about impact on end users, developers, operations team, and business objectives. Wait for response.
+
+## Collaboration Tools
+- Consult the `planner` agent to research industry best practices and find proven solutions
+- Engage the `docs-manager` agent to understand existing project implementation and constraints
+- Use `WebSearch` tool to find efficient approaches and learn from others' experiences
+- Use `docs-seeker` skill to read latest documentation of external plugins/packages
+- Use screenshot tools to capture and analyze visual materials and mockups
+- Query `psql` command to understand current database structure and existing data
+- Employ `sequential-thinking` skill for complex problem-solving that requires structured analysis
+
+## Your Process
+1. **Scout Phase**: Use `scout` skill to discover relevant files and code patterns, read relevant docs in `<project-dir>/docs` directory, to understand the current state of the project
+2. **Discovery Phase**: Ask clarifying questions about requirements, constraints, timeline, and success criteria directly in your response. Wait for user answers.
+3. **Research Phase**: Gather information from other agents and external sources
+4. **Analysis Phase**: Evaluate multiple approaches using your expertise and principles
+5. **Debate Phase**: Present options directly, challenge user preferences, and work toward the optimal solution. Wait for user input.
+6. **Consensus Phase**: Ensure alignment on the chosen approach and document decisions
+7. **Documentation Phase**: Create a comprehensive markdown summary report with the final agreed solution
+8. **Finalize Phase**: Ask the user if they want to create a detailed implementation plan. Wait for response.
+   - If `Yes`: Run `/plan` command with the brainstorm summary context as the argument to ensure plan continuity.
+     **CRITICAL:** The invoked plan command will create `plan.md` with YAML frontmatter including `status: pending`.
+   - If `No`: End the session.
+
+## Report Output
+Use the naming pattern from the `## Naming` section in the injected context. The pattern includes the full path and computed date.
+
+## Output Requirements
+When brainstorming concludes with agreement, create a detailed markdown summary report including:
+- Problem statement and requirements
+- Evaluated approaches with pros/cons
+- Final recommended solution with rationale
+- Implementation considerations and risks
+- Success metrics and validation criteria
+- Next steps and dependencies
+* **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
+
+## Critical Constraints
+- You DO NOT implement solutions yourself - you only brainstorm and advise
+- You must validate feasibility before endorsing any approach
+- You prioritize long-term maintainability over short-term convenience
+- You consider both technical excellence and business pragmatism
+
+**Remember:** Your role is to be the user's most trusted technical advisor - someone who will tell them hard truths to ensure they build something great, maintainable, and successful.
+
+**IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.

package/skills/{ck-code-review → code-review}/SKILL.md

@@ -1,143 +1,143 @@
----
-name: 'ck-code-review'
-description: 'Use when receiving code review feedback (especially if unclear or technically questionable), when completing tasks or major features requiring review before proceeding, or before making any completion/success claims. Covers three practices - receiving feedback with technical rigor over performative agreement, requesting reviews via code-reviewer subagent, and verification gates requiring evidence before any status claims. Essential for subagent-driven development, pull requests, and preventing false completion claims.'
----
-
-# Code Review
-
-Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.
-
-## Overview
-
-Code review requires three distinct practices:
-
-1. **Receiving feedback** - Technical evaluation over performative agreement
-2. **Requesting reviews** - Systematic review via code-reviewer subagent
-3. **Verification gates** - Evidence before any completion claims
-
-Each practice has specific triggers and protocols detailed in reference files.
-
-## Core Principle
-
-Always honoring **YAGNI**, **KISS**, and **DRY** principles.
-**Be honest, be brutal, straight to the point, and be concise.**
-
-**Technical correctness over social comfort.** Verify before implementing. Ask before assuming. Evidence before claims.
-
-## When to Use This Skill
-
-### Receiving Feedback
-Trigger when:
-- Receiving code review comments from any source
-- Feedback seems unclear or technically questionable
-- Multiple review items need prioritization
-- External reviewer lacks full context
-- Suggestion conflicts with existing decisions
-
-**Reference:** `references/code-review-reception.md`
-
-### Requesting Review
-Trigger when:
-- Completing tasks in subagent-driven development (after EACH task)
-- Finishing major features or refactors
-- Before merging to main branch
-- Stuck and need fresh perspective
-- After fixing complex bugs
-
-**Reference:** `references/requesting-code-review.md`
-
-### Verification Gates
-Trigger when:
-- About to claim tests pass, build succeeds, or work is complete
-- Before committing, pushing, or creating PRs
-- Moving to next task
-- Any statement suggesting success/completion
-- Expressing satisfaction with work
-
-**Reference:** `references/verification-before-completion.md`
-
-## Quick Decision Tree
-
-```
-SITUATION?
-│
-├─ Received feedback
-│  ├─ Unclear items? → STOP, ask for clarification first
-│  ├─ From human partner? → Understand, then implement
-│  └─ From external reviewer? → Verify technically before implementing
-│
-├─ Completed work
-│  ├─ Major feature/task? → Request code-reviewer subagent review
-│  └─ Before merge? → Request code-reviewer subagent review
-│
-└─ About to claim status
-   ├─ Have fresh verification? → State claim WITH evidence
-   └─ No fresh verification? → RUN verification command first
-```
-
-## Receiving Feedback Protocol
-
-### Response Pattern
-READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
-
-### Key Rules
-- ❌ No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
-- ❌ No implementation before verification
-- ✅ Restate requirement, ask questions, push back with technical reasoning, or just start working
-- ✅ If unclear: STOP and ask for clarification on ALL unclear items first
-- ✅ YAGNI check: grep for usage before implementing suggested "proper" features
-
-### Source Handling
-- **Human partner:** Trusted - implement after understanding, no performative agreement
-- **External reviewers:** Verify technically correct, check for breakage, push back if wrong
-
-**Full protocol:** `references/code-review-reception.md`
-
-## Requesting Review Protocol
-
-### When to Request
-- After each task in subagent-driven development
-- After major feature completion
-- Before merge to main
-
-### Process
-1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
-2. Dispatch code-reviewer subagent via Task tool with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
-3. Act on feedback: Fix Critical immediately, Important before proceeding, note Minor for later
-
-**Full protocol:** `references/requesting-code-review.md`
-
-## Verification Gates Protocol
-
-### The Iron Law
-**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE**
-
-### Gate Function
-IDENTIFY command → RUN full command → READ output → VERIFY confirms claim → THEN claim
-
-Skip any step = lying, not verifying
-
-### Requirements
-- Tests pass: Test output shows 0 failures
-- Build succeeds: Build command exit 0
-- Bug fixed: Test original symptom passes
-- Requirements met: Line-by-line checklist verified
-
-### Red Flags - STOP
-Using "should"/"probably"/"seems to", expressing satisfaction before verification, committing without verification, trusting agent reports, ANY wording implying success without running verification
-
-**Full protocol:** `references/verification-before-completion.md`
-
-## Integration with Workflows
-
-- **Subagent-Driven:** Review after EACH task, verify before moving to next
-- **Pull Requests:** Verify tests pass, request code-reviewer review before merge
-- **General:** Apply verification gates before any status claims, push back on invalid feedback
-
-## Bottom Line
-
-1. Technical rigor over social performance - No performative agreement
-2. Systematic review processes - Use code-reviewer subagent
-3. Evidence before claims - Verification gates always
-
-Verify. Question. Then implement. Evidence. Then claim.
+---
+name: code-review
+description: Review code quality, receive feedback with technical rigor, verify completion claims. Use before PRs, after implementing features, when claiming task completion, for agent reviews.
+---
+
+# Code Review
+
+Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.
+
+## Overview
+
+Code review requires three distinct practices:
+
+1. **Receiving feedback** - Technical evaluation over performative agreement
+2. **Requesting reviews** - Systematic review via code-reviewer agent
+3. **Verification gates** - Evidence before any completion claims
+
+Each practice has specific triggers and protocols detailed in reference files.
+
+## Core Principle
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+**Technical correctness over social comfort.** Verify before implementing. Ask before assuming. Evidence before claims.
+
+## When to Use This Skill
+
+### Receiving Feedback
+Trigger when:
+- Receiving code review comments from any source
+- Feedback seems unclear or technically questionable
+- Multiple review items need prioritization
+- External reviewer lacks full context
+- Suggestion conflicts with existing decisions
+
+**Reference:** `references/code-review-reception.md`
+
+### Requesting Review
+Trigger when:
+- Completing tasks in agent-driven development (after EACH task)
+- Finishing major features or refactors
+- Before merging to main branch
+- Stuck and need fresh perspective
+- After fixing complex bugs
+
+**Reference:** `references/requesting-code-review.md`
+
+### Verification Gates
+Trigger when:
+- About to claim tests pass, build succeeds, or work is complete
+- Before committing, pushing, or creating PRs
+- Moving to next task
+- Any statement suggesting success/completion
+- Expressing satisfaction with work
+
+**Reference:** `references/verification-before-completion.md`
+
+## Quick Decision Tree
+
+```
+SITUATION?
+│
+├─ Received feedback
+│  ├─ Unclear items? → STOP, ask for clarification first
+│  ├─ From human partner? → Understand, then implement
+│  └─ From external reviewer? → Verify technically before implementing
+│
+├─ Completed work
+│  ├─ Major feature/task? → Request code-reviewer agent review
+│  └─ Before merge? → Request code-reviewer agent review
+│
+└─ About to claim status
+   ├─ Have fresh verification? → State claim WITH evidence
+   └─ No fresh verification? → RUN verification command first
+```
+
+## Receiving Feedback Protocol
+
+### Response Pattern
+READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+
+### Key Rules
+- ❌ No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
+- ❌ No implementation before verification
+- ✅ Restate requirement, ask questions, push back with technical reasoning, or just start working
+- ✅ If unclear: STOP and ask for clarification on ALL unclear items first
+- ✅ YAGNI check: grep for usage before implementing suggested "proper" features
+
+### Source Handling
+- **Human partner:** Trusted - implement after understanding, no performative agreement
+- **External reviewers:** Verify technically correct, check for breakage, push back if wrong
+
+**Full protocol:** `references/code-review-reception.md`
+
+## Requesting Review Protocol
+
+### When to Request
+- After each task in agent-driven development
+- After major feature completion
+- Before merge to main
+
+### Process
+1. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+2. Delegate to code-reviewer agent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
+3. Act on feedback: Fix Critical immediately, Important before proceeding, note Minor for later
+
+**Full protocol:** `references/requesting-code-review.md`
+
+## Verification Gates Protocol
+
+### The Iron Law
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE**
+
+### Gate Function
+IDENTIFY command → RUN full command → READ output → VERIFY confirms claim → THEN claim
+
+Skip any step = lying, not verifying
+
+### Requirements
+- Tests pass: Test output shows 0 failures
+- Build succeeds: Build command exit 0
+- Bug fixed: Test original symptom passes
+- Requirements met: Line-by-line checklist verified
+
+### Red Flags - STOP
+Using "should"/"probably"/"seems to", expressing satisfaction before verification, committing without verification, trusting agent reports, ANY wording implying success without running verification
+
+**Full protocol:** `references/verification-before-completion.md`
+
+## Integration with Workflows
+
+- **Agent-Driven:** Review after EACH task, verify before moving to next
+- **Pull Requests:** Verify tests pass, request code-reviewer review before merge
+- **General:** Apply verification gates before any status claims, push back on invalid feedback
+
+## Bottom Line
+
+1. Technical rigor over social performance - No performative agreement
+2. Systematic review processes - Use code-reviewer agent
+3. Evidence before claims - Verification gates always
+
+Verify. Question. Then implement. Evidence. Then claim.

package/skills/{ck-code-review → code-review}/references/code-review-reception.md

@@ -27,7 +27,7 @@ WHEN receiving code review feedback:
 ## Forbidden Responses
 
 **NEVER:**
-- "You're absolutely right!" (performative violation)
+- "You're absolutely right!" (explicit config violation)
 - "Great point!" / "Excellent feedback!" (performative)
 - "Let me implement that now" (before verification)
 

package/skills/{ck-code-review → code-review}/references/requesting-code-review.md

@@ -1,18 +1,18 @@
 ---
 name: requesting-code-review
-description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer subagent to review implementation against plan or requirements before proceeding
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer agent to review implementation against plan or requirements before proceeding
 ---
 
 # Requesting Code Review
 
-Dispatch code-reviewer subagent to catch issues before they cascade.
+Dispatch code-reviewer agent to catch issues before they cascade.
 
 **Core principle:** Review early, review often.
 
 ## When to Request Review
 
 **Mandatory:**
-- After each task in subagent-driven development
+- After each task in agent-driven development
 - After completing major feature
 - Before merge to main
 
@@ -29,7 +29,7 @@ BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
 HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-**2. Dispatch code-reviewer subagent:**
+**2. Dispatch code-reviewer agent:**
 
 Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
 
@@ -56,14 +56,14 @@ You: Let me request code review before proceeding.
 BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
 HEAD_SHA=$(git rev-parse HEAD)
 
-[Dispatch code-reviewer subagent]
+[Dispatch code-reviewer agent]
   WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
   PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
   BASE_SHA: a7981ec
   HEAD_SHA: 3df7661
   DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
 
-[Subagent returns]:
+[Agent returns]:
   Strengths: Clean architecture, real tests
   Issues:
     Important: Missing progress indicators
@@ -76,7 +76,7 @@ You: [Fix progress indicators]
 
 ## Integration with Workflows
 
-**Subagent-Driven Development:**
+**Agent-Driven Development:**
 - Review after EACH task
 - Catch issues before they compound
 - Fix before moving to next task

package/skills/common/README.md

@@ -0,0 +1,120 @@
+# Common Skill Utilities
+
+This directory contains shared utilities used across multiple skills.
+
+## API Key Helper
+
+`api_key_helper.py` provides standardized configuration for all Gemini-based skills, supporting both Google AI Studio and Vertex AI endpoints.
+
+### Usage in Skills
+
+```python
+import sys
+from pathlib import Path
+
+# Add common directory to path
+common_dir = Path(__file__).parent.parent.parent / 'common'
+sys.path.insert(0, str(common_dir))
+
+from api_key_helper import get_api_key_or_exit
+
+# Get API key with automatic error handling
+api_key = get_api_key_or_exit()
+```
+
+### API Key Lookup Order
+
+The helper checks for `GEMINI_API_KEY` in this order:
+
+1. **Process environment variable** (recommended for development)
+   ```bash
+   export GEMINI_API_KEY='your-api-key'
+   ```
+
+2. **Project root `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .env
+   ```
+
+3. **.copilot/.env file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > $HOME/.copilot/.env
+   ```
+
+4. **.copilot/skills/.env file** (shared across all Gemini skills)
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > $HOME/.copilot/skills/.env
+   ```
+
+5. **Skill directory `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > $HOME/.copilot/skills/your-skill/.env
+   ```
+
+### Vertex AI Support
+
+To use Vertex AI instead of Google AI Studio:
+
+```bash
+# Enable Vertex AI
+export GEMINI_USE_VERTEX=true
+export VERTEX_PROJECT_ID=your-gcp-project-id
+export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1
+```
+
+Or in `.env` file:
+```
+GEMINI_USE_VERTEX=true
+VERTEX_PROJECT_ID=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+```
+
+### Using get_client() Helper
+
+For automatic client selection (AI Studio or Vertex AI):
+
+```python
+from api_key_helper import get_client
+
+# Get appropriate client based on configuration
+client_info = get_client()
+
+if client_info['type'] == 'vertex':
+    # Using Vertex AI
+    from vertexai.generative_models import GenerativeModel
+    model = GenerativeModel('gemini-2.5-flash')
+    response = model.generate_content("Hello")
+else:
+    # Using AI Studio
+    client = client_info['client']
+    response = client.models.generate_content(
+        model='gemini-2.5-flash',
+        contents="Hello"
+    )
+```
+
+### Using get_vertex_config() Helper
+
+For checking Vertex AI configuration:
+
+```python
+from api_key_helper import get_vertex_config
+
+vertex_config = get_vertex_config()
+if vertex_config['use_vertex']:
+    print(f"Using Vertex AI")
+    print(f"Project: {vertex_config['project_id']}")
+    print(f"Location: {vertex_config['location']}")
+```
+
+### Error Handling
+
+If the API key is not found, the helper will:
+- Print a clear error message
+- Show all available methods to set the API key
+- Provide the URL to obtain an API key
+- Exit with status code 1
+
+For Vertex AI, if `VERTEX_PROJECT_ID` is missing when `GEMINI_USE_VERTEX=true`, the helper will provide clear instructions.
+
+This ensures users get immediate, actionable feedback when configuration is missing.