cokit-cli 1.2.6 → 1.3.0

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

@@ -1,105 +1,116 @@
----
-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
-
+---
+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
+---
+
+# Requesting Code Review
+
+Dispatch code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Scout first, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-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
+
+**0. Scout edge cases first (NEW):**
+```
+Before dispatching code-reviewer, invoke /ck-scout to find:
+- Files affected by changes (not just modified files)
+- Data flow paths that could break
+- Edge cases and boundary conditions
+- Potential side effects
+
+See: references/edge-case-scouting.md
+```
+
+**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 subagent:**
+
+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 subagent]
+  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]:
+  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
+
+**Subagent-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/code-review/references/spec-compliance-review.md

@@ -0,0 +1,43 @@
+---
+name: spec-compliance-review
+description: First-pass review checking implementation matches spec/plan requirements before quality review
+---
+
+# Spec Compliance Review
+
+## Purpose
+
+Verify implementation matches what was requested BEFORE evaluating code quality.
+Well-written code that doesn't match requirements is still wrong.
+
+## When to Use
+
+- After implementing features from a plan
+- Before code quality review pass
+- When plan/spec exists for the work being reviewed
+
+## Process
+
+1. **Load spec/plan** — Read the plan.md or phase file that defined this work
+2. **List requirements** — Extract every requirement, acceptance criterion
+3. **Check each requirement** against actual implementation:
+   - Present? → PASS
+   - Missing? → MISSING (must fix before quality review)
+   - Extra (not in spec)? → EXTRA (flag for removal unless justified)
+4. **Verdict:**
+   - All requirements met, no unjustified extras → PASS → proceed to quality review
+   - Missing requirements → FAIL → implementer fixes → re-review
+   - Unjustified extras → WARN → discuss with user
+
+## Checklist Template
+
+| # | Requirement | Status | Notes |
+|---|-------------|--------|-------|
+| 1 | [from spec] | PASS/MISSING/EXTRA | [evidence] |
+
+## Red Flags
+
+- Skipping spec review because "code looks good"
+- Accepting extra features without spec justification
+- Treating spec review as optional
+- Reviewing code quality before confirming spec compliance

package/skills/code-review/references/task-management-reviews.md

