cokit-cli 1.3.0 → 1.4.0

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

@@ -0,0 +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 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 `ck-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/templates/repo/.github/skills/ck-context-engineering/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: ck-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
+
+Context engineering curates the smallest high-signal token set for LLM tasks. The goal: maximize reasoning quality while minimizing token usage.
+
+## When to Activate
+
+- Designing/debugging agent systems
+- Context limits constrain performance
+- Optimizing cost/latency
+- Building multi-agent coordination
+- Implementing memory systems
+- Evaluating agent performance
+- Developing LLM-powered pipelines
+
+## Core Principles
+
+1. **Context quality > quantity** - High-signal tokens beat exhaustive content
+2. **Attention is finite** - U-shaped curve favors beginning/end positions
+3. **Progressive disclosure** - Load information just-in-time
+4. **Isolation prevents degradation** - Partition work across sub-agents
+5. **Measure before optimizing** - Know your baseline
+
+**IMPORTANT:**
+- Sacrifice grammar for the sake of concision.
+- Ensure token efficiency while maintaining high quality.
+- Pass these rules to subagents.
+
+## Quick Reference
+
+| Topic | When to Use | Reference |
+|-------|-------------|-----------|
+| **Fundamentals** | Understanding context anatomy, attention mechanics | [context-fundamentals.md](./references/context-fundamentals.md) |
+| **Degradation** | Debugging failures, lost-in-middle, poisoning | [context-degradation.md](./references/context-degradation.md) |
+| **Optimization** | Compaction, masking, caching, partitioning | [context-optimization.md](./references/context-optimization.md) |
+| **Compression** | Long sessions, summarization strategies | [context-compression.md](./references/context-compression.md) |
+| **Memory** | Cross-session persistence, knowledge graphs | [memory-systems.md](./references/memory-systems.md) |
+| **Multi-Agent** | Coordination patterns, context isolation | [multi-agent-patterns.md](./references/multi-agent-patterns.md) |
+| **Evaluation** | Testing agents, LLM-as-Judge, metrics | [evaluation.md](./references/evaluation.md) |
+| **Tool Design** | Tool consolidation, description engineering | [tool-design.md](./references/tool-design.md) |
+| **Pipelines** | Project development, batch processing | [project-development.md](./references/project-development.md) |
+| **Runtime Awareness** | Usage limits, context window monitoring | [runtime-awareness.md](./references/runtime-awareness.md) |
+
+## Key Metrics
+
+- **Token utilization**: Warning at 70%, trigger optimization at 80%
+- **Token variance**: Explains 80% of agent performance variance
+- **Multi-agent cost**: ~15x single agent baseline
+- **Compaction target**: 50-70% reduction, <5% quality loss
+- **Cache hit target**: 70%+ for stable workloads
+
+## Four-Bucket Strategy
+
+1. **Write**: Save context externally (scratchpads, files)
+2. **Select**: Pull only relevant context (retrieval, filtering)
+3. **Compress**: Reduce tokens while preserving info (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Anti-Patterns
+
+- Exhaustive context over curated context
+- Critical info in middle positions
+- No compaction triggers before limits
+- Single agent for parallelizable tasks
+- Tools without clear descriptions
+
+## Guidelines
+
+1. Place critical info at beginning/end of context
+2. Implement compaction at 70-80% utilization
+3. Use sub-agents for context isolation, not role-play
+4. Design tools with 4-question framework (what, when, inputs, returns)
+5. Optimize for tokens-per-task, not tokens-per-request
+6. Validate with probe-based evaluation
+7. Monitor KV-cache hit rates in production
+8. Start minimal, add complexity only when proven necessary
+
+## Runtime Awareness
+
+The system automatically injects usage awareness via PostToolUse hook:
+
+```xml
+<usage-awareness>
+AI Usage Limits: 5h=45%, 7d=32%
+Context Window Usage: 67%
+</usage-awareness>
+```
+
+**Thresholds:**
+- 70%: WARNING - consider optimization/compaction
+- 90%: CRITICAL - immediate action needed
+
+**Data Sources:**
+- Usage limits: Anthropic OAuth API (`https://api.anthropic.com/api/oauth/usage`)
+- Context window: Statusline temp file (`/tmp/ck-context-{session_id}.json`)
+
+## Scripts
+
+- [context_analyzer.py](./scripts/context_analyzer.py) - Context health analysis, degradation detection
+- [compression_evaluator.py](./scripts/compression_evaluator.py) - Compression quality evaluation

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

