@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/skills/clean-code/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
+compatibility: opencode
+metadata:
+  when_to_use: "\"Always active for ALL code writing. Enforces concise, direct coding standards, testing pyramid, and performance best practices.\""
+  version: "2.0.0"
+---
+# Clean Code - Pragmatic AI Coding Standards
+
+> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+
+---
+
+## Core Principles
+
+| Principle | Rule |
+|-----------|------|
+| **SRP** | Single Responsibility - each function/class does ONE thing |
+| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
+| **KISS** | Keep It Simple - simplest solution that works |
+| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
+| **Boy Scout** | Leave code cleaner than you found it |
+
+---
+
+## Naming Rules
+
+| Element | Convention |
+|---------|------------|
+| **Variables** | Reveal intent: `userCount` not `n` |
+| **Functions** | Verb + noun: `getUserById()` not `user()` |
+| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
+| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Rule:** If you need a comment to explain a name, rename it.
+
+---
+
+## Function Rules
+
+| Rule | Description |
+|------|-------------|
+| **Small** | Max 20 lines, ideally 5-10 |
+| **One Thing** | Does one thing, does it well |
+| **One Level** | One level of abstraction per function |
+| **Few Args** | Max 3 arguments, prefer 0-2 |
+| **No Side Effects** | Don't mutate inputs unexpectedly |
+
+---
+
+## Code Structure
+
+| Pattern | Apply |
+|---------|-------|
+| **Guard Clauses** | Early returns for edge cases |
+| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
+| **Composition** | Small functions composed together |
+| **Colocation** | Keep related code close |
+
+---
+
+## AI Coding Style
+
+| Situation | Action |
+|-----------|--------|
+| User asks for feature | Write it directly |
+| User reports bug | Fix it, don't explain |
+| No clear requirement | Ask, don't assume |
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Pattern | ✅ Fix |
+|-----------|-------|
+| Comment every line | Delete obvious comments |
+| Helper for one-liner | Inline the code |
+| Factory for 2 objects | Direct instantiation |
+| utils.ts with 1 function | Put code where used |
+| "First we import..." | Just write code |
+| Deep nesting | Guard clauses |
+| Magic numbers | Named constants |
+| God functions | Split by responsibility |
+
+---
+
+## 🔴 Before Editing ANY File (THINK FIRST!)
+
+**Before changing a file, ask yourself:**
+
+| Question | Why |
+|----------|-----|
+| **What imports this file?** | They might break |
+| **What does this file import?** | Interface changes |
+| **What tests cover this?** | Tests might fail |
+| **Is this a shared component?** | Multiple places affected |
+
+**Quick Check:**
+```
+File to edit: UserService.ts
+└── Who imports this? → UserController.ts, AuthController.ts
+└── Do they need changes too? → Check function signatures
+```
+
+> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
+> 🔴 **Never leave broken imports or missing updates.**
+
+---
+
+## Summary
+
+| Do | Don't |
+|----|-------|
+| Write code directly | Write tutorials |
+| Let code self-document | Add obvious comments |
+| Fix bugs immediately | Explain the fix first |
+| Inline small things | Create unnecessary files |
+| Name things clearly | Use abbreviations |
+| Keep functions small | Write 100+ line functions |
+
+> **Remember: The user wants working code, not a programming lesson.**
+
+---
+
+## 🔴 Self-Check Before Completing (MANDATORY)
+
+**Before saying "task complete", verify:**
+
+| Check | Question |
+|-------|----------|
+| ✅ **Goal met?** | Did I do exactly what user asked? |
+| ✅ **Files edited?** | Did I modify all necessary files? |
+| ✅ **Code works?** | Did I test/verify the change? |
+| ✅ **No errors?** | Lint and TypeScript pass? |
+| ✅ **Nothing forgotten?** | Any edge cases missed? |
+
+> 🔴 **Rule:** If ANY check fails, fix it before completing.
+
+---
+
+## Verification Scripts (MANDATORY)
+
+> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
+
+### Agent → Script Mapping
+
+| Agent | Script | Command |
+|-------|--------|---------|
+| **frontend-specialist** | UX Audit | `python .opencode/skills/frontend-design/scripts/ux_audit.py .` |
+| **frontend-specialist** | A11y Check | `python .opencode/skills/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist** | API Validator | `python .opencode/skills/api-patterns/scripts/api_validator.py .` |
+| **mobile-developer** | Mobile Audit | `python .opencode/skills/mobile-design/scripts/mobile_audit.py .` |
+| **database-architect** | Schema Validate | `python .opencode/skills/database-design/scripts/schema_validator.py .` |
+| **security-auditor** | Security Scan | `python .opencode/skills/vulnerability-scanner/scripts/security_scan.py .` |
+| **seo-specialist** | SEO Check | `python .opencode/skills/seo-fundamentals/scripts/seo_checker.py .` |
+| **seo-specialist** | GEO Check | `python .opencode/skills/geo-fundamentals/scripts/geo_checker.py .` |
+| **performance-optimizer** | Lighthouse | `python .opencode/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python .opencode/skills/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python .opencode/skills/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Any agent** | Lint Check | `python .opencode/skills/lint-and-validate/scripts/lint_runner.py .` |
+| **Any agent** | Type Coverage | `python .opencode/skills/lint-and-validate/scripts/type_coverage.py .` |
+| **Any agent** | i18n Check | `python .opencode/skills/i18n-localization/scripts/i18n_checker.py .` |
+
+> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
+> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
+
+---
+
+### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
+
+**When running a validation script, you MUST:**
+
+1. **Run the script** and capture ALL output
+2. **Parse the output** - identify errors, warnings, and passes
+3. **Summarize to user** in this format:
+
+```markdown
+## Script Results: [script_name.py]
+
+### ❌ Errors Found (X items)
+- [File:Line] Error description 1
+- [File:Line] Error description 2
+
+### ⚠️ Warnings (Y items)
+- [File:Line] Warning description
+
+### ✅ Passed (Z items)
+- Check 1 passed
+- Check 2 passed
+
+**Should I fix the X errors?**
+```
+
+4. **Wait for user confirmation** before fixing
+5. **After fixing** → Re-run script to confirm
+
+> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
+> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
+> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
+