@@ -0,0 +1,155 @@
+# Review Task Management Patterns
+
+Track review pipeline execution via Native Tasks (TaskCreate, TaskUpdate, TaskList).
+
+## When to Create Tasks
+
+| Review Scope | Tasks? | Rationale |
+|--------------|--------|-----------|
+| Single-file fix | No | Scout + review + done, overhead not worth it |
+| Multi-file feature (3+ files) | Yes | Track scout → review → fix → verify chain |
+| Parallel reviewers (2+ scopes) | Yes | Coordinate independent reviews |
+| Review cycle with Critical fixes | Yes | Dependencies between fix → re-verify |
+
+**3-Task Rule:** Skip task creation when review pipeline has <3 meaningful steps.
+
+## Review Pipeline as Tasks
+
+```
+TaskCreate: "Scout edge cases"         → pending
+TaskCreate: "Review implementation"    → pending, blockedBy: [scout]
+TaskCreate: "Adversarial review"       → pending, blockedBy: [review]
+TaskCreate: "Fix critical issues"      → pending, blockedBy: [adversarial]
+TaskCreate: "Verify fixes pass"        → pending, blockedBy: [fix]
+```
+
+Dependency chain auto-unblocks: scout → review → adversarial → fix → verify.
+
+## Task Schemas
+
+### Scout Task
+
+```
+TaskCreate(
+  subject: "Scout edge cases for {feature}",
+  activeForm: "Scouting edge cases",
+  description: "Identify affected files, data flows, boundary conditions. Changed: {files}",
+  metadata: { reviewStage: "scout", feature: "{feature}",
+              changedFiles: "src/auth.ts,src/middleware.ts",
+              priority: "P2", effort: "3m" }
+)
+```
+
+### Review Task
+
+```
+TaskCreate(
+  subject: "Review {feature} implementation",
+  activeForm: "Reviewing {feature}",
+  description: "Code-reviewer subagent reviews {BASE_SHA}..{HEAD_SHA}. Plan: {plan_ref}",
+  metadata: { reviewStage: "review", feature: "{feature}",
+              baseSha: "{BASE_SHA}", headSha: "{HEAD_SHA}",
+              priority: "P1", effort: "10m" },
+  addBlockedBy: ["{scout-task-id}"]
+)
+```
+
+### Adversarial Task
+
+```
+TaskCreate(
+  subject: "Adversarial review for {feature}",
+  activeForm: "Red-teaming {feature}",
+  description: "Spawn adversarial reviewer to break the code. See references/adversarial-review.md",
+  metadata: { reviewStage: "adversarial", feature: "{feature}",
+              priority: "P1", effort: "10m" },
+  addBlockedBy: ["{review-task-id}"]
+)
+```
+
+### Fix Task (created after adversarial finds issues)
+
+```
+TaskCreate(
+  subject: "Fix {severity} issues from review",
+  activeForm: "Fixing {severity} review issues",
+  description: "Address: {issue_list}",
+  metadata: { reviewStage: "fix", severity: "critical",
+              issueCount: 3, priority: "P1", effort: "15m" },
+  addBlockedBy: ["{review-task-id}"]
+)
+```
+
+### Verify Task
+
+```
+TaskCreate(
+  subject: "Verify fixes pass tests and build",
+  activeForm: "Verifying fixes",
+  description: "Run test suite, build, confirm 0 failures. Evidence before claims.",
+  metadata: { reviewStage: "verify", priority: "P1", effort: "5m" },
+  addBlockedBy: ["{fix-task-id}"]
+)
+```
+
+## Parallel Review Coordination
+
+For multi-scope reviews (e.g., backend + frontend changed independently):
+
+```
+// Create scoped review tasks — no blockedBy between them
+TaskCreate(subject: "Review backend auth changes",
+  metadata: { reviewStage: "review", scope: "src/api/,src/middleware/",
+              agentIndex: 1, totalAgents: 2, priority: "P1" })
+
+TaskCreate(subject: "Review frontend auth UI",
+  metadata: { reviewStage: "review", scope: "src/components/auth/",
+              agentIndex: 2, totalAgents: 2, priority: "P1" })
+
+// Both run simultaneously via separate code-reviewer subagents
+// Fix task blocks on BOTH completing:
+TaskCreate(subject: "Fix all review issues",
+  addBlockedBy: ["{backend-review-id}", "{frontend-review-id}"])
+```
+
+## Task Lifecycle
+
+```
+Scout:       pending → in_progress → completed (scout report returned)
+Review:      pending → in_progress → completed (reviewer findings returned)
+Adversarial: pending → in_progress → completed (red-team findings adjudicated)
+Fix:         pending → in_progress → completed (all Critical/Important fixed)
+Verify:      pending → in_progress → completed (tests pass, build clean)
+```
+
+### Handling Re-Reviews
+
+When fixes introduce new issues → create new review cycle:
+
+```
+TaskCreate(subject: "Re-review after fixes",
+  addBlockedBy: ["{fix-task-id}"],
+  metadata: { reviewStage: "review", cycle: 2, priority: "P1" })
+```
+
+Limit to 3 cycles. If still failing after cycle 3 → escalate to user.
+
+## Integration with Planning Tasks
+
+Review tasks are **separate from** cook/planning phase tasks.
+
+**When cook spawns review:**
+1. Cook completes implementation phase → creates review pipeline tasks
+2. Review pipeline executes (scout → review → adversarial → fix → verify)
+3. All review tasks complete → cook marks phase as reviewed
+4. Cook proceeds to next phase
+
+Review tasks reference the phase but don't block it directly — the orchestrator manages handoff.
+
+## Quality Check
+
+After pipeline registration: `Registered [N] review tasks (scout → review → adversarial → fix → verify chain)`
+
+## Error Handling
+
+If `TaskCreate` fails: log warning, fall back to sequential review without task tracking. Review pipeline functions identically — tasks add visibility, not functionality.

package/skills/common/README.md

