/maintain-cross-platform

name: maintain-cross-platform
description: "Use when preparing releases, validating cross-platform compatibility, or updating installation infrastructure. Meta-skill for maintaining AgentSys's 3-platform architecture."
metadata:
  short-description: "Meta-skill: maintain 3-platform architecture"
  scope: local
  audience: repo-maintainers

Maintain Cross-Platform Architecture

**Purpose:** Comprehensive knowledge of AgentSys's cross-platform infrastructure for release preparation, validation, and maintenance.

**Scope:** LOCAL skill for this repository only. Contains specific file locations, transformation rules, and automation patterns for maintaining Claude Code + OpenCode + Codex CLI compatibility.

Critical Rules

1. **3 platforms MUST work** - Claude Code, OpenCode, Codex CLI. No exceptions. 2. **Validation before every push** - Pre-push hook runs 6 validators automatically. 3. **All version fields must align** - 11 files total (package.json + 10 plugin.json files). 4. **Documentation must be accurate** - Counts, paths, and platform references validated by CI. 5. **Update this skill** - If you find misalignments or automation opportunities, update this file.

---

Platform Differences (The Complete Matrix)

Configuration

| Aspect | Claude Code | OpenCode | Codex CLI | |--------|-------------|----------|-----------| | **Config format** | JSON | JSON/JSONC | TOML | | **Config location** | `~/.claude/settings.json` | `~/.config/opencode/opencode.json` | `~/.codex/config.toml` | | **State directory** | `.claude/` | `.opencode/` | `.codex/` | | **Command prefix** | `/` | `/` | `$` | | **Project instructions** | `CLAUDE.md` | `AGENTS.md` (reads CLAUDE.md) | `AGENTS.md` |

Component Locations

| Component | Claude Code | OpenCode | Codex CLI | |-----------|-------------|----------|-----------| | **Commands** | Plugin `commands/` | `~/.config/opencode/commands/` | N/A (use skills) | | **Agents** | Plugin `agents/` | `~/.config/opencode/agents/` | N/A (use MCP) | | **Skills** | Plugin `skills/` | `.opencode/skills/` (singular) | `~/.codex/skills/` | | **Hooks** | Plugin `hooks/` | Plugin `hooks/` | Plugin `hooks/` |

Install Locations (This Repo)

| Platform | Package Copy | Commands | Agents | Skills | Config | |----------|--------------|----------|--------|--------|--------| | Claude Code | Via marketplace | Plugin bundled | Plugin bundled | Plugin bundled | N/A | | OpenCode | `~/.agentsys/` | `~/.config/opencode/commands/` | `~/.config/opencode/agents/` (29 files) | N/A | `~/.config/opencode/opencode.json` | | Codex CLI | `~/.agentsys/` | N/A | N/A | `~/.codex/skills/` (9 directories) | `~/.codex/config.toml` |

Frontmatter Differences

**Command Frontmatter:**

# Claude Code
---
description: Task description
argument-hint: "[args]"
allowed-tools: Bash(git:*), Read, Task
---

# OpenCode (transformed by installer)
---
description: Task description
agent: general
# model field REMOVED (uses user's default model)
---

# Codex (skills use different format)
---
name: skill-name
description: "Use when user asks to \"trigger\". Does X."
---

**Agent Frontmatter:**

# Claude Code
---
name: agent-name
description: Agent description
tools: Bash(git:*), Read, Edit, Task
model: sonnet
---

# OpenCode (transformed by installer)
---
name: agent-name
description: Agent description
mode: subagent
# model field REMOVED (OpenCode doesn't support per-agent models yet)
permission:
  read: allow
  edit: allow
  bash: ask
  task: allow
---

**Transformation Rules (bin/cli.js handles this):**

| Claude Code | OpenCode | |-------------|----------| | `tools: Bash(git:*)` | `permission: { bash: "allow" }` | | `tools: Read` | `permission: { read: "allow" }` | | `tools: Edit, Write` | `permission: { edit: "allow" }` | | `tools: Task` | `permission: { task: "allow" }` | | `model: sonnet/opus/haiku` | **REMOVED** (OpenCode uses user default) |

**CRITICAL:** The `--strip-models` flag in `bin/cli.js` removes model specifications for OpenCode users who don't have access to all three model tiers.

---

File Locations (This Repository)

Installation Infrastructure

| File | Purpose | |------|---------| | `bin/cli.js` | Main installer (811 lines) - handles all 3 platforms | | `scripts/setup-hooks.js` | Git hooks installer (pre-commit, pre-push) | | `adapters/opencode-plugin/` | Native OpenCode TypeScript plugin | | `adapters/opencode/` | OpenCode install script (legacy) | | `adapters/codex/` | Codex install script (legacy) | | `mcp-server/index.js` | Cross-platform MCP server |

Validation Scripts (All in CI + Pre-Push)

| Script | What It Validates | Exit 1 If | |--------|-------------------|-----------| | `scripts/validate-plugins.js` | Plugin structure, plugin.json validity | Invalid plugin.json | | `scripts/validate-cross-platform.js` | 3-platform compatibility | Platform-specific code | | `scripts/validate-repo-consistency.js` | Repo integrity | Inconsistencies | | `scripts/check-hardcoded-paths.js` | No hardcoded `.claude/` paths | Hardcoded paths found | | `scripts/validate-counts.js` | Doc accuracy (agents, plugins, skills, versions) | Count mismatches | | `scripts/validate-cross-platform-docs.js` | Platform docs consistency | Doc conflicts |

Transformation Mappings (bin/cli.js)

**Search markers in bin/cli.js:**

• `PLUGINS_ARRAY` - Line 138 - Plugins to install for Claude Code
• `OPENCODE_COMMAND_MAPPINGS` - Line 242 - Commands to copy for OpenCode
• `CODEX_SKILL_MAPPINGS` - Line ~280 - Skills to create for Codex

**OPENCODE_COMMAND_MAPPINGS format:**

['dest-file.md', 'plugin-name', 'source-file.md']

**CODEX_SKILL_MAPPINGS format:**

['skill-name', 'plugin-name', 'source-file.md', 'Trigger description with "phrases"']

Version Fields (11 Files Total)

All must have SAME version for releases:

1. `package.json` - Line 3 2. `.claude-plugin/plugin.json` - Root plugin 3. `.claude-plugin/marketplace.json` -