cokit-cli 1.2.7 → 1.3.0

package/templates/repo/.github/skills/code-review/references/input-mode-resolution.md

@@ -0,0 +1,135 @@
+---
+name: input-mode-resolution
+description: How to parse code-review arguments and resolve PR number, commit hash, pending changes, or default context into a reviewable diff
+---
+
+# Input Mode Resolution
+
+Resolve `/code-review` arguments into a diff for the review pipeline.
+
+## Auto-Detection Rules
+
+Parse arguments left-to-right. First match wins.
+
+| Pattern | Mode | Example |
+|---------|------|---------|
+| `#\d+` | PR | `#123`, `#45` |
+| GitHub PR URL | PR | `https://github.com/org/repo/pull/123` |
+| `[0-9a-f]{7,40}` | Commit | `abc1234`, full SHA |
+| `--pending` | Pending | explicit flag |
+| `codebase` | Codebase | existing mode |
+| *(none + context)* | Default | recent changes |
+| *(none + no context)* | Prompt | ask user by asking the user |
+
+## Resolution Commands
+
+### PR Mode
+
+```bash
+# Extract PR number from argument
+PR_NUM=$(echo "$ARG" | grep -oE '[0-9]+$')
+
+# Fetch PR metadata
+gh pr view "$PR_NUM" --json title,body,files,additions,deletions,baseRefName,headRefName
+
+# Get the diff
+gh pr diff "$PR_NUM"
+
+# Get changed file list
+gh pr diff "$PR_NUM" --name-only
+```
+
+**Context passed to reviewers:**
+- PR title and description (intent)
+- Base branch (what it merges into)
+- Full diff
+- Changed file list for scout
+
+### Commit Mode
+
+```bash
+# Validate commit exists
+git cat-file -t "$COMMIT_HASH"
+
+# Get commit metadata
+git log -1 --format="%H%n%s%n%b" "$COMMIT_HASH"
+
+# Get the diff
+git show "$COMMIT_HASH" --stat
+git show "$COMMIT_HASH" -- # full diff
+
+# Changed files
+git show "$COMMIT_HASH" --name-only --format=""
+```
+
+**Context passed to reviewers:**
+- Commit message (intent)
+- Parent commit (what it changed from)
+- Full diff
+- Changed file list for scout
+
+### Pending Mode
+
+```bash
+# Staged changes
+git diff --cached
+
+# Unstaged changes
+git diff
+
+# Combined (staged + unstaged vs HEAD)
+git diff HEAD
+
+# Changed files
+git diff HEAD --name-only
+
+# Status overview
+git status --short
+```
+
+**Context passed to reviewers:**
+- No commit message yet — ask user for brief intent description
+- Combined diff (staged + unstaged)
+- Changed file list for scout
+
+### Default Mode
+
+Use recent changes already in conversation context. If no changes apparent, fall back to Prompt mode.
+
+### Prompt Mode
+
+When no arguments and no recent context, ask the user:
+- Header: "Review Target"
+- Question: "What would you like to review?"
+- Options: Pending changes, Enter PR number, Enter commit hash, Full codebase scan, Parallel codebase audit
+
+For PR/commit options, follow up with second asking the user to get the number/hash.
+
+### Codebase Mode
+
+Codebase modes bypass diff resolution — they scan the full codebase instead.
+- `codebase` → hand off to `references/codebase-scan-workflow.md`
+- `codebase parallel` → hand off to `references/parallel-review-workflow.md`
+
+Both workflows include adversarial review (always-on).
+
+## Pipeline Handoff
+
+After resolving the diff, pass to the review pipeline:
+
+```
+Resolved diff
+  ├─ Changed files → Edge case scout
+  ├─ Full diff → Stage 1 (Spec compliance, if plan exists)
+  ├─ Full diff → Stage 2 (Code quality review)
+  └─ Full diff + findings → Stage 3 (Adversarial review)
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| PR not found | `gh pr view` fails → report "PR #N not found in this repo" |
+| Commit not found | `git cat-file` fails → report "Commit not found — is it pushed?" |
+| No pending changes | `git diff HEAD` empty → report "No pending changes to review" |
+| Ambiguous input | Could be PR or commit → prefer PR (more common), note assumption |

package/templates/repo/.github/skills/code-review/references/parallel-review-workflow.md

@@ -0,0 +1,76 @@
+# Parallel Review Workflow
+
+**Ultrathink** to exhaustively list ALL potential edge cases, then dispatch parallel `code-reviewer` agents to verify: <scope>$ARGUMENTS</scope>
+
+**IMPORTANT:** Activate needed skills. Ensure token efficiency. Sacrifice grammar for concision.
+
+## Workflow
+
+### 1. Ultrathink Edge Cases
+
+Main agent deeply analyzes the scope to LIST all potential edge cases FIRST:
+- Read `codebase-summary.md` for context
+- Use `/ck-scout` to find relevant files
+- **Think exhaustively** about what could go wrong:
+  - Null/undefined scenarios
+  - Boundary conditions (off-by-one, empty, max values)
+  - Error handling gaps
+  - Race conditions, async edge cases
+  - Input validation holes
+  - Security vulnerabilities
+  - Resource leaks
+  - Untested code paths
+
+**Output format:**
+```markdown
+## Edge Cases Identified
+
+### Category: [scope-area]
+1. [edge case description] → files: [file1, file2]
+```
+
+### 2. Categorize & Assign
+
+Group edge cases by similar scope for parallel verification:
+- Each category → one `code-reviewer` agent
+- Max 6 categories (merge small ones)
+- Each reviewer gets specific edge cases to VERIFY, not discover
+
+### 3. Parallel Verification
+
+Launch N `code-reviewer` subagents simultaneously:
+- Pass: category name, list of edge cases, relevant files
+- Task: **VERIFY** if each edge case is properly handled in code
+- Report: which edge cases are handled vs unhandled
+
+### 4. Aggregate Results
+
+```markdown
+## Edge Case Verification Report
+
+### Summary
+- Total edge cases: X
+- Handled: Y
+- Unhandled: Z
+- Partial: W
+
+### Unhandled Edge Cases (Need Fix)
+| # | Edge Case | File | Status |
+|---|-----------|------|--------|
+```
+
+### 5. Adversarial Review (Always-On)
+
+After aggregation, spawn adversarial reviewer (see `adversarial-review.md`) on the full scope:
+- Adversarial reviewer receives aggregated findings + unhandled edge cases as context
+- Actively tries to break the code beyond what edge case verification found
+- Adjudicate findings: Accept / Reject / Defer
+
+### 6. Auto-Fix Pipeline
+
+**IF** unhandled/partial edge cases found:
+- Ask: "Found N unhandled edge cases. Fix with /ck-fix --parallel? [Y/n]"
+
+### 7. Final Report
+- Summary of verification
+- Ask: "Commit? [Y/n]" → use `git-manager`

package/templates/repo/.github/skills/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 agent 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 subagent to review implementation against plan or requirements before proceeding
 ---
 
 # Requesting Code Review
 
-Dispatch code-reviewer agent to catch issues before they cascade.
+Dispatch code-reviewer subagent to catch issues before they cascade.
 
-**Core principle:** Review early, review often.
+**Core principle:** Scout first, review often.
 
 ## When to Request Review
 
 **Mandatory:**
-- After each task in agent-driven development
+- After each task in subagent-driven development
 - After completing major feature
 - Before merge to main
 
@@ -23,13 +23,24 @@ Dispatch code-reviewer agent to catch issues before they cascade.
 
 ## 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 agent:**
+**2. Dispatch code-reviewer subagent:**
 
 Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
 
@@ -56,14 +67,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 agent]
+[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
 
-[Agent returns]:
+[Subagent returns]:
   Strengths: Clean architecture, real tests
   Issues:
     Important: Missing progress indicators
@@ -76,7 +87,7 @@ You: [Fix progress indicators]
 
 ## Integration with Workflows
 
-**Agent-Driven Development:**
+**Subagent-Driven Development:**
 - Review after EACH task
 - Catch issues before they compound
 - Fix before moving to next task

package/templates/repo/.github/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/templates/repo/.github/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/templates/repo/.github/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/templates/repo/.github/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/templates/repo/.github/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/templates/repo/.github/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