@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/skills/context-compression/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: context-compression
+description: Manage and compress conversation context in long sessions. Detect when context is growing large, summarize completed work phases, archive old findings while preserving key decisions. Prevents context degradation.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When a session has 20+ turns, when context feels repetitive, when the agent is losing track of earlier work, or when the user says 'summarize what we've done'. NOT for short sessions.\""
+  version: "1.0.0"
+---
+# Context Compression — Long Session Management
+
+> Keep sessions productive by compressing completed work while preserving key decisions.
+
+## Overview
+
+Long sessions (30+ turns) cause context degradation — the AI loses track of earlier work, repeats itself, or forgets decisions. Context compression proactively summarizes completed phases so the context window stays focused on active work.
+
+**Token Impact:** Recovers 5,000-15,000 tokens in long sessions by replacing verbose tool outputs with semantic summaries.
+
+---
+
+## When to Compress
+
+| Signal | Action |
+|---|---|
+| Session has 20+ turns | Consider proactive compression |
+| Agent repeats earlier suggestions | Context is saturated — compress now |
+| User says "we already discussed this" | Compress immediately |
+| Switching to a new phase of work | Compress the completed phase |
+| Large tool output (500+ lines) | Micro-compact the output |
+
+---
+
+## Compression Levels
+
+### Level 1: Micro-Compact (Tool Output)
+
+Compress individual tool outputs while retaining semantic content:
+
+```
+❌ Before (raw grep output — 200 lines, ~4,000 tokens):
+src/auth/jwt.ts:15: import { verify } from 'jsonwebtoken'
+src/auth/jwt.ts:23: export function validateToken(token: string) {
+src/auth/jwt.ts:24:   try {
+src/auth/jwt.ts:25:     const decoded = verify(token, SECRET)
+... (195 more lines)
+
+✅ After (micro-compact — 5 lines, ~100 tokens):
+Grep results for "jwt": Found 8 files, 42 matches.
+Key files: src/auth/jwt.ts (main JWT logic), src/middleware/auth.ts (middleware),
+src/api/login.ts (token creation). Token validation at jwt.ts:23-40.
+Error handling at jwt.ts:42-55. Secret loaded from env at jwt.ts:8.
+```
+
+### Level 2: Phase Summary
+
+Replace a completed work phase with a summary:
+
+```
+❌ Before (full research transcript — ~3,000 tokens):
+[turn 1] Read package.json...
+[turn 2] Read src/index.ts...
+[turn 3] Grep for "auth"...
+[turn 4] Found 8 files related to auth...
+[turn 5] Read src/auth/jwt.ts...
+... (10 more turns of exploration)
+
+✅ After (phase summary — ~200 tokens):
+## Research Phase Complete
+- Project: Next.js 15 app with JWT auth
+- Auth files: 8 files in src/auth/, src/middleware/, src/api/
+- Token flow: login → create JWT → store in httpOnly cookie → validate in middleware
+- Bug location: src/auth/jwt.ts:45 — expiry check uses `<` instead of `<=`
+- Decision: Fix the comparison operator, add edge case test
+```
+
+### Level 3: Session Checkpoint
+
+Full session summary for long-running work:
+
+```markdown
+## Session Checkpoint (Turn 35)
+
+### Completed
+- [x] Researched auth system (8 files, JWT flow mapped)
+- [x] Fixed token expiry bug in jwt.ts:45
+- [x] Added edge case test in jwt.test.ts
+- [x] Verified: all 42 tests passing
+
+### In Progress
+- [ ] Update API documentation
+- [ ] Review related middleware
+
+### Key Decisions
+1. Keep httpOnly cookies (not localStorage) for token storage
+2. Use `<=` for expiry check to include exact-moment expiry
+3. Add 5-minute grace period for clock skew
+
+### Files Modified
+- src/auth/jwt.ts (line 45: comparison fix)
+- tests/auth/jwt.test.ts (added 3 edge case tests)
+```
+
+---
+
+## Compression Protocol
+
+### Step 1: Identify Completed Phases
+```
+What work is DONE and won't be revisited?
+→ Research findings already synthesized
+→ Implementation already verified
+→ Decisions already made and applied
+```
+
+### Step 2: Extract Key Information
+```
+From the completed phase, preserve:
+✅ Decisions made and WHY
+✅ File paths and line numbers of changes
+✅ Key findings that inform ongoing work
+✅ Error messages or test results (summarized)
+
+Discard:
+❌ Step-by-step tool invocation details
+❌ Full file contents that were read
+❌ Exploratory dead-ends that didn't lead anywhere
+❌ Verbose error stack traces (keep the message only)
+```
+
+### Step 3: Write Summary
+```
+Use the Phase Summary format above.
+Keep to 100-300 tokens per completed phase.
+Include enough detail to resume work without re-reading.
+```
+
+---
+
+## Best Practices
+
+1. **Compress phases, not facts** — Individual decisions should stay, full transcripts should go
+2. **Preserve "why" over "what"** — Why a decision was made matters more than the exact commands run
+3. **Never auto-compress** — Always tell the user "I'm summarizing the completed research phase to keep context focused"
+4. **Keep file references** — Always preserve file paths and line numbers in summaries
+5. **Checkpoint on phase transitions** — Natural compression point when switching from research to implementation

