---
title: "Maintain Cross-Platform Architecture"
description: "**Purpose:** Comprehensive knowledge of AgentSys's cross-platform infrastructure for release preparation, validation, and maintenance."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/skill-34
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:44:36.198Z
license: CC-BY-4.0
attribution: "Maintain Cross-Platform Architecture — Claudary (https://claudary.paisolsolutions.com/skills/skill-34)"
---

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

## Overview

---
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:**

```yaml
# 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:**

```yaml
# 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:**
```javascript
['dest-file.md', 'plugin-name', 'source-file.md']
```

**CODEX_SKILL_MAPPINGS format:**
```javascript
['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` - 9 plugin entries
4. `mcp-server/index.js` - Search: `MCP_SERVER_VERSION`
5-13. `plugins/*/. claude-plugin/plugin.json` - All 9 plugins

**Quick check:**
```bash
grep -r '"version"' package.json plugins/*/.claude-plugin/plugin.json .claude-plugin/plugin.json
```

---

## Release Process (RC and Production)

### RC Release (3.X.0-rc.N)

**Step 1: Update Versions**
```bash
# Bump to RC version in ALL 11 files
NEW_VERSION="3.6.0-rc.1"

# package.json
npm version $NEW_VERSION --no-git-tag-version

# All plugin.json files (9 plugins + root)
find . -name "plugin.json" -path "*/.claude-plugin/*" -exec sed -i '' "s/\\"version\\": \\".*\\"/\\"version\\": \\"$NEW_VERSION\\"/" {} \\;

# mcp-server/index.js
sed -i '' "s/version: '.*'/version: '$NEW_VERSION'/" mcp-server/index.js
```

**Step 2: Update CHANGELOG.md**
```markdown
## [3.6.0-rc.1] - 2026-01-30

### Added
- Feature description

### Changed
- Change description

### Fixed
- Bug fix description
```

**Step 3: Validate**
```bash
npm run validate    # All 6 validators
npm test            # All tests
npm pack --dry-run  # Package builds
```

**Step 4: Commit and Tag**
```bash
git add -A
git commit -m "chore: release v3.6.0-rc.1"
git tag v3.6.0-rc.1
git push origin main --tags
```

**Step 5: Verify**
```bash
# Wait for GitHub Actions
npm view agentsys@rc version  # Should show 3.6.0-rc.1
```

### Production Release (3.X.0)

Same as RC but:
- Remove `-rc.N` suffix from version
- Tag with `v3.X.0` (no suffix)
- npm publishes to `latest` tag automatically

---

## What Changes Per Release

### Always Update

1. **Version fields (11 files)** - See "Version Fields" section above
2. **CHANGELOG.md** - Add new entry at top
3. **Run validation** - `npm run validate` (includes all 6 validators)
4. **Run tests** - `npm test` (1400+ tests)
5. **Package build** - `npm pack --dry-run`

### If New Command Added

1. **Convention-based discovery** - Plugins auto-discovered from `plugins/*/` with `.claude-plugin/plugin.json`
2. **Commands auto-discovered** - From `plugins/*/commands/*.md` files
3. **Codex trigger phrases** - Use `codex-description` frontmatter in command files
4. **docs/INSTALLATION.md** - Add `/plugin install <name>@agentsys` line
5. **.claude-plugin/marketplace.json** - Add plugin entry to `plugins` array
6. **README.md** - Add to commands table
7. **Validation will catch** - If counts don't match (plugins count)

### If New Agent Added

1. **No changes needed** - Installer auto-copies agents to OpenCode `~/.config/opencode/agents/`
2. **Codex uses MCP** - Agents not directly supported, use MCP tools instead
3. **Validation will catch** - If file-based agent count changes

### If New Skill Added

1. **Codex requires trigger phrases** - Description must include "Use when user asks to..."
2. **Validation will catch** - If skill count doesn't match

### If New MCP Tool Added

1. **mcp-server/index.js** - Add to TOOLS array and toolHandlers
2. **.claude-plugin/marketplace.json** - Add to `mcpServer.tools` array
3. **bin/cli.js** - Update MCP tools console output (OpenCode + Codex)
4. **README.md** - Add to MCP tools table if user-facing

### If Library Module Changed

1. **lib/{module}/** - Make changes
2. **lib/index.js** - Export if new module
3. **Run sync** - `./scripts/sync-lib.sh` (or `agentsys-dev sync-lib`) copies lib/ to all 9 plugins
4. **Commit both** - Source in lib/ AND copies in plugins/*/lib/

---

## Platform-Specific Transformations (What bin/cli.js Does)

### OpenCode Transformations

**1. Remove Model Specifications (if --strip-models)**
```javascript
// Original (Claude Code):
model: sonnet

// Transformed (OpenCode):
(field removed entirely)
```

**Why:** Not all OpenCode users have access to all three model tiers. Uses user's default model instead.

**2. Transform Tools to Permissions**
```javascript
// Original:
tools: Bash(git:*), Read, Edit, Task

// Transformed:
permission:
  bash: allow
  read: allow
  edit: allow
  task: allow
```

**3. Replace Environment Variables**
```javascript
// Original:
${CLAUDE_PLUGIN_ROOT}

// Transformed:
${PLUGIN_ROOT}
```

