opencode-agent-kit 1.0.0

package/template/.opencode/rules/android/gradle.md

@@ -0,0 +1,62 @@
+# Android Gradle Rules
+
+## Version Catalog (libs.versions.toml)
+- Use TOML version catalog in `gradle/` directory
+- Group dependencies by category (compose, hilt, room, retrofit, testing)
+- Pin Compose BOM version; never pin individual Compose artifacts separately
+
+```toml
+[versions]
+compose-bom = "2025.01.00"
+hilt = "2.51"
+room = "2.6.1"
+kotlin = "2.0.21"
+
+[libraries]
+compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
+ui = { group = "androidx.compose.ui", name = "ui" }
+material3 = { group = "androidx.compose.material3", name = "material3" }
+hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
+hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }
+room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
+room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
+
+[plugins]
+android-application = { id = "com.android.application", version = "8.7.0" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+ksp = { id = "com.google.devtools.ksp", version = "2.0.21-1.0.27" }
+```
+
+## Build Variants
+- Use `debug` / `release` build types
+- Configure `applicationIdSuffix` for debug builds
+- Separate signing config for release
+- Enable R8/ProGuard for release builds
+
+## Core Dependencies
+```kotlin
+// compose-bom
+implementation(platform(libs.compose.bom))
+implementation(libs.ui)
+implementation(libs.material3)
+implementation(libs.navigation.compose)
+
+// DI
+implementation(libs.hilt.android)
+ksp(libs.hilt.compiler)
+
+// Room
+implementation(libs.room.runtime)
+ksp(libs.room.compiler)
+
+// Networking
+implementation(libs.retrofit)
+implementation(libs.okhttp)
+implementation(libs.gson)
+
+// Testing
+testImplementation(libs.junit)
+androidTestImplementation(libs.compose.ui.test)
+```

package/template/.opencode/rules/android/testing.md

@@ -0,0 +1,27 @@
+# Android Testing Rules
+
+## Unit Tests
+- Use JUnit 5 + MockK for ViewModel/UseCase/Repository tests
+- Each ViewModel must have a corresponding test file
+- Test Loading → Success → Error state transitions
+- Use `runTest` for coroutine-based ViewModels
+
+```kotlin
+@Test
+fun `loadProducts emits loading then success`() = runTest {
+    val viewModel = ProductViewModel(mockGetProductsUseCase)
+    assertEquals(UiState.Loading, viewModel.uiState.value)
+    // ... assertions
+}
+```
+
+## Compose UI Tests
+- Use `createComposeRule()` for Jetpack Compose tests
+- Test user interactions with `performClick()`, `performTextInput()`
+- Test accessibility with `semantics()` assertions
+- Use `onNodeWithText()`, `onNodeWithContentDescription()` for finding elements
+
+## Instrumentation Tests
+- Run on emulator or physical device via `./gradlew connectedAndroidTest`
+- Use Espresso for mixed Compose + XML layouts
+- Test navigation flows end-to-end

package/template/.opencode/rules/common/agents.md

@@ -0,0 +1,49 @@
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/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 |
+
+## 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
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker

package/template/.opencode/rules/common/coding-style.md

@@ -0,0 +1,48 @@
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## 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 hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

package/template/.opencode/rules/common/git-workflow.md