package/kit/.opencode/skills/coordinator-mode/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: coordinator-mode
+description: Advanced multi-agent orchestration with parallel workers, synthesis protocols, and coordinator lifecycle. Use when complex tasks require multiple agents working in parallel with intelligent result synthesis.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When the user needs multi-agent coordination, parallel task execution, complex multi-domain work, or when /coordinate or /orchestrate is invoked. NOT for single-domain tasks.\""
+  version: "1.0.0"
+---
+# Coordinator Mode — Multi-Agent Orchestration
+
+> Distilled from production-proven coordinator patterns. Transforms sequential agent chains into intelligent parallel orchestration.
+
+## Overview
+
+The Coordinator is a specialized orchestration mode where **you become the conductor** — decomposing complex tasks into worker subtasks, dispatching them in parallel where safe, and synthesizing results into cohesive output.
+
+**You are NOT a worker. You are the coordinator.** Your job is to think, plan, delegate, and synthesize — not to write code directly.
+
+---
+
+## Coordinator Lifecycle
+
+```
+User Request
+    ↓
+1. DECOMPOSE — Break task into worker subtasks
+    ↓
+2. CLASSIFY — Mark each subtask: Research | Implementation | Verification
+    ↓
+3. DISPATCH — Launch workers (parallel for reads, sequential for writes)
+    ↓
+4. MONITOR — Track worker completion notifications
+    ↓
+5. SYNTHESIZE — Combine results into unified response
+    ↓
+6. VERIFY — Ensure completeness before reporting to user
+```
+
+---
+
+## Phase-Based Workflow
+
+| Phase | Purpose | Concurrency | Worker Type |
+|-------|---------|-------------|-------------|
+| **Research** | Gather information, explore codebase | ✅ Fully parallel | Read-only agents |
+| **Synthesis** | Analyze findings, plan approach | ❌ Coordinator only | No workers |
+| **Implementation** | Make changes to code/files | ⚠️ Sequential per file set | Write-capable agents |
+| **Verification** | Test, lint, validate changes | ✅ Parallel (independent) | Test/security agents |
+
+> 🔴 **Rule:** NEVER skip the Synthesis phase. Research → direct Implementation = poor results.
+
+---
+
+## Concurrency Rules
+
+### Safe to Parallelize
+- ✅ Multiple agents reading different files
+- ✅ Security audit + performance audit (read-only)
+- ✅ Test runner + linter (independent)
+- ✅ Exploring different directories
+
+### Must Be Sequential
+- ❌ Two agents writing to the same file
+- ❌ Implementation that depends on another agent's output
+- ❌ Database migration + code that uses the new schema
+- ❌ API change + frontend that consumes the API
+
+---
+
+## Worker Prompt Writing Guide
+
+### 🔴 The Golden Rule: Never Delegate Understanding
+
+```
+❌ WRONG: "Based on your findings, fix the bug"
+❌ WRONG: "Based on the research, implement it"
+❌ WRONG: "Look at the code and do what's needed"
+
+✅ RIGHT: "The bug is in src/auth/jwt.ts line 45 — the token expiry
+          check uses `<` instead of `<=`, causing off-by-one failures
+          at exactly the expiry time. Change line 45 from
+          `if (now < expiry)` to `if (now <= expiry)`"
+```
+
+> **Why:** Phrases like "based on your findings" push synthesis onto the worker instead of doing it yourself. Write prompts that prove YOU understood — include file paths, line numbers, what specifically to change.
+
+### Writing Effective Worker Prompts
+
+Brief the worker like a **smart colleague who just walked into the room**:
+
+1. **Explain what** you're trying to accomplish and why
+2. **Describe what** you've already learned or ruled out
+3. **Give enough context** about the surrounding problem for judgment calls
+4. **Be specific** about scope: what's in, what's out, what another agent handles
+5. **State the output format** you expect ("report in under 200 words")
+
+### Prompt Templates
+
+#### Research Worker
+```
+Investigate [specific question] in [file/directory scope].
+Context: We're trying to [goal] because [reason].
+I've already checked [what you checked] and found [what you found].
+Report: List [specific deliverable]. Under 200 words.
+```
+
+#### Implementation Worker
+```
+Modify [specific file(s)] to [specific change].
+Context: [Why this change is needed].
+The current code at [file:line] does [X], change it to [Y].
+Constraints: Don't touch [out-of-scope files]. Another agent handles [related area].
+Verify: [How the worker should confirm success].
+```
+
+#### Verification Worker
+```
+Verify that [specific change] works correctly.
+Run: [specific commands].
+Check: [what success looks like].
+Report: Pass/fail with details on any failures.
+```
+
+---
+
+## Fork Semantics
+
+### When to Fork (vs. Spawn Fresh Agent)
+
+| Scenario | Action | Why |
+|----------|--------|-----|
+| Open-ended research question | **Fork** (omit agent type) | Fork inherits context, shorter prompt |
+| Independent parallel research | **Fork** multiple in one message | Each fork shares cache |
+| Specialized domain work | **Spawn** (specify agent type) | Fresh specialist starts clean |
+| Second opinion on your work | **Spawn** | Independent perspective |
+
+### Fork Rules
+
+1. **Don't peek.** Don't read the fork's output file mid-flight. You'll get a completion notification. Reading the transcript pulls tool noise into your context.
+
+2. **Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results. If the user asks before notification lands, say "the fork is still running."
+
+3. **Keep prompts short.** Forks inherit your full context — write a *directive* (what to do), not a *briefing* (what the situation is).
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|---|---|---|
+| "Look at the code and fix it" | Zero context = workers make wrong assumptions | Provide specific file paths, line numbers, and what to change |
+| Skipping Research phase | Implementation without understanding = rework | Always research first, even briefly |
+| Launching 10+ workers at once | Overwhelms synthesis, diminishing returns | 2-5 workers per round, synthesize, then more if needed |
+| Fabricating worker results | User gets wrong information | Wait for actual notification, say "still running" if asked |
+| Coordinator writes code directly | Loses orchestration benefits | Always delegate to appropriate specialist |
+
+---
+
+## Synthesis Protocol
+
+After all workers complete:
+
+```markdown
+## Coordinator Synthesis
+
+### Task: [Original Request]
+
+### Workers Dispatched
+| Worker | Type | Status | Key Finding |
+|--------|------|--------|-------------|
+| agent-1 | Research | ✅ | Found X in file Y |
+| agent-2 | Research | ✅ | Identified Y pattern |
+
+### Consolidated Analysis
+[Your synthesis — not a copy-paste of worker output]
+
+### Decision & Rationale
+[What you decided based on ALL worker findings and why]
+
+### Implementation Plan
+1. [Specific change with file path]
+2. [Specific change with file path]
+
+### Remaining Risk
+- [Anything workers flagged but couldn't resolve]
+```
+
+---
+
+## Continue vs. Spawn Decision
+
+| Situation | Action |
+|-----------|--------|
+| Worker completed, need follow-up on same topic | **Continue** (send message to worker ID) |
+| Worker completed, need different domain work | **Spawn new** specialist |
+| Worker failed, need retry with same context | **Continue** with corrected instructions |
+| Worker failed, need fundamentally different approach | **Spawn new** |
+
+---
+
+## Best Practices
+
+1. **Start with 2-3 workers** — add more after synthesis if needed
+2. **Research before implementation** — always, even for "simple" tasks
+3. **Synthesize, don't copy** — your summary should add insight, not repeat
+4. **Verify independently** — verification workers shouldn't trust implementation workers
+5. **Track state** — note which workers are pending/completed/failed
+6. **Share scratchpad** — use a known directory for cross-worker artifacts

