@iamnishankhan/opencode-kit-grok 1.0.0

package/bin/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { init } from "../lib/init.js";
+
+const args = process.argv.slice(2);
+const command = args[0] || "init";
+
+const flags = {
+  force: args.includes("--force") || args.includes("-f"),
+  path: getFlagValue(args, "--path") || ".",
+  quiet: args.includes("--quiet") || args.includes("-q"),
+};
+
+function getFlagValue(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1) return null;
+  return argv[i + 1] || null;
+}
+
+async function main() {
+  if (command === "init") {
+    await init(flags);
+    return;
+  }
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(`
+Usage:
+  npx @iamnishankhan/opencode-kit-grok init
+
+Options:
+  --path <dir>   Install into this folder (default: current folder)
+  --force, -f    Overwrite existing .opencode
+  --quiet, -q    Less text
+`);
+    return;
+  }
+
+  console.error("Unknown command:", command);
+  console.error("Run with: init | help");
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/kit/.opencode/AGENTS.md

@@ -0,0 +1,392 @@
+# AGENTS.md — OpenCode Project Instructions
+
+Converted from AG Kit rules for OpenCode. These instructions apply to all agents in this workspace.
+
+## Core Operating Principles
+
+- Prefer the smallest correct change; avoid unrelated refactors.
+- Validate with tests/lint when behavior changes.
+- Never hardcode secrets; use environment variables.
+- Match the user's language for responses; keep code identifiers in English.
+- For multi-domain work, plan first, then delegate to specialist subagents.
+
+## Specialist Routing Hints
+
+| Domain | Prefer agent | Prefer skills |
+|--------|--------------|---------------|
+| Backend / API / auth | `@backend-specialist` | `api-patterns`, `nodejs-best-practices`, `python-patterns` |
+| Frontend / UI | `@frontend-specialist` | `frontend-design`, `tailwind-patterns`, `nextjs-react-expert` |
+| Database / schema | `@database-architect` | `database-design` |
+| Debugging | `@debugger` | `systematic-debugging` |
+| Security audit | `@security-auditor` | `vulnerability-scanner` |
+| Penetration testing | `@penetration-tester` | `red-team-tactics` |
+| DevOps / deploy | `@devops-engineer` | `deployment-procedures`, `server-management` |
+| Tests | `@test-engineer` | `testing-patterns`, `tdd-workflow` |
+| QA automation | `@qa-automation-engineer` | `webapp-testing`, `testing-patterns` |
+| Performance | `@performance-optimizer` | `performance-profiling` |
+| SEO | `@seo-specialist` | `seo-fundamentals` |
+| Mobile | `@mobile-developer` | `mobile-design` |
+| Games | `@game-developer` | `game-development` |
+| Planning | `@project-planner` or `/plan` | `plan-writing`, `architecture` |
+| Multi-agent coord | `@orchestrator` or `/orchestrate` | `coordinator-mode`, `parallel-agents` |
+| Legacy / refactor | `@code-archaeologist` | `simplify-code`, `clean-code` |
+| Docs | `@documentation-writer` | `documentation-templates` |
+| Discovery | `@explorer-agent` | — |
+| Product | `@product-manager` / `@product-owner` | — |
+
+## Commands
+
+Custom slash commands live under `.opencode/commands/`. Examples: `/create`, `/debug`, `/plan`, `/test`, `/verify`, `/orchestrate`, `/deploy`.
+
+## Skills
+
+Domain skills live under `.opencode/skills/*/SKILL.md`. Load with the skill tool when relevant.
+
+## Memory
+
+Optional durable notes live under `.opencode/memory/`. Use the `memory-system` skill and `/remember` command to save preferences and decisions into `.opencode/memory/`.
+
+## Rule: code-rules
+
+# Code Rules (TIER 1) - OpenCode kit
+
+> Loaded when the request involves writing or modifying code.
+
+---
+
+## 📱 Project Type Routing
+
+| Project Type                           | Primary Agent         | Skills                        |
+| -------------------------------------- | --------------------- | ----------------------------- |
+| **MOBILE** (iOS, Android, RN, Flutter) | `mobile-developer`    | mobile-design                 |
+| **WEB** (Next.js, React web)           | `frontend-specialist` | frontend-design               |
+| **BACKEND** (API, server, DB)          | `backend-specialist`  | api-patterns, database-design |
+
+> 🔴 **Mobile + frontend-specialist = WRONG.** Mobile = mobile-developer ONLY.
+
+---
+
+## 🛑 GLOBAL SOCRATIC GATE
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type            | Strategy       | Required Action                                                   |
+| ----------------------- | -------------- | ----------------------------------------------------------------- |
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions                                 |
+| **Code Edit / Bug Fix** | Context Check  | Confirm understanding + ask impact questions                      |
+| **Vague / Simple**      | Clarification  | Ask Purpose, Users, and Scope                                     |
+| **Full Orchestration**  | Gatekeeper     | **STOP** subagents until user confirms plan details               |
+| **Direct "Proceed"**    | Validation     | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:**
+
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+4. **Reference:** Full protocol in `@[skills/brainstorming]`.
+
+---
+
+## 🏁 Plan Mode (4-Phase)
+
+1. ANALYSIS → Research, questions
+2. PLANNING → `{task-slug}.md`, task breakdown
+3. SOLUTIONING → Architecture, design (NO CODE!)
+4. IMPLEMENTATION → Code + tests
+
+---
+
+## 🏁 Final Checklist Protocol
+
+**Trigger:** When the user says "run the final checks", "final checks", "run all the tests", or similar phrases.
+
+| Task Stage       | Command                                            | Purpose                        |
+| ---------------- | -------------------------------------------------- | ------------------------------ |
+| **Manual Audit** | `python .opencode/scripts/checklist.py .`             | Priority-based project audit   |
+| **Pre-Deploy**   | `python .opencode/scripts/checklist.py . --url <URL>` | Full Suite + Performance + E2E |
+
+**Priority Execution Order:**
+
+1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **UX** → 6. **Seo** → 7. **Lighthouse/E2E**
+
+**Rules:**
+
+- **Completion:** A task is NOT finished until `checklist.py` returns success.
+- **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
+
+**Available Scripts (10 total):**
+
+| Script                     | Skill                 | When to Use         |
+| -------------------------- | --------------------- | ------------------- |
+| `security_scan.py`         | vulnerability-scanner | Always on deploy    |
+| `lint_runner.py`           | lint-and-validate     | Every code change   |
+| `test_runner.py`           | testing-patterns      | After logic change  |
+| `schema_validator.py`      | database-design       | After DB change     |
+| `ux_audit.py`              | frontend-design       | After UI change     |
+| `accessibility_checker.py` | frontend-design       | After UI change     |
+| `seo_checker.py`           | seo-fundamentals      | After page change   |
+| `mobile_audit.py`          | mobile-design         | After mobile change |
+| `lighthouse_audit.py`      | performance-profiling | Before deploy       |
+| `playwright_runner.py`     | webapp-testing        | Before deploy       |
+
+> 🔴 **Agents & Skills can invoke ANY script** via `python .opencode/skills/<skill>/scripts/<script>.py`
+
+---
+
+## Rule: core-protocol
+
+# Core Protocol - OpenCode kit
+
+> The highest-priority workspace rules. How the AI loads agents/skills and what it must do before any implementation.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+
+Agent activated → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (Workspace Rules in `.opencode/rules/`) > P1 (Agent `.md`) > P2 (SKILL.md). All rules are binding.
+
+### 1.1 Skill Announcement (MANDATORY)
+
+**Every time you load and apply a skill, announce it BEFORE using it** — so the user can verify which knowledge is active.
+
+```markdown
+📚 **Using skill: `@[skill-name]`...**
+```
+
+- List multiple skills together: `📚 Using skills: @frontend-design + @design-spec...`
+- Announce on-demand skills too (e.g. a companion skill pulled from a hub, or `app-builder` for a new app), not just frontmatter ones.
+- ❌ Applying a skill without announcing it = **USER CANNOT VERIFY THE SKILL WAS USED**.
+
+### 2. Enforcement Protocol
+
+1. **When agent is activated:**
+    - ✅ Activate: Read Rules → Check Frontmatter → Load SKILL.md → Apply All.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+
+---
+
+## 📁 File Dependency Awareness
+
+**Before modifying ANY file:**
+
+1. If `CODEBASE.md` exists, check its File Dependencies section.
+2. Otherwise, discover dependencies with targeted search/import analysis; do not block waiting for a missing file.
+3. Identify dependent files and update all affected files together.
+
+---
+
+## 🗺️ System Map & Memory Read
+
+> 🔴 **MANDATORY:** At session start, you MUST read `.opencode/memory/MEMORY.md` to load persistent project conventions, user preferences, and decisions.
+
+> 📚 **Catalog lookup (on-demand, NOT every session):** Need the full list of Agents / Skills / Scripts? The `quick-reference` rule has the essentials. For the complete catalog, read `.opencode/ARCHITECTURE.md` only when you actually need it (e.g. orchestration, or discovering a skill you're unsure exists) — do NOT load it on every request.
+
+**Path Awareness (Note: the project directory name is `.agents` plural):**
+
+- Agents: `.opencode/agent/` (Project)
+- Skills: `.opencode/skills/` (Project)
+- Memory: `.opencode/memory/` (Project)
+- Runtime Scripts: `.opencode/skills/<skill>/scripts/`
+
+---
+
+## 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## Rule: design-rules
+
+# Design Rules (TIER 2) - OpenCode kit
+
+> Loaded when touching UI files. Design rules live in the specialist agents, NOT here.
+
+## 🛑 GATE: DESIGN.md before any UI code (MANDATORY)
+
+Before writing or editing UI (components, pages, styles — web or mobile), a **`DESIGN.md` must exist at the project root**.
+
+1. **Check** for `DESIGN.md` at the project root.
+2. **If missing:** infer the design direction from the brief, then **create `DESIGN.md` first** (tokens + rationale) following the `design-spec` skill. Do not write UI code until it exists.
+3. **If present:** READ it and build strictly against its tokens. Descriptive names in prose map to token names.
+4. **Keep it in sync** when the visual language changes — it is the single source of truth.
+
+> Exception: none for new UI. A genuinely trivial tweak to existing UI (one button color, a spacing nudge) may proceed if a `DESIGN.md` already governs the project. Net-new UI always requires the gate.
+
+| Need | Read |
+| ---- | ---- |
+| DESIGN.md format / tokens | `.opencode/skills/design-spec/SKILL.md` |
+
+---
+
+| Task         | Read                            |
+| ------------ | ------------------------------- |
+| Web UI/UX    | `.opencode/agent/frontend-specialist.md` |
+| Mobile UI/UX | `.opencode/agent/mobile-developer.md`    |
+
+**These agents contain:**
+
+- Purple Ban (no purple by default — brand/brief override allowed)
+- Template Ban (no standard layouts)
+- Anti-cliché rules
+- Deep Design Thinking protocol
+
+> 🔴 **For design work:** Open and READ the agent file. Rules are there.
+
+---
+
+## Rule: quick-reference
+
+# Quick Reference - OpenCode kit
+
+> A fast index of the most-used agents, skills, and scripts.
+
+## Agents & Skills
+
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor` (Cyber/Audit), `backend-specialist` (API/DB), `frontend-specialist` (UI/UX), `mobile-developer`, `debugger`, `game-developer`
+- **Key Skills**: `clean-code`, `brainstorming`, `app-builder`, `frontend-design`, `mobile-design`, `plan-writing`, `behavioral-modes`
+
+## Key Scripts
+
+- **Verify**: `.opencode/scripts/verify_all.py`, `.opencode/scripts/checklist.py`
+- **Scanners**: `security_scan.py`
+- **Audits**: `ux_audit.py`, `mobile_audit.py`, `lighthouse_audit.py`, `seo_checker.py`
+- **Test**: `playwright_runner.py`, `test_runner.py`
+
+---
+
+## Rule: request-routing
+
+# Request Routing - OpenCode kit
+
+> Always-active. Classify every request, then auto-route to the best specialist agent(s) before responding.
+
+---
+
+## 📥 REQUEST CLASSIFIER (STEP 1)
+
+**Before ANY action, classify the request:**
+
+| Request Type     | Trigger Keywords                           | Active Tiers                   | Result                      |
+| ---------------- | ------------------------------------------ | ------------------------------ | --------------------------- |
+| **QUESTION**     | "what is", "how does", "explain"           | TIER 0 only                    | Text Response               |
+| **SURVEY/INTEL** | "analyze", "list files", "overview"        | TIER 0 + Explorer              | Session Intel (No File)     |
+| **SIMPLE CODE**  | "fix", "add", "change" (single file)       | TIER 0 + TIER 1 (lite)         | Inline Edit                 |
+| **COMPLEX CODE** | "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **NEW APP**      | "new app", "from scratch", "build me a/an", multi-page | `project-planner` (loads `app-builder`) → `orchestrator` | **{task-slug}.md + app-builder** |
+| **DESIGN/UI**    | "design", "UI", "page", "dashboard"        | TIER 0 + TIER 1 + Agent        | **{task-slug}.md Required** |
+| **SLASH CMD**    | /create, /orchestrate, /debug              | Command-specific flow          | Variable                    |
+
+> 🔴 **NEW APP / scaffold from scratch:** route through `project-planner` or `orchestrator` (both load `app-builder`), NOT a lone specialist like `frontend-specialist`. A specialist alone has no project-detection, tech-stack selection, or template knowledge — `app-builder` does. Or run `/create`.
+
+---
+
+## 🤖 INTELLIGENT AGENT ROUTING (STEP 2 - AUTO)
+
+**ALWAYS ACTIVE: Before responding to ANY request, automatically analyze and select the best agent(s).**
+
+> 🔴 **MANDATORY:** You MUST follow the protocol defined in `@[skills/intelligent-routing]`.
+
+### Auto-Selection Protocol
+
+1. **Analyze (Silent)**: Detect domains (Frontend, Backend, Security, etc.) from user request.
+2. **Select Agent(s)**: Choose the most appropriate specialist(s).
+3. **Inform User**: Concisely state which expertise is being applied.
+4. **Apply**: Generate response using the selected agent's persona and rules.
+
+### Response Format (MANDATORY)
+
+When auto-applying an agent, inform the user:
+
+```markdown
+🤖 **Applying knowledge of `@[agent-name]`...**
+
+[Continue with specialized response]
+```
+
+**Rules:**
+
+1. **Silent Analysis**: No verbose meta-commentary ("I am analyzing...").
+2. **Respect Overrides**: If user mentions `@agent`, use it.
+3. **Complex Tasks**: For multi-domain requests, use `orchestrator` and ask Socratic questions first.
+
+### ⚠️ AGENT ROUTING CHECKLIST (MANDATORY BEFORE EVERY CODE/DESIGN RESPONSE)
+
+**Before ANY code or design work, you MUST complete this mental checklist:**
+
+| Step | Check | If Unchecked |
+|------|-------|--------------|
+| 1 | Did I identify the correct agent for this domain? | → STOP. Analyze request domain first. |
+| 2 | Did I READ the agent's `.md` file (or recall its rules)? | → STOP. Open `.opencode/agent/{agent}.md` |
+| 3 | Did I announce `🤖 Applying knowledge of @[agent]...`? | → STOP. Add announcement before response. |
+| 4 | Did I load required skills from agent's frontmatter? | → STOP. Check `skills:` field and read them. |
+
+**Failure Conditions:**
+
+- ❌ Writing code without identifying an agent = **PROTOCOL VIOLATION**
+- ❌ Skipping the announcement = **USER CANNOT VERIFY AGENT WAS USED**
+- ❌ Ignoring agent-specific rules (e.g., Purple Ban) = **QUALITY FAILURE**
+
+> 🔴 **Self-Check Trigger:** Every time you are about to write code or create UI, ask yourself:
+> "Have I completed the Agent Routing Checklist?" If NO → Complete it first.
+
+---
+
+## 🎭 Gemini Mode Mapping
+
+| Mode     | Agent             | Behavior                                     |
+| -------- | ----------------- | -------------------------------------------- |
+| **plan** | `project-planner` | 4-phase methodology. NO CODE before Phase 4. |
+| **ask**  | -                 | Focus on understanding. Ask questions.       |
+| **edit** | `orchestrator`    | Execute. Check `{task-slug}.md` first.       |
+
+> 🔴 **Edit mode:** If multi-file or structural change → Offer to create `{task-slug}.md`. For single-file fixes → Proceed directly.
+> Full Plan Mode (4-Phase) protocol lives in `code-rules.md`.
+
+---
+
+## Rule: universal-rules
+
+# Universal Rules (TIER 0) - OpenCode kit
+
+> Always-active rules that apply to every request, regardless of domain.
+
+---
+
+## 🌐 Language Handling
+
+When user's prompt is NOT in English:
+
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+---
+
+## 🧹 Clean Code (Global Mandatory)
+
+**ALL code MUST follow `@[skills/clean-code]` rules. No exceptions.**
+
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to current Core Web Vitals standards.
+- **Infra/Safety**: 5-Phase Deployment. Verify secrets security.
+
+---
+

package/kit/.opencode/README.md

@@ -0,0 +1,71 @@
+# OpenCode Kit (from AG Kit)
+
+Pure conversion of the AG Kit toolkit for **OpenCode**.
+Everything lives under `.opencode/` so your project root stays clean.
+
+## Layout
+
+```
+your-project/
+└── .opencode/
+    ├── opencode.json       # default_agent, instructions
+    ├── AGENTS.md           # rules + routing hints
+    ├── USAGE.md            # full usage guide
+    ├── README.md           # this file
+    ├── agents/             # 20 specialist agents
+    ├── skills/             # 47 domain skills
+    ├── commands/           # 13 slash commands
+    ├── memory/             # durable notes (preferences, decisions)
+    └── scripts/            # validation helpers
+```
+
+## Install
+
+```bash
+# From the unzipped kit, copy the folder into any project:
+cp -r .opencode /path/to/your/project/
+
+# Or unzip so .opencode lands at project root:
+unzip opencode-kit.zip -d /path/to/your/project
+```
+
+Open the project in OpenCode. The IDE discovers `.opencode/` automatically.
+
+## Defaults
+
+- **Primary agent:** `orchestrator`
+- **Also primary:** `project-planner`
+- **Instructions:** `.opencode/AGENTS.md`
+- **Subagents:** all other specialists (`@backend-specialist`, …)
+
+## Commands
+
+`/plan` `/create` `/enhance` `/debug` `/test` `/verify` `/deploy`  
+`/orchestrate` `/coordinate` `/brainstorm` `/preview` `/remember` `/status`
+
+## Memory & scripts
+
+| Path | Purpose |
+|------|---------|
+| `.opencode/memory/` | Cross-session preferences and decisions (`/remember`) |
+| `.opencode/scripts/` | Checklist / verify helpers |
+
+Run helpers from the **project root**:
+
+```bash
+python .opencode/scripts/checklist.py .
+python .opencode/scripts/verify_all.py . --url http://localhost:3000
+```
+
+Skill-bundled scripts:
+
+```bash
+python .opencode/skills/vulnerability-scanner/scripts/security_scan.py .
+python .opencode/skills/lint-and-validate/scripts/lint_runner.py .
+```
+
+## Notes
+
+- Antigravity hooks/doctor/plugin were not ported.
+- No legacy sample agents (builder/verifier/etc.) — AG Kit specialists only.
+- See `USAGE.md` for workflows and troubleshooting.