package/kit/.opencode/skills/code-review-checklist/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: code-review-checklist
+description: Code review guidelines covering code quality, security, and best practices.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When reviewing code for quality, security, and best practices. When the user says 'review my code' or 'check this PR'.\""
+  version: "1.0.0"
+---
+# Code Review Checklist
+
+## Quick Review Checklist
+
+### Correctness
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error handling in place
+- [ ] No obvious bugs
+
+### Security
+- [ ] Input validated and sanitized
+- [ ] No SQL/NoSQL injection vulnerabilities
+- [ ] No XSS or CSRF vulnerabilities
+- [ ] No hardcoded secrets or sensitive credentials
+- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
+- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No unnecessary loops
+- [ ] Appropriate caching
+- [ ] Bundle size impact considered
+
+### Code Quality
+- [ ] Clear naming
+- [ ] DRY - no duplicate code
+- [ ] SOLID principles followed
+- [ ] Appropriate abstraction level
+
+### Testing
+- [ ] Unit tests for new code
+- [ ] Edge cases tested
+- [ ] Tests readable and maintainable
+
+### Documentation
+- [ ] Complex logic commented
+- [ ] Public APIs documented
+- [ ] README updated if needed
+
+## AI & LLM Review Patterns
+
+### Logic & Hallucinations
+- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
+- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
+- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
+
+### Prompt Engineering Review
+```markdown
+// ❌ Vague prompt in code
+const response = await ai.generate(userInput);
+
+// ✅ Structured & Safe prompt
+const response = await ai.generate({
+  system: "You are a specialized parser...",
+  input: sanitize(userInput),
+  schema: ResponseSchema
+});
+```
+
+## Anti-Patterns to Flag
+
+```typescript
+// ❌ Magic numbers
+if (status === 3) { ... }
+
+// ✅ Named constants
+if (status === Status.ACTIVE) { ... }
+
+// ❌ Deep nesting
+if (a) { if (b) { if (c) { ... } } }
+
+// ✅ Early returns
+if (!a) return;
+if (!b) return;
+if (!c) return;
+// do work
+
+// ❌ Long functions (100+ lines)
+// ✅ Small, focused functions
+
+// ❌ any type
+const data: any = ...
+
+// ✅ Proper types
+const data: UserData = ...
+```
+
+## Review Comments Guide
+
+```
+// Blocking issues use 🔴
+🔴 BLOCKING: SQL injection vulnerability here
+
+// Important suggestions use 🟡
+🟡 SUGGESTION: Consider using useMemo for performance
+
+// Minor nits use 🟢
+🟢 NIT: Prefer const over let for immutable variable
+
+// Questions use ❓
+❓ QUESTION: What happens if user is null here?
+```

