cokit-cli 1.2.7 → 1.4.0

package/templates/repo/.github/skills/ck-cook/references/workflow-steps.md

@@ -0,0 +1,192 @@
+# Unified Workflow Steps
+
+All modes share core steps with mode-specific variations.
+
+**Task Tool Fallback:** `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for progress tracking. All workflow steps remain functional without Task tools.
+
+## Step 0: Intent Detection & Setup
+
+1. Parse input with `intent-detection.md` rules
+2. Log detected mode: `✓ Step 0: Mode [X] - [reason]`
+3. If mode=code: detect plan path, set active plan
+4. Use `TaskCreate` to create workflow step tasks (with dependencies if complex)
+
+**Output:** `✓ Step 0: Mode [interactive|auto|fast|parallel|no-test|code] - [detection reason]`
+
+## Step 1: Research (skip if fast/code mode)
+
+**Interactive/Auto:**
+- Spawn multiple `ck-researcher` agents in parallel
+- Use `/ck-scout ext` or `ck-scout` agent for codebase search
+- Keep reports ≤150 lines
+
+**Parallel:**
+- Optional: max 2 researchers if complex
+
+**Output:** `✓ Step 1: Research complete - [N] reports gathered`
+
+### [Review Gate 1] Post-Research (skip if auto mode)
+- Present research summary to user
+- Use asking the user to ask: "Proceed to planning?" / "Request more research" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 2: Planning
+
+**Interactive/Auto/No-test:**
+- Use `ck-planner` agent with research context
+- Create `plan.md` + `phase-XX-*.md` files
+
+**Fast:**
+- Use `/ck-plan --fast` with scout results only
+- Minimal planning, focus on action
+
+**Parallel:**
+- Use `/ck-plan --parallel` for dependency graph + file ownership matrix
+
+**Code:**
+- Skip - plan already exists
+- Parse existing plan for phases
+
+**Output:** `✓ Step 2: Plan created - [N] phases`
+
+### [Review Gate 2] Post-Plan (skip if auto mode)
+- Present plan overview with phases
+- Use asking the user to ask: "Validate the plan or approve plan to start implementation?" - "Validate" / "Approve" / "Abort" / "Other" ("Request revisions")
+  - "Validate": run `/ck-plan validate` skill invocation
+  - "Approve": continue to implementation
+  - "Abort": stop the workflow
+  - "Other": revise the plan based on user's feedback
+- **Auto mode:** Skip this gate
+
+## Step 3: Implementation
+
+**IMPORTANT:**
+1. `TaskList` first — check for existing tasks (hydrated by planning skill in same session)
+2. If tasks exist → pick them up, skip re-creation
+3. If no tasks → read plan phases, `TaskCreate` for each unchecked `[ ]` item with priority order and metadata (`phase`, `planDir`, `phaseFile`)
+4. Tasks can be blocked by other tasks via `addBlockedBy`
+
+**All modes:**
+- Use `TaskUpdate` to mark tasks as `in_progress` immediately.
+- Execute phase tasks sequentially (Step 3.1, 3.2, etc.)
+- Use `ck-ui-ux-designer` for frontend
+- Use `ai-multimodal` (if available) for image assets
+- Run type checking after each file
+
+**Parallel mode:**
+- Utilize all tools of Tasks: `TaskCreate`, `TaskUpdate`, `TaskGet` and `TaskList`
+- Launch multiple `ck-fullstack-developer` agents
+- When agents pick up a task, use `TaskUpdate` to assign task to agent and mark tasks as `in_progress` immediately.
+- Respect file ownership boundaries
+- Wait for parallel group before next
+
+**Output:** `✓ Step 3: Implemented [N] files - [X/Y] tasks complete`
+
+### [Review Gate 3] Post-Implementation (skip if auto mode)
+- Present implementation summary (files changed, key changes)
+- Use asking the user to ask: "Proceed to testing?" / "Request implementation changes" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 4: Testing (skip if no-test mode)
+
+**All modes (except no-test):**
+- Write tests: happy path, edge cases, errors
+- **MUST** spawn `ck-tester` subagent: `Task(subagent_type="tester", prompt="Run test suite", description="Run tests")`
+- If failures: **MUST** spawn `ck-debugger` subagent → fix → repeat
+- **Forbidden:** fake mocks, commented tests, changed assertions, skipping subagent delegation
+
+**Output:** `✓ Step 4: Tests [X/X passed] - tester subagent invoked`
+
+### [Review Gate 4] Post-Testing (skip if auto mode)
+- Present test results summary
+- Use asking the user to ask: "Proceed to code review?" / "Request test fixes" / "Abort"
+- **Auto mode:** Skip this gate
+
+## Step 5: Code Review
+
+**All modes - MANDATORY subagent:**
+- **MUST** spawn `ck-code-reviewer` subagent: `Task(subagent_type="code-reviewer", prompt="Review changes. Return score, critical issues, warnings.", description="Code review")`
+- **DO NOT** review code yourself - delegate to subagent
+
+**Interactive/Parallel/Code/No-test:**
+- Interactive cycle (max 3): see `review-cycle.md`
+- Requires user approval
+
+**Auto:**
+- Auto-approve if score≥9.5 AND 0 critical
+- Auto-fix critical (max 3 cycles)
+- Escalate to user after 3 failed cycles
+
+**Fast:**
+- Simplified review, no fix loop
+- User approves or aborts
+
+**Output:** `✓ Step 5: Review [score]/10 - [Approved|Auto-approved] - code-reviewer subagent invoked`
+
+## Step 6: Finalize
+
+**All modes - MANDATORY subagents (NON-NEGOTIABLE):**
+1. **MUST** spawn these subagents in parallel:
+   - `Task(subagent_type="project-manager", prompt="Run full sync-back for [plan-path]: reconcile all completed Tasks with all phase files, backfill stale completed checkboxes across every phase, then update plan.md frontmatter/table progress. Do NOT only mark current phase.", description="Update plan")`
+   - `Task(subagent_type="docs-manager", prompt="Update docs for changes.", description="Update docs")`
+2. Project-manager sync-back MUST include:
+
+### Status Sync (Finalize)
+
+Use CLI commands for deterministic status updates:
+
+```bash
+# Mark completed phases
+ck plan check <phase-id>
+
+# Mark in-progress phases
+ck plan check <phase-id> --start
+
+# Revert if needed
+ck plan uncheck <phase-id>
+```
+
+**Fallback:** If `ck` is not available, edit plan.md directly —
+only change the Status column cell, preserve table structure.
+   - Sweep all `phase-XX-*.md` files in the plan directory.
+   - Mark every completed item `[ ] → [x]` based on completed tasks (including earlier phases finished before current phase).
+   - Update `plan.md` status/progress (`pending`/`in-progress`/`completed`) from actual checkbox state.
+   - Return unresolved mappings if any completed task cannot be matched to a phase file.
+3. Use `TaskUpdate` to mark Tasks complete after sync-back confirmation.
+4. Onboarding check (API keys, env vars)
+5. **MUST** spawn git subagent: `Task(subagent_type="git-manager", prompt="Stage and commit changes", description="Commit")`
+
+**CRITICAL:** Step 6 is INCOMPLETE without spawning all 3 subagents. DO NOT skip subagent delegation.
+
+**Auto mode:** Continue to next phase automatically, start from **Step 3**.
+**Others:** Ask user before next phase
+
+**Output:** `✓ Step 6: Finalized - 3 subagents invoked - Full-plan sync-back completed - Committed`
+
+## Mode-Specific Flow Summary
+
+Legend: `[R]` = Review Gate (human approval required)
+
+```
+interactive: 0 → 1 → [R] → 2 → [R] → 3 → [R] → 4 → [R] → 5(user) → 6
+auto:        0 → 1 → 2 → 3 → 4 → 5(auto) → 6 → next phase (NO stops)
+fast:        0 → skip → 2(fast) → [R] → 3 → [R] → 4 → [R] → 5(simple) → 6
+parallel:    0 → 1? → [R] → 2(parallel) → [R] → 3(multi-agent) → [R] → 4 → [R] → 5(user) → 6
+no-test:     0 → 1 → [R] → 2 → [R] → 3 → [R] → skip → 5(user) → 6
+code:        0 → skip → skip → 3 → [R] → 4 → [R] → 5(user) → 6
+```
+
+**Key difference:** `auto` mode is the ONLY mode that skips all review gates.
+
+## Critical Rules
+
+- Never skip steps without mode justification
+- **MANDATORY SUBAGENT DELEGATION:** Steps 4, 5, 6 MUST spawn subagents via Task tool. DO NOT implement directly.
+  - Step 4: `ck-tester` (and `ck-debugger` if failures)
+  - Step 5: `ck-code-reviewer`
+  - Step 6: `ck-project-manager`, `ck-docs-manager`, `ck-git-manager`
+- Use `TaskCreate` to create Tasks for each unchecked item with priority order and dependencies (or `TodoWrite` if Task tools unavailable).
+- Use `TaskUpdate` to mark Tasks `in_progress` when picking up a task (skip if Task tools unavailable).
+- Use `TaskUpdate` to mark Tasks `complete` immediately after finalizing the task (skip if Task tools unavailable).
+- All step outputs follow format: `✓ Step [N]: [status] - [metrics]`
+- **VALIDATION:** If Task tool calls = 0 at end of workflow, the workflow is INCOMPLETE.

package/templates/repo/.github/skills/ck-databases/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ck-databases
+description: Design schemas, write queries for MongoDB and PostgreSQL. Use for database design, SQL/NoSQL queries, aggregation pipelines, indexes, migrations, replication, performance optimization, psql CLI.
+license: MIT
+argument-hint: "[query or schema task]"
+---
+
+# Databases Skill
+
+Unified guide for working with MongoDB (document-oriented) and PostgreSQL (relational) databases. Choose the right database for your use case and master both systems.
+
+## When to Use This Skill
+
+Use when:
+- Designing database schemas and data models
+- Writing queries (SQL or MongoDB query language)
+- Building aggregation pipelines or complex joins
+- Optimizing indexes and query performance
+- Implementing database migrations
+- Setting up replication, sharding, or clustering
+- Configuring backups and disaster recovery
+- Managing database users and permissions
+- Analyzing slow queries and performance issues
+- Administering production database deployments
+
+## Reference Navigation
+
+### Database Design
+- **[db-design.md](references/db-design.md)** - Activate when user requests: Database/table design for transactional (OLTP), analytics (OLAP), create or extend schema, design fact/dimension tables, analyze/review CSV/JSON/SQL files to create tables, or need advice on data storage structure.
+
+### MongoDB References
+- **[mongodb-crud.md](references/mongodb-crud.md)** - CRUD operations, query operators, atomic updates
+- **[mongodb-aggregation.md](references/mongodb-aggregation.md)** - Aggregation pipeline, stages, operators, patterns
+- **[mongodb-indexing.md](references/mongodb-indexing.md)** - Index types, compound indexes, performance optimization
+- **[mongodb-atlas.md](references/mongodb-atlas.md)** - Atlas cloud setup, clusters, monitoring, search
+
+### PostgreSQL References
+- **[postgresql-queries.md](references/postgresql-queries.md)** - SELECT, JOINs, subqueries, CTEs, window functions
+- **[postgresql-psql-cli.md](references/postgresql-psql-cli.md)** - psql commands, meta-commands, scripting
+- **[postgresql-performance.md](references/postgresql-performance.md)** - EXPLAIN, query optimization, vacuum, indexes
+- **[postgresql-administration.md](references/postgresql-administration.md)** - User management, backups, replication, maintenance
+
+## Python Utilities
+
+Database utility scripts in `scripts/`:
+- **db_migrate.py** - Generate and apply migrations for both databases (MongoDB and PostgreSQL)
+- **db_backup.py** - Backup and restore MongoDB and PostgreSQL
+- **db_performance_check.py** - Analyze slow queries and recommend indexes
+
+```bash
+# Generate migration
+python scripts/db_migrate.py --db mongodb --generate "add_user_index"
+
+# Run backup
+python scripts/db_backup.py --db postgres --output /backups/
+
+# Check performance
+python scripts/db_performance_check.py --db mongodb --threshold 100ms
+```
+
+## Best Practices
+
+**MongoDB:**
+- Use embedded documents for 1-to-few relationships
+- Reference documents for 1-to-many or many-to-many
+- Index frequently queried fields
+- Use aggregation pipeline for complex transformations
+- Enable authentication and TLS in production
+- Use Atlas for managed hosting
+
+**PostgreSQL:**
+- Normalize schema to 3NF, denormalize for performance
+- Use foreign keys for referential integrity
+- Index foreign keys and frequently filtered columns
+- Use EXPLAIN ANALYZE to optimize queries
+- Regular VACUUM and ANALYZE maintenance
+- Connection pooling (pgBouncer) for web apps
+
+## Resources
+
+- MongoDB: https://www.mongodb.com/docs/
+- PostgreSQL: https://www.postgresql.org/docs/
+- MongoDB University: https://learn.mongodb.com/
+- PostgreSQL Tutorial: https://www.postgresqltutorial.com/

package/templates/repo/.github/skills/ck-databases/db-design.md

@@ -0,0 +1,188 @@
+---
+name: db-design
+description: "Activate when user requests: Database/table design for transactional (OLTP), analytics (OLAP), create or extend schema, design fact/dimension tables, analyze/review CSV/JSON/SQL files to create tables, or need advice on data storage structure."
+---
+
+# SKILL: Database Schema Design
+
+## Execution Process
+
+### Step 1: Analyze Context (MANDATORY)
+
+Before ANY design work, AI MUST check:
+
+- [ ] Database stack identified? (MySQL / PostgreSQL / BigQuery / SQLite / D1)
+- [ ] Existing schema explored via tools/MCP?
+- [ ] Use case clear? (transactional vs analytics vs ETL)
+
+**If ANY checkbox is unclear → STOP and ask user before proceeding.**
+
+### Step 2: Gather Requirements
+
+**MUST ask if missing:**
+
+| Missing Info | Required Question |
+|--------------|-------------------|
+| Entities unclear | "What are the main entities involved in this feature?" |
+| Query patterns unknown | "What queries/reports will run most often?" |
+| Granularity unclear | "What level of detail needed? (per order, per item, per day)" |
+| Constraints unknown | "Any uniqueness, retention, or multi-tenant requirements?" |
+| Relationships unclear | "How do these entities relate to each other?" |
+
+**DO NOT assume or proceed without answers. DO NOT design schema without understanding the business context.**
+
+### Step 3: Load Documentation by Intent
+
+| Intent | Keywords | Load file |
+|--------|----------|-----------|
+| **OLTP** | "business tables", "transactional", "CRUD", "orders", "users" | [transactional.md](transactional.md) |
+| **OLAP** | "analytics", "statistics", "reports", "fact", "dimension" | [analytics.md](analytics.md) |
+| **ETL** | "incremental", "load", "sync", "watermark", "etl" | [incremental-etl.md](incremental-etl.md) |
+
+**Database stacks:** [MySQL](stacks/mysql.md) · [PostgreSQL](stacks/postgres.md) · [BigQuery](stacks/bigquery.md) · [SQLite](stacks/sqlite.md) · [D1 Cloudflare](stacks/d1_cloudflare.md)
+
+### Step 4: Design & Propose
+
+Only after Steps 1-3 complete:
+- Propose DDL with reasoning
+- **Wait for user approval before execution**
+- Never auto-execute DDL
+
+### Step 5: Verify Checklist
+
+Before delivering final DDL, verify the **Final Checklist** at the end of this file.
+
+---
+
+## Scope & Objectives
+
+Design or extend database schemas ensuring:
+
+- Consistent, understandable, maintainable data structures
+- Good performance with appropriate indexes
+- Design that fits existing tables (avoid duplication, avoid breaking logic)
+
+---
+
+## Naming Conventions
+
+### Table naming
+
+- Use **snake_case**, English, plural for main entities:
+  - `users`, `orders`, `order_items`, `product_variants`
+- Junction/mapping tables:
+  - `role_permissions`, `user_roles`, `product_categories`
+- Fact & dimension tables (analytics):
+  - Fact: `fact_orders`, `fact_order_items`, `fact_pageviews`
+  - Dimension: `dim_date`, `dim_customer`, `dim_product`, `dim_store`
+- Avoid unclear abbreviations:
+  - ❌ `usr`, `ord`, `inv_tx`
+  - ✅ `users`, `orders`, `inventory_transactions`
+
+### Column naming
+
+- Use **snake_case**, clear meaning, consistent across tables
+- **Primary key**: `id` (main PK of table)
+- **Foreign key**: `xxx_id` pointing to table `xxx`:
+  - `user_id` → `users.id`
+  - `order_id` → `orders.id`
+- **Audit & lifecycle**:
+  - `created_at`, `updated_at`, `deleted_at` (soft delete)
+- **Boolean flags**:
+  - `is_active`, `is_deleted`, `is_primary`, `is_verified`
+- **Quantities & prices**:
+  - `quantity`, `unit_price`, `total_price`, `discount_amount`, `tax_amount`
+- **Time ranges**:
+  - `start_at`, `end_at` or `valid_from`, `valid_to` (pick one convention and use consistently)
+- **Enum/state**:
+  - `status` (combine with ENUM / CHECK constraint)
+
+---
+
+## Workflow
+
+### 1. Understand business requirements
+
+- Summarize requirements in your own words
+- If missing context, ask:
+  - What entities are involved?
+  - What is the main business flow?
+  - What queries/reports are commonly used?
+
+### 2. Explore existing schema (MANDATORY before proposing)
+
+- Use tools/MCP to list tables and describe structure
+- For DBs with comments (MySQL/PostgreSQL/BigQuery): read comments directly
+- For SQLite/D1: query `metadata_tables` and `metadata_columns` tables
+
+### 3. Analyze and propose draft
+
+- Which tables already partially cover requirements?
+- Which tables need additional columns/indexes?
+- Which tables are completely missing (need to create)?
+
+### 4. Confirm with user before finalizing design
+
+- Required granularity
+- Metrics to calculate
+- Important business constraints (uniqueness, retention, privacy)
+
+### 5. Design detailed schema
+
+- Provide proposed DDL - **do NOT auto-execute**
+- Wait for user approval before execution
+
+---
+
+## Processing Data Files (CSV/JSON/SQL)
+
+When user provides files:
+
+1. **Read and identify structure**: headers, data types, relationships
+2. **Large files**: write Python script to parse and analyze
+3. **SQL files**: review naming, indexes, constraints, propose improvements
+4. **Output**: Proposed DDL with reasoning
+
+---
+
+## Output Format
+
+When delivering design results:
+
+1. **Summary**: list of new tables / tables to modify
+2. **Complete DDL SQL**: columns, types, PK, FK, indexes, comments
+3. **Reasoning**: explain why this structure/index was chosen, tied to actual queries
+
+---
+
+## Final Checklist
+
+Before delivering final DDL:
+
+- [ ] Explored existing schema via tools/MCP
+- [ ] No duplicate tables with existing schema
+- [ ] All FKs have indexes
+- [ ] Composite indexes match main query patterns
+- [ ] Naming convention consistent with existing schema
+- [ ] Added comments/descriptions for tables and columns
+- [ ] For SQLite/D1: prepared INSERTs for metadata tables
+- [ ] Explained reasoning for important design decisions
+
+---
+
+## File Structure
+
+```
+skills/databases/
+├── SKILL.md                  # Skill description (entry + execution process + checklist)
+├── db-design.md              # This file 
+├── transactional.md          # OLTP design rules
+├── analytics.md              # OLAP / Star Schema rules
+├── incremental-etl.md        # ETL & watermark patterns
+└── stacks/
+    ├── mysql.md              # MySQL-specific rules
+    ├── postgres.md           # PostgreSQL-specific rules
+    ├── bigquery.md           # BigQuery-specific rules
+    ├── sqlite.md             # SQLite-specific rules
+    └── d1_cloudflare.md      # D1 Cloudflare-specific rules
+```

package/templates/repo/.github/skills/ck-debug/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ck-debug
+description: "Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation, log analysis, CI/CD failures, database diagnostics, system investigation."
+languages: all
+argument-hint: "[error or issue description]"
+---
+
+# Debugging & System Investigation
+
+Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+
+Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.
+
+## When to Use
+
+**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems
+**System-level:** Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis
+**Always:** Before claiming work complete
+
+## Techniques
+
+### 1. Systematic Debugging (`references/systematic-debugging.md`)
+
+Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.
+
+**Load when:** Any bug/issue requiring investigation and fix
+
+### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
+
+Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes `scripts/find-polluter.sh` for bisecting test pollution.
+
+**Load when:** Error deep in call stack, unclear where invalid data originated
+
+### 3. Defense-in-Depth (`references/defense-in-depth.md`)
+
+Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation
+
+**Load when:** After finding root cause, need comprehensive validation
+
+### 4. Verification (`references/verification.md`)
+
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.
+
+**Load when:** About to claim work complete, fixed, or passing
+
+### 5. Investigation Methodology (`references/investigation-methodology.md`)
+
+Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development
+
+**Load when:** Server incidents, system behavior analysis, multi-component failures
+
+### 6. Log & CI/CD Analysis (`references/log-and-ci-analysis.md`)
+
+Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: `gh` CLI, structured log queries, correlation across sources.
+
+**Load when:** CI/CD pipeline failures, server errors, deployment issues
+
+### 7. Performance Diagnostics (`references/performance-diagnostics.md`)
+
+Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.
+
+**Load when:** Performance degradation, slow queries, high latency, resource exhaustion
+
+### 8. Reporting Standards (`references/reporting-standards.md`)
+
+Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence
+
+**Load when:** Need to produce investigation report or diagnostic summary
+
+### 9. Task Management (`references/task-management-debugging.md`)
+
+Track investigation pipelines via Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. **Fallback:** Task tools are CLI-only — if unavailable (VSCode extension), use `TodoWrite` for tracking. Debug workflow remains fully functional.
+
+**Load when:** Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents
+
+### 10. Frontend Verification (`references/frontend-verification.md`)
+
+Visual verification of frontend implementations via Chrome MCP (if available) or `chrome-devtools` (if available) skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.
+
+**Load when:** Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions
+
+## Quick Reference
+
+```
+Code bug       → systematic-debugging.md (Phase 1-4)
+  Deep in stack  → root-cause-tracing.md (trace backward)
+  Found cause    → defense-in-depth.md (add layers)
+  Claiming done  → verification.md (verify first)
+
+System issue   → investigation-methodology.md (5 steps)
+  CI/CD failure  → log-and-ci-analysis.md
+  Slow system    → performance-diagnostics.md
+  Need report    → reporting-standards.md
+
+Frontend fix   → frontend-verification.md (Chrome/devtools)
+```
+
+## Tools Integration
+
+- **Database:** `psql` for PostgreSQL queries and diagnostics
+- **CI/CD:** `gh` CLI for GitHub Actions logs and pipeline debugging
+- **Codebase:** `docs-seeker` skill for package/plugin docs; `repomix` skill for codebase summary
+- **Scouting:** `/ck-scout` or `/ck-scout ext` for finding relevant files
+- **Frontend:** Chrome browser or `chrome-devtools` (if available) skill for visual verification (screenshots, console, network)
+- **Skills:** Activate `ck-problem-solving` skill when stuck on complex issues
+
+## Red Flags
+
+Stop and follow process if thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "It's probably X, let me fix that"
+- "Should work now" / "Seems fixed"
+- "Tests pass, we're done"
+
+**All mean:** Return to systematic process.

package/templates/repo/.github/skills/ck-debug/references/frontend-verification.md

@@ -0,0 +1,103 @@
+# Frontend Verification
+
+Visual verification of frontend implementations using Chrome MCP (if available) or `chrome-devtools` (if available) skill fallback.
+
+## Applicability Check
+
+**Skip entirely if task is NOT frontend-related.** Frontend indicators:
+- Files modified: `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.css`, `*.scss`
+- Changes to: components, layouts, pages, styles, DOM structure, UI behavior
+- Keywords: render, display, layout, responsive, animation, visual, UI, UX
+
+If none match, skip this technique.
+
+## Step 1: Detect Chrome MCP Availability
+
+Check if Chrome MCP server is available via `mcp-management` skill or `ListMcpResourcesTool`:
+
+```
+Use ListMcpResourcesTool to check for Chrome MCP tools.
+Look for tools prefixed with "chrome__" (e.g., chrome__navigate, chrome__screenshot).
+```
+
+**Available** → Proceed to Step 2A (Chrome MCP)
+**Not available** → Proceed to Step 2B (chrome-devtools fallback)
+
+## Step 2A: Chrome MCP Available — Direct Verification
+
+Use Chrome MCP tools to verify the implementation in the user's actual browser. Ensure dev server is running first.
+
+### Navigate & Screenshot
+
+```
+1. chrome__navigate → http://localhost:3000 (or project dev URL)
+2. chrome__screenshot → capture current page state
+3. Read the screenshot with Read tool to visually inspect
+```
+
+### Visual Inspection Checklist
+
+After capturing screenshot, verify:
+1. **Layout** — Elements positioned correctly, no overflow/overlap
+2. **Content** — Text, images, data rendered as expected
+3. **Responsiveness** — Resize viewport if MCP supports it
+4. **Interactions** — Use chrome__click / chrome__type to test interactive elements
+5. **Console errors** — Use chrome__evaluate to check `console.error` output
+
+### Console Error Check
+
+```
+chrome__evaluate → "JSON.stringify(window.__consoleErrors || [])"
+```
+
+Or navigate and observe any error output from Chrome MCP tool responses.
+
+### Get Page Content
+
+```
+chrome__get_content → extract DOM/text to verify rendered output matches expectations
+```
+
+## Step 2B: Chrome MCP NOT Available — Fallback to chrome-devtools Skill
+
+When Chrome MCP is not configured, use `chrome-devtools` (if available) skill (Puppeteer with bundled Chromium):
+
+```bash
+SKILL_DIR="chrome-devtools scripts (if available)"
+
+# Install deps if first time
+npm install --prefix "$SKILL_DIR" 2>/dev/null
+
+# Screenshot + console error check
+node "$SKILL_DIR/screenshot.js" --url http://localhost:3000 --output ./verification-screenshot.png
+node "$SKILL_DIR/console.js" --url http://localhost:3000 --types error,pageerror --duration 5000
+```
+
+If `chrome-devtools` (if available) skill is also unavailable, skip visual verification and note in report:
+> "Visual verification skipped — no Chrome MCP or chrome-devtools available."
+
+## Step 3: Analyze Results
+
+After capture:
+1. **Read screenshot** — Use Read tool on the PNG to visually inspect
+2. **Check console output** — Zero errors = pass; errors = investigate before claiming done
+3. **Compare with expected** — Match against design specs or user description
+4. **Document findings** — Include screenshot path and any issues found in verification report
+
+## Integration with Verification Protocol
+
+This technique extends `verification.md`. After standard verification (tests pass, build succeeds), add frontend verification as final gate:
+
+```
+Standard verification → Tests pass → Build succeeds → Frontend visual verification → Claim complete
+```
+
+Report format:
+```
+## Frontend Verification
+- Method: [Chrome MCP | chrome-devtools | skipped]
+- Screenshot: ./verification-screenshot.png
+- Console errors: [none | list]
+- Visual check: [pass | issues found]
+- Responsive: [checked at X viewports | skipped]
+```