cokit-cli 1.2.7 → 1.4.0

package/skills/code-review/SKILL.md

@@ -1,193 +0,0 @@
----
-name: code-review
-description: Review code quality, receive feedback with technical rigor, verify completion claims. Includes edge case scouting for multi-file features. 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
-
-| Practice | When | Protocol |
-|----------|------|----------|
-| **Edge Case Scouting** | Before any review on 3+ file features | `/ck-scout` for hidden paths and untested scenarios |
-| **Receiving Feedback** | Feedback from human or agent | READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT |
-| **Requesting Reviews** | After each task, before merge, after major features | Delegate to `code-reviewer` agent |
-| **Verification Gates** | Before any completion claim | Run command, read output, then claim |
-
-## 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
-
-### Edge Case Scouting
-Trigger when:
-- Feature touches 3+ files
-- Implementing complex business logic
-- Before requesting formal code review
-- After implementation, before testing
-
-**Reference:** `references/requesting-code-review.md`
-
-### 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?
-│
-├─ Multi-file feature (3+ files)?
-│  └─ Run edge case scouting first → /ck-scout then request review
-│
-├─ 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
-```
-
-## Edge Case Scouting
-
-### When to Scout
-Before formal review of any multi-file feature (3+ files changed).
-
-### Process
-1. Use `/ck-scout` to search for hidden code paths, edge inputs, error branches
-2. Document untested scenarios found
-3. Add tests or guards for critical edge cases
-4. Then proceed to formal `code-reviewer` review
-
-### What to Look For
-- Null/undefined paths not covered by tests
-- Error branches lacking handlers
-- Boundary conditions (empty arrays, max values, concurrent calls)
-- Async race conditions
-- Permission/auth edge cases
-
-## Task-Managed Review Pipeline (Multi-File Features)
-
-For features spanning 3+ files, use a structured pipeline:
-
-```
-scout → review → fix → verify
-```
-
-**Steps:**
-1. **Scout** - Use `/ck-scout` or `/ck-scout ext` to identify edge cases and gaps
-2. **Review** - Delegate to `code-reviewer` agent with full context
-3. **Fix** - Implement critical and important feedback
-4. **Verify** - Run tests, confirm fixes, then claim completion
-
-Track progress using a checklist in your plan or task notes:
-```
-- [ ] Edge case scouting complete
-- [ ] `code-reviewer` review complete
-- [ ] Critical issues fixed
-- [ ] Verification passed
-```
-
-## 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: search for usage before implementing suggested "proper" features
-
-**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. Scout edge cases (3+ file features): use `/ck-scout` first
-2. Get git SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
-3. Delegate to `code-reviewer` agent with: WHAT_WAS_IMPLEMENTED, PLAN_OR_REQUIREMENTS, BASE_SHA, HEAD_SHA, DESCRIPTION
-4. 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:** Scout edge cases first (3+ files), review after EACH task, verify before moving to next
-- **Pull Requests:** Scout → verify tests pass → request `code-reviewer` review before merge
-- **General:** Apply verification gates before any status claims, push back on invalid feedback
-- **Pipeline:** For complex features use the full `scout → review → fix → verify` pipeline
-
-## Bottom Line
-
-1. **Scout first** - Edge cases found before review save rework cycles
-2. Technical rigor over social performance - No performative agreement
-3. Systematic review processes - Use `code-reviewer` agent via pipeline
-4. Evidence before claims - Verification gates always
-
-Scout. Verify. Question. Then implement. Evidence. Then claim.

package/skills/code-review/references/code-review-reception.md

@@ -1,209 +0,0 @@
----
-name: receiving-code-review
-description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
----
-
-# Code Review Reception
-
-## Overview
-
-Code review requires technical evaluation, not emotional performance.
-
-**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
-
-## The Response Pattern
-
-```
-WHEN receiving code review feedback:
-
-1. READ: Complete feedback without reacting
-2. UNDERSTAND: Restate requirement in own words (or ask)
-3. VERIFY: Check against codebase reality
-4. EVALUATE: Technically sound for THIS codebase?
-5. RESPOND: Technical acknowledgment or reasoned pushback
-6. IMPLEMENT: One item at a time, test each
-```
-
-## Forbidden Responses
-
-**NEVER:**
-- "You're absolutely right!" (explicit config violation)
-- "Great point!" / "Excellent feedback!" (performative)
-- "Let me implement that now" (before verification)
-
-**INSTEAD:**
-- Restate the technical requirement
-- Ask clarifying questions
-- Push back with technical reasoning if wrong
-- Just start working (actions > words)
-
-## Handling Unclear Feedback
-
-```
-IF any item is unclear:
-  STOP - do not implement anything yet
-  ASK for clarification on unclear items
-
-WHY: Items may be related. Partial understanding = wrong implementation.
-```
-
-**Example:**
-```
-your human partner: "Fix 1-6"
-You understand 1,2,3,6. Unclear on 4,5.
-
-❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
-✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
-```
-
-## Source-Specific Handling
-
-### From your human partner
-- **Trusted** - implement after understanding
-- **Still ask** if scope unclear
-- **No performative agreement**
-- **Skip to action** or technical acknowledgment
-
-### From External Reviewers
-```
-BEFORE implementing:
-  1. Check: Technically correct for THIS codebase?
-  2. Check: Breaks existing functionality?
-  3. Check: Reason for current implementation?
-  4. Check: Works on all platforms/versions?
-  5. Check: Does reviewer understand full context?
-
-IF suggestion seems wrong:
-  Push back with technical reasoning
-
-IF can't easily verify:
-  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
-
-IF conflicts with your human partner's prior decisions:
-  Stop and discuss with your human partner first
-```
-
-**your human partner's rule:** "External feedback - be skeptical, but check carefully"
-
-## YAGNI Check for "Professional" Features
-
-```
-IF reviewer suggests "implementing properly":
-  grep codebase for actual usage
-
-  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
-  IF used: Then implement properly
-```
-
-**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
-
-## Implementation Order
-
-```
-FOR multi-item feedback:
-  1. Clarify anything unclear FIRST
-  2. Then implement in this order:
-     - Blocking issues (breaks, security)
-     - Simple fixes (typos, imports)
-     - Complex fixes (refactoring, logic)
-  3. Test each fix individually
-  4. Verify no regressions
-```
-
-## When To Push Back
-
-Push back when:
-- Suggestion breaks existing functionality
-- Reviewer lacks full context
-- Violates YAGNI (unused feature)
-- Technically incorrect for this stack
-- Legacy/compatibility reasons exist
-- Conflicts with your human partner's architectural decisions
-
-**How to push back:**
-- Use technical reasoning, not defensiveness
-- Ask specific questions
-- Reference working tests/code
-- Involve your human partner if architectural
-
-**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
-
-## Acknowledging Correct Feedback
-
-When feedback IS correct:
-```
-✅ "Fixed. [Brief description of what changed]"
-✅ "Good catch - [specific issue]. Fixed in [location]."
-✅ [Just fix it and show in the code]
-
-❌ "You're absolutely right!"
-❌ "Great point!"
-❌ "Thanks for catching that!"
-❌ "Thanks for [anything]"
-❌ ANY gratitude expression
-```
-
-**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
-
-**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
-
-## Gracefully Correcting Your Pushback
-
-If you pushed back and were wrong:
-```
-✅ "You were right - I checked [X] and it does [Y]. Implementing now."
-✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
-
-❌ Long apology
-❌ Defending why you pushed back
-❌ Over-explaining
-```
-
-State the correction factually and move on.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Performative agreement | State requirement or just act |
-| Blind implementation | Verify against codebase first |
-| Batch without testing | One at a time, test each |
-| Assuming reviewer is right | Check if breaks things |
-| Avoiding pushback | Technical correctness > comfort |
-| Partial implementation | Clarify all items first |
-| Can't verify, proceed anyway | State limitation, ask for direction |
-
-## Real Examples
-
-**Performative Agreement (Bad):**
-```
-Reviewer: "Remove legacy code"
-❌ "You're absolutely right! Let me remove that..."
-```
-
-**Technical Verification (Good):**
-```
-Reviewer: "Remove legacy code"
-✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
-```
-
-**YAGNI (Good):**
-```
-Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
-✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
-```
-
-**Unclear Item (Good):**
-```
-your human partner: "Fix items 1-6"
-You understand 1,2,3,6. Unclear on 4,5.
-✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
-```
-
-## The Bottom Line
-
-**External feedback = suggestions to evaluate, not orders to follow.**
-
-Verify. Question. Then implement.
-
-No performative agreement. Technical rigor always.

package/skills/code-review/references/requesting-code-review.md

@@ -1,105 +0,0 @@
----
-name: requesting-code-review
-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 agent to catch issues before they cascade.
-
-**Core principle:** Review early, review often.
-
-## When to Request Review
-
-**Mandatory:**
-- After each task in agent-driven development
-- After completing major feature
-- Before merge to main
-
-**Optional but valuable:**
-- When stuck (fresh perspective)
-- Before refactoring (baseline check)
-- After fixing complex bug
-
-## How to Request
-
-**1. Get git SHAs:**
-```bash
-BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
-HEAD_SHA=$(git rev-parse HEAD)
-```
-
-**2. Dispatch code-reviewer agent:**
-
-Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
-
-**Placeholders:**
-- `{WHAT_WAS_IMPLEMENTED}` - What you just built
-- `{PLAN_OR_REQUIREMENTS}` - What it should do
-- `{BASE_SHA}` - Starting commit
-- `{HEAD_SHA}` - Ending commit
-- `{DESCRIPTION}` - Brief summary
-
-**3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Important issues before proceeding
-- Note Minor issues for later
-- Push back if reviewer is wrong (with reasoning)
-
-## Example
-
-```
-[Just completed Task 2: Add verification function]
-
-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 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
-
-[Agent returns]:
-  Strengths: Clean architecture, real tests
-  Issues:
-    Important: Missing progress indicators
-    Minor: Magic number (100) for reporting interval
-  Assessment: Ready to proceed
-
-You: [Fix progress indicators]
-[Continue to Task 3]
-```
-
-## Integration with Workflows
-
-**Agent-Driven Development:**
-- Review after EACH task
-- Catch issues before they compound
-- Fix before moving to next task
-
-**Executing Plans:**
-- Review after each batch (3 tasks)
-- Get feedback, apply, continue
-
-**Ad-Hoc Development:**
-- Review before merge
-- Review when stuck
-
-## Red Flags
-
-**Never:**
-- Skip review because "it's simple"
-- Ignore Critical issues
-- Proceed with unfixed Important issues
-- Argue with valid technical feedback
-
-**If reviewer wrong:**
-- Push back with technical reasoning
-- Show code/tests that prove it works
-- Request clarification
-
-See template at: requesting-code-review/code-reviewer.md

package/skills/common/README.md

@@ -1,120 +0,0 @@
-# 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.