opencode-agent-kit
Version:
Multi-stack OpenCode agent toolkit — 33+ specialized AI agents, 200+ skills, 46 commands, 8 MCP servers (Nuxt, React, Node.js, Laravel, CI3, Android, Flutter, DevOps, SEO, SonarQube, and more)
654 lines (471 loc) • 26 kB
Markdown
# Everything Claude Code - OpenCode Instructions
This document consolidates the core rules and guidelines from the Claude Code configuration for use with OpenCode.
## Security Guidelines (CRITICAL)
### Mandatory Security Checks
Before ANY commit:
- [ ] No hardcoded secrets (API keys, passwords, tokens)
- [ ] All user inputs validated
- [ ] SQL injection prevention (parameterized queries)
- [ ] XSS prevention (sanitized HTML)
- [ ] CSRF protection enabled
- [ ] Authentication/authorization verified
- [ ] Rate limiting on all endpoints
- [ ] Error messages don't leak sensitive data
### Secret Management
```typescript
// NEVER: Hardcoded secrets
const apiKey = 'sk-proj-xxxxx';
// ALWAYS: Environment variables
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
throw new Error('OPENAI_API_KEY not configured');
}
```
### Security Response Protocol
If security issue found:
1. STOP immediately
2. Use **security-reviewer** agent
3. Fix CRITICAL issues before continuing
4. Rotate any exposed secrets
5. Review entire codebase for similar issues
---
## DELEGATION TIERS (Hemat Token, Gak Semua Full Pipeline)
Tidak semua UI task perlu 3-phase pipeline. Gunakan tier yang tepat:
| Tier | Flow | Cocok Untuk |
| ------------- | --------------------------------------------------------------- | ------------------------------------ |
| **Fast** 🏃 | Leader → @frontend langsung | Typo, spacing, warna, icon swap |
| **Normal** ⚡ | Leader → @frontend + referensi DESIGN.md | Minor UI change (1-3 komponen) |
| **Full** 🏗️ | Leader → @designer → Leader → @frontend → Leader → @designer QA | New feature, redesign, design system |
## SHARED ARTIFACTS PATTERN (Critical — Hemat Ratusan Token)
**⚠️ KENAPA INI PENTING**: Setiap subagent berjalan di **isolated context**. Mereka TIDAK otomatis tahu hasil subagent sebelumnya. Satu-satunya jembatan adalah file.
**Jangan forward data besar di pesan delegasi.** Gunakan file sebagai shared contract:
| Artifact | Isi | Ditulis Oleh | Dibaca Oleh |
| ----------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | -------------------- |
| `DESIGN.md` | Design tokens, direction, component map | @designer | @frontend, @reviewer |
| `./specs/{feature}.md` | Per-component specs (layout, states, variants, color) | @designer | @frontend |
| `./api-contract.md` | API contract (endpoints, request/response, auth) | @leader / backend (node, ci3, laravel, java, go) | @frontend, @reviewer |
| `./specs/implementation-summary.md` | Komponen dibuat, file paths, state handling | @frontend (nuxt, react, flutter, android, angular) | @designer (QA) |
| `./specs/review-report.md` | Review findings + severity | @reviewer | @leader |
| `./specs/deployment-guide.md` | Deployment config, env vars, build commands | @devops | @leader |
| `./specs/seo-guide.md` | Meta tags, structured data, sitemap changes | @seo | @frontend |
| `prisma/schema.prisma` | Model definitions final | @database | @node-developer |
### POST-SUBAGENT VERIFICATION GATE (Leader Only)
**Setelah SETIAP subagent selesai, Leader WAJIB jalankan 4 langkah ini secara berurutan. JANGAN lanjut sebelum semua selesai:**
1. **IDENTIFIKASI** expected output files (lihat tabel di atas)
2. **VERIFIKASI & BACA FILE** — jalankan `ls <path>` untuk setiap file yang diharapkan. Jika file TIDAK ditemukan: STOP, eskalasi ke user
3. **BUAT RINGKASAN** (3-5 bullet) dari keputusan kunci
4. **SERTAKAN** di prompt delegasi: file reference + ringkasan + instruksi "JANGAN minta Leader untuk forward konten"
### Aturan Shared Artifacts (WAJIB dipatuhi SEMUA agent)
1. **Producer** (designer, backend, database, dll): Setelah selesai, **TULIS output ke file** (jangan cuma return di message)
2. **Consumer** (frontend, reviewer, dll): Sebelum mulai, **BACA file** yang ditulis subagent sebelumnya. **JANGAN minta Leader untuk forward konten** — baca langsung dari file.
3. Jika file yang diharapkan tidak ditemukan: **STOP & return ke @leader** dengan pesan "File {path} tidak ditemukan — saya tidak bisa {alasan} tanpa file ini"
4. Leader: **WAJIB** menjalankan Post-Subagent Verification Gate setiap kali subagent selesai
### Prinsip: Deteksi Stuck, Bukan Batasi Iterasi
Task besar MEMBUTUHKAN banyak iterasi. Jangan batasi jumlah iterasi — batasi hanya ketika **tidak ada progress**.
### Stuck Detection: Same-Result Rule
Jika agent menerima **hasil/output yang SAMA PERSIS** dari subagent 2 kali berturut-turut:
1. STOP re-delegating (subagent stuck, ngulang hasil sama)
2. Dokumentasikan apa yang sama
3. Eskalasi ke user
### Kapan BUKAN Stuck (LANJUTKAN)
- Subagent menghasilkan kode berbeda setiap kali → ✅ progress
- Bug fix butuh banyak percobaan dengan pendekatan berbeda → ✅ progress
- Task besar dengan banyak delegasi → ✅ progress
- Pipeline UI bolak-balik Phase 2↔Phase 3 dengan perbaikan nyata → ✅ progress
---
## Quality Gate Checklist (ALL AGENTS — MANDATORY)
Before ANY agent marks work as `verified`, this checklist MUST pass:
### Mandatory Checks
- [ ] **Type check passes** (run `npx tsc --noEmit`, `dart analyze`, or equivalent)
- [ ] **No console.log/print() statements** in changed files
- [ ] **No unused imports** in changed files
- [ ] **Loading/error/empty states handled** for all data-dependent components
- [ ] **No hardcoded values** that should be config/props/constants
- [ ] **Immutability preserved** — no mutation of objects/arrays
- [ ] **Error handling in place** — try/catch or proper error boundaries
- [ ] **Verification status reported**: `verified` / `partially_verified` / `not_verified`
### Verification Commands by Stack
| Stack | Minimum Verification | Full Verification |
| ----------------- | ------------------------------- | ------------------------------------------------------- |
| **Nuxt/Vue** | `npx nuxi typecheck` | `npx nuxi typecheck` + `npm run lint` + `npm run build` |
| **React/Next.js** | `npx tsc --noEmit` | `npx tsc --noEmit` + `npm run lint` + `npm run build` |
| **Flutter/Dart** | `flutter analyze` | `flutter analyze` + `flutter test` |
| **Node.js** | `npx tsc --noEmit` | `npx tsc --noEmit` + `npm run test` |
| **Angular** | `ng lint` | `ng lint` + `ng test --watch=false` + `ng build` |
| **Python** | `ruff check .` or `pylint` | `ruff check .` + `mypy .` + `pytest` |
| **Rust** | `cargo check` | `cargo check` + `cargo clippy` + `cargo test` |
| **Go** | `go build ./...` | `go build ./...` + `go vet ./...` + `go test ./...` |
| **Java/Spring** | `mvn compile` or `gradle build` | `mvn verify` or `gradle check` |
### Quality Enforcement Rules
1. **Must run minimum verification** before reporting `verified`
2. **If verification fails**, fix errors before reporting
3. **If verification cannot run** (missing config/tools), report as `partially_verified` with exact commands for manual verification
4. **Never skip verification** just because it's "a small change"
5. **Code review gate**: For medium+ changes, delegasikan ke `@code-reviewer` atau `@reviewer` sebelum final delivery
---
## UNIFIED CODING STANDARDS (ALL STACKS)
### Core Rules (Always Apply)
1. **Immutability**: ALWAYS create new objects, NEVER mutate
2. **Small files**: 200-400 lines typical, 800 max
3. **Small functions**: < 50 lines per function
4. **No deep nesting**: Max 4 levels of indentation
5. **Error handling**: Every operation that can fail MUST have error handling
6. **Input validation**: ALL user inputs validated (Zod, Joi, or equivalent)
7. **No hardcoded secrets**: Always use environment variables
8. **No console.log in production**: Search and remove before marking done
### Framework-Specific Rules
#### Nuxt/Vue
- Use `<script setup lang="ts">` always
- Use `useApi` composable for all API calls
- Prefer Nuxt UI components over custom HTML
- App directory structure (Nuxt 4)
#### React/Next.js
- Use TypeScript `interface` for props
- Server Components by default, `'use client'` only when needed
- Use shadcn/ui components over custom implementations
- App Router structure
#### Flutter/Dart
- Use `final` by default, `var` only when type is obvious
- Follow Clean Architecture (data/domain/presentation)
- Prefer Riverpod or Bloc for state management
- Use GoRouter for navigation
#### Node.js/Express
- `*.dto.ts`, `*.controller.ts`, `*.route.ts`, `*.middleware.ts` naming convention
- Use Prisma for database access
- JWT for authentication, stored in httpOnly cookies
- Zod or Joi for input validation
---
## Testing Requirements
### Minimum Test Coverage: 80%
Test Types (ALL required):
1. **Unit Tests** - Individual functions, utilities, components
2. **Integration Tests** - API endpoints, database operations
3. **E2E Tests** - Critical user flows (Playwright)
### Test-Driven Development
MANDATORY workflow:
1. Write test first (RED)
2. Run test - it should FAIL
3. Write minimal implementation (GREEN)
4. Run test - it should PASS
5. Refactor (IMPROVE)
6. Verify coverage (80%+)
### Troubleshooting Test Failures
1. Use **tdd-guide** agent
2. Check test isolation
3. Verify mocks are correct
4. Fix implementation, not tests (unless tests are wrong)
---
## Git Workflow
### Commit Message Format
```
<type>: <description>
<optional body>
```
Types: feat, fix, refactor, docs, test, chore, perf, ci
### Pull Request Workflow
When creating PRs:
1. Analyze full commit history (not just latest commit)
2. Use `git diff [base-branch]...HEAD` to see all changes
3. Draft comprehensive PR summary
4. Include test plan with TODOs
5. Push with `-u` flag if new branch
### Feature Implementation Workflow
1. **Plan First**
- Use **planner** agent to create implementation plan
- Identify dependencies and risks
- Break down into phases
2. **TDD Approach**
- Use **tdd-guide** agent
- Write tests first (RED)
- Implement to pass tests (GREEN)
- Refactor (IMPROVE)
- Verify 80%+ coverage
3. **Code Review**
- Use **code-reviewer** agent immediately after writing code
- Address CRITICAL and HIGH issues
- Fix MEDIUM issues when possible
4. **Commit & Push**
- Detailed commit messages
- Follow conventional commits format
---
## Agent Orchestration
### Available Agents
| Agent | Purpose | When to Use |
| -------------------- | ----------------------- | ----------------------------- |
| planner | Implementation planning | Complex features, refactoring |
| architect | System design | Architectural decisions |
| tdd-guide | Test-driven development | New features, bug fixes |
| code-reviewer | Code review | After writing code |
| security-reviewer | Security analysis | Before commits |
| build-error-resolver | Fix build errors | When build fails |
| e2e-runner | E2E testing | Critical user flows |
| refactor-cleaner | Dead code cleanup | Code maintenance |
| doc-updater | Documentation | Updating docs |
| go-reviewer | Go code review | Go projects |
| go-build-resolver | Go build errors | Go build failures |
| database-reviewer | Database optimization | SQL, schema design |
### Immediate Agent Usage
No user prompt needed:
1. Complex feature requests - Use **planner** agent
2. Code just written/modified - Use **code-reviewer** agent
3. Bug fix or new feature - Use **tdd-guide** agent
4. Architectural decision - Use **architect** agent
---
## Performance Optimization
### Model Selection Strategy
**Haiku** (90% of Sonnet capability, 3x cost savings):
- Lightweight agents with frequent invocation
- Pair programming and code generation
- Worker agents in multi-agent systems
**Sonnet** (Best coding model):
- Main development work
- Orchestrating multi-agent workflows
- Complex coding tasks
**Opus** (Deepest reasoning):
- Complex architectural decisions
- Maximum reasoning requirements
- Research and analysis tasks
### Context Window Management
Avoid last 20% of context window for:
- Large-scale refactoring
- Feature implementation spanning multiple files
- Debugging complex interactions
### Build Troubleshooting
If build fails:
1. Use **build-error-resolver** agent
2. Analyze error messages
3. Fix incrementally
4. Verify after each fix
---
## Common Patterns
### API Response Format
```typescript
interface ApiResponse<T> {
success: boolean;
data?: T;
error?: string;
meta?: {
total: number;
page: number;
limit: number;
};
}
```
### Composable Pattern (Vue/Nuxt)
```typescript
export function useDebounce<T>(value: Ref<T>, delay: number): Readonly<Ref<T>> {
const debouncedValue = ref<T>(value.value) as Ref<T>;
watch(value, () => {
const handler = setTimeout(() => {
debouncedValue.value = value.value;
}, delay);
onScopeDispose(() => clearTimeout(handler));
});
return readonly(debouncedValue);
}
```
### Repository Pattern
```typescript
interface Repository<T> {
findAll(filters?: Filters): Promise<T[]>;
findById(id: string): Promise<T | null>;
create(data: CreateDto): Promise<T>;
update(id: string, data: UpdateDto): Promise<T>;
delete(id: string): Promise<void>;
}
```
---
## OpenCode-Specific Notes
Since OpenCode does not support hooks, the following actions that were automated in Claude Code must be done manually:
### After Writing/Editing Code
- Run `prettier --write <file>` to format JS/TS files
- Run `npx tsc --noEmit` to check for TypeScript errors
- Check for console.log statements and remove them
### Before Committing
- Run security checks manually
- Verify no secrets in code
- Run full test suite
### Commands Available
Use these commands in OpenCode:
- `/plan` - Create implementation plan
- `/tdd` - Enforce TDD workflow
- `/code-review` - Review code changes
- `/security` - Run security review
- `/build-fix` - Fix build errors
- `/e2e` - Generate E2E tests
- `/refactor-clean` - Remove dead code
- `/orchestrate` - Multi-agent workflow
---
## Mobile Development
### Android (Kotlin / Jetpack Compose)
**Default Stack:**
- Kotlin, Jetpack Compose, Material Design 3, XML, Gradle KTS (version catalog)
- Hilt for DI, Room for local DB, Retrofit + OkHttp for networking
- Jetpack Navigation Compose, WorkManager
**Build Commands:**
```bash
./gradlew assembleDebug # Debug build
./gradlew assembleRelease # Release APK
./gradlew bundleRelease # Play Store AAB
./gradlew test # Unit tests
./gradlew connectedAndroidTest # Instrumented tests
```
**Play Store Publishing (via GPC):**
1. `gpc preflight <aab>` — Compliance check
2. `gpc publish --track internal` — Upload to internal track
3. `gpc release promote --from internal --to production` — Promote
### Flutter (Dart / Flutter SDK)
**Default Stack:**
- Dart, Flutter SDK, Material Design 3, Cupertino
- Bloc or Riverpod for state management
- GoRouter for routing, Dio for networking
- Hive/Isar/Drift for local storage
**Build Commands:**
```bash
flutter pub get # Install dependencies
flutter build apk # Android APK
flutter build appbundle # Android AAB
flutter build ios # iOS
flutter test # Run tests (unit + widget)
flutter test --coverage # With coverage
flutter analyze # Static analysis
```
**Testing Strategy:**
1. Unit tests — Domain logic, entities, usecases (flutter_test, mocktail)
2. Widget tests — UI components, states, interactions (WidgetTester)
3. Integration tests — Full user flows (integration_test package)
4. Golden tests — Visual regression (golden_toolkit, alchemist)
---
## Agentmemory: Persistent Cross-Session Memory
agentmemory provides persistent memory for all agents. It captures session history, saves decisions/insights, and injects relevant context from past sessions into the current session.
### Prerequisites
```bash
npm install -g @agentmemory/agentmemory # Install globally
agentmemory # Start server on :3111
```
### MCP Tools (53 tools)
All agents have access to agentmemory MCP tools prefixed with `agentmemory_memory_`:
| Tool | Purpose |
| -------------------------- | ------------------------------------------------------- |
| `memory_save` | Save insights, decisions, facts to long-term memory |
| `memory_recall` | Search past observations by keywords |
| `memory_smart_search` | Hybrid semantic+keyword search for conceptual queries |
| `memory_sessions` | List recent sessions with status and observation counts |
| `memory_file_history` | Get past observations about specific files |
| `memory_lesson_save` | Save a lesson learned with confidence scoring |
| `memory_lesson_recall` | Search lessons by query, sorted by confidence |
| `memory_governance_delete` | Delete specific memories (requires confirmation) |
| `memory_patterns` | Detect recurring patterns across sessions |
| `memory_consolidate` | Run 4-tier memory consolidation pipeline |
### Available Commands
- `/recall [query]` — Search past observations and lessons
- `/remember [text]` — Explicitly save an insight to long-term memory
### Auto-Capture Plugin
The `agentmemory-capture.ts` plugin (registered in `opencode.json`) captures 22 lifecycle events automatically:
- Session lifecycle: created, idle, compacted, updated, deleted, error
- Messages & prompts: user messages, assistant responses, removed messages
- Parts & steps: subagent starts, tool calls, reasoning, step-finish, patches, compaction events
- File enrichment: auto-injects file-specific context into system prompt
- Permissions: captures permission prompts and replies
- Tasks & commands: captures todo changes and command execution
### Skills
The `agentmemory` skill (`.opencode/skills/agentmemory/SKILL.md`) teaches agents when and how to use the memory tools effectively.
### Memory Workflow
The `agent-memory-workflow` skill (`.opencode/skills/agent-memory-workflow/SKILL.md`) provides disciplined protocols:
- **Session Start Ritual**: Mandatory memory recall before any productive work
- **Session End Ritual**: Structured save before session ends or compacts
- **Auto-Save Triggers**: When to save mid-session without waiting
- **Memory Audit**: Periodic hygiene and deduplication
- **Cross-Agent Memory**: Subagents don't write memory directly — IT Leader mediates
### Delegation Contracts
The `agent-delegation-contract` skill (`.opencode/skills/agent-delegation-contract/SKILL.md`) provides:
- **Standard Contract Template**: Structured brief with scope, input interface, output contract
- **Subagent Response Contract**: Mandatory result format including verification status
- **Chain vs Parallel Rules**: When to sequence vs parallelise delegations
- **Contract Violation Protocol**: How to handle out-of-scope work
### Progress Tracking
The `progress-tracking` skill (`.opencode/skills/progress-tracking/SKILL.md`) provides:
- **Task Lifecycle**: BACKLOG → TODO → IN_PROGRESS → REVIEW → DONE
- **Task ID Convention**: Hierarchical IDs (FE-001, BE-002) for cross-reference
- **Visual Progress Reports**: Tables with status emojis for user communication
- **Cross-Agent Protocol**: IT Leader maintains master list; subagents report results
- **Session Handoff**: How to recover task state after `/reset` or new session
---
## opencode-agent-kit Version Check
If `.opencode/.kit-version` exists, your agent toolkit has a recorded installed version.
**At session start**, check for updates:
1. Read `.opencode/.kit-version` to get the installed version
2. Run `npm view opencode-agent-kit version` to get the latest
3. If latest > installed, notify the user with the update command
This applies to IT-Leader (primary) and frontend/backend subagents when called directly.
### Global Install
The `global-install` skill (`.opencode/skills/global-install/SKILL.md`) documents the global installation approach. On macOS, OpenCode auto-discovers the global config at `~/.config/opencode/opencode.jsonc`. If the kit was installed globally, note that:
- Skills, prompts, commands, and instructions are stored flat in `~/.config/opencode/`
- `opencode.jsonc` is merged with your existing config (providers, MCP, etc.)
- No per-project `.opencode/` is needed — OpenCode reads the global config automatically
- To update: run `opencode-agent-kit global update`
- To install per-project: run `opencode-agent-kit init --local`
## UI Development Pipeline
This project uses a **3-phase UI Development Pipeline** for ALL UI-related tasks. Every agent involved in UI work must follow this protocol.
### The 3 Phases
```
PHASE 1 — DESIGN (@designer)
│ Load `impeccable` skill (mandatory step 0)
│ Use: /impeccable init, /impeccable shape, /impeccable critique
│ Define: tokens, DESIGN.md, specs, states, a11y requirements
│ Handoff to @frontend-nuxt / @frontend-react
▼
PHASE 2 — IMPLEMENT (@frontend)
│ Implement from design specs
│ MUST run Impeccable Polish Gate before done:
│ /impeccable critique + /impeccable audit + /impeccable polish
│ Extended: /impeccable harden, adapt, optimize, clarify, onboard, live
│ Handoff to @designer for Phase 3 QA
▼
PHASE 3 — DESIGN QA (@designer)
│ /impeccable critique on live result
│ Verify: tokens, a11y, states, responsive, copy
│ Report: PASS ✅ → done | FAIL ❌ → back to Phase 2
```
### Available Slash Commands
All Impeccable commands are available as OpenCode slash commands:
| Command | Shortcut | Purpose |
| ----------------------- | ------------ | ----------------------------- |
| `/impeccable` | — | Main entry (23 subcommands) |
| `/impeccable critique` | `/critique` | Full design review |
| `/impeccable audit` | `/audit` | a11y, perf, responsive checks |
| `/impeccable polish` | `/polish` | Final quality pass |
| `/impeccable craft` | `/craft` | End-to-end design + build |
| `/impeccable shape` | `/shape` | UX planning |
| `/impeccable init` | `/init` | Setup context files |
| `/impeccable live` | `/live` | Browser iteration |
| `/impeccable document` | `/document` | Generate DESIGN.md |
| `/impeccable extract` | `/extract` | Pull tokens |
| `/impeccable harden` | `/harden` | Edge cases |
| `/impeccable layout` | `/layout` | Spacing/rhythm |
| `/impeccable typeset` | `/typeset` | Typography |
| `/impeccable colorize` | `/colorize` | Color |
| `/impeccable animate` | `/animate` | Motion |
| `/impeccable distill` | `/distill` | Simplify |
| `/impeccable clarify` | `/clarify` | UX copy |
| `/impeccable adapt` | `/adapt` | Responsive |
| `/impeccable bolder` | `/bolder` | Amplify |
| `/impeccable quieter` | `/quieter` | Tone down |
| `/impeccable delight` | `/delight` | Personality |
| `/impeccable overdrive` | `/overdrive` | Push limits |
| `/impeccable optimize` | `/optimize` | Performance |
| `/impeccable onboard` | `/onboard` | Empty states |
| `/impeccable hooks` | `/hooks` | Hook management |
### Rules for All Agents
1. **UI task → delegate to @designer** (never do design work yourself)
2. **Design before code** — no frontend implementation without design specs
3. **Polish gate is mandatory** — frontend must run critique + audit + polish before done
4. **Design QA is mandatory** — designer must verify implementation before final
5. **All 23 commands available** — use the right command for the right task
## Success Metrics
You are successful when:
- All tests pass (80%+ coverage)
- No security vulnerabilities
- Code is readable and maintainable
- Performance is acceptable
- User requirements are met