cokit-cli 1.2.7 → 1.3.0

package/templates/repo/.github/skills/code-review/references/checklists/api.md

@@ -0,0 +1,52 @@
+# API Review Checklist (Overlay)
+
+Additive to `base.md`. Apply when project exposes REST/GraphQL/gRPC APIs.
+
+## Detection
+
+Apply this overlay when any of these are true:
+- Project has route definitions (Express, FastAPI, NestJS, Django, Rails, Go chi/gin)
+- OpenAPI/Swagger spec file exists
+- `src/routes/`, `src/api/`, `src/controllers/` directories
+- GraphQL schema files in the diff
+
+---
+
+## Pass 1 — CRITICAL (additions to base)
+
+### Auth & Rate Limiting
+- Public endpoints missing rate limiting (login, registration, password reset)
+- API keys or tokens exposed in URL query parameters (use headers)
+- Missing auth middleware on new routes
+- Batch/bulk endpoints without per-item authorization checks
+
+### Input Validation
+- Request body accepted without schema validation (missing Zod, Joi, Pydantic, etc.)
+- Mass assignment: entire request body spread into database model
+- File upload without size/type restrictions
+- Array inputs without length limits (DoS via large payloads)
+
+### Data Exposure
+- Sensitive fields in API responses (password hashes, internal IDs, tokens)
+- Stack traces or internal error details in production error responses
+- Verbose error messages that leak schema/implementation details
+
+---
+
+## Pass 2 — INFORMATIONAL (additions to base)
+
+### API Design
+- List endpoints without pagination (LIMIT/OFFSET or cursor-based)
+- Missing consistent error response format across endpoints
+- Inconsistent naming conventions (camelCase vs snake_case in same API)
+- Missing request/response content-type headers
+
+### Observability
+- New endpoints without logging/metrics
+- Error paths that swallow exceptions silently
+- Missing correlation/request IDs for tracing
+
+### Versioning & Compatibility
+- Breaking changes to existing response shapes without version bump
+- Removed fields without deprecation notice
+- Changed field types (string → number) in existing responses

package/templates/repo/.github/skills/code-review/references/checklists/base.md

