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)
451 lines (336 loc) • 12.3 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
---
## Coding Style
### Immutability (CRITICAL)
ALWAYS create new objects, NEVER mutate:
```javascript
// WRONG: Mutation
function updateUser(user, name) {
user.name = name // MUTATION!
return user
}
// CORRECT: Immutability
function updateUser(user, name) {
return {
...user,
name
}
}
```
### File Organization
MANY SMALL FILES > FEW LARGE FILES:
- High cohesion, low coupling
- 200-400 lines typical, 800 max
- Extract utilities from large components
- Organize by feature/domain, not by type
### Error Handling
ALWAYS handle errors comprehensively:
```typescript
try {
const result = await riskyOperation()
return result
} catch (error) {
console.error('Operation failed:', error)
throw new Error('Detailed user-friendly message')
}
```
### Input Validation
ALWAYS validate user input:
```typescript
import { z } from 'zod'
const schema = z.object({
email: z.string().email(),
age: z.number().int().min(0).max(150)
})
const validated = schema.parse(input)
```
### Code Quality Checklist
Before marking work complete:
- [ ] Code is readable and well-named
- [ ] Functions are small (<50 lines)
- [ ] Files are focused (<800 lines)
- [ ] No deep nesting (>4 levels)
- [ ] Proper error handling
- [ ] No console.log statements
- [ ] No hardcoded values
- [ ] No mutation (immutable patterns used)
---
## 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.
---
## 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.
## 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