package/kit/.opencode/skills/database-design/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: database-design
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When designing database schemas, choosing ORMs, planning migrations, or optimizing queries. When working with Prisma, Drizzle, or SQL files.\""
+  version: "1.0.0"
+---
+# Database Design
+
+> **Learn to THINK, not copy SQL patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+
+---
+
+## ⚠️ Core Principle
+
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
+
+---
+
+## Decision Checklist
+
+Before designing schema:
+
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
+
+---
+
+## Anti-Patterns
+
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries

package/kit/.opencode/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | FK support enabled per-database |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/kit/.opencode/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/kit/.opencode/skills/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |

package/kit/.opencode/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# Query Optimization
+
+> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
+
+## N+1 Problem
+
+```
+What is N+1?
+├── 1 query to get parent records
+├── N queries to get related records
+└── Very slow!
+
+Solutions:
+├── JOIN → Single query with all data
+├── Eager loading → ORM handles JOIN
+├── DataLoader → Batch and cache (GraphQL)
+└── Subquery → Fetch related in one query
+```
+
+## Query Analysis Mindset
+
+```
+Before optimizing:
+├── EXPLAIN ANALYZE the query
+├── Look for Seq Scan (full table scan)
+├── Check actual vs estimated rows
+└── Identify missing indexes
+```
+
+## Optimization Priorities
+
+1. **Add missing indexes** (most common issue)
+2. **Select only needed columns** (not SELECT *)
+3. **Use proper JOINs** (avoid subqueries when possible)
+4. **Limit early** (pagination at database level)
+5. **Cache** (when appropriate)

