maintain-cross-platform

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

Quick check:

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

# 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

## [3.6.0-rc.1] - 2026-01-30

### Added
- Feature description

### Changed
- Change description

### Fixed
- Bug fix description

Step 3: Validate

npm run validate    # All 6 validators
npm test            # All tests
npm pack --dry-run  # Package builds

Step 4: Commit and Tag

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

# 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)

// 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

// Original:
tools: Bash(git:*), Read, Edit, Task

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

3. Replace Environment Variables

// Original:
${CLAUDE_PLUGIN_ROOT}

// Transformed:
${PLUGIN_ROOT}

4. Normalize Windows Paths in require()

// Original:
require('${CLAUDE_PLUGIN_ROOT}/lib/module.js')

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

Why: Windows backslashes (C:\Users\...) break JavaSc

---

Content truncated.