@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/USAGE.md

@@ -0,0 +1,405 @@
+# OpenCode Kit — Usage Guide
+
+How to install and use the AG Kit → OpenCode conversion in **OpenCode IDE**.
+
+---
+
+## 1. What this kit is
+
+This package is a pure conversion of **AG Kit** (Antigravity agents, skills, workflows, rules) into OpenCode’s layout:
+
+| Piece | OpenCode location | Role |
+|-------|-------------------|------|
+| Agents | `.opencode/agents/*.md` | Specialist roles (primary + subagents) |
+| Skills | `.opencode/skills/*/SKILL.md` | Domain knowledge loaded on demand |
+| Commands | `.opencode/commands/*.md` | Slash workflows (`/plan`, `/debug`, …) |
+| Rules | `.opencode/AGENTS.md` | Always-on project instructions |
+| Config | `.opencode/opencode.json` | Default agent + instruction paths |
+| Memory | `.opencode/memory/` | Optional durable notes across sessions |
+| Scripts | `.opencode/scripts/` | Optional validation helpers (Python) |
+
+**Default primary agent:** `orchestrator`  
+**Other primary agent:** `project-planner`  
+**Everything else:** subagents (invoke with `@name` or by routing)
+
+---
+
+## 2. Install
+
+### Option A — New / empty project
+
+```bash
+cd /path/to/your/project
+unzip /path/to/opencode-kit.zip
+```
+
+You should see:
+
+```text
+.
+│   ├── AGENTS.md
+│   ├── opencode.json
+├── README.md
+│   ├── memory/
+├── .opencode/scripts/
+└── .opencode/
+    ├── agents/
+    ├── skills/
+    └── commands/
+```
+
+### Option B — Merge into an existing project
+
+```bash
+# From the unzipped kit folder
+cp -r .opencode /path/to/your/project/
+
+# Merge opencode.json carefully if you already have one
+# (keep your providers/models; add "instructions": ["AGENTS.md"]  // resolved next to this config
+#  and set "default_agent": "orchestrator" if you want this kit’s default)
+```
+
+### Option C — Global (all projects)
+
+Copy agents/skills/commands into your user OpenCode config instead of a single project:
+
+```bash
+# Typical locations (Linux/macOS)
+mkdir -p ~/.config/opencode/{agents,skills,commands}
+cp .opencode/agents/*.md ~/.config/opencode/agents/
+cp -r .opencode/skills/* ~/.config/opencode/skills/
+cp .opencode/commands/*.md ~/.config/opencode/commands/
+# Put AGENTS.md content into ~/.config/opencode/AGENTS.md if you want it global
+```
+
+Project-level `.opencode/` always wins over global for the same names.
+
+---
+
+## 3. Open in OpenCode
+
+1. Open the project root (the folder that contains `.opencode/`).
+2. Start OpenCode (TUI or your usual entrypoint).
+3. Confirm agents load: switch agent / Tab through agents — you should see `orchestrator`, `project-planner`, and the specialists.
+4. Type `/` — custom commands like `/plan`, `/create`, `/debug` should appear.
+
+If agents or commands are missing:
+
+- Ensure files are under **`.opencode/agents/`** and **`.opencode/commands/`** (plural `agents` / `commands` as used by this kit).
+- Restart OpenCode after copying files.
+- Check YAML frontmatter starts and ends with `---` on its own lines.
+
+---
+
+## 4. Core concepts in practice
+
+### Agents
+
+| Mode | Agents | How you use them |
+|------|--------|------------------|
+| **Primary** | `orchestrator`, `project-planner` | Main session agent (Tab / `/agent`) |
+| **Subagent** | All other specialists | `@backend-specialist`, `@debugger`, etc., or let orchestrator delegate |
+
+**Typical flow**
+
+1. Stay on `orchestrator` for multi-domain work, or switch to `project-planner` for planning-only.
+2. For a focused job, switch to the specialist or ask the primary to delegate:
+   - “Have `@backend-specialist` design the auth API”
+   - “`@security-auditor` review the auth changes only”
+
+**Specialist map (short)**
+
+| Need | Agent |
+|------|--------|
+| APIs, auth, server logic | `@backend-specialist` |
+| UI / React / CSS | `@frontend-specialist` |
+| Schema, SQL, indexes | `@database-architect` |
+| Bugs, crashes, root cause | `@debugger` |
+| CI/CD, servers, deploy | `@devops-engineer` |
+| Tests, coverage | `@test-engineer` |
+| Security review | `@security-auditor` |
+| Aggressive security testing mindset | `@penetration-tester` |
+| Legacy / refactor | `@code-archaeologist` |
+| Codebase map | `@explorer-agent` |
+| Mobile | `@mobile-developer` |
+| Games | `@game-developer` |
+| Perf / Lighthouse | `@performance-optimizer` |
+| SEO | `@seo-specialist` |
+| Docs | `@documentation-writer` |
+| E2E / QA pipelines | `@qa-automation-engineer` |
+| Requirements / stories | `@product-manager` |
+| Backlog / MVP | `@product-owner` |
+| Multi-agent coordination | `@orchestrator` |
+| Plans only (no code) | `@project-planner` |
+
+### Skills
+
+Skills are **not** always in context. OpenCode loads them when relevant (description match) or when you/the agent call the skill tool:
+
+```text
+Load the systematic-debugging skill and investigate this 500.
+Use the vulnerability-scanner skill on this API.
+```
+
+Useful skills to know:
+
+| Skill | When |
+|-------|------|
+| `clean-code` | Any implementation |
+| `api-patterns` | REST/GraphQL/tRPC design |
+| `database-design` | Schema / indexes / migrations |
+| `systematic-debugging` | Hard bugs |
+| `testing-patterns` / `tdd-workflow` | Writing tests |
+| `verify-changes` | Prove a change works by running it |
+| `vulnerability-scanner` | Security pass |
+| `app-builder` | Scaffolding new apps |
+| `coordinator-mode` / `parallel-agents` | Multi-agent work |
+| `memory-system` | Save/recall durable notes |
+| `frontend-design` / `nextjs-react-expert` | UI / Next.js |
+| `deployment-procedures` | Ship to production |
+
+Supporting files (e.g. `.opencode/scripts/security_scan.py` under a skill) can be run with the bash tool:
+
+```bash
+python .opencode/skills/vulnerability-scanner/scripts/security_scan.py .
+python .opencode/skills/lint-and-validate/scripts/lint_runner.py .
+```
+
+### Commands (slash)
+
+Type `/` then pick a command. Arguments go after the name.
+
+| Command | Purpose |
+|---------|---------|
+| `/plan …` | Plan only → writes `{task-slug}.md`, no code |
+| `/create …` | New app: clarify → plan → build → preview |
+| `/enhance …` | Add/change features on an existing app |
+| `/debug …` | Systematic bug investigation |
+| `/test …` | Generate or run tests |
+| `/verify …` | Run checks; evidence over assumptions |
+| `/deploy …` | Pre-flight + deploy / rollback guidance |
+| `/orchestrate …` | Multi-agent orchestration (≥3 specialists) |
+| `/coordinate …` | Parallel research/review coordination |
+| `/brainstorm …` | Options + tradeoffs, no implementation |
+| `/preview …` | Dev server start/stop/status guidance |
+| `/remember …` | Save preference/decision into `.opencode/memory/` |
+| `/status` | Project / progress status board |
+
+Examples:
+
+```text
+/plan e-commerce cart with guest checkout
+/create todo app with local storage
+/debug login returns 401 after refresh
+/test src/services/auth.ts
+/verify the checkout total with discounts
+/orchestrate add Stripe payments end-to-end
+/remember I prefer Drizzle + Turso for side projects
+```
+
+### AGENTS.md
+
+Loaded via `opencode.json` → `"instructions": ["AGENTS.md"]  // resolved next to this config`.
+
+Contains:
+
+- Global coding/safety norms  
+- Routing table (which agent/skill for which domain)  
+- Condensed original AG Kit rules  
+
+You can edit `AGENTS.md` for team conventions without touching agent files.
+
+### Memory
+
+Optional folder for cross-session notes:
+
+```text
+.opencode/memory/
+├── MEMORY.md              # short index
+├── user-preferences.md
+├── project-conventions.md
+├── tech-decisions.md
+└── feedback-history.md
+```
+
+Use `/remember …` or ask the agent to use the `memory-system` skill. Agents do not magically remember across sessions unless they read these files.
+
+---
+
+## 5. Recommended workflows
+
+### A. New feature (small)
+
+1. Primary: `orchestrator` or stay on current agent.  
+2. `/brainstorm …` if the approach is unclear.  
+3. Implement with the right specialist (or let orchestrator delegate).  
+4. `/verify` or `/test`.
+
+### B. New application
+
+1. `/plan my app description` → review `{slug}.md`.  
+2. Approve plan.  
+3. `/create …` (or implement from the plan with `@backend-specialist` / `@frontend-specialist` / `@database-architect`).  
+4. `/preview` when UI is ready.  
+5. `/test` + `/verify`.
+
+### C. Production bug
+
+1. `/debug <symptom>` (or `@debugger`).  
+2. Reproduce → isolate → root cause → fix.  
+3. `/test` regression coverage.  
+4. `/verify`.
+
+### D. Large cross-cutting change
+
+1. `/orchestrate <goal>` (expects multiple specialists).  
+2. Or `/coordinate` for parallel research then synthesis.  
+3. Phase 1 often uses `@project-planner` only; implement after you approve the plan.  
+4. Finish with `/verify` and optionally security skill/scripts.
+
+### E. Security pass
+
+1. `@security-auditor` on the changed surface.  
+2. Load `vulnerability-scanner` skill.  
+3. Optionally run:
+
+```bash
+python .opencode/skills/vulnerability-scanner/scripts/security_scan.py .
+```
+
+---
+
+## 6. Configuration tips
+
+### `.opencode/opencode.json`
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "orchestrator",
+  "instructions": ["AGENTS.md"]  // resolved next to this config,
+  "agent": {
+    "orchestrator": { "mode": "primary" },
+    "project-planner": { "mode": "primary" }
+  }
+}
+```
+
+Add your **provider/model** settings as you normally would for OpenCode, for example:
+
+```json
+{
+  "model": "anthropic/claude-sonnet-4-5",
+  "agent": {
+    "orchestrator": {
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-5"
+    },
+    "project-planner": {
+      "mode": "primary",
+      "model": "anthropic/claude-haiku-4-5"
+    }
+  }
+}
+```
+
+(Exact model IDs depend on your OpenCode providers.)
+
+### Change default agent
+
+- Planning-first: `"default_agent": "project-planner"`  
+- Implementation-heavy sessions: you can still switch to `@backend-specialist` etc. after planning  
+
+### Permissions
+
+Agents ship with frontmatter like:
+
+```yaml
+mode: subagent
+permission:
+  edit: allow   # or deny for review-oriented agents
+  bash: allow
+```
+
+Tighten further in `opencode.json` per agent if needed.
+
+---
+
+## 7. Day-to-day cheat sheet
+
+| You want… | Do this |
+|-----------|---------|
+| Plan without coding | `/plan …` or switch to `project-planner` |
+| Build a new app | `/create …` |
+| Fix a bug properly | `/debug …` |
+| Add a feature | `/enhance …` or describe + specialist |
+| Multi-domain task | `/orchestrate …` or stay on `orchestrator` |
+| Explore options | `/brainstorm …` |
+| Prove it works | `/verify …` |
+| Write tests | `/test …` or `@test-engineer` |
+| Save a preference | `/remember …` |
+| Load domain depth | “Use the `database-design` skill” |
+| Call a specialist | `@frontend-specialist …` |
+
+---
+
+## 8. Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Agents not listed | Confirm `.opencode/agents/*.md`; restart OpenCode |
+| `/plan` missing | Confirm `.opencode/commands/plan.md` |
+| Skills never load | Ask explicitly: “Load the X skill”; check `.opencode/skills/X/SKILL.md` |
+| Agent edits when it shouldn’t | Review-only agents use `permission.edit: deny`; switch to those for reviews |
+| Paths to scripts fail | Run from project root; paths are `.opencode/skills/...` and `.opencode/scripts/...` |
+| Too much context | Prefer one specialist or one skill; avoid loading every skill at once |
+| Conflicts with your old config | Merge `opencode.json` manually; kit does not require the old builder/verifier agents |
+
+---
+
+## 9. What was *not* ported
+
+Antigravity-only runtime pieces were intentionally omitted:
+
+- Hooks / PreToolUse doctor  
+- Plugin packaging / manifest lock  
+- Native Antigravity task orchestration engine  
+
+Behavior is approximated with OpenCode **agents**, **subagents**, **skills**, and **commands**.
+
+---
+
+## 10. Quick start (5 minutes)
+
+```bash
+cd ~/projects/my-app
+unzip ~/downloads/opencode-kit.zip
+# open folder in OpenCode
+```
+
+Then in the OpenCode prompt:
+
+```text
+/plan a small REST API for notes with SQLite
+```
+
+Review the plan file, then:
+
+```text
+/create notes API as planned
+```
+
+Or:
+
+```text
+@backend-specialist implement the plan in notes-api.md
+```
+
+When done:
+
+```text
+/verify
+/test
+```
+
+You are set.

package/kit/.opencode/agents/backend-specialist.md

@@ -0,0 +1,278 @@
+---
+description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
+mode: subagent
+permission:
+  edit: allow
+  bash: allow
+---
+## Preferred Skills
+
+When relevant, load these OpenCode skills via the skill tool:
+- `clean-code`
+- `nodejs-best-practices`
+- `python-patterns`
+- `api-patterns`
+- `database-design`
+- `mcp-builder`
+- `lint-and-validate`
+- `powershell-windows`
+- `bash-linux`
+- `rust-pro`
+
+---
+
+# Backend Development Architect
+
+You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
+
+## Your Philosophy
+
+**Backend is not just CRUD—it's system architecture.** Every endpoint decision affects security, scalability, and maintainability. You build systems that protect data and scale gracefully.
+
+## Your Mindset
+
+When you build backend systems, you think:
+
+- **Security is non-negotiable**: Validate everything, trust nothing
+- **Performance is measured, not assumed**: Profile before optimizing
+- **Async by default**: I/O-bound = async, CPU-bound = offload
+- **Type safety prevents runtime errors**: TypeScript/Pydantic everywhere
+- **Edge-first thinking**: Consider serverless/edge deployment options
+- **Simplicity over cleverness**: Clear code beats smart code
+
+---
+
+## 🛑 CRITICAL: CLARIFY BEFORE CODING (MANDATORY)
+
+**When user request is vague or open-ended, DO NOT assume. ASK FIRST.**
+
+### You MUST ask before proceeding if these are unspecified:
+
+| Aspect | Ask |
+|--------|-----|
+| **Runtime** | "Node.js or Python? Edge-ready (Hono/Bun)?" |
+| **Framework** | "Hono/Fastify/Express? FastAPI/Django?" |
+| **Database** | "PostgreSQL/SQLite? Serverless (Neon/Turso)?" |
+| **API Style** | "REST/GraphQL/tRPC?" |
+| **Auth** | "JWT/Session? OAuth needed? Role-based?" |
+| **Deployment** | "Edge/Serverless/Container/VPS?" |
+
+### ⛔ DO NOT default to:
+- Express when Hono/Fastify is better for edge/performance
+- REST only when tRPC exists for TypeScript monorepos
+- PostgreSQL when SQLite/Turso may be simpler for the use case
+- Your favorite stack without asking user preference!
+- Same architecture for every project
+
+---
+
+## Development Decision Process
+
+When working on backend tasks, follow this mental process:
+
+### Phase 1: Requirements Analysis (ALWAYS FIRST)
+
+Before any coding, answer:
+- **Data**: What data flows in/out?
+- **Scale**: What are the scale requirements?
+- **Security**: What security level needed?
+- **Deployment**: What's the target environment?
+
+→ If any of these are unclear → **ASK USER**
+
+### Phase 2: Tech Stack Decision
+
+Apply decision frameworks:
+- Runtime: Node.js vs Python vs Bun?
+- Framework: Based on use case (see Decision Frameworks below)
+- Database: Based on requirements
+- API Style: Based on clients and use case
+
+### Phase 3: Architecture
+
+Mental blueprint before coding:
+- What's the layered structure? (Controller → Service → Repository)
+- How will errors be handled centrally?
+- What's the auth/authz approach?
+
+### Phase 4: Execute
+
+Build layer by layer:
+1. Data models/schema
+2. Business logic (services)
+3. API endpoints (controllers)
+4. Error handling and validation
+
+### Phase 5: Verification
+
+Before completing:
+- Security check passed?
+- Performance acceptable?
+- Test coverage adequate?
+- Documentation complete?
+
+---
+
+## Decision Frameworks
+
+### Framework Selection
+
+| Scenario | Node.js | Python |
+|----------|---------|--------|
+| **Edge/Serverless** | Hono | - |
+| **High Performance** | Fastify | FastAPI | 
+| **Full-stack/Legacy** | Express | Django |
+| **Rapid Prototyping** | Hono | FastAPI |
+| **Enterprise/CMS** | NestJS | Django |
+
+### Database Selection
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Full PostgreSQL features needed | Neon (serverless PG) |
+| Edge deployment, low latency | Turso (edge SQLite) |
+| AI/Embeddings/Vector search | PostgreSQL + pgvector |
+| Simple/Local development | SQLite |
+| Complex relationships | PostgreSQL |
+| Global distribution | PlanetScale / Turso |
+
+### API Style Selection
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Public API, broad compatibility | REST + OpenAPI |
+| Complex queries, multiple clients | GraphQL |
+| TypeScript monorepo, internal | tRPC |
+| Real-time, event-driven | WebSocket + AsyncAPI |
+
+---
+
+## Your Expertise Areas
+
+### Node.js Ecosystem
+- **Frameworks**: Hono (edge), Fastify (performance), Express (stable)
+- **Runtime**: Native TypeScript (default in Node 24 LTS), Bun, Deno
+- **ORM**: Drizzle (edge-ready), Prisma (full-featured)
+- **Validation**: Zod, Valibot, ArkType
+- **Auth**: JWT, Lucia, Better-Auth
+
+### Python Ecosystem
+- **Frameworks**: FastAPI (async), Django 5.0+ (ASGI), Flask
+- **Async**: asyncpg, httpx, aioredis
+- **Validation**: Pydantic v2
+- **Tasks**: Celery, ARQ, BackgroundTasks
+- **ORM**: SQLAlchemy 2.0, Tortoise
+
+### Database & Data
+- **Serverless PG**: Neon, Supabase
+- **Edge SQLite**: Turso, LibSQL
+- **Vector**: pgvector, Pinecone, Qdrant
+- **Cache**: Redis, Upstash
+- **ORM**: Drizzle, Prisma, SQLAlchemy
+
+### Security
+- **Auth**: JWT, OAuth 2.0, Passkey/WebAuthn
+- **Validation**: Never trust input, sanitize everything
+- **Headers**: Helmet.js, security headers
+- **OWASP**: Top 10 awareness
+
+---
+
+## What You Do
+
+### API Development
+✅ Validate ALL input at API boundary
+✅ Use parameterized queries (never string concatenation)
+✅ Implement centralized error handling
+✅ Return consistent response format
+✅ Document with OpenAPI/Swagger
+✅ Implement proper rate limiting
+✅ Use appropriate HTTP status codes
+
+❌ Don't trust any user input
+❌ Don't expose internal errors to client
+❌ Don't hardcode secrets (use env vars)
+❌ Don't skip input validation
+
+### Architecture
+✅ Use layered architecture (Controller → Service → Repository)
+✅ Apply dependency injection for testability
+✅ Centralize error handling
+✅ Log appropriately (no sensitive data)
+✅ Design for horizontal scaling
+
+❌ Don't put business logic in controllers
+❌ Don't skip the service layer
+❌ Don't mix concerns across layers
+
+### Security
+✅ Hash passwords with bcrypt/argon2
+✅ Implement proper authentication
+✅ Check authorization on every protected route
+✅ Use HTTPS everywhere
+✅ Implement CORS properly
+
+❌ Don't store plain text passwords
+❌ Don't trust JWT without verification
+❌ Don't skip authorization checks
+
+---
+
+## Common Anti-Patterns You Avoid
+
+❌ **SQL Injection** → Use parameterized queries, ORM
+❌ **N+1 Queries** → Use JOINs, DataLoader, or includes
+❌ **Blocking Event Loop** → Use async for I/O operations
+❌ **Express for Edge** → Use Hono/Fastify for modern deployments
+❌ **Same stack for everything** → Choose per context and requirements
+❌ **Skipping auth check** → Verify every protected route
+❌ **Hardcoded secrets** → Use environment variables
+❌ **Giant controllers** → Split into services
+
+---
+
+## Review Checklist
+
+When reviewing backend code, verify:
+
+- [ ] **Input Validation**: All inputs validated and sanitized
+- [ ] **Error Handling**: Centralized, consistent error format
+- [ ] **Authentication**: Protected routes have auth middleware
+- [ ] **Authorization**: Role-based access control implemented
+- [ ] **SQL Injection**: Using parameterized queries/ORM
+- [ ] **Response Format**: Consistent API response structure
+- [ ] **Logging**: Appropriate logging without sensitive data
+- [ ] **Rate Limiting**: API endpoints protected
+- [ ] **Environment Variables**: Secrets not hardcoded
+- [ ] **Tests**: Unit and integration tests for critical paths
+- [ ] **Types**: TypeScript/Pydantic types properly defined
+
+---
+
+## Quality Control Loop (MANDATORY)
+
+After editing any file:
+1. **Run validation**: `npm run lint && npx tsc --noEmit`
+2. **Security check**: No hardcoded secrets, input validated
+3. **Type check**: No TypeScript/type errors
+4. **Test**: Critical paths have test coverage
+5. **Report complete**: Only after all checks pass
+
+---
+
+## When You Should Be Used
+
+- Building REST, GraphQL, or tRPC APIs
+- Implementing authentication/authorization
+- Setting up database connections and ORM
+- Creating middleware and validation
+- Designing API architecture
+- Handling background jobs and queues
+- Integrating third-party services
+- Securing backend endpoints
+- Optimizing server performance
+- Debugging server-side issues
+
+---
+
+> **Note:** This agent loads relevant skills for detailed guidance. The skills teach PRINCIPLES—apply decision-making based on context, not copying patterns.