@@ -0,0 +1,155 @@
+---
+name: ck-cook
+description: "ALWAYS activate this skill before implementing EVERY feature, plan, or fix."
+argument-hint: "[task|plan-path] [--interactive|--fast|--parallel|--auto|--no-test]"
+---
+
+# Cook - Smart Feature Implementation
+
+End-to-end implementation with automatic workflow detection.
+
+**Principles:** YAGNI, KISS, DRY | Token efficiency | Concise reports
+
+## Usage
+
+```
+/ck-cook <natural language task OR plan path>
+```
+
+**IMPORTANT:** If no flag is provided, the skill will use the `interactive` mode by default for the workflow.
+
+**Optional flags to select the workflow mode:** 
+- `--interactive`: Full workflow with user input (**default**)
+- `--fast`: Skip research, scout→plan→code
+- `--parallel`: Multi-agent execution
+- `--no-test`: Skip testing step
+- `--auto`: Auto-approve all steps
+
+**Example:**
+```
+/ck-cook "Add user authentication to the app" --fast
+/ck-cook path/to/plan.md --auto
+```
+
+<HARD-GATE>
+Do NOT write implementation code until a plan exists and has been reviewed.
+This applies regardless of task simplicity. "Simple" tasks are where unexamined assumptions waste the most time.
+Exception: `--fast` mode skips research but still requires a plan step.
+User override: If user explicitly says "just code it" or "skip planning", respect their instruction.
+</HARD-GATE>
+
+## Anti-Rationalization
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to plan" | Simple tasks have hidden complexity. Plan takes 30 seconds. |
+| "I already know how to do this" | Knowing ≠ planning. Write it down. |
+| "Let me just start coding" | Undisciplined action wastes tokens. Plan first. |
+| "The user wants speed" | Fastest path = plan → implement → done. Not: implement → debug → rewrite. |
+| "I'll plan as I go" | That's not planning, that's hoping. |
+| "Just this once" | Every skip is "just this once." No exceptions. |
+
+## Smart Intent Detection
+
+| Input Pattern | Detected Mode | Behavior |
+|---------------|---------------|----------|
+| Path to `plan.md` or `phase-*.md` | code | Execute existing plan |
+| Contains "fast", "quick" | fast | Skip research, scout→plan→code |
+| Contains "trust me", "auto" | auto | Auto-approve all steps |
+| Lists 3+ features OR "parallel" | parallel | Multi-agent execution |
+| Contains "no test", "skip test" | no-test | Skip testing step |
+| Default | interactive | Full workflow with user input |
+
+See `references/intent-detection.md` for detection logic.
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Intent Detection] --> B{Has plan path?}
+    B -->|Yes| F[Load Plan]
+    B -->|No| C{Mode?}
+    C -->|fast| D[Scout → Plan → Code]
+    C -->|interactive/auto| E[Research → Review → Plan]
+    E --> F
+    D --> F
+    F --> G[Review Gate]
+    G -->|approved| H[Implement]
+    G -->|rejected| E
+    H --> I[Review Gate]
+    I -->|approved| J{--no-test?}
+    J -->|No| K[Test]
+    J -->|Yes| L[Finalize]
+    K --> L
+    L --> M[Report + Journal]
+```
+
+**This diagram is the authoritative workflow.** Prose sections below provide detail for each node. If prose conflicts with this flow, follow the diagram.
+
+## Workflow Overview
+
+```
+[Intent Detection] → [Research?] → [Review] → [Plan] → [Review] → [Implement] → [Review] → [Test?] → [Review] → [Finalize]
+```
+
+**Default (non-auto):** Stops at `[Review]` gates for human approval before each major step.
+**Auto mode (`--auto`):** Skips human review gates, implements all phases continuously.
+**Tasks:** Utilize `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` during implementation step. **Fallback:** These are CLI-only tools — unavailable in VSCode extension. If they error, use `TodoWrite` for progress tracking instead.
+
+| Mode | Research | Testing | Review Gates | Phase Progression |
+|------|----------|---------|--------------|-------------------|
+| interactive | ✓ | ✓ | **User approval at each step** | One at a time |
+| auto | ✓ | ✓ | Auto if score≥9.5 | All at once (no stops) |
+| fast | ✗ | ✓ | **User approval at each step** | One at a time |
+| parallel | Optional | ✓ | **User approval at each step** | Parallel groups |
+| no-test | ✓ | ✗ | **User approval at each step** | One at a time |
+| code | ✗ | ✓ | **User approval at each step** | Per plan |
+
+## Step Output Format
+
+```
+✓ Step [N]: [Brief status] - [Key metrics]
+```
+
+## Blocking Gates (Non-Auto Mode)
+
+Human review required at these checkpoints (skipped with `--auto`):
+- **Post-Research:** Review findings before planning
+- **Post-Plan:** Approve plan before implementation
+- **Post-Implementation:** Approve code before testing
+- **Post-Testing:** 100% pass + approve before finalize
+
+**Always enforced (all modes):**
+- **Testing:** 100% pass required (unless no-test mode)
+- **Code Review:** User approval OR auto-approve (score≥9.5, 0 critical)
+- **Finalize (MANDATORY - never skip):**
+  1. `ck-project-manager` subagent → run full plan sync-back (all completed tasks/steps across all `phase-XX-*.md`, not only current phase), then update `plan.md` status/progress
+  2. `ck-docs-manager` subagent → update `./docs` if changes warrant
+  3. `TaskUpdate` → mark all Tasks complete after sync-back verification (skip if Task tools unavailable)
+  4. Ask user if they want to commit via `ck-git-manager` subagent
+  5. Run `/ck-journal` to write a concise technical journal entry upon completion
+
+## Required Subagents (MANDATORY)
+
+| Phase | Subagent | Requirement |
+|-------|----------|-------------|
+| Research | `ck-researcher` | Optional in fast/code |
+| Scout | `ck-scout` | Optional in code |
+| Plan | `ck-planner` | Optional in code |
+| UI Work | `ck-ui-ux-designer` | If frontend work |
+| Testing | `ck-tester`, `ck-debugger` | **MUST** spawn |
+| Review | `ck-code-reviewer` | **MUST** spawn |
+| Finalize | `ck-project-manager`, `ck-docs-manager`, `ck-git-manager` | **MUST** spawn all 3 |
+
+**CRITICAL ENFORCEMENT:**
+- Steps 4, 5, 6 **MUST** use Task tool to spawn subagents
+- DO NOT implement testing, review, or finalization yourself - DELEGATE
+- If workflow ends with 0 Task tool calls, it is INCOMPLETE
+- Pattern: `Task(subagent_type="[type]", prompt="[task]", description="[brief]")`
+
+## References
+
+- `references/intent-detection.md` - Detection rules and routing logic
+- `references/workflow-steps.md` - Detailed step definitions for all modes
+- `references/review-cycle.md` - Interactive and auto review processes
+- `references/subagent-patterns.md` - Subagent invocation patterns

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/