@@ -36,19 +36,9 @@ The helper checks for `GEMINI_API_KEY` in this order:
    echo 'GEMINI_API_KEY=your-api-key' > .env
    ```
 
-3. **.copilot/.env file**
+3. **Skill directory `.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
+   echo 'GEMINI_API_KEY=your-api-key' > skills/your-skill/.env
    ```
 
 ### Vertex AI Support

package/skills/common/api_key_helper.py

@@ -7,9 +7,7 @@ Supports both Google AI Studio and Vertex AI endpoints.
 API Key Detection Order:
 1. Process environment variable
 2. Project root .env file
-3. ./.copilot/.env
-4. ./.copilot/skills/.env
-5. Skill directory .env file
+3. Skill directory .env file
 
 Vertex AI Configuration:
 - GEMINI_USE_VERTEX: Set to "true" to use Vertex AI endpoint
@@ -26,12 +24,10 @@ from typing import Optional, Dict, Any, List
 
 def find_api_key(skill_dir: Optional[Path] = None) -> Optional[str]:
     """
-    Find GEMINI_API_KEY using 5-step lookup:
+    Find GEMINI_API_KEY using 3-step lookup:
     1. Process environment
     2. Project root .env
-    3. ./.copilot/.env
-    4. ./.copilot/skills/.env
-    5. Skill directory .env
+    3. Skill directory .env
 
     Args:
         skill_dir: Path to skill directory (optional, auto-detected if None)
@@ -58,23 +54,7 @@ def find_api_key(skill_dir: Optional[Path] = None) -> Optional[str]:
             print(f"✓ Using API key from {project_env}", file=sys.stderr)
             return api_key
 
-    # Step 3: Check ./.copilot/.env
-    config_env = project_dir / '.copilot' / '.env'
-    if config_env.exists():
-        api_key = load_env_file(config_env)
-        if api_key:
-            print(f"✓ Using API key from {config_env}", file=sys.stderr)
-            return api_key
-
-    # Step 4: Check ./.copilot/skills/.env
-    skills_config_env = project_dir / '.copilot' / 'skills' / '.env'
-    if skills_config_env.exists():
-        api_key = load_env_file(skills_config_env)
-        if api_key:
-            print(f"✓ Using API key from {skills_config_env}", file=sys.stderr)
-            return api_key
-
-    # Step 5: Check skill directory .env
+    # Step 3: Check skill directory .env
     skill_env = skill_dir / '.env'
     if skill_env.exists():
         api_key = load_env_file(skill_env)
@@ -139,7 +119,7 @@ def load_env_var(env_path: Path, var_name: str) -> Optional[str]:
 
 def find_env_var(var_name: str, skill_dir: Optional[Path] = None) -> Optional[str]:
     """
-    Find environment variable using 5-step lookup (same as API key)
+    Find environment variable using 3-step lookup (same as API key)
 
     Args:
         var_name: Name of environment variable
@@ -158,11 +138,9 @@ def find_env_var(var_name: str, skill_dir: Optional[Path] = None) -> Optional[st
         skill_dir = Path(__file__).parent.parent
     project_dir = skill_dir.parent.parent.parent
 
-    # Step 2-5: Check .env files in order
+    # Step 2-3: Check .env files in order
     env_files = [
         project_dir / '.env',
-        project_dir / '.copilot' / '.env',
-        project_dir / '.copilot' / 'skills' / '.env',
         skill_dir / '.env'
     ]
 
@@ -202,8 +180,6 @@ def find_all_api_keys(skill_dir: Optional[Path] = None) -> List[str]:
     # Collect all .env file paths in priority order
     env_files = [
         project_dir / '.env',
-        project_dir / '.copilot' / '.env',
-        project_dir / '.copilot' / 'skills' / '.env',
         skill_dir / '.env'
     ]
 
@@ -338,13 +314,7 @@ def get_api_key_or_exit(skill_dir: Optional[Path] = None) -> str:
         print("\n2️⃣  Project root .env file:", file=sys.stderr)
         print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.env", file=sys.stderr)
 
-        print("\n3️⃣  .copilot/.env file:", file=sys.stderr)
-        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.copilot/.env", file=sys.stderr)
-
-        print("\n4️⃣  .copilot/skills/.env file (shared across all Gemini skills):", file=sys.stderr)
-        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.copilot/skills/.env", file=sys.stderr)
-
-        print("\n5️⃣  Skill directory .env file:", file=sys.stderr)
+        print("\n3️⃣  Skill directory .env file:", file=sys.stderr)
         print(f"   echo 'GEMINI_API_KEY=your-api-key' > {skill_dir}/.env", file=sys.stderr)
 
         print("\n🔑 Get your API key at: https://aistudio.google.com/apikey", file=sys.stderr)

package/skills/context-engineering/SKILL.md

@@ -3,6 +3,7 @@ name: context-engineering
 description: >-
   Check context usage limits, monitor time remaining, optimize token consumption, debug context failures.
   Use when asking about context percentage, rate limits, usage warnings, context optimization, agent architectures, memory systems.
+argument-hint: "[topic or question]"
 ---
 
 # Context Engineering
@@ -30,7 +31,7 @@ Context engineering curates the smallest high-signal token set for LLM tasks. Th
 **IMPORTANT:**
 - Sacrifice grammar for the sake of concision.
 - Ensure token efficiency while maintaining high quality.
-- Pass these rules to agents.
+- Pass these rules to subagents.
 
 ## Quick Reference
 
@@ -87,7 +88,7 @@ The system automatically injects usage awareness via PostToolUse hook:
 
 ```xml
 <usage-awareness>