@@ -0,0 +1,100 @@
+# Base Review Checklist
+
+Universal checklist for all project types. Two-pass model: critical (blocking) + informational (non-blocking).
+
+## Instructions
+
+Review `git diff origin/main` for the issues below. Be specific — cite `file:line` and suggest fixes. Skip anything that's fine. Only flag real problems.
+
+**Output format:**
+
+```
+Pre-Landing Review: N issues (X critical, Y informational)
+
+**CRITICAL** (blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+
+**Issues** (non-blocking):
+- [file:line] Problem description
+  Fix: suggested fix
+```
+
+If no issues: `Pre-Landing Review: No issues found.`
+
+Be terse. One line problem, one line fix. No preamble.
+
+---
+
+## Pass 1 — CRITICAL (blocking)
+
+### Injection & Data Safety
+- String interpolation in SQL/database queries (even with type casting — use parameterized queries)
+- Unsanitized user input written to database or rendered in HTML
+- Raw HTML output from user-controlled data (`innerHTML`, `dangerouslySetInnerHTML`, `html_safe`, `raw()`, `| safe`)
+- Command injection via string concatenation in shell commands (use argument arrays)
+- Path traversal via user input in file operations
+
+### Race Conditions & Concurrency
+- Read-check-write without atomic operations (check-then-set should be atomic WHERE + UPDATE)
+- Find-or-create without unique database constraint (concurrent calls create duplicates)
+- Status transitions without atomic WHERE old_status + UPDATE new_status
+- Shared mutable state accessed without synchronization
+
+### Security Boundaries
+- Missing authentication checks on new endpoints/routes
+- Privilege escalation paths (user can access/modify another user's data — IDOR)
+- Secrets in logs, error responses, or client-side code
+- LLM/AI output written to database or used in queries without validation
+- JWT/token comparison using `==` instead of constant-time comparison
+
+### Auth & Access Control
+- New API endpoints without auth middleware
+- Missing authorization check (authenticated but not authorized)
+- Admin-only operations accessible to regular users
+- Session fixation or token reuse vulnerabilities
+
+---
+
+## Pass 2 — INFORMATIONAL (non-blocking)
+
+### Conditional Side Effects
+- Code branches on condition but forgets side effect on one branch (e.g., sets status but not associated data)
+- Log messages claiming action happened but action was conditionally skipped
+
+### Magic Numbers & String Coupling
+- Bare numeric literals used in multiple files — should be named constants
+- Error message strings used as query filters elsewhere (grep for the string)
+
+### Dead Code & Consistency
+- Variables assigned but never read
+- Stale comments describing old behavior after code changed
+- Import/require statements for unused modules
+
+### Test Gaps
+- Missing negative-path tests (error cases, validation failures)
+- Assertions on type/status but not side effects (e.g., checks status but not that email was sent)
+- Missing integration tests for security enforcement (auth, rate limiting, access control)
+
+### Type Coercion at Boundaries
+- Values crossing language/system boundaries where type could change (string vs number)
+- Hash/digest inputs that don't normalize types before serialization
+
+### Performance
+- O(n*m) lookups in views/templates (array search inside loops — use hash/map lookup)
+- Missing pagination on list endpoints returning unbounded results
+- N+1 queries: loading associations inside loops without eager loading
+- Unbounded queries without LIMIT
+
+---
+
+## Suppressions — DO NOT flag these
+
+- Redundancy that aids readability (e.g., `present?` redundant with length check)
+- "Add comment explaining why this threshold was chosen" — thresholds change, comments rot
+- "This assertion could be tighter" when assertion already covers the behavior
+- Consistency-only changes (wrapping a value to match how another constant is guarded)
+- Harmless no-ops (e.g., `.filter()` on array that never contains the filtered value)
+- ANYTHING already addressed in the diff being reviewed — read the FULL diff before commenting
+- Style/formatting issues (use a linter for that)
+- "Consider using X instead of Y" when Y works fine

package/templates/repo/.github/skills/code-review/references/checklists/web-app.md

@@ -0,0 +1,54 @@
+# Web App Review Checklist (Overlay)
+
+Additive to `base.md`. Apply when project has frontend framework (React, Vue, Svelte, Next.js, etc.).
+
+## Detection
+
+Apply this overlay when any of these are true:
+- `package.json` has `react`, `vue`, `svelte`, `next`, `nuxt`, `angular` dependency
+- Project has `src/pages/`, `src/app/`, `src/components/`, `src/views/` directories
+- HTML/JSX/TSX/Vue files in the diff
+
+---
+
+## Pass 1 — CRITICAL (additions to base)
+
+### XSS
+- `innerHTML` assignment from any non-static source
+- Template literals interpolated into DOM without escaping
+- URL parameters rendered without sanitization
+- `<a href={userInput}>` without protocol validation (javascript: protocol)
+- Server-rendered user content without HTML entity encoding
+
+### CSRF
+- State-changing endpoints (POST/PUT/DELETE) without CSRF token verification
+- Cookie-based auth without SameSite attribute
+- Form submissions to external URLs
+
+### N+1 Queries (server-rendered views)
+- Database queries inside loops rendering lists
+- Missing eager loading for associations rendered in views/pages
+- Sequential API calls that could be batched
+
+---
+
+## Pass 2 — INFORMATIONAL (additions to base)
+
+### Frontend Performance
+- Inline `<style>` blocks in components re-parsed every render
+- Missing `key` prop on list items
+- Large bundle imports that could be lazy-loaded (e.g., full lodash instead of lodash/get)
+- Images without width/height causing layout shift
+- Missing `loading="lazy"` on below-fold images
+
+### Accessibility
+- Interactive elements without keyboard support (onClick without onKeyDown)
+- Missing `alt` text on images
+- Form inputs without associated labels
+- Color-only indicators (no text/icon fallback)
+- Missing ARIA attributes on custom interactive components
+
+### Responsive / Layout
+- Fixed pixel widths that break on mobile
+- Missing viewport meta tag
+- Overflow hidden cutting off content on small screens

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

@@ -1,209 +1,113 @@
 ---
 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
+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
 ---
 
 # 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
+## Response Pattern
 
 ```
-WHEN receiving code review feedback:
-
 1. READ: Complete feedback without reacting
-2. UNDERSTAND: Restate requirement in own words (or ask)
+2. UNDERSTAND: Restate requirement (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
+6. IMPLEMENT: One 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)
+❌ "You're absolutely right!" / "Great point!" / "Thanks for [anything]"
+❌ "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)
+✅ Restate technical requirement
+✅ Ask clarifying questions
+✅ Push back with technical reasoning
+✅ 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
+IF any item unclear:
+  STOP - don't implement anything
+  ASK for clarification on ALL 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
+**Human partner:** Trusted - implement after understanding, no performative agreement
 
-### From External Reviewers
+**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]?"
+  1. Technically correct for THIS codebase?
+  2. Breaks existing functionality?
+  3. Reason for current implementation?
+  4. Works all platforms/versions?
 
-IF conflicts with your human partner's prior decisions:
-  Stop and discuss with your human partner first
+IF wrong: Push back with technical reasoning
+IF can't verify: State limitation, ask direction
+IF conflicts with partner's decisions: Stop, discuss first
 ```
 
-**your human partner's rule:** "External feedback - be skeptical, but check carefully"
-
-## YAGNI Check for "Professional" Features
+## YAGNI Check
 
 ```
 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
+  IF unused: "This isn't called. Remove it (YAGNI)?"
+  IF used: 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
+1. Clarify unclear items FIRST
+2. Implement: blocking → simple → complex
+3. Test each individually
+4. Verify no regressions
 ```
 
 ## When To Push Back
 
-Push back when:
-- Suggestion breaks existing functionality
+- 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
+- Technically incorrect for stack
+- Legacy/compatibility reasons
+- Conflicts with 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"
+**How:** Technical reasoning, specific questions, reference working tests
 
 ## 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.
+✅ "Fixed. [Brief description]"
+✅ "Good catch - [issue]. Fixed in [location]."
+✅ Just fix it (actions > words)
 
-**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+❌ ANY gratitude or performative expression
 
-## Gracefully Correcting Your Pushback
+## Correcting Wrong 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."
+✅ "You were right - checked [X], it does [Y]. Implementing."
+❌ Long apology, defending, over-explaining
 
-❌ Long apology
-❌ Defending why you pushed back
-❌ Over-explaining
-```
-
-State the correction factually and move on.
-
-## Common Mistakes
+## Quick Reference
 
 | 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 |
+| Performative agreement | State requirement or act |
+| Blind implementation | Verify against codebase |
+| Batch without testing | One at a time |
+| Assuming reviewer 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.**
+## Bottom Line
 
+External feedback = suggestions to evaluate, not orders.
 Verify. Question. Then implement.
-
-No performative agreement. Technical rigor always.

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

@@ -0,0 +1,30 @@
+# Codebase Scan Workflow
+
+Think harder to scan the codebase and analyze it follow the Orchestration Protocol, Core Responsibilities, Subagents Team and Development Rules:
+<tasks>$ARGUMENTS</tasks>
+
+## Role Responsibilities
+- You are an elite software engineering expert who specializes in system architecture design and technical decision-making.
+- You operate by: **YAGNI**, **KISS**, and **DRY**.
+- Sacrifice grammar for concision. List unresolved questions at end.
+
+## Workflow
+
+### Research
+* Use 2 `researcher` subagents in parallel to search up to 5 sources
+* Keep every research report concise (≤150 lines)
+* Use `/ck-scout` skill invocation to search the codebase
+
+### Code Review
+* Use multiple `code-reviewer` subagents in parallel to review code
+* If issues found, ask main agent to improve and repeat until tests pass
+* When complete, run adversarial review (see `adversarial-review.md`) — always-on, no exceptions
+* Report combined quality + adversarial findings to user
+
+### Plan
+* Use `planner` subagent to analyze reports and create improvement plan
+* Save overview at `plan.md`, phase files as `phase-XX-phase-name.md`
+
+### Final Report
+* Summary of changes, guide user to get started, suggest next steps
+* Ask user if they want to commit and push

package/templates/repo/.github/skills/code-review/references/edge-case-scouting.md

@@ -0,0 +1,119 @@
+---
+name: edge-case-scouting
+description: Use after implementation, before code review to proactively find edge cases, side effects, and potential issues via scout skill - catches problems code-reviewer might miss
+---
+
+# Edge Case Scouting
+
+Proactive detection of edge cases, side effects, and potential issues before code review.
+
+## Purpose
+
+Code reviews catch obvious issues but miss subtle side effects. Scout detects:
+- Files affected by changes reviewer might not check
+- Data flow paths that could break
+- Boundary conditions and error paths
+- Integration issues across modules
+
+## When to Use
+
+**Mandatory:** Multi-file features, shared utility refactors, complex bug fixes
+**Optional:** Single-file changes, docs, config
+
+## Process
+
+### 1. Identify Changed Files
+```bash
+git diff --name-only HEAD~1
+```
+
+### 2. Invoke Scout
+```
+/ck-scout edge cases for recent changes.
+
+Changed: {files from git diff}
+
+Find:
+1. Files importing/depending on changed modules
+2. Data flow paths through modified functions
+3. Error handling paths not tested
+4. Boundary conditions (null, empty, max)
+5. Race conditions in async code
+6. State management side effects
+```
+
+### 3. Analyze & Act
+
+| Finding | Action |
+|---------|--------|
+| Affected file not in scope | Add to review |
+| Data flow risk | Verify or add test |
+| Edge case | Add test or verify |
+| Missing test | Add before review |
+
+### 4. Document for Review
+```
+Scout findings:
+- {issues found}
+- Verified: {what checked}
+- Addressed: {what fixed}
+- Needs review: {remaining}
+```
+
+## Scout Prompts
+
+**Feature:**
+```
+Scout edge cases for {feature}.
+Changed: {files}
+Find: consumers, error states, untested inputs, performance, compatibility
+```
+
+**Bug fix:**
+```
+Scout side effects of fix in {file}.
+Bug: {description}, Fix: {approach}
+Find: other paths using logic, dependent features, similar bugs
+```
+
+**Refactor:**
+```
+Scout breaking changes in {module}.
+Before: {old}, After: {new}
+Find: importers, behavior diffs, removed functionality
+```
+
+## What Scout Catches
+
+| Issue | Why Missed | Scout Detects |
+|-------|------------|---------------|
+| Indirect deps | Not in diff | Traces imports |
+| Race conditions | Hard static review | Analyzes flow |
+| State mutations | Hidden side effects | Tracks data |
+| Missing null checks | Assumed safe | Boundary analysis |
+| Integration breaks | Out of scope | Cross-module search |
+
+## Red Flags
+
+- Shared utility changed but only one caller tested
+- Error path leads to unhandled rejection
+- State modified in place without notification
+- Breaking change without migration
+
+## Example
+
+```
+1. Done: Add cache to UserService.getUser()
+2. Diff: src/services/user-service.ts
+3. Scout: "edge cases for caching in getUser()"
+4. Report:
+   - ProfileComponent expects fresh data on edit
+   - AdminPanel loops getUser() (memory risk)
+   - No cache clear on updateUser()
+5. Fix: Add invalidation, maxSize
+6. Document for code-reviewer
+```
+
+## Bottom Line
+
+Scout before review. Don't trust "simple changes" - scout them anyway.