@@ -0,0 +1,45 @@
+# Git Workflow
+
+## Commit Message Format
+
+```
+<type>: <description>
+
+<optional body>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+Note: Attribution disabled globally via ~/.claude/settings.json.
+
+## 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

package/template/.opencode/rules/common/hooks.md

@@ -0,0 +1,30 @@
+# Hooks System
+
+## Hook Types
+
+- **PreToolUse**: Before tool execution (validation, parameter modification)
+- **PostToolUse**: After tool execution (auto-format, checks)
+- **Stop**: When session ends (final verification)
+
+## Auto-Accept Permissions
+
+Use with caution:
+- Enable for trusted, well-defined plans
+- Disable for exploratory work
+- Never use dangerously-skip-permissions flag
+- Configure `allowedTools` in `~/.claude.json` instead
+
+## TodoWrite Best Practices
+
+Use TodoWrite tool to:
+- Track progress on multi-step tasks
+- Verify understanding of instructions
+- Enable real-time steering
+- Show granular implementation steps
+
+Todo list reveals:
+- Out of order steps
+- Missing items
+- Extra unnecessary items
+- Wrong granularity
+- Misinterpreted requirements

package/template/.opencode/rules/common/patterns.md

@@ -0,0 +1,31 @@
+# Common Patterns
+
+## Skeleton Projects
+
+When implementing new functionality:
+1. Search for battle-tested skeleton projects
+2. Use parallel agents to evaluate options:
+   - Security assessment
+   - Extensibility analysis
+   - Relevance scoring
+   - Implementation planning
+3. Clone best match as foundation
+4. Iterate within proven structure
+
+## Design Patterns
+
+### Repository Pattern
+
+Encapsulate data access behind a consistent interface:
+- Define standard operations: findAll, findById, create, update, delete
+- Concrete implementations handle storage details (database, API, file, etc.)
+- Business logic depends on the abstract interface, not the storage mechanism
+- Enables easy swapping of data sources and simplifies testing with mocks
+
+### API Response Format
+
+Use a consistent envelope for all API responses:
+- Include a success/status indicator
+- Include the data payload (nullable on error)
+- Include an error message field (nullable on success)
+- Include metadata for paginated responses (total, page, limit)

package/template/.opencode/rules/common/performance.md

@@ -0,0 +1,55 @@
+# Performance Optimization
+
+## Model Selection Strategy
+
+**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
+- Lightweight agents with frequent invocation
+- Pair programming and code generation
+- Worker agents in multi-agent systems
+
+**Sonnet 4.5** (Best coding model):
+- Main development work
+- Orchestrating multi-agent workflows
+- Complex coding tasks
+
+**Opus 4.5** (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
+
+Lower context sensitivity tasks:
+- Single-file edits
+- Independent utility creation
+- Documentation updates
+- Simple bug fixes
+
+## Extended Thinking + Plan Mode
+
+Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.
+
+Control extended thinking via:
+- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)
+- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json`
+- **Budget cap**: `export MAX_THINKING_TOKENS=10000`
+- **Verbose mode**: Ctrl+O to see thinking output
+
+For complex tasks requiring deep reasoning:
+1. Ensure extended thinking is enabled (on by default)
+2. Enable **Plan Mode** for structured approach
+3. Use multiple critique rounds for thorough analysis
+4. Use split role sub-agents for diverse perspectives
+
+## Build Troubleshooting
+
+If build fails:
+1. Use **build-error-resolver** agent
+2. Analyze error messages
+3. Fix incrementally
+4. Verify after each fix

package/template/.opencode/rules/common/security.md

@@ -0,0 +1,29 @@
+# Security Guidelines
+
+## 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
+
+- NEVER hardcode secrets in source code
+- ALWAYS use environment variables or a secret manager
+- Validate that required secrets are present at startup
+- Rotate any secrets that may have been exposed
+
+## 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

package/template/.opencode/rules/common/testing.md

@@ -0,0 +1,29 @@
+# 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 (framework chosen per language)
+
+## 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)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first

package/template/.opencode/rules/flutter/state-management.md