-Usage Limits: 5h=45%, 7d=32%
+AI Usage Limits: 5h=45%, 7d=32%
 Context Window Usage: 67%
 </usage-awareness>
 ```
@@ -97,7 +98,7 @@ Context Window Usage: 67%
 - 90%: CRITICAL - immediate action needed
 
 **Data Sources:**
-- Usage limits: Platform OAuth API (platform-specific endpoint)
+- Usage limits: Anthropic OAuth API (`https://api.anthropic.com/api/oauth/usage`)
 - Context window: Statusline temp file (`/tmp/ck-context-{session_id}.json`)
 
 ## Scripts

package/skills/context-engineering/references/context-degradation.md

@@ -52,8 +52,8 @@ Predictable degradation as context grows. Not binary - a continuum.
 | Model | Degradation Onset | Severe Degradation |
 |-------|-------------------|-------------------|
 | GPT-5.2 | ~64K tokens | ~200K tokens |
-| Model (Large) | ~100K tokens | ~180K tokens |
-| Model (Medium) | ~80K tokens | ~150K tokens |
+| Opus 4.5 | ~100K tokens | ~180K tokens |
+| Sonnet 4.5 | ~80K tokens | ~150K tokens |
 | Gemini 3 Pro | ~500K tokens | ~800K tokens |
 
 ## Four-Bucket Mitigation

package/skills/context-engineering/references/runtime-awareness.md

@@ -1,6 +1,6 @@
 # Runtime Awareness
 
-Monitor usage limits and context window utilization in real-time to optimize AI agent sessions.
+Monitor usage limits and context window utilization in real-time to optimize Copilot sessions.
 
 ## Overview
 
@@ -24,48 +24,6 @@ Runtime awareness provides visibility into two critical metrics:
                        └──────────────────────────┘
 ```
 
-## Usage Limits API
-
-### Endpoint
-
-```
-GET <platform-specific-usage-endpoint>
-```
-
-### Authentication
-
-Requires OAuth Bearer token with platform-specific headers.
-
-### Credential Locations
-
-| Platform | Method | Location |
-|----------|--------|----------|
-| macOS | Keychain | `agent-credentials` |
-| Windows | File | `%USERPROFILE%.copilot\.credentials.json` |
-| Linux | File | `~/.copilot/.credentials.json` |
-
-### Response Structure
-
-```json
-{
-  "five_hour": {
-    "utilization": 45,
-    "resets_at": "2025-01-15T18:00:00Z"
-  },
-  "seven_day": {
-    "utilization": 32,
-    "resets_at": "2025-01-22T00:00:00Z"
-  },
-  "seven_day_sonnet": {
-    "utilization": 11,
-    "resets_at": "2025-01-15T09:00:00Z"
-  }
-}
-```
-
-- `utilization`: Already a percentage (0-100), NOT a decimal
-- `resets_at`: ISO 8601 timestamp when quota resets
-- `seven_day_sonnet`: Model-specific limit (may be null)
 
 ## Context Window Data
 
@@ -157,7 +115,7 @@ Context: 91% [CRITICAL - compaction needed]
 | 5-Hour | Action |
 |--------|--------|
 | < 70% | Normal usage |
-| 70-90% | Reduce parallelization, delegate to agents |
+| 70-90% | Reduce parallelization, delegate to subagents |
 | > 90% | Wait for reset or use lower-tier models |
 
 | 7-Day | Action |
@@ -168,7 +126,7 @@ Context: 91% [CRITICAL - compaction needed]
 
 ## Configuration
 
-### Hook Settings (`$HOME/.copilot/settings.json`)
+### Hook Settings (`.vscode/settings.json`)
 
 ```json
 {
@@ -178,7 +136,7 @@ Context: 91% [CRITICAL - compaction needed]
         "matcher": "*",
         "hooks": [{
           "type": "command",
-          "command": "node $HOME/.copilot/hooks/usage-context-awareness.cjs"
+          "command": "node hooks/usage-context-awareness.cjs"
         }]
       }
     ]
@@ -196,7 +154,7 @@ Context: 91% [CRITICAL - compaction needed]
 
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| No usage limits shown | No OAuth token | Run the agent login command |
+| No usage limits shown | No OAuth token | Check credentials |
 | Stale context data | Statusline not updating | Check statusline config |
 | 401 Unauthorized | Expired token | Re-authenticate |
 | Hook not firing | Settings misconfigured | Verify PostToolUse matcher |