package/kit/.opencode/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM Selection
+
+> Choose ORM based on deployment and DX needs.
+
+## Decision Tree
+
+```
+What's the context?
+│
+├── Edge deployment / Bundle size matters
+│   └── Drizzle (smallest, SQL-like)
+│
+├── Best DX / Schema-first
+│   └── Prisma (migrations, studio)
+│
+├── Maximum control
+│   └── Raw SQL with query builder
+│
+└── Python ecosystem
+    └── SQLAlchemy 2.0 (async support)
+```
+
+## Comparison
+
+| ORM | Best For | Trade-offs |
+|-----|----------|------------|
+| **Drizzle** | Edge, TypeScript | Newer, less examples |
+| **Prisma** | DX, schema management | Heavier, not edge-ready |
+| **Kysely** | Type-safe SQL builder | Manual migrations |
+| **Raw SQL** | Complex queries, control | Manual type safety |

package/kit/.opencode/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema Design Principles
+
+> Normalization, primary keys, timestamps, relationships.
+
+## Normalization Decision
+
+```
+When to normalize (separate tables):
+├── Data is repeated across rows
+├── Updates would need multiple changes
+├── Relationships are clear
+└── Query patterns benefit
+
+When to denormalize (embed/duplicate):
+├── Read performance critical
+├── Data rarely changes
+├── Always fetched together
+└── Simpler queries needed
+```
+
+## Primary Key Selection
+
+| Type | Use When |
+|------|----------|
+| **UUID** | Distributed systems, security |
+| **ULID** | UUID + sortable by time |
+| **Auto-increment** | Simple apps, single database |
+| **Natural key** | Rarely (business meaning) |
+
+## Timestamp Strategy
+
+```
+For every table:
+├── created_at → When created
+├── updated_at → Last modified
+└── deleted_at → Soft delete (if needed)
+
+Use TIMESTAMPTZ (with timezone) not TIMESTAMP
+```
+
+## Relationship Types
+
+| Type | When | Implementation |
+|------|------|----------------|
+| **One-to-One** | Extension data | Separate table with FK |
+| **One-to-Many** | Parent-children | FK on child table |
+| **Many-to-Many** | Both sides have many | Junction table |
+
+## Foreign Key ON DELETE
+
+```
+├── CASCADE → Delete children with parent
+├── SET NULL → Children become orphans
+├── RESTRICT → Prevent delete if children exist
+└── SET DEFAULT → Children get default value
+```