**4. Normalize Windows Paths in require()**
```javascript
// Original:
require('${CLAUDE_PLUGIN_ROOT}/lib/module.js')

// Transformed:
require('${PLUGIN_ROOT}'.replace(/\\\\/g, '/') + '/lib/module.js')
```

**Why:** Windows backslashes (`C:\\Users\\...`) break JavaScript string escaping.

### Codex Transformations

**1. Command → Skill Conversion**
```javascript
// Commands become skills with trigger phrases
// Original command: /next-task
// Becomes: $next-task with SKILL.md

// SKILL.md requires:
---
name: next-task
description: "Use when user asks to \\"find next task\\", \\"automate workflow\\". Master orchestrator."
---
```

**2. Agent Logic → Inline in Skills**
- Agents not supported directly in Codex
- Agent workflows embedded in skill instructions
- Or use MCP tools to invoke agent logic

---

## Validation Suite (Pre-Push + CI)

### validate:plugins
**File:** `scripts/validate-plugins.js`
**Checks:**
- plugin.json structure validity
- Required fields present
- Commands/agents/skills exist as declared

**Exit 1 if:** Invalid plugin.json

### validate:cross-platform
**File:** `scripts/validate-cross-platform.js`
**Checks:**
- Code works on all 3 platforms
- No platform-specific assumptions
- Proper use of AI_STATE_DIR

**Exit 1 if:** Platform-specific code detected

### validate:consistency
**File:** `scripts/validate-repo-consistency.js`
**Checks:**
- Repository integrity
- File structure consistency

**Exit 1 if:** Inconsistencies found

### validate:paths
**File:** `scripts/check-hardcoded-paths.js`
**Checks:**
- No hardcoded `.claude/` paths in agents/commands/skills
- Excludes: docs, SKILL.md in enhance/, RESEARCH.md, examples

**Patterns detected:**
```regex
/\\.claude\\/(?!.*\\(example\\)|.*Platform|.*State directory)/
/\\.opencode\\/(?!.*\\(example\\)|.*Platform)/
/\\.codex\\/(?!.*\\(example\\)|.*Platform)/
```

**Safe contexts (skipped):**
- Documentation tables (`| State Dir |`)
- Platform comparison examples
- Skill documentation (enhance/* SKILL.md)
- Checklist references

**Exit 1 if:** Hardcoded paths found outside safe contexts

### validate:counts
**File:** `scripts/validate-counts.js`
**Checks:**
- Plugin count (9) across README, CLAUDE.md, AGENTS.md, package.json, docs
- Agent count (39 total = 29 file-based + 10 role-based) across all docs
- Skill count (23) across all docs
- Version alignment (package.json matches all 10 plugin.json files)
- CLAUDE.md ↔ AGENTS.md critical rules alignment (>90% similarity)

**Actual counts (filesystem):**
- Plugins: 9 directories in `plugins/`
- File-based agents: 29 .md files in `plugins/*/agents/`
- Role-based agents: 10 (from audit-project, defined inline)
- Skills: 23 SKILL.md files in `plugins/*/skills/*/SKILL.md`

**Smart validation:**
- Accepts "39 agents" or "39 agents (29 file-based + 10 role-based)"
- Skips plugin-specific counts like "next-task (12 agents)"
- Only validates top-level totals

**Exit 1 if:** Count mismatches or version misalignment

### validate:platform-docs
**File:** `scripts/validate-cross-platform-docs.js`
**Checks:**
- Command prefix consistency (/ vs $)
- State directory references platform-appropriate
- Feature parity (all 9 commands documented for all platforms)
- Installation instructions consistent
- MCP server configurations correct

**Smart validation:**
- Skips comparison tables
- Skips checklist references
- Skips skill name mentions (like `enhance-claude-memory`)
- Skips documentation examples

**Exit 1 if:** Platform conflicts or missing features

---

## Pre-Push Hook (Automatic Enforcement)

**File:** `scripts/setup-hooks.js` → Creates `.git/hooks/pre-push`

**Phase 1: Validation Suite**
```bash
npm run validate  # Runs all 6 validators
```
Blocks if any validator fails.

**Phase 2: Enhanced Content Check**
Detects modified:
- `agents/*.md`
- `skills/*/SKILL.md`
- `hooks/*.md`
- `prompts/*.md`

Prompts: "Have you run /enhance on these files? (y/N)"
Blocks if "N" (per CLAUDE.md Critical Rule #7).

**Phase 3: Release Tag Validation**
If pushing version tag (v*):
- Runs `npm test`
- Runs `npm pack --dry-run`
- Blocks if either fails

**Skip hook:** `git push --no-verify` (use with caution)

---

## Installer Deep Dive (bin/cli.js)

### Interactive Flow

1. **Platform Selection** - Multi-select: Claude Code, OpenCode, Codex CLI
2. **Clean Old Installation** - Removes `~/.agentsys/` if exists
3. **Copy Package** - From npm global to `~/.agentsys/`
4. **Install Dependencies** - Runs `npm install --production` in package and mcp-server
5. **Per-Platform Installation:**
   - Claude Code: Adds marketplace, installs 9 plugins
   - OpenCode: Copies commands, agents; updates config; installs native plugin
   - Codex: Creates skills with trigger phrases; updates config

### Key Functions

**installForClaude()** - Line 116
- Adds marketplace: `claude plugin marketplace add agent-sh/agentsys`
- Installs 9 plugins: `claude plugin install {plugin}@agentsys

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/skill-34) · https://claudary.paisolsolutions.com