diff --git a/.opencode/.env.example b/.opencode/.env.example index 58df7f1d..03f41849 100644 --- a/.opencode/.env.example +++ b/.opencode/.env.example @@ -9,6 +9,12 @@ DA=YourAIName TIME_ZONE=Europe/Berlin PAI_DIR=/path/to/your/.opencode +# ============================================================================ +# OPENCODE EXPERIMENTAL FEATURES +# ============================================================================ +# Opt-in: set to true to enable LSP-based code navigation (experimental) +OPENCODE_EXPERIMENTAL_LSP_TOOL=false + # ============================================================================ # VOICE SERVER CONFIGURATION (Optional) # ============================================================================ diff --git a/.opencode/skills/OpenCodeSystem/SKILL.md b/.opencode/skills/OpenCodeSystem/SKILL.md new file mode 100644 index 00000000..432768f3 --- /dev/null +++ b/.opencode/skills/OpenCodeSystem/SKILL.md @@ -0,0 +1,126 @@ +--- +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/skills/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 | + +### 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: +1. Plugin not loading +2. Custom tools missing +3. Post-compaction recovery +4. Model routing issues +5. Path errors +6. Skill not triggering +7. Runtime/bun errors +8. Agent spawn issues + +--- + +## OPTIONAL — Architecture in 30 Seconds + +```text +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 + +_No dedicated CLI tools for this skill. Reference documents are read directly via `read` tool._ + +## Workflows + +_No workflow files. This skill operates by directing the Algorithm to the correct reference document._ + +--- + +## Related Skills + +- **PAI** — Algorithm core, ISC creation, verification +- **System** — System maintenance, integrity check, documentation diff --git a/.opencode/skills/skill-index.json b/.opencode/skills/skill-index.json index 4aed2489..b987d31d 100644 --- a/.opencode/skills/skill-index.json +++ b/.opencode/skills/skill-index.json @@ -1,11 +1,11 @@ { - "generated": "2026-03-08T23:47:52.369Z", - "totalSkills": 52, + "generated": "2026-03-12T07:24:22.833Z", + "totalSkills": 53, "categories": 7, - "flatSkills": 17, + "flatSkills": 18, "hierarchicalSkills": 35, "alwaysLoadedCount": 2, - "deferredCount": 50, + "deferredCount": 51, "skills": { "agents": { "name": "Agents", @@ -533,6 +533,29 @@ "tier": "deferred", "isHierarchical": false }, + "opencodesystem": { + "name": "OpenCodeSystem", + "path": "OpenCodeSystem/SKILL.md", + "category": null, + "fullDescription": "PAI-OpenCode system self-awareness. USE WHEN asking about tools, config, model routing, plugin handlers, MCP servers, troubleshooting, or operating environment.", + "triggers": [ + "asking", + "tools", + "config", + "model", + "routing", + "plugin", + "handlers", + "mcp", + "servers", + "troubleshooting", + "operating", + "environment" + ], + "workflows": [], + "tier": "deferred", + "isHierarchical": false + }, "osint": { "name": "OSINT", "path": "Investigation/OSINT/SKILL.md", @@ -1039,14 +1062,19 @@ "name": "USMetrics", "path": "USMetrics/SKILL.md", "category": null, - "fullDescription": "US metrics and data tracking. USE WHEN US metrics, American data, statistics, demographics, tracking.", + "fullDescription": "US metrics, economic indicators and data tracking. USE WHEN US metrics, American data, statistics, demographics, GDP, inflation, unemployment, economic metrics, gas prices.", "triggers": [ "metrics", "american", "data", "statistics", "demographics", - "tracking" + "gdp", + "inflation", + "unemployment", + "economic", + "gas", + "prices" ], "workflows": [ "UpdateData", diff --git a/docs/architecture/Configuration.md b/docs/architecture/Configuration.md new file mode 100644 index 00000000..ea48263f --- /dev/null +++ b/docs/architecture/Configuration.md @@ -0,0 +1,191 @@ +--- +title: Configuration Reference +doc_type: reference +tags: [architecture, configuration, ADR-017, wp-n6] +last_updated: 2026-03-12 +--- + +# Configuration Reference + +> [!info] Authoritative Source +> PAI-OpenCode configuration reference (ADR-017 / WP-N6). +> **Single Source of Truth for models: `opencode.json`** — no other file should hardcode model names. + +--- + +## Two-File Configuration (ADR-005) + +PAI-OpenCode uses two configuration files with distinct responsibilities: + +| File | Location | Purpose | Managed By | +|------|----------|---------|-----------| +| `opencode.json` | Project root (symlink) | OpenCode runtime: model routing, agents, permissions | Developer / this repo | +| `settings.json` | `~/.opencode/` | User preferences: PAI behavior, identity, overrides | User's local install | + +**Rule:** `opencode.json` is committed to the repo. `settings.json` is user-local and never committed. + +--- + +## Config Switching (Symlink Architecture) + +`opencode.json` at project root is a **symlink** pointing to one of multiple config variants: + +```text +opencode.json → opencode.anthropic.json (Anthropic models — Opus/Sonnet/Haiku) + → opencode.zen.json (Zen/multi-provider models) +``` + +Terminal commands switch the active configuration: + +| Command | What It Does | +|---------|-------------| +| `oc-anthropic` | Switch to Anthropic model config | +| `oc-zen` | Switch to Zen/multi-provider config | +| `oc-which` | Show which config variant is currently active | + +**Key principle:** The Algorithm and all agents are **unaware** which config variant is active. They only see `opencode.json` and interact with it via the three-tier model system. This means model names change transparently without any code or documentation updates. + +--- + +## opencode.json + +Full schema reference: `https://opencode.ai/config.json` + +### Top-Level Fields + +```json +{ + "$schema": "https://opencode.ai/config.json", + "theme": "dark", + "model": "", // Default model for interactive sessions + "snapshot": true, // Enable session snapshots + "username": "User", + "permission": { ... }, // Tool permission rules + "mode": { ... }, // Mode-specific system prompts + "agent": { ... } // Agent model routing (three-tier) +} +``` + +### Three-Tier Model System + +Every agent has three model tiers. The Algorithm selects tiers based on task complexity: + +| Tier | When | Cost Profile | +|------|------|-------------| +| `quick` | Simple tasks, batch operations, data transformation | Cheapest | +| `standard` | Normal operations (default for most agents) | Balanced | +| `advanced` | Complex reasoning, architecture decisions | Most expensive | + +```json +"agent": { + "Engineer": { + "model": "", + "model_tiers": { + "quick": { "model": "" }, + "standard": { "model": "" }, + "advanced": { "model": "" } + } + } +} +``` + +> [!important] Model Names Are NOT Documented Here +> Actual model names live **exclusively** in `opencode.json`. This prevents documentation drift when models change (e.g., new model release, provider switch, config variant swap). To see current models: `cat opencode.json`. + +### Algorithm Delegation Principle + +The Algorithm runs on the **most capable and most expensive model** in the system. Because of this cost profile, it should: + +1. **Delegate aggressively** — write clear instructions for cheaper agents to execute +2. **Write instructions, not code** — for anything >100 lines of code or significant documents, spawn an Engineer/Writer agent +3. **Use `quick` tier agents** for batch operations, simple edits, data transformations +4. **Reserve `advanced` tier** for genuinely complex reasoning that `standard` cannot handle + +The agents doing the actual work use significantly cheaper models. The Algorithm's value is in **orchestration and instruction quality**, not in doing the work itself. + +### Permissions + +```json +"permission": { + "*": "allow", // Allow all tools by default + "websearch": "allow", // Web search: no prompt + "codesearch": "allow", // Code search: no prompt + "webfetch": "allow", // URL fetch: no prompt + "doom_loop": "ask", // Recursive agent calls: requires confirmation + "external_directory": "ask" // Files outside project: requires confirmation +} +``` + +### Mode Prompts + +```json +"mode": { + "build": { "prompt": "You are a Personal AI assistant powered by PAI-OpenCode infrastructure." }, + "plan": { "prompt": "You are a Personal AI assistant powered by PAI-OpenCode infrastructure." } +} +``` + +--- + +## settings.json + +Located at `~/.opencode/settings.json`. User-local, never committed. + +### Common PAI Settings + +```json +{ + "daidentity": { + "name": "Jeremy" // DA name used in voice output + }, + "principal": { + "name": "Steffen", // User name + "timezone": "Europe/Berlin" + } +} +``` + +See `AGENTS.md` for the full list of settings.json fields the PAI Algorithm reads. + +--- + +## AGENTS.md + +Located at project root (`AGENTS.md`). **Not a config file** — it is the Algorithm's runtime instructions document. Loaded automatically by OpenCode as project-level agent instructions. + +Key sections: +- `## Build, Test & Lint Commands` — commands the Algorithm uses +- `## Technology Stack` — stack preferences and rules +- `## Session Recovery` (added WP-N3) — how to use `session_registry` + `session_results` +- `## LSP Integration` (added WP-N4) — LSP opt-in instructions +- `## Session Fork Pattern` (added WP-N4) — experiment isolation pattern + +--- + +## Environment Variables + +Set in `.env` (auto-loaded by Bun, never committed). See `.opencode/.env.example` for template. + +| Variable | Purpose | Default | Where Used | +|----------|---------|---------|-----------| +| `OPENCODE_EXPERIMENTAL_LSP_TOOL` | Enable LSP tool integration | `true` | OpenCode runtime, documented in ADR-014 | +| `PAI_LOG_LEVEL` | Plugin logging verbosity | — | `pai-unified.ts` handlers | +| `DA` | AI assistant name | — | Voice server, prompt templates | +| `TIME_ZONE` | User timezone | — | Timestamp formatting | +| `PAI_DIR` | Path to `.opencode/` directory | — | Skill and memory system | + +--- + +## Plugin Loading + +> [!warning] Only `pai-unified.ts` Should Load at Startup +> OpenCode discovers `.ts` files in `.opencode/plugins/`. The **only** file that should be loaded as a plugin is `pai-unified.ts`. All handler modules in `handlers/` are imported by `pai-unified.ts` internally — they are NOT standalone plugins. +> +> TypeScript files in `skills/*/Tools/` are CLI tools meant to be run on-demand with `bun run `, NOT loaded as plugins. If OpenCode tries to load ALL `.ts` files in the directory tree, this creates errors and performance issues. + +Plugin behavior is configured via: +1. `settings.json` values (read at runtime) +2. Hard-coded constants in handler files +3. Environment variables + +There is no separate plugin config file — all tuning is done in the handler source or environment. diff --git a/docs/architecture/SystemArchitecture.md b/docs/architecture/SystemArchitecture.md new file mode 100644 index 00000000..73512fb6 --- /dev/null +++ b/docs/architecture/SystemArchitecture.md @@ -0,0 +1,184 @@ +--- +title: PAI-OpenCode System Architecture +description: Authoritative source for Algorithm self-awareness — directory layout, plugin handlers, event hooks +type: reference +adr: ADR-017 +wp: WP-N6 +updated: 2026-03-12 +--- + +# PAI-OpenCode System Architecture + +> [!NOTE] +> **Authoritative source for Algorithm self-awareness (ADR-017 / WP-N6)** + +--- + +## Directory Layout + +```text +pai-opencode/ +├── .opencode/ +│ ├── plugins/ ← Plugin system (loaded by opencode at startup) +│ │ ├── pai-unified.ts ← Single plugin entry point — all hooks registered here +│ │ ├── handlers/ ← Modular handler implementations +│ │ │ ├── session-registry.ts (WP-N1) Custom tools: session_registry, session_results +│ │ │ ├── compaction-intelligence.ts (WP-N2) Context injection during compaction +│ │ │ ├── agent-capture.ts Agent output capture +│ │ │ ├── algorithm-tracker.ts Algorithm phase tracking +│ │ │ ├── format-reminder.ts Response format enforcement +│ │ │ ├── implicit-sentiment.ts Implicit rating detection +│ │ │ ├── integrity-check.ts Session integrity validation +│ │ │ ├── isc-validator.ts Ideal State Criteria validation +│ │ │ ├── learning-capture.ts Learning phase capture +│ │ │ ├── observability-emitter.ts Metrics emission +│ │ │ ├── prd-sync.ts PRD file synchronization +│ │ │ ├── question-tracking.ts User question tracking +│ │ │ ├── rating-capture.ts Rating extraction +│ │ │ ├── relationship-memory.ts Relational context +│ │ │ ├── response-capture.ts Full response capture +│ │ │ ├── security-validator.ts Security threat detection +│ │ │ ├── session-cleanup.ts Session lifecycle cleanup +│ │ │ ├── skill-guard.ts Skill execution gating +│ │ │ ├── skill-restore.ts Skill restoration after compaction +│ │ │ ├── tab-state.ts Multi-tab state management +│ │ │ ├── update-counts.ts Token/update counters +│ │ │ ├── voice-notification.ts Voice alert delivery +│ │ │ ├── work-tracker.ts Active work tracking +│ │ │ ├── adapters/ Low-level OpenCode API adapters +│ │ │ └── lib/ Shared handler utilities +│ │ ├── agent-execution-guard.ts Agent execution safety wrapper +│ │ ├── check-version.ts Version check utility +│ │ └── last-response-cache.ts Response caching +│ └── skills/ ← Skill library (on-demand loading) +│ ├── skill-index.json ← Skill registry — USE WHEN triggers for capability audit +│ ├── PAI/SKILL.md ← PAI Algorithm core skill +│ ├── OpenCodeSystem/ ← System self-awareness (WP-N6) +│ ├── Agents/ ← Agent composition skills +│ ├── Research/ ← Research skills +│ └── [40+ other skills] +├── docs/ +│ ├── architecture/ +│ │ ├── adr/ ← Architecture Decision Records +│ │ ├── SystemArchitecture.md ← THIS FILE +│ │ ├── ToolReference.md ← All tools catalog +│ │ ├── Configuration.md ← opencode.json + settings.json +│ │ └── Troubleshooting.md ← Self-diagnostic checklist +│ └── epic/ ← Project planning documents +│ ├── TODO-v3.0.md +│ ├── OPTIMIZED-PR-PLAN.md +│ └── EPIC-v3.0-OpenCode-Native.md +├── PAI-Install/ ← Installer system +├── opencode.json ← OpenCode configuration (model routing, permissions, agents) +└── AGENTS.md ← Algorithm operating instructions +``` + +--- + +## Plugin System + +PAI-OpenCode uses a **single unified plugin** (`pai-unified.ts`) that registers all handlers. OpenCode loads this at startup and the plugin wires up all event hooks. + +### Event Hooks Registered + +| Hook | When | Primary Handlers | +|------|------|-----------------| +| `session.created` | New session starts | Algorithm tracker, tab-state, integrity check | +| `session.compacted` | Context compaction completes | Learning rescue, skill-restore | +| `experimental.session.compacting` | Compaction in progress (WP-N2) | `compaction-intelligence` — injects context summary | +| `permission.ask` | Tool permission requested (blocking gate) | `security-validator` — blocks dangerous operations | +| `permission.asked` | After permission decision made (audit log) | Observability, decision logging | +| `tool.execute.before` | Before any tool runs | Security check, work tracker update | +| `tool.execute.after` | After any tool runs | Response capture, agent output capture | +| `message.completed` | AI response finished | Format reminder, rating capture, PRD sync | + +### Custom Tools (WP-N1) + +Two custom tools registered via `tool:` config in `pai-unified.ts`: + +| Tool | Purpose | When to Call | +|------|---------|--------------| +| `session_registry` | Lists recent sessions with summaries | Post-compaction CONTEXT RECOVERY | +| `session_results` | Gets detailed results for a specific session ID | When session_registry returns relevant session | + +**Note:** These are native OpenCode custom tools (not MCP), registered directly in the plugin's `tool:` object. + +--- + +## Algorithm Flow + +```text +User Input + │ + ▼ +AGENTS.md (runtime instructions loaded at session start) + │ + ▼ +PAI Algorithm 7 phases: OBSERVE → THINK → PLAN → BUILD → EXECUTE → VERIFY → LEARN + │ + ├── OBSERVE: ISC creation, voice curl, capability audit (reads skill-index.json) + ├── THINK: Pressure test ISC + ├── PLAN: PRD creation, execution strategy + ├── BUILD: Artifact creation + ├── EXECUTE: Run artifacts + ├── VERIFY: Check each ISC criterion + └── LEARN: Reflections, PRD update +``` + +
+Algorithm Flow (Mermaid) + +```mermaid +flowchart TD + UI[User Input] --> AM[AGENTS.md
Runtime Instructions] + AM --> OBS[1. OBSERVE
ISC creation, capability audit] + OBS --> THK[2. THINK
Pressure test ISC] + THK --> PLN[3. PLAN
PRD creation, execution strategy] + PLN --> BLD[4. BUILD
Artifact creation] + BLD --> EXE[5. EXECUTE
Run artifacts] + EXE --> VER[6. VERIFY
Check each ISC criterion] + VER --> LRN[7. LEARN
Reflections, PRD update] + VER -->|Criteria failing| BLD + + style OBS fill:#e8f0fe,stroke:#333 + style VER fill:#e8f5e9,stroke:#333 + style LRN fill:#fff3e0,stroke:#333 +``` + +
+ +### Session Persistence + +- **Active session:** Work tracked in OpenCode's native session store +- **Post-compaction:** `session_registry` tool provides access to prior session summaries +- **PRD files:** `~/.opencode/MEMORY/WORK/{session-slug}/PRD-*.md` — persistent ISC storage + +--- + +## Memory Layout + +```text +~/.opencode/ +├── MEMORY/ +│ ├── WORK/ ← PRD files, session handoffs +│ ├── STATE/ ← Runtime state +│ └── LEARNING/ ← Algorithm reflections JSONL +└── skills/ ← User-level skills (if separate from project) +``` + +**Project skills** (in repo) take precedence over user-level skills when both exist. + +--- + +## Key Architectural Decisions + +| ADR | Decision | +|-----|----------| +| ADR-001 | Hooks → Plugin architecture (Claude Code hooks → OpenCode plugin) | +| ADR-005 | Dual-file config: `opencode.json` (model/agents) + `settings.json` (PAI behavior) | +| ADR-012 | `session_registry` + `session_results` as native custom tools | +| ADR-013 | SKILL.md CONTEXT RECOVERY uses custom tools for post-compaction awareness | +| ADR-015 | Compaction intelligence via `experimental.session.compacting` hook | +| ADR-017 | System self-awareness skill + reference docs (this WP) | + +Full ADR index: `docs/architecture/adr/README.md` diff --git a/docs/architecture/ToolReference.md b/docs/architecture/ToolReference.md new file mode 100644 index 00000000..ed5c17d2 --- /dev/null +++ b/docs/architecture/ToolReference.md @@ -0,0 +1,177 @@ +--- +title: Tool Reference +description: Authoritative source for all tools available in PAI-OpenCode +type: reference +adr: ADR-017 +wp: WP-N6 +updated: 2026-03-12 +--- + +# Tool Reference + +> [!NOTE] +> **Authoritative source for all tools available in PAI-OpenCode (ADR-017 / WP-N6)** + +--- + +## Native OpenCode Tools + +These are built into OpenCode and always available regardless of configuration. + +| Tool | Description | Common Use | +|------|-------------|------------| +| `read` | Read file contents | Read source files, configs, PRDs | +| `write` | Write file contents | Create or overwrite files | +| `edit` | Apply diff to file | Targeted file modifications | +| `bash` | Execute shell commands | Git, bun, build commands | +| `glob` | Pattern file search | Find files by name pattern | +| `grep` | Content search | Search code for patterns | +| `webfetch` | Fetch a URL | Read documentation, APIs | +| `websearch` | Web search | Research, lookup current info | +| `codesearch` | Search codebase | Semantic code search (if enabled) | +| `task` | Spawn a subagent | Delegate work to specialist agents | + +### Tool Permissions + +Configured in `opencode.json` under `permission:`: + +```json +{ + "permission": { + "*": "allow", + "websearch": "allow", + "codesearch": "allow", + "webfetch": "allow", + "doom_loop": "ask", + "external_directory": "ask" + } +} +``` + +`"*": "allow"` grants all tools without prompting. `"ask"` requires user confirmation. + +--- + +## Custom PAI Tools (WP-N1) + +Registered by `pai-unified.ts` plugin. Available in every session. + +### `session_registry` + +**Purpose:** Lists recent sessions with summaries — primary entry point for post-compaction CONTEXT RECOVERY. + +**When to use:** +- After context compaction when prior work is lost from working memory +- When user says "continue from where we left off" +- During OBSERVE CONTEXT RECOVERY step + +**Returns:** List of sessions with IDs, timestamps, task descriptions, and summaries. + +**Example flow:** +``` +1. Call session_registry → get list of recent sessions +2. Identify session matching current task context +3. Call session_results with that session ID → get detailed results +4. Rebuild working memory from results +``` + +### `session_results` + +**Purpose:** Gets detailed output, ISC criteria, and work done for a specific session ID. + +**When to use:** After `session_registry` identifies a relevant prior session. + +**Input:** Session ID from `session_registry` output. + +**Returns:** Full session results including completed ISC criteria, decisions made, artifacts created. + +--- + +## Subagent Types (task tool) + +When using the `task` tool to spawn agents, use these `subagent_type` values: + +| subagent_type | Model Tier | Best For | +|---------------|-----------|----------| +| `Algorithm` | advanced | Full PAI Algorithm runs, complex reasoning | +| `Architect` | standard | System design, ADR writing, architecture decisions | +| `Engineer` | standard | Implementation, file edits, code writing | +| `explore` | quick | Fast codebase exploration | +| `Intern` | quick | Simple tasks, data transformation | +| `Writer` | standard | Documentation, content | +| `DeepResearcher` | standard | Multi-model research orchestration | +| `GeminiResearcher` | standard | Google Gemini research | +| `GrokResearcher` | standard | xAI Grok contrarian analysis | +| `PerplexityResearcher` | standard | Real-time web search | +| `CodexResearcher` | standard | Technical archaeology | +| `QATester` | standard | Quality assurance, test writing | +| `Pentester` | standard | Security testing | +| `Designer` | standard | UI/UX design | +| `Artist` | standard | Visual content generation | +| `general` | standard | General purpose fallback | + +> [!IMPORTANT] +> **Model tier override:** Pass `model_tier: "quick" | "standard" | "advanced"` to override the default model for any agent type. Actual model names are resolved from `opencode.json` — never hardcode model names in prompts or docs. + +--- + +## MCP Servers + +MCP (Model Context Protocol) servers extend the tool set with domain-specific capabilities. + +> [!TIP] +> **Check `opencode.json` for currently connected MCP servers.** The list below reflects a typical PAI-OpenCode setup — your installation may differ. + +### Detecting Connected MCP Servers + +If unsure which MCP servers are active, inspect `opencode.json` for an `mcp` or `mcpServers` section: + +```bash +# List configured MCP servers from opencode.json +grep -A 5 '"mcp"\|"mcpServers"' opencode.json +``` + +MCP tools appear with the `mcp_` prefix in tool calls (e.g., `mcp_task`, `mcp_jira_create_issue`). + +--- + +## Tool Selection Decision Tree + +```text +Need to find files? + ├── By name/pattern → glob + └── By content → grep or codesearch + +Need to read a file? + └── read (always prefer over bash cat) + +Need to modify a file? + ├── Replace specific text → edit + └── Full rewrite → write + +Need to run commands? + └── bash (with workdir parameter — NEVER cd &&) + +Need prior session context? + ├── Step 1: session_registry (list sessions) + └── Step 2: session_results (get details) + +Need to delegate complex work? + └── task (with subagent_type, full context, effort level) + +Need current web information? + ├── Specific URL → webfetch + └── General search → websearch or PerplexityResearcher agent +``` + +--- + +## Anti-Patterns + +| ❌ Don't | ✅ Do Instead | +|---------|--------------| +| `bash: cd /path && command` | Use `workdir` parameter on bash | +| `bash: cat file.txt` | Use `read` tool | +| Spawn agent for grep/glob | Use grep/glob directly (2-second rule) | +| Guess tool names | Check this reference or inspect opencode.json | +| Use `npm install` | Always `bun install` | diff --git a/docs/architecture/Troubleshooting.md b/docs/architecture/Troubleshooting.md new file mode 100644 index 00000000..4b8c660a --- /dev/null +++ b/docs/architecture/Troubleshooting.md @@ -0,0 +1,280 @@ +--- +title: Troubleshooting — Self-Diagnostic Checklist +description: Algorithm self-diagnosis when something isn't working +type: reference +adr: ADR-017 +wp: WP-N6 +updated: 2026-03-12 +--- + +# Troubleshooting — Self-Diagnostic Checklist + +> [!NOTE] +> Walk each checklist top-to-bottom. Stop at the first match. + +--- + +## Quick Triage + +```text +Start — What's broken? +├── Plugin not firing / hooks silent → Plugin Not Loading +├── Custom tools not available → Custom Tools Missing +├── Session context lost → Post-Compaction Recovery +├── Wrong model being used → Model Routing +├── Path errors (~/.claude/ vs ~/.opencode/) → Path Errors +├── Skill not triggering → Skill Not Triggering +├── Bun / npm errors → Runtime Errors +└── Agent spawn failing → Agent Spawn Issues +``` + +| Symptom | Jump To | +|---------|---------| +| Plugin not firing / hooks silent | [Plugin Not Loading](#plugin-not-loading) | +| Custom tools not available | [Custom Tools Missing](#custom-tools-missing) | +| Session context lost after compaction | [Post-Compaction Recovery](#post-compaction-recovery) | +| Wrong model being used | [Model Routing](#model-routing) | +| Path errors (`~/.claude/` vs `~/.opencode/`) | [Path Errors](#path-errors) | +| Skill not triggering | [Skill Not Triggering](#skill-not-triggering) | +| Bun / npm errors | [Runtime Errors](#runtime-errors) | +| Agent spawn failing | [Agent Spawn Issues](#agent-spawn-issues) | + +
+Quick Triage Flowchart (Mermaid) + +```mermaid +flowchart TD + Start([Something is broken]) --> Q1{What symptom?} + Q1 -->|Plugin not firing| PL[Plugin Not Loading] + Q1 -->|Custom tools missing| CT[Custom Tools Missing] + Q1 -->|Context lost after compaction| PC[Post-Compaction Recovery] + Q1 -->|Wrong model| MR[Model Routing] + Q1 -->|Path errors| PE[Path Errors] + Q1 -->|Skill not triggering| SN[Skill Not Triggering] + Q1 -->|Bun / npm errors| RE[Runtime Errors] + Q1 -->|Agent spawn failing| AS[Agent Spawn Issues] + + style Start fill:#e8f0fe,stroke:#333 + style Q1 fill:#fff3e0,stroke:#333 +``` + +
+ +--- + +## Plugin Not Loading + +```text +□ Does .opencode/plugins/pai-unified.ts exist? + → NO: Run PAI installer or restore from git + +□ Does pai-unified.ts have syntax errors? + → Check: bun check .opencode/plugins/pai-unified.ts + → Fix syntax errors before restart + +□ Did you restart OpenCode after changing plugin files? + → Plugin changes require OpenCode restart to take effect + +□ Is the plugin exporting a default plugin object? + → Must export: export default { ... } with hooks + → Check pai-unified.ts final lines + +□ Are handlers imported correctly in pai-unified.ts? + → Check import paths at top of pai-unified.ts + → All handlers are in .opencode/plugins/handlers/ +``` + +--- + +## Custom Tools Missing + +`session_registry` and `session_results` not available: + +```text +□ Is the plugin loaded? (See Plugin Not Loading above) + +□ Check pai-unified.ts for tool: { } registration block + → Search: grep -n "session_registry" .opencode/plugins/pai-unified.ts + → Should show line ~370: session_registry: sessionRegistryTool + +□ Check session-registry.ts exports + → grep -n "export" .opencode/plugins/handlers/session-registry.ts + → Should export: sessionRegistryTool, sessionResultsTool + +□ Restart OpenCode — custom tools require fresh session to register +``` + +--- + +## Post-Compaction Recovery + +Context was compacted and working memory is lost: + +```text +□ Use session_registry tool immediately + → Call: session_registry (no arguments needed) + → Returns: list of recent sessions with IDs and task descriptions + +□ Identify the relevant session from the list + → Match task description to current work context + +□ Call session_results with that session ID + → Returns: ISC criteria, decisions, artifacts from that session + +□ If session_registry returns empty: + → Sessions may have been cleaned up + → Check ~/.opencode/MEMORY/WORK/ for PRD files + → Read PRD file directly to recover ISC and context + +□ Rebuild working memory from recovered data + → Re-create ISC via TaskCreate matching recovered criteria + → Resume from last known phase in PRD LOG section +``` + +See AGENTS.md "Session Recovery" section for the full CONTEXT RECOVERY protocol. + +--- + +## Model Routing + +Wrong model being used for an agent: + +```text +□ Check opencode.json agent section + → cat opencode.json | grep -A 10 '"AgentName"' + → Verify model field matches expected + +□ Verify model_tier is being passed correctly in task tool call + → model_tier: "quick" | "standard" | "advanced" + → Only works if model_tiers block exists in opencode.json for that agent + +□ Is the model provider configured? + → Anthropic models: require ANTHROPIC_API_KEY in environment + → Google models: require GOOGLE_API_KEY + → xAI models: require XAI_API_KEY + → Perplexity: require PERPLEXITY_API_KEY + +□ Check opencode.json top-level "model" field + → This is the default for interactive sessions, not for agents + → Agent routing always comes from "agent" section +``` + +Full model table: `docs/architecture/Configuration.md` + +--- + +## Path Errors + +Files being written to wrong location: + +```text +□ CRITICAL: This is OpenCode, NOT Claude Code + → CORRECT: ~/.opencode/ + → WRONG: ~/.claude/ or ~/.Claude/ + +□ Check every file operation path before executing + → Memory: ~/.opencode/MEMORY/ + → Skills: ~/.opencode/skills/ (user-level) or .opencode/skills/ (project) + → PRDs: ~/.opencode/MEMORY/WORK/{session-slug}/ + +□ If files were written to ~/.claude/: + → First backup: cp -r ~/.claude/MEMORY/ ~/.claude/MEMORY.bak/ + → Ensure target exists: mkdir -p ~/.opencode/MEMORY/ + → Then move: rsync -av ~/.claude/MEMORY/ ~/.opencode/MEMORY/ + → Verify: ls ~/.opencode/MEMORY/ (confirm files arrived) + → Only then remove source: rm -rf ~/.claude/MEMORY/ + → Update any references in PRD files + +□ Working directory in bash tool + → Always use workdir parameter + → NEVER use cd && pattern +``` + +--- + +## Skill Not Triggering + +A skill's USE WHEN condition matches but skill isn't being loaded: + +```text +□ Is the skill in skill-index.json? + → grep -n "SkillName" .opencode/skills/skill-index.json + → If missing: add entry with name, path, triggers, fullDescription + +□ Does the skill path in skill-index.json match the actual file? + → Check path field in index matches real file location + → Paths are relative to .opencode/skills/ + +□ Is CAPABILITY AUDIT reading skill-index.json? + → OBSERVE phase must show: "🔍 SKILL INDEX SCAN (#4 — MANDATORY)" + → If missing from output, re-read AGENTS.md CAPABILITY AUDIT section + +□ Do the skill triggers match the task context? + → Check triggers array in skill-index.json for the skill + → Triggers are keyword matches against the task description +``` + +--- + +## Runtime Errors + +Bun or build errors: + +```text +□ Always use bun, never npm/yarn/pnpm + → bun install (not npm install) + → bun run dev (not npm run dev) + → bun test (not jest or vitest) + +□ TypeScript errors in plugin files + → bun check .opencode/plugins/pai-unified.ts + → Fix type errors before testing + +□ Module not found errors + → Bun resolves relative imports without extension automatically, trying .tsx/.ts/.js in order + → import { foo } from './bar' is valid; no extension required in most cases + → Add explicit .ts only if resolution fails: import { foo } from './bar.ts' + +□ Environment variables not loading + → Bun auto-loads .env — do NOT use dotenv package + → Verify .env exists at project root + → Verify variable names match exactly (case-sensitive) +``` + +--- + +## Agent Spawn Issues + +Task tool not spawning agents or agents failing: + +```text +□ Is subagent_type valid? + → Valid types: Algorithm, Architect, Engineer, explore, Intern, Writer, + DeepResearcher, GeminiResearcher, GrokResearcher, PerplexityResearcher, + CodexResearcher, QATester, Pentester, Designer, Artist, general + → Check ToolReference.md for full list with model defaults + +□ Is the task prompt complete? + → Include: CONTEXT, TASK, EFFORT LEVEL, OUTPUT FORMAT + → Agents need full context — they don't inherit session memory + +□ Did you check if Grep/Glob/Read can do this instead? + → 2-second rule: if search/read can answer in <2s, don't spawn agent + → Agent spawning has 5-15s overhead + permission prompt risk + +□ Is doom_loop triggering? + → opencode.json has "doom_loop": "ask" + → If agent is recursively spawning agents, user sees a prompt + → This is expected safety behavior +``` + +--- + +## Still Stuck? + +If none of the above resolves the issue, escalate through reference materials: + +1. Read the relevant ADR: `docs/architecture/adr/README.md` — find the ADR for the failing component and re-read its rationale and implementation notes +2. Review collected diagnostic artifacts: run `git log --oneline -10` and `git diff HEAD~1` to surface recent changes that may have introduced the regression +3. Read the full handler file for the failing component — check imports, hook registration, and exported symbols against what `pai-unified.ts` expects +4. Cross-reference all four architecture docs: `SystemArchitecture.md` (handler map), `ToolReference.md` (tool list), `Configuration.md` (model routing), `Troubleshooting.md` (this file) — confirm the component is documented and wired as expected diff --git a/docs/architecture/adr/ADR-017-system-self-awareness.md b/docs/architecture/adr/ADR-017-system-self-awareness.md new file mode 100644 index 00000000..45f1ecc7 --- /dev/null +++ b/docs/architecture/adr/ADR-017-system-self-awareness.md @@ -0,0 +1,125 @@ +--- +title: "ADR-017: System Self-Awareness Documentation" +status: accepted +date: 2026-03-12 +deciders: [Steffen, Jeremy] +tags: [opencode-native, algorithm, self-awareness, documentation, skills] +wp: WP-N6 +type: adr +related_adrs: [ADR-013, ADR-012, ADR-005] +--- + +# ADR-017: System Self-Awareness Documentation + +## Quick Overview + +```text +┌────────────────────┐ ┌──────────────────────────┐ ┌──────────────────┐ +│ Algorithm stuck │────▶│ OpenCodeSystem skill │────▶│ Answers found │ +│ "what tools do │ │ (self-awareness layer) │ │ without asking │ +│ I have?" │ └──────────────────────────┘ │ the user │ +└────────────────────┘ │ └──────────────────┘ + ▼ + ┌──────────────────────┐ + │ 4 reference docs │ + │ • SystemArchitecture │ + │ • ToolReference │ + │ • Configuration │ + │ • Troubleshooting │ + └──────────────────────┘ +``` + +
+Detailed Diagram + +```mermaid +flowchart TD + Algorithm[PAI Algorithm\nRunning in Session] -->|"Needs to know:\n'what tools exist?'\n'how is model routing set up?'\n'why is X broken?'"| SkillTrigger[OpenCodeSystem\nSkill Triggered] + + SkillTrigger --> SA[SystemArchitecture.md\nPlugin handlers, directory layout] + SkillTrigger --> TR[ToolReference.md\nNative + MCP tools catalog] + SkillTrigger --> CF[Configuration.md\nopencode.json, model routing] + SkillTrigger --> TS[Troubleshooting.md\nSelf-diagnostic checklist] + + SA & TR & CF & TS --> Answer[Algorithm answers\nits own question] + + style SkillTrigger fill:#bbf,stroke:#333 + style Answer fill:#bfb,stroke:#333 +``` + +
+ +--- + +**Status:** Accepted +**Date:** 2026-03-12 +**Deciders:** Steffen, Jeremy +**Tags:** opencode-native, algorithm, self-awareness, documentation, skills +**WP:** WP-N6 + +--- + +## Context + +After WP-N1 through WP-N5, the PAI Algorithm can track sessions (WP-N1), survive compaction (WP-N2), recover prior work (WP-N3), and knows about LSP + session forks (WP-N4). However, it still lacks a structured way to answer basic questions about its own operating environment: + +- "What custom tools do I have access to?" +- "How is model routing configured?" +- "What MCP servers are connected?" +- "Why is plugin handler X not firing?" +- "What's the difference between `opencode.json` and `settings.json`?" + +Currently the Algorithm either asks the user, hallucinates an answer, or reads raw source files — all suboptimal. A dedicated self-awareness skill and supporting reference docs solve this cleanly. + +## Decision + +Create a **system self-awareness layer** consisting of: + +1. **`OpenCodeSystem` skill** (`.opencode/skills/OpenCodeSystem/SKILL.md`) — a self-activating skill with USE WHEN triggers that fires when the Algorithm needs environment information. + +2. **Four reference documents** in `docs/architecture/`: + - `SystemArchitecture.md` — directory layout, plugin handler map, event hooks + - `ToolReference.md` — all native OpenCode tools + registered MCP servers + custom tools (session_registry, session_results) + - `Configuration.md` — `opencode.json` schema, model routing, `settings.json` overlay + - `Troubleshooting.md` — self-diagnostic checklist for common failure modes + +3. **skill-index.json entry** — ensures the skill is discoverable during CAPABILITY AUDIT. + +## Rationale + +### Why a skill rather than inline AGENTS.md sections? + +AGENTS.md is the Algorithm's runtime contract — it should stay focused on operational rules, not reference data. A skill is the correct abstraction for on-demand reference material: it loads only when needed, is version-controlled alongside the code it documents, and follows the established skill pattern already used for PAI, Research, etc. + +### Why 4 separate docs rather than one big reference? + +Single-responsibility principle: each doc has a distinct query pattern. A user asking "what tools exist?" needs ToolReference. A user asking "why is the plugin not firing?" needs Troubleshooting. Separating them keeps each doc focused and reduces noise when the skill loads only the relevant section. + +### Why docs/architecture/ rather than .opencode/skills/OpenCodeSystem/? + +The reference documents describe the project structure and are useful to human developers reading the repo. Placing them in `docs/architecture/` follows the established pattern (ADRs, installer plan, etc.) and keeps `.opencode/skills/` focused on skill logic rather than project documentation. + +## Consequences + +### Positive +- Algorithm can answer "what environment am I running in?" without user interruption +- Reduces hallucinated tool names or incorrect configuration assumptions +- Single authoritative source for environment facts — easy to update when config changes +- Skill auto-activates via USE WHEN triggers — zero manual invocation needed + +### Negative / Trade-offs +- Reference docs require manual maintenance when configuration changes (e.g., new MCP server added, model routing updated) +- Risk of drift between `opencode.json` actuals and `Configuration.md` — mitigated by keeping docs close to source and noting the authoritative source in each doc header + +## Implementation Notes + +- The SKILL.md uses a **pointer pattern**: it documents where information lives and provides the key facts inline, but directs the Algorithm to read the source files for complete detail +- `Configuration.md` must reference model tiers (`quick`/`standard`/`advanced`) — never hardcode specific model names. `opencode.json` is the single source of truth for actual model routing +- `Troubleshooting.md` uses a checklist format so the Algorithm can walk it step by step +- skill-index.json triggers: `["opencode", "system", "tools", "config", "plugin", "mcp", "troubleshoot", "environment", "routing", "handlers"]` + +## Related ADRs + +- **ADR-005** (Dual-file configuration) — describes `opencode.json` + `settings.json` split that `Configuration.md` documents +- **ADR-012** (Session Registry custom tools) — the `session_registry` + `session_results` tools documented in `ToolReference.md` +- **ADR-013** (Algorithm Session Awareness) — the CONTEXT RECOVERY flow that relies on tools cataloged here diff --git a/docs/architecture/adr/README.md b/docs/architecture/adr/README.md index 1bf6e28e..cc49cea8 100644 --- a/docs/architecture/adr/README.md +++ b/docs/architecture/adr/README.md @@ -150,6 +150,7 @@ to "genuinely native". See `docs/epic/EPIC-v3.0-OpenCode-Native.md` for context. | ADR-014 | LSP-Native Code Navigation | ✅ Merged | WP-N4 | | ADR-015 | Compaction Intelligence via Plugin Hook | ✅ Merged | WP-N2 | | ADR-016 | Session Fork for Experiment Isolation | ✅ Merged | WP-N4 | +| ADR-017 | System Self-Awareness Documentation | ✅ Merged | WP-N6 | ## Legacy Future ADRs @@ -190,5 +191,5 @@ to "genuinely native". See `docs/epic/EPIC-v3.0-OpenCode-Native.md` for context. --- -*Last Updated: 2026-03-10* -*ADRs Created: 16 (ADR-011: Security Hardening — WP-B; ADR-012–016: OpenCode-Native Transformation — all merged)* +*Last Updated: 2026-03-12* +*ADRs Created: 17 (ADR-011: Security Hardening — WP-B; ADR-012–017: OpenCode-Native Transformation — ADR-012–016 merged, ADR-017 WP-N6)* diff --git a/docs/epic/OPTIMIZED-PR-PLAN.md b/docs/epic/OPTIMIZED-PR-PLAN.md index b68353de..875b3bdb 100644 --- a/docs/epic/OPTIMIZED-PR-PLAN.md +++ b/docs/epic/OPTIMIZED-PR-PLAN.md @@ -1,6 +1,6 @@ --- title: PAI-OpenCode v3.0 - Corrected PR Plan -description: Port complete — WP-N1..N4 shipped (PR #50–#53), WP-N5 plan sync in progress +description: Port complete — WP-N1..N5 shipped (PR #50–#54), WP-N6 in progress (PR #55 open) version: "3.0-native-1" status: active authors: [Jeremy] @@ -32,7 +32,9 @@ tags: [architecture, migration, v3.0, PR-strategy, native-transformation] | **WP-N2** | Compaction Intelligence | #51 | ✅ **Merged** | experimental.session.compacting hook + context injection | | **WP-N3** | Algorithm Awareness | #52+#53 | ✅ **Merged** | SKILL.md context recovery, PRD parent_session_id | | **WP-N4** | LSP + Fork Documentation | #53 | ✅ **Merged** | AGENTS.md LSP + Fork sections, installer .env | -| **WP-N5** | Plan Update | #54 | 🔄 **In Progress** | Sync all planning docs to reflect N1-N4 complete | +| **WP-N5** | Plan Update | #54 | ✅ **Merged** | Sync all planning docs to reflect N1-N4 complete | +| **WP-N6** | System Self-Awareness | #55 | 🔄 **In Progress** | OpenCodeSystem skill, 4 architecture reference docs, ADR-017 | +| **WP-N7** | Obsidian CLI + Agent Matrix | — | 📋 **Planned** | Formatting guidelines, agent capability matrix | > [!NOTE] > **2026-03-08 Live Audit:** WP-C scope significantly reduced after comparing repo against v4.0.3. @@ -203,21 +205,23 @@ Current state (dev branch): ├── WP-N1 ✅ Session Registry (PR #50) ├── WP-N2 ✅ Compaction Intelligence (PR #51) ├── WP-N3 ✅ Algorithm Awareness (PR #52+#53) -└── WP-N4 ✅ LSP + Fork Documentation (PR #53) +├── WP-N4 ✅ LSP + Fork Documentation (PR #53) +├── WP-N5 ✅ Plan Update (PR #54) +└── WP-N6 🔄 System Self-Awareness (PR #55) ``` --- -## Summary (Updated 2026-03-11) +## Summary (Updated 2026-03-12) -| Metric | 2026-03-08 | **Current (2026-03-11)** | -|--------|------------|--------------------------| -| Port WPs done | 8 ✅ | **9 ✅ (WP-E merged PR #48)** | -| Native WPs done | 0 | **4 ✅ (WP-N1–N4, PR #50–#53)** | -| Open PRs | 2 (C, D) | **1 (WP-N5 #54 in progress)** | -| Remaining native work | Not planned | **WP-N5 (docs sync), WP-N6 (system awareness)** | +| Metric | 2026-03-08 | 2026-03-11 | **Current (2026-03-12)** | +|--------|------------|------------|--------------------------| +| Port WPs done | 8 ✅ | 9 ✅ (WP-E) | **9 ✅** | +| Native WPs done | 0 | 4 ✅ (N1–N4) | **5 ✅ (N1–N5), N6 in progress** | +| Open PRs | 2 (C, D) | 1 (#55) | **1 (#55 — open, in progress)** | +| Remaining native work | Not planned | WP-N6 in progress | **WP-N6 in progress (#55), then WP-N7 planned** | -**Status:** Port complete (WP-E merged). Native transformation underway — WP-N1 through WP-N4 shipped. WP-N5 (plan sync) and WP-N6 (system self-awareness) remain. +**Status:** Port complete. Native transformation: WP-N1 through WP-N5 merged. WP-N6 in progress (PR #55 open). WP-N7 planned (Obsidian CLI + Agent Matrix). **Native transformation plan:** `docs/epic/EPIC-v3.0-OpenCode-Native.md` **Full gap analysis:** `docs/epic/GAP-ANALYSIS-v3.0.md` @@ -229,3 +233,4 @@ Current state (dev branch): *Correction 1 (2026-03-06): Fixed WP3 completion status — was never fully done* *Correction 2 (2026-03-08): WP-A (#42) + WP-B (#43) merged; WP-C scope verified against v4.0.3 upstream* *Correction 3 (2026-03-11): WP-N1–N4 complete (PR #50–#53); WP-N5 plan sync in progress* +*Correction 4 (2026-03-12): WP-N5 merged (PR #54); WP-N6 in progress (PR #55 open); WP-N7 planned* diff --git a/docs/epic/TODO-v3.0.md b/docs/epic/TODO-v3.0.md index 806d7e09..c4ae939a 100644 --- a/docs/epic/TODO-v3.0.md +++ b/docs/epic/TODO-v3.0.md @@ -9,7 +9,7 @@ date: 2026-03-10 > [!NOTE] > **Basis:** Gap-Analysis 2026-03-06 | Reference: `GAP-ANALYSIS-v3.0.md` | Plan: `OPTIMIZED-PR-PLAN.md` -> **Updated:** 2026-03-11 — WP-N1 through WP-N4 complete (PR #50–#53). WP-N5 next. +> **Updated:** 2026-03-12 — WP-N1 through WP-N5 complete (PR #50–#54). WP-N6 in progress. --- @@ -32,6 +32,7 @@ WP-N2 ████████████ 100% ✅ ← Compaction Intelligence WP-N3 ████████████ 100% ✅ ← Algorithm Awareness complete, PR #52+#53 WP-N4 ████████████ 100% ✅ ← LSP + Fork Documentation complete, PR #53 WP-N5 ████████████ 100% ✅ ← Plan Update complete, PR #54 +WP-N6 ██████████░░ 85% 🔄 ← System Self-Awareness, PR #55 (fix commit pending) ``` > **The port is done. The native transformation starts with WP-N1.** @@ -426,22 +427,41 @@ graph TD --- -### WP-N6: System Self-Awareness — ⏳ Planned +### WP-N6: System Self-Awareness — 🔄 In Progress (PR #55) **Branch:** `feature/wp-n6-system-awareness` **Spec:** ADR-017 **Dependencies:** WP-N3 (Algorithm Awareness) + WP-N4 (LSP/Fork documented) **Goal:** Algorithm understands its operating environment -- [ ] Create `.opencode/skills/OpenCodeSystem/SKILL.md` with USE WHEN triggers -- [ ] Create `SystemArchitecture.md` — PAI-OpenCode 3.0 structure -- [ ] Create `ToolReference.md` — all native + MCP tools -- [ ] Create `Configuration.md` — settings.json, opencode.json, model routing -- [ ] Create `Troubleshooting.md` — self-diagnostic checklist -- [ ] Create ADR-017: System Self-Awareness -- [ ] Integration test: Algorithm consults skill when stuck +- [x] Create `.opencode/skills/OpenCodeSystem/SKILL.md` with USE WHEN triggers +- [x] Create `SystemArchitecture.md` — PAI-OpenCode 3.0 structure +- [x] Create `ToolReference.md` — all native + MCP tools +- [x] Create `Configuration.md` — settings.json, opencode.json, model routing +- [x] Create `Troubleshooting.md` — self-diagnostic checklist +- [x] Create ADR-017: System Self-Awareness +- [x] Update skill-index.json with OpenCodeSystem entry +- [x] Update ADR README + TODO + OPTIMIZED-PR-PLAN +- [x] Fix: Remove hardcoded model names → tier-only references +- [x] Fix: Add YAML frontmatter + Obsidian callouts to all docs +- [x] Fix: Add `permission.asked` hook to SystemArchitecture.md +- [x] Fix: Safe rsync in Troubleshooting.md (was unsafe mv) +- [x] Fix: Restructure SKILL.md to PAI v3.0 schema (MANDATORY/OPTIONAL) +- [x] Fix: Add `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` to .env.example +- [x] Fix: MCP detection uses grep (no cat pipe), searches both keys + +--- + +### WP-N7: Obsidian CLI + Agent Capability Matrix — 📋 Planned +**Branch:** TBD +**Dependencies:** WP-N6 +**Goal:** Obsidian formatting guidelines + agent permissions/tools/MCP capability matrix + +- [ ] Obsidian CLI integration guide (frontmatter, callouts, collapsible sections) +- [ ] Formatting guidelines document for all PAI-OpenCode docs +- [ ] Agent capability matrix (permissions, tools, MCP access per agent type) --- *Created: 2026-03-06* -*Updated: 2026-03-11 — WP-N1 through WP-N4 complete (PR #50–#53); WP-N5 next; WP-N6 System Awareness defined* +*Updated: 2026-03-12 — WP-N1 through WP-N5 complete (PR #50–#54); WP-N6 in progress (PR #55 open); WP-N7 planned* *Basis: GAP-ANALYSIS-v3.0.md + EPIC-v3.0-Synthesis-Architecture.md + EPIC-v3.0-OpenCode-Native.md*