A production-aware OpenCode configuration for planning, building, debugging, testing, and releasing mobile applications.
This repository adds a structured agent workflow for React Native, Expo, iOS, and Android projects. It includes:
- 4 primary agents for planning, implementation, and debugging
- 12 specialist subagents for architecture, platforms, quality, and releases
- 8 reusable slash commands for common mobile development workflows
- 29 skills covering mobile frameworks, features, security, QA, and stores
- Permission rules that gate edits, builds, credentials, uploads, and destructive operations
The configuration assists with engineering work. It does not automatically publish applications or bypass review of production-sensitive operations.
- Prerequisites
- Install OpenCode
- Install This Configuration
- Verify the Setup
- How It Works
- Commands
- Agents
- Skills
- App Development Flows
- Permission Model
- Update the Configuration
- Troubleshooting
- Remove the Configuration
- macOS, Linux, or WSL
- Git
- An OpenCode-compatible AI provider account
- A mobile project, preferably React Native or Expo, for using the mobile flows
- Node.js only when installing OpenCode through npm, pnpm, Yarn, or Bun
Platform tools such as Xcode, Android Studio, CocoaPods, and EAS CLI are only required when the target project needs them.
Install the latest OpenCode release using one of the official methods.
Recommended for macOS and Linux:
brew install anomalyco/tap/opencodenpm install -g opencode-ai@latestOther supported package managers are documented in the OpenCode installation guide.
Authenticate with your preferred model provider:
opencode auth login
opencode auth listOpenCode stores provider credentials locally. Do not add API keys, provider tokens, signing credentials, or store credentials to this repository.
Choose one installation method. The isolated method is recommended because it does not replace an existing global OpenCode configuration.
Clone the repository to a stable location:
mkdir -p "$HOME/Developer"
git clone https://github.com/Tutorials-Dojo/opencode-configs.git "$HOME/Developer/opencode-configs"Start OpenCode with this configuration:
export OPENCODE_CONFIG_DIR="$HOME/Developer/opencode-configs"
cd /path/to/your/mobile-app
opencodeAdd the OPENCODE_CONFIG_DIR export to ~/.zshrc, ~/.bashrc, or the
equivalent shell profile if this configuration should load in every new shell.
This option can coexist with ~/.config/opencode. OpenCode loads the custom
directory after its normal global and project configuration directories, so
the custom directory can override settings with the same names.
Use this method only when ~/.config/opencode does not already exist or after
you have intentionally backed up its contents.
Clone the repository:
mkdir -p "$HOME/Developer"
git clone https://github.com/Tutorials-Dojo/opencode-configs.git "$HOME/Developer/opencode-configs"Check for an existing global configuration before creating the link:
ls -la "$HOME/.config/opencode"If the path does not exist, create the global symlink:
mkdir -p "$HOME/.config"
ln -s "$HOME/Developer/opencode-configs" "$HOME/.config/opencode"Do not overwrite or merge an existing global configuration without reviewing its agents, commands, skills, plugins, and permission rules. Use Option 1 when an existing configuration must remain intact.
After changing opencode.json, an agent, a command, or a skill, quit and
restart OpenCode. Configuration files are loaded when OpenCode starts and are
not hot-reloaded into an existing session.
-
Confirm OpenCode is installed and authenticated:
opencode --version opencode auth list
-
Open a React Native or Expo project:
cd /path/to/your/mobile-app opencode -
Type
/in the TUI and confirm commands such as/mega-plan,/plan-feature, and/build-featureappear. -
Run a read-only smoke test:
/plan-feature Add an offline indicator to the home screen. -
Confirm a specialist can be addressed directly:
@tester Create a manual QA checklist for the login flow. Do not edit files.
The default agent is plan, so a new session starts with read-only planning
behavior unless a command or explicit agent selection uses another agent.
The repository follows OpenCode's global/custom configuration layout:
opencode-configs/
|-- opencode.json # Defaults, permissions, watcher ignores, and tool limits
|-- agents/ # Primary agents and specialist subagents
|-- commands/ # Slash-command workflow templates
`-- skills/ # Mobile development knowledge and checklists
The layers have separate responsibilities:
| Layer | Responsibility |
|---|---|
opencode.json |
Selects the default agent and defines shared permissions and limits. |
| Primary agents | Own complete planning, building, or debugging conversations. |
| Specialist agents | Review or handle focused architecture, platform, quality, and release tasks. |
| Commands | Route repeatable requests to the correct agent with a predefined workflow. |
| Skills | Supply task-specific mobile conventions and checklists. |
Use slash commands for the common workflows documented below. Address a
specialist manually with an @ mention when a focused review is needed:
@security-reviewer Review token storage and sensitive logging. Do not edit files.
Arguments written after a command replace the command template's $ARGUMENTS
placeholder.
| Command | Agent | Purpose | Example |
|---|---|---|---|
/mega-plan |
mega-plan |
Create a complete MVP, architecture, app-flow, and phased delivery roadmap. | /mega-plan Build an Expo meal-planning app with auth, offline grocery lists, and reminders. |
/plan-feature |
plan |
Inspect the project and plan one focused feature without editing files. | /plan-feature Add email login with session restore and protected routes. |
/build-feature |
build |
Implement a feature in small, reviewable patches and verify it. | /build-feature Implement the approved authentication plan. |
/debug-mobile |
debugger |
Diagnose runtime, Expo, Metro, EAS, Xcode, Gradle, simulator, emulator, or crash issues. | /debug-mobile Android release build fails with the following Gradle error: ... |
/polish-ui |
ui-polisher |
Improve usability, accessibility, layout, states, and native platform feel. | /polish-ui Improve the checkout screen keyboard behavior and error states. |
/predeploy-mobile |
release-manager |
Evaluate final startup, auth, flow, permission, offline, security, version, IAP, analytics, and QA gates. | /predeploy-mobile Review version 1.0 before external beta testing. |
/release-ios |
release-manager |
Check EAS, TestFlight, App Store Connect, privacy, IAP, and iOS QA readiness. | /release-ios Prepare version 1.0 for TestFlight review. |
/release-android |
release-manager |
Check EAS, AAB, Play Console, Data Safety, IAP, and Android QA readiness. | /release-android Prepare version 1.0 for the internal testing track. |
Commands that reference release work perform readiness checks by default. Release builds, uploads, signing changes, credential operations, and store changes still require explicit approval.
Primary agents can own the complete user interaction. Commands automatically
select their configured agent. In the TUI, use Tab to cycle through primary
agents manually.
| Agent | Access | Use it for |
|---|---|---|
plan |
Read-only | Planning one feature, identifying affected files, edge cases, and verification steps. This is the default agent. |
mega-plan |
Read-only | MVP scoping, architecture, user flows, API/data needs, phased roadmaps, and release planning. |
build |
Edit-enabled | Implementing safe, focused mobile changes with tests or practical verification. |
debugger |
Approval-gated edits | Evidence-based diagnosis and targeted fixes for runtime, build, native, and dependency failures. |
Specialists can be selected by a primary agent or invoked manually with
@agent-name.
| Agent | Specialty |
|---|---|
mobile-architect |
App structure, navigation, state, data flow, API boundaries, and offline-first design. |
react-native-specialist |
Components, screens, hooks, navigation, platform behavior, and native-module-aware logic. |
expo-specialist |
Expo SDK, Expo Router, config plugins, permissions, development builds, and prebuild decisions. |
eas-build-specialist |
EAS profiles, credentials, TestFlight, AAB/APK output, versioning, and build failures. |
ios-specialist |
Xcode, CocoaPods, signing, provisioning, StoreKit, permissions, and App Store concerns. |
android-specialist |
Gradle, AndroidManifest, package configuration, Firebase, permissions, and Play concerns. |
api-integrator |
Typed API clients, auth headers, environment URLs, retries, caching, and offline/error states. |
ui-polisher |
Layout, typography, safe areas, accessibility, dark mode, responsive states, and native feel. |
tester |
Unit/integration strategy, manual regression, device matrices, and release validation. |
security-reviewer |
Secure storage, token handling, permissions, secrets, logs, local data, and privacy risks. |
performance-reviewer |
Startup, rendering, memory, bundle size, lists, images, animations, caching, and crash prevention. |
release-manager |
Store readiness, versions, metadata, privacy forms, IAP, QA gates, rollout, and rollback planning. |
Examples:
@mobile-architect Review whether this sync feature belongs in the existing data layer.
@performance-reviewer Review this product list for unnecessary renders and image-memory risk.
Skills are loaded according to the task rather than all at once.
| Category | Included skills |
|---|---|
| Planning and implementation | mega-plan, feature-plan, mobile-build, mobile-debug |
| Framework and navigation | react-native, expo, expo-router, react-navigation, react-native-ui, mobile-state-management |
| Data and app services | mobile-api, mobile-auth, mobile-storage, mobile-offline-sync, mobile-notifications |
| Device capabilities | mobile-permissions, mobile-camera-ocr, mobile-voice-audio, react-native-native-modules |
| Native platforms and builds | ios-native, android-native, eas-build |
| Quality and production | mobile-testing-qa, mobile-performance, mobile-crash-analytics, security-privacy |
| Commerce and stores | mobile-payments-iap, app-store-connect, google-play-console |
The following flows show how to combine commands and specialist agents. They are starting points; OpenCode still inspects the current project and preserves its established framework, architecture, and style.
Start with product and architecture planning:
/mega-plan Build an Expo meal-planning app with email authentication, recipe search, offline grocery lists, push reminders, and a subscription tier.
The mega-plan agent can consult architecture, security, performance, and QA
specialists while remaining read-only. Use its phases to select the smallest
working feature, then continue with the feature loop:
/plan-feature Add email authentication with secure session restore and protected routes.
/build-feature Implement the approved email authentication plan.
@tester Create an iOS and Android regression checklist for authentication and session restore.
Repeat the plan, build, and test sequence for each roadmap slice rather than asking one agent to generate the entire application in a single change.
Recommended flow:
/plan-feature Add OAuth login, token refresh, logout, and session restore. Tokens must use secure storage.
@api-integrator Review the planned OAuth exchange, refresh behavior, and API error handling.
/build-feature Implement the reviewed OAuth and session-management plan.
@security-reviewer Review token storage, redirect handling, logout cleanup, logs, and privacy risks. Report findings before editing.
@tester Test success, cancellation, expired tokens, refresh failure, offline startup, logout, and app relaunch on iOS and Android.
This flow separates implementation from security and QA review while keeping the same project conventions.
Plan permission, native-module, privacy, and device constraints first:
/plan-feature Add receipt scanning with camera capture, image confirmation, OCR correction, and permission-denied UX.
Ask the relevant platform specialist to verify Expo compatibility:
@expo-specialist Determine whether this feature works in Expo Go or requires a development build and config plugin.
Implement and validate on physical devices:
/build-feature Implement the approved receipt-scanning feature without changing native identifiers.
@tester Create a real-device matrix covering permission states, poor images, large images, cancellation, backgrounding, and OCR failure.
/plan-feature Add offline-first task creation with queued writes, retry status, conflict handling, and reconnect synchronization.
@api-integrator Review request idempotency, retry policy, cache invalidation, environment URLs, and typed error handling.
/build-feature Implement the approved offline task synchronization plan.
@performance-reviewer Review queue growth, render frequency, storage usage, and synchronization work on the main thread.
@tester Test airplane mode, intermittent connectivity, duplicate requests, app termination, relaunch, and conflicting updates.
/polish-ui Improve the profile screen for small devices, keyboard overlap, loading, empty, error, offline, dark mode, and accessibility states.
The command routes work to ui-polisher, which preserves the existing design
system and can edit focused UI files. If the screen includes large lists,
images, or animations, follow with:
@performance-reviewer Review the changed screen for rendering, memory, image, and animation regressions.
Provide the exact error, environment, and reproduction path:
/debug-mobile EAS Android production build fails during Gradle configuration. Expo SDK: <version>. Local development works. Exact error: <paste error>.
The debugger distinguishes JavaScript, Expo, EAS, iOS, Android, network, permission, signing, and device-only causes before proposing a fix. It avoids random upgrades, destructive cache clearing, and release operations as a first response.
Run the cross-platform gate first:
/predeploy-mobile Review version 1.0 for external beta. Include auth, offline behavior, permissions, IAP, crash reporting, and real-device QA.
Then run the platform-specific readiness checks:
/release-ios Prepare version 1.0 build 12 for TestFlight and App Store review.
/release-android Prepare version 1.0 version code 12 for the Play internal testing track.
These commands produce pass/fail findings and a go/no-go recommendation. They do not upload builds or change signing, credentials, bundle IDs, package names, product IDs, store tracks, or metadata without explicit approval.
The configuration favors inspection and review before mutation.
| Operation | Default behavior |
|---|---|
| Read, search, LSP, skills, and web research | Allowed |
| Project edits | Agent-dependent: denied, approval-gated, or allowed for focused implementation |
| Common test commands | Allowed for implementation and testing agents |
| EAS builds, submissions, credentials, Fastlane, pushes, and tags | Approval required |
| External directories | Approval required |
rm -rf and sudo |
Denied by the shared policy; inspect agent-specific overrides |
Agent-specific permissions override the shared defaults. Important examples:
planandmega-plancannot edit files or run shell commands.buildcan edit files but asks before most shell commands and release work.debuggerasks before edits and non-routine diagnostics.ui-polishercan make focused UI edits.- Release and platform specialists ask before production-sensitive changes.
Some specialist agents define their own approval-gated shell rules. Because agent-specific permissions override shared defaults, treat an approval prompt as a security boundary even when the shared configuration denies the same command.
Always review an approval request before accepting it, especially for signing, credentials, native identifiers, dependency changes, builds, uploads, or store operations.
Pull the latest changes from the clone:
cd "$HOME/Developer/opencode-configs"
git pull --ff-onlyQuit and restart OpenCode after updating. Existing sessions continue using the configuration loaded when they started.
Review upstream changes to opencode.json before updating when you maintain
local permission or agent overrides.
- Confirm
OPENCODE_CONFIG_DIRpoints to the repository root, not itsagents/orcommands/directory. - If using the global method, confirm
~/.config/opencoderesolves to the cloned repository. - Quit all OpenCode sessions and start a new one after configuration changes.
- Confirm the clone contains
opencode.json,agents/,commands/, andskills/at its root.
Run OpenCode with the directory set for one command:
OPENCODE_CONFIG_DIR="$HOME/Developer/opencode-configs" opencodeIf another project configuration is active, remember that OpenCode merges
configuration scopes. Project-level .opencode settings and files can add to
or override global behavior.
opencode auth login
opencode auth listRe-authenticate the provider and verify that the selected model is available to the account. Credentials are stored separately from this repository.
Start OpenCode without the current project's configuration:
OPENCODE_DISABLE_PROJECT_CONFIG=1 opencodeCorrect the invalid project configuration, quit OpenCode, and restart without the environment variable.
For the isolated method, remove OPENCODE_CONFIG_DIR from the shell profile,
open a new shell, and restart OpenCode. The cloned repository can remain for
future use.
For the global symlink method, verify the path is a symlink and unlink it:
ls -ld "$HOME/.config/opencode"
unlink "$HOME/.config/opencode"unlink removes the symlink, not the cloned repository.