# 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