package/kit/.opencode/skills/code-review-graph/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: code-review-graph
+description: Token-efficient code review using Tree-sitter AST graphs and MCP. Cuts AI token usage on large codebases by computing the blast radius of changes instead of reading entire codebases. Uses a SQLite graph database for structural analysis.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When reviewing code in large codebases (500+ files), when token costs are high, when making multi-file changes with cross-module dependencies, or when working with monorepos. Also for dead code detec"
+  version: "1.0.0"
+---
+# Code Review Graph — Token-Efficient Codebase Context via MCP
+
+> Cut AI token usage substantially on large codebases by giving the AI a structural map instead of letting it read everything. Savings scale with codebase size — marginal on small projects, large on monorepos.
+
+## Overview
+
+`code-review-graph` is an MCP server that uses **Tree-sitter** to parse your codebase into an AST graph stored in **SQLite**. When your AI assistant needs context for a task, it queries the graph first — getting only the files in the **blast radius** of your change — instead of reading every file in the directory.
+
+**Token Impact (illustrative — varies by codebase):**
+
+| Codebase Type | Pattern |
+|---------------|---------|
+| Large monorepo (10K+ files) | Biggest savings — graph reads a small fraction of files |
+| Mid-size app (1-5K files) | Meaningful reduction on multi-file changes |
+| Small project (<200 files) | Little benefit — graph overhead can exceed savings |
+
+> **Quality angle:** scoping the AI to the blast radius reduces noise, which tends to improve review focus. Measure on your own repo rather than relying on a fixed multiplier.
+
+## Bootstrap Protocol (opt-in)
+
+When invoked during `/plan` or standard usage on a mid-to-large project, check whether graph analysis is available before relying on it:
+1. **Step 1:** Check if the tool is installed: `Get-Command code-review-graph` (Windows) or `which code-review-graph` (macOS/Linux).
+2. **Step 2:** Check if a `.code-review-graph/` directory exists in the workspace.
+3. **Step 3:** If installed but the index is missing, ask the user before running `code-review-graph build` (it scans the whole project).
+4. **Step 4:** If not installed and the project is large, ask the user: "Would you like to `pip install code-review-graph` and build a local map to cut token usage for this project?" Never install or run build without confirmation.
+
+---
+
+## When to Use vs When to Skip
+
+### ✅ Install it if:
+- Codebase is **500+ files**
+- You make **multi-file changes** with cross-module dependencies
+- You spend **$20+/month** on AI assistant tokens
+- You work with **monorepos**, microservices, or cross-package TypeScript
+- You want **better review quality** in addition to cost savings
+
+### ❌ Skip it if:
+- Codebase is **under ~200 files** with isolated single-file changes
+- Heavy use of **dynamic patterns** (reflection, runtime code gen, dynamic imports)
+- You want **zero-maintenance** — the graph needs to stay in sync
+- Team hasn't standardized on an AI coding tool yet
+
+### ⚠️ Evaluate first if:
+- Codebase is **200–500 files** — benchmark before committing
+- Mix of **static and dynamic patterns** — test on representative commits
+
+---
+
+## How It Works (4 Layers)
+
+```
+Layer 1: PARSE    → Tree-sitter builds ASTs from 19 languages
+Layer 2: STORE    → Nodes + edges saved in SQLite graph
+Layer 3: TRACE    → BFS computes blast radius of changes
+Layer 4: SERVE    → MCP exposes graph to AI assistants
+```
+
+### What the Graph Contains
+- **Nodes:** Files, functions, methods, classes, imports, tests
+- **Edges:** "A calls B", "X imports Y", "TestZ covers FunctionW", "ClassA extends ClassB"
+- **Metadata:** Name, type, file path, line range per node
+- **Privacy:** Structural metadata only — NO source code content in the graph
+
+### Supported Languages (19)
+Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Vue SFC, Solidity, Dart, R, Perl, Lua, Jupyter/Databricks notebooks.
+
+---
+
+## Installation
+
+### Prerequisites
+- Python 3.9+ (`python3 --version`)
+- pip or pipx installed
+- An MCP-compatible AI client (OpenCode kit, Claude Code, Cursor, Windsurf, Zed)
+- Git-tracked codebase (for incremental updates)
+
+### Step 1: Install the Package
+
+```bash
+# Recommended: isolated environment
+pipx install code-review-graph
+
+# Alternative: fastest, no permanent install
+uvx code-review-graph install
+
+# Alternative: global pip
+pip install code-review-graph
+```
+
+### Step 2: Configure MCP Client
+
+```bash
+# Auto-detect all supported tools
+code-review-graph install
+
+# Or target a specific platform
+code-review-graph install --platform claude-code
+code-review-graph install --platform cursor
+code-review-graph install --platform windsurf
+```
+
+> **Restart your editor** after this step. The MCP server activates on restart.
+
+### Step 3: Build the Initial Graph
+
+```bash
+cd /your/project
+code-review-graph build
+```
+
+| Codebase Size | Expected Build Time |
+|---------------|---------------------|
+| 500 files | 10–30 seconds |
+| 5,000 files | 2–5 minutes |
+| 27,000 files | 5–10 minutes |
+
+### Step 4: Enable Watch Mode (Recommended)
+
+```bash
+# Keep graph current as you work
+code-review-graph watch
+```
+
+Incremental updates complete in **under 2 seconds**. If you prefer manual updates:
+
+```bash
+code-review-graph update
+```
+
+### Step 5: Verify Integration
+
+Open your AI client and check MCP connection. For Claude Code: run `/mcp` and confirm `code-review-graph` appears.
+
+---
+
+## Configuration
+
+### Ignore File
+
+Create `.code-review-graphignore` at project root (uses `.gitignore` syntax):
+
+```
+# Build artifacts
+dist/**
+.next/**
+build/**
+
+# Dependencies
+node_modules/**
+vendor/**
+
+# Generated files
+generated/**
+*.generated.ts
+*.min.js
+
+# Test fixtures (if large)
+__fixtures__/**
+```
+
+> Excluding generated files and build artifacts is critical — they inflate the graph with meaningless nodes.
+
+### Multi-Repo Setup
+
+For microservice architectures:
+
+```bash
+# Register additional repos
+code-review-graph register /path/to/other/repo
+
+# List all registered repos
+code-review-graph repos
+```
+
+The MCP server serves context across all registered repositories.
+
+---
+
+## Core Workflows
+
+### 1. Blast Radius Analysis (Primary Use)
+
+This is automatic when the MCP server is active. Your AI assistant queries the graph before reading files, getting only the impacted files instead of everything.
+
+```
+Without graph:  Changed auth/middleware.py → AI reads 200+ files → 8,200 tokens
+With graph:     Changed auth/middleware.py → Graph returns 12 impacted files → 1,000 tokens
+```
+
+### 2. Risk-Scored Change Analysis
+
+```bash
+code-review-graph detect-changes
+```
+
+Scores each uncommitted change by risk level:
+- Number of dependents
+- Test coverage gaps
+- Whether changed functions are on critical paths
+- High-risk changes flagged **before** you ask for review
+
+### 3. Dead Code Detection
+
+The graph finds nodes with **no incoming edges** — no callers, no importers, no test coverage:
+
+```bash
+# Surfaces functions/classes that are candidates for removal
+# Useful on mature codebases to reduce cruft
+```
+
+### 4. Refactoring Preview
+
+```bash
+code-review-graph rename preview --from OldClassName --to NewClassName
+```
+
+Shows every file affected by a rename, and flags edge cases (dynamic string references that static analysis can't catch).
+
+### 5. Architecture Visualization
+
+```bash
+code-review-graph visualize
+```
+
+Generates interactive visualization showing module clusters using community detection (Leiden algorithm). Useful for:
+- Onboarding new contributors
+- Identifying architectural drift
+- Spotting overly-coupled modules
+
+### 6. Wiki Generation
+
+```bash
+code-review-graph wiki
+```
+
+Generates markdown wiki of codebase structure — every module, its public API, dependencies, and test coverage.
+
+---
+
+## Known Limitations
+
+| Limitation | Impact | Mitigation |
+|-----------|--------|------------|
+| **Dynamic imports** (`require(variable)`, `import(buildPath())`) | Dependencies invisible to parser | Manually note in `.code-review-graphignore` or accept over-prediction |
+| **Reflection-based calls** (Django signals, `getattr()`, Java reflection) | Missed edges in graph | Serena (LSP-based) is better for these codebases |
+| **Runtime-generated code** (`eval`, template engines) | Not parseable at static time | Accept limitation or exclude from graph |
+| **Cross-language boundaries** (Python calling TypeScript API) | No edges between language runtimes | Use multi-repo registration as partial workaround |
+| **Stale graph** (without watch mode) | Claude queries outdated relationships | Always run `code-review-graph update` before tasks, or use watch mode |
+| **TypeScript path aliases** (`@/components/...`) | May require tsconfig resolution config | Check `tsconfig_resolver.py` handles your setup |
+
+---
+
+## Alternatives Comparison
+
+| Tool | Approach | Pros | Cons | Best For |
+|------|----------|------|------|----------|
+| **code-review-graph** | Tree-sitter + SQLite | Fast, 19 languages, local, no deps | Static analysis only | General use, large codebases |
+| **Claudette** | Go rewrite | Single binary, no Python | Fewer languages, simpler | Python-averse teams |
+| **Serena** | LSP-based | Deep semantic precision, type resolution | Heavy setup, slower | Polymorphism-heavy codebases |
+| **code-graph-rag** | RAG + vector search | Natural language queries | Complex setup | Codebase exploration |
+| **Native IDE context** | Editor built-in | Zero setup | No explicit blast radius | Simple projects |
+
+---
+
+## Integration with OpenCode kit
+
+### Complementary Skills
+
+| OpenCode kit Skill | How It Complements |
+|-------------------|--------------------|
+| `context-compression` | Graph reduces input context; compression reduces output verbosity |
+| `coordinator-mode` | Graph-aware workers can be dispatched with precise file lists |
+| `verify-changes` | After graph-informed review, verify changes via execution |
+| `batch-operations` | Graph's blast radius informs which files need batch updates |
+
+### Recommended Session Architecture
+
+```
+1. Start fresh session for each distinct task
+2. Graph pre-filters context → AI reads only blast radius
+3. Context compression summarizes completed phases
+4. Memory system saves key decisions for next session
+5. Result: minimum tokens, maximum quality
+```
+
+---
+
+## Best Practices
+
+1. **Always run watch mode** in development — stale graphs produce stale context
+2. **Exclude generated files** — they inflate the graph with noise
+3. **Benchmark first** — measure token usage for 1 week without, 1 week with
+4. **Combine with output constraints** — graph reduces input, prompt engineering reduces output
+5. **Use `.code-review-graphignore`** for build artifacts, `node_modules`, `dist/`
+6. **Keep sessions short** — fresh sessions + graph = optimal token efficiency
+7. **Multi-repo registration** for microservice architectures