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

Component Locations

Install Locations (This Repo)

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

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

Validation Scripts (All in CI + Pre-Push)

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 JavaScript string escaping.

Codex Transformations

1. Command → Skill Conversion

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

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

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