@@ -0,0 +1,57 @@
+# Flutter State Management Rules
+
+## Choice of Approach
+
+| Approach | When to Use |
+|----------|------------|
+| Riverpod | Default for new projects; simpler API, no BuildContext needed |
+| Bloc | Complex apps requiring strict unidirectional data flow |
+| Provider | Legacy projects; not recommended for new apps |
+| ValueNotifier + ListenableBuilder | Trivial local widget state only |
+
+## Riverpod Patterns
+
+### Provider Scoping
+- Scoped providers via `family` modifier for parameterized repos
+- Use `autoDispose` for ephemeral state (forms, search results)
+- Use `keepAlive` for long-lived services (auth, API clients)
+
+```dart
+final productProvider = FutureProvider.family<Product, String>((ref, id) {
+  return ref.read(productRepositoryProvider).getProduct(id);
+});
+```
+
+### State Notifier
+- Extend `AsyncNotifier` for async state with loading/error/data
+- Use `Notifier` for synchronous state
+- Never emit error states manually — let `AsyncNotifier` handle exceptions via `.when()`
+
+## Bloc Patterns
+
+### Event Design
+- Use sealed classes for events with `const` constructors
+- Events carry only primitive/immutable data
+- One event per action type (avoid overloaded events with nullable fields)
+
+### State Design
+- Use sealed classes for states with `const` constructors
+- Include user-friendly error messages in error states
+- Never put mutable objects in state classes
+
+### Testing
+```dart
+blocTest<CounterBloc, int>(
+  'emits [1] when increment is added',
+  build: () => CounterBloc(),
+  act: (bloc) => bloc.add(Increment()),
+  expect: () => [1],
+);
+```
+
+## Anti-Patterns to Avoid
+- ❌ Storing BuildContext in state notifiers
+- ❌ Calling Provider.of/ref.watch outside widget tree
+- ❌ Mixing multiple state management libs in one project
+- ❌ Putting UI-only state (selected tab, text field focus) in global providers
+- ❌ Neglecting `autoDispose` / `close()` leading to memory leaks

package/template/.opencode/rules/flutter/testing.md

@@ -0,0 +1,42 @@
+# Flutter Testing Rules
+
+## Unit Tests
+- Test domain logic (entities, usecases, models) with pure Dart tests
+- Mock dependencies with `mocktail` or `mockito`
+- Test repository implementations with mocked datasources
+- Test Bloc events/states with `bloc_test`:
+```dart
+blocTest<ProductBloc, ProductState>(
+  'emits [Loading, Loaded] when products are fetched',
+  build: () => ProductBloc(mockRepo),
+  act: (bloc) => bloc.add(LoadProducts()),
+  expect: () => [ProductLoading(), ProductLoaded(products)],
+);
+```
+
+## Widget Tests
+- Use `WidgetTester` with `pumpWidget` and `pumpAndSettle`
+- Verify widget existence with `Finder`:
+  - `find.text('Title')` — by text
+  - `find.byType(ProductCard)` — by type
+  - `find.byKey(Key('product_card'))` — by key
+- Test loading, error, empty, and data states
+- Scroll with `scrollUntilVisible`, `drag`
+
+## Integration Tests
+- Use `integration_test` package for full app flows
+- Test critical user paths (login → browse → cart → checkout)
+- Run on emulators and physical devices
+
+## Golden Tests
+- Use `golden_toolkit` or `alchemist` for visual regression
+- Snapshot widgets at multiple screen sizes
+- Store goldens in `test/goldens/` directory
+
+## Command Reference
+```bash
+flutter test                          # Run all tests
+flutter test --coverage               # With coverage report
+flutter test test/widget/             # Widget tests only
+flutter test --name "product"         # Filter by name
+```

package/template/.opencode/rules/golang/coding-style.md

@@ -0,0 +1,26 @@
+# Go Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Go specific content.
+
+## Formatting
+
+- **gofmt** and **goimports** are mandatory — no style debates
+
+## Design Principles
+
+- Accept interfaces, return structs
+- Keep interfaces small (1-3 methods)
+
+## Error Handling
+
+Always wrap errors with context:
+
+```go
+if err != nil {
+    return fmt.Errorf("failed to create user: %w", err)
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go idioms and patterns.

package/template/.opencode/rules/golang/hooks.md

@@ -0,0 +1,11 @@
+# Go Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Go specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **gofmt/goimports**: Auto-format `.go` files after edit
+- **go vet**: Run static analysis after editing `.go` files
+- **staticcheck**: Run extended static checks on modified packages

package/template/.opencode/rules/golang/patterns.md

@@ -0,0 +1,39 @@
+# Go Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Go specific content.
+
+## Functional Options
+
+```go
+type Option func(*Server)
+
+func WithPort(port int) Option {
+    return func(s *Server) { s.port = port }
+}
+
+func NewServer(opts ...Option) *Server {
+    s := &Server{port: 8080}
+    for _, opt := range opts {
+        opt(s)
+    }
+    return s
+}
+```
+
+## Small Interfaces
+
+Define interfaces where they are used, not where they are implemented.
+
+## Dependency Injection
+
+Use constructor functions to inject dependencies:
+
+```go
+func NewUserService(repo UserRepository, logger Logger) *UserService {
+    return &UserService{repo: repo, logger: logger}
+}
+```
+
+## Reference
+
+See skill: `golang-patterns` for comprehensive Go patterns including concurrency, error handling, and package organization.

package/template/.opencode/rules/golang/security.md

@@ -0,0 +1,28 @@
+# Go Security
+
+> This file extends [common/security.md](../common/security.md) with Go specific content.
+
+## Secret Management
+
+```go
+apiKey := os.Getenv("OPENAI_API_KEY")
+if apiKey == "" {
+    log.Fatal("OPENAI_API_KEY not configured")
+}
+```
+
+## Security Scanning
+
+- Use **gosec** for static security analysis:
+  ```bash
+  gosec ./...
+  ```
+
+## Context & Timeouts
+
+Always use `context.Context` for timeout control:
+
+```go
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+```

package/template/.opencode/rules/golang/testing.md

@@ -0,0 +1,25 @@
+# Go Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Go specific content.
+
+## Framework
+
+Use the standard `go test` with **table-driven tests**.
+
+## Race Detection
+
+Always run with the `-race` flag:
+
+```bash
+go test -race ./...
+```
+
+## Coverage
+
+```bash
+go test -cover ./...
+```
+
+## Reference
+
+See skill: `golang-testing` for detailed Go testing patterns and helpers.

package/template/.opencode/rules/mobile/performance.md

@@ -0,0 +1,36 @@
+# Mobile Performance Rules
+
+## App Startup
+- Avoid synchronous initialization on main thread
+- Use `SplashScreen` (Android) / launch screen (iOS/Flutter) while warming cache
+- Lazy-initialize non-critical services
+- Profile startup with Android Studio Profiler / Flutter DevTools
+
+## Rendering Performance
+- Keep widget tree shallow — avoid unnecessary nesting
+- Use `const` constructors wherever possible
+- Wrap expensive widgets in `RepaintBoundary`
+- Use `ListView.builder` / `GridView.builder` for large lists
+- Avoid `Opacity` and `ClipRect` in scrollables — prefer `AnimatedOpacity` with `visible:`
+
+## Memory Management
+- Dispose controllers, streams, subscriptions in `dispose()`
+- Use `cached_network_image` for remote images
+- Clear `ImageCache` when memory warning received
+- Avoid retaining large Bitmaps in Activity/Fragment references
+- Use `WeakReference` for long-lived caches
+
+## Battery & Network
+- Batch network requests with `connectivity_plus` checks
+- Use `WorkManager` (Android) for deferrable background work
+- Compress images server-side; never resize large bitmaps on-device
+- Implement caching with `Room` (Android) / `Hive` (Flutter)
+- Use `ETag` / `If-Modified-Since` headers for HTTP caching
+
+## Tooling
+```bash
+flutter run --profile      # Profile mode with DevTools
+flutter run --release      # Release mode for final perf testing
+flutter build apk --split-per-abi   # Smaller APK per architecture
+./gradlew assembleRelease --stats   # Android build stats
+```