| name | OpenCodeSystem |
| description | PAI-OpenCode system self-awareness. USE WHEN asking about tools, config, model routing, plugin handlers, MCP servers, troubleshooting, or operating environment. |
Customization
Before executing, check for user customizations at:
~/.opencode/PAI/USER/SKILLCUSTOMIZATIONS/OpenCodeSystem/
If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
OpenCodeSystem — System Self-Awareness
System self-awareness for PAI-OpenCode. Enables the Algorithm to answer questions about its own operating environment without asking the user or hallucinating.
Visibility
This skill runs in the foreground. All lookups and diagnostic output should be visible to maintain transparency.
MANDATORY — Quick Reference
| Question | Answer Location |
|---|
| Directory layout + handler map | docs/architecture/SystemArchitecture.md |
| All available tools (native + custom + agents) | docs/architecture/ToolReference.md |
| Model routing, opencode.json, settings.json | docs/architecture/Configuration.md |
| Something not working? | docs/architecture/Troubleshooting.md |
| Why was a decision made? | docs/architecture/adr/README.md → find relevant ADR |
MANDATORY — Key Facts (Inline — No File Read Needed)
Runtime Identity
- Platform: OpenCode (NOT Claude Code — never use
~/.claude/)
- Correct path:
~/.opencode/
- Project config:
opencode.json (root) + settings.json (~/.opencode/)
- Plugin entry:
.opencode/plugins/pai-unified.ts
Custom Tools Always Available
| Tool | Purpose |
|---|
session_registry | List recent sessions for CONTEXT RECOVERY |
session_results | Get detailed results for a specific session ID |
code_review | AI code review via roborev — call in VERIFY phase (WP-N7) |
Model Tiers
quick → fast, cheap (exploration, simple tasks)standard → balanced (default for most agents)advanced → complex reasoning (Algorithm agent)- Actual model names resolved from
opencode.json — never hardcode
The 2-Second Rule
If Grep, Glob, or Read can answer in <2 seconds → use them directly. Never spawn an agent for what a direct tool call can do instantly.
Critical Path Rules
bash workdir parameter → ALWAYS (never cd &&)
imports → ALWAYS include .ts extension
package manager → ALWAYS bun (never npm/yarn/pnpm)
memory paths → ALWAYS ~/.opencode/ (never ~/.claude/)
MANDATORY — When Something Doesn't Work
Walk docs/architecture/Troubleshooting.md top-to-bottom. The checklist covers:
- Plugin not loading
- Custom tools missing
- Post-compaction recovery
- Model routing issues
- Path errors
- Skill not triggering
- Runtime/bun errors
- Agent spawn issues
OPTIONAL — Architecture in 30 Seconds
opencode.json → model routing, permissions, agent definitions
pai-unified.ts → single plugin, all event hooks registered
handlers/ → 20+ modular handlers (session, security, capture, etc.)
AGENTS.md → Algorithm's runtime operating instructions
skills/skill-index.json → skill discovery registry for CAPABILITY AUDIT
~/.opencode/MEMORY/ → PRDs, session data, reflections
Full details: docs/architecture/SystemArchitecture.md
OPTIONAL — USE WHEN Triggers
- "What tools do I have?"
- "What custom tools are available?"
- "How is model routing configured?"
- "What MCP servers are connected?"
- "Why isn't the plugin firing?"
- "What's the difference between opencode.json and settings.json?"
- "How do I troubleshoot X not working?"
- "What agents can I spawn?"
- "Where is the memory stored?"
- "What hooks does the plugin register?"
- Any question about the operating environment, directory structure, or system configuration
Tools
| Tool | Path | Purpose |
|---|
db-archive.ts | Tools/db-archive.ts | Archive old sessions to reclaim disk space. Supports --dry-run, --vacuum, and --restore. Run with bun Tools/db-archive.ts. |
migration-v2-to-v3.ts | Tools/migration-v2-to-v3.ts | Migrate existing v2.x PAI-OpenCode installations to v3.0 directory structure. Supports --dry-run, --force, --backup-dir. Run with bun Tools/migration-v2-to-v3.ts. |
Workflows
No dedicated workflow files. Operational procedures for the tools above are documented inline in each tool's source header and in docs/DB-MAINTENANCE.md (archival) and docs/MIGRATION.md (v2→v3 migration).
Related Skills
- PAI — Algorithm core, ISC creation, verification
- System — System maintenance, integrity check, documentation
