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
• OPENCODECOMMANDMAPPINGS - Line 242 - Commands to copy for OpenCode
• CODEXSKILLMAPPINGS - Line ~280 - Skills to create for Codex

OPENCODECOMMANDMAPPINGS format:

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

CODEXSKILLMAPPINGS 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: MCPSERVERVERSION

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 AISTATEDIR

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
• Commands: /next-task, /ship, /deslop, /audit-project, /drift-detect, /enhance, /perf, /sync-docs, /repo-intel

installForOpenCode(installDir, options) - Line 165

• Creates dirs: ~/.config/opencode/commands/, ~/.config/opencode/plugins/agentsys.ts
• Copies native plugin from adapters/opencode-plugin/
• Transforms commands using OPENCODECOMMANDMAPPINGS
• Transforms agents (tools → permissions, strips models if --strip-models)
• Updates ~/.config/opencode/opencode.json with MCP config

installForCodex(installDir) - Line 330+

• Creates dir: ~/.codex/skills/
• Creates SKILL.md files using CODEXSKILLMAPPINGS
• Each skill gets trigger-phrase description
• Updates ~/.codex/config.toml with MCP config

Command Mappings (OpenCode)

OPENCODECOMMANDMAPPINGS - Line ~242:

const commandMappings = [
  ['deslop.md', 'deslop', 'deslop.md'],
  ['enhance.md', 'enhance', 'enhance.md'],
  ['next-task.md', 'next-task', 'next-task.md'],
  ['delivery-approval.md', 'next-task', 'delivery-approval.md'],
  ['sync-docs.md', 'sync-docs', 'sync-docs.md'],
  ['audit-project.md', 'audit-project', 'audit-project.md'],
  ['drift-detect.md', 'drift-detect', 'drift-detect.md'],
  ['repo-intel.md', 'repo-intel', 'repo-intel.md'],
  ['perf.md', 'perf', 'perf.md'],
  ['ship.md', 'ship', 'ship.md']
];

Skill Mappings (Codex)

CODEXSKILLMAPPINGS - Line ~280+:

const skillMappings = [
  ['next-task', 'next-task', 'next-task.md',
    'Use when user asks to "find next task", "automate workflow". Master workflow orchestrator.'],
  ['ship', 'ship', 'ship.md',
    'Use when user asks to "create PR", "ship changes", "merge PR". Complete PR workflow.'],
  // ... 7 more
];

Adding New Features (Step-by-Step)

New Command (e.g., /my-command)

1. Create command file:

plugins/my-plugin/commands/my-command.md

2. Update bin/cli.js - 3 locations:

a) PLUGINS_ARRAY (if new plugin):

// Line ~138
const plugins = ['next-task', 'ship', ..., 'my-plugin'];

b) OPENCODECOMMANDMAPPINGS:

// Line ~242
['my-command.md', 'my-plugin', 'my-command.md'],

c) CODEXSKILLMAPPINGS:

// Line ~280
['my-command', 'my-plugin', 'my-command.md',
  'Use when user asks to "trigger phrase". Description of capability.'],

3. Update marketplace.json:

// .claude-plugin/marketplace.json - Add to plugins array
{
  "name": "my-plugin",
  "version": "3.5.0",
  "description": "...",
  "path": "plugins/my-plugin"
}

4. Create plugin.json:

plugins/my-plugin/.claude-plugin/plugin.json

5. Update docs:

• docs/INSTALLATION.md - Add install command
• README.md - Add to commands table
• CHANGELOG.md - Add under "Added"

6. Validate:

npm run validate  # Will catch missing mappings

New Agent (e.g., my-agent)

1. Create agent file:

plugins/my-plugin/agents/my-agent.md

With proper frontmatter:

---
name: my-agent
description: Brief description
tools: Bash(git:*), Read, Edit
model: sonnet
---

2. Installer handles automatically:

• ✅ Copies to ~/.config/opencode/agents/my-agent.md
• ✅ Transforms frontmatter (tools → permissions)
• ✅ Strips model if --strip-models flag
• ✅ Normalizes Windows paths in require()

3. No Codex changes needed - Codex uses MCP, not agents

4. Validate:

npm run validate:counts  # Will update agent count if added

New Skill (e.g., my-skill)

1. Create skill directory and file:

plugins/my-plugin/skills/my-skill/SKILL.md

With frontmatter:

---
name: my-skill
description: "Use when user asks to \"trigger\". Description."
metadata:
  short-description: "Brief"
---

2. If user-invocable (Codex): Add to CODEXSKILLMAPPINGS in bin/cli.js

3. Validate:

npm run validate:counts  # Will check skill count matches

New MCP Tool

1. Add to mcp-server/index.js:

a) TOOLS array:

const TOOLS = [
  // ...
  {
    name: 'my_tool',
    description: 'Tool description',
    inputSchema: {
      type: 'object',
      properties: { param: { type: 'string' } },
      required: ['param']
    }
  }
];

b) toolHandlers object:

const toolHandlers = {
  // ...
  my_tool: async (params) => {
    // Implementation
    return xplat.successResponse({ result: 'data' });
  }
};

2. Update marketplace.json:

// .claude-plugin/marketplace.json
"mcpServer": {
  "tools": ["workflow_status", ..., "my_tool"]
}

3. Update docs:

• README.md - Add to features if user-facing

Common Release Pitfalls (And How Validators Catch Them)

Pitfall 1: Forgot to Update Plugin Version

# Symptoms:
- package.json says 3.6.0
- plugins/next-task/.claude-plugin/plugin.json says 3.5.0

# Caught by:
npm run validate:counts
# → [ERROR] Version misalignment

Pitfall 2: Hardcoded .claude/ Path

# Symptoms:
- Agent contains: `.claude/flow.json`
- OpenCode and Codex break

# Caught by:
npm run validate:paths
# → [ERROR] Hardcoded path found in agents/my-agent.md:42

Pitfall 3: Agent Count Mismatch

# Symptoms:
- Added new agent
- README still says "39 agents"
- Actually 40 now

# Caught by:
npm run validate:counts
# → [ERROR] README.md agents: Expected 40, Actual 39

Pitfall 4: Missing Trigger Phrase (Codex)

# Symptoms:
- Codex skill has: description: "Master orchestrator"
- No trigger phrases
- Codex doesn't know when to invoke

# Caught by:
/enhance --focus=skills
# → [MEDIUM] Description missing trigger phrases

Pitfall 5: OpenCode Label Too Long

# Symptoms:
- AskUserQuestion label: "#123: Fix authentication timeout in ProfileScreen component"
- 65 characters
- OpenCode throws error

# Prevention:
Use truncateLabel() function in task-discoverer agent
Max 30 chars for OpenCode compatibility

Pitfall 6: Forgot to Run /enhance

# Symptoms:
- Modified agents/skills
- Didn't run /enhance
- Pushed anyway

# Caught by:
Pre-push hook prompts: "Have you run /enhance? (y/N)"
Blocks push if "N"

Automation Opportunities (Always Consider)

Current Automations

1. ✅ lib/ sync - Pre-commit hook auto-syncs lib/ to plugins/
2. ✅ Validation - Pre-push hook runs 6 validators
3. ✅ Agent transformation - Installer auto-transforms frontmatter
4. ✅ Model stripping - --strip-models flag for OpenCode
5. ✅ Version checking - validate:counts catches misalignment
6. ✅ Path checking - validate:paths catches hardcoded paths
7. ✅ /enhance enforcement - Pre-push hook prompts

Potential Improvements

1. Version Bump Automation

# Current: Manual find/replace in 11 files
# Opportunity: Script that updates all version fields atomically
# Script: scripts/bump-version.js <new-version>

2. CHANGELOG Entry Generation

# Current: Manual entry creation
# Opportunity: Parse git log since last tag, categorize commits
# Script: scripts/generate-changelog-entry.js

3. Cross-Platform Install Test

# Current: Manual testing on each platform
# Opportunity: Docker containers for each platform, automated smoke tests
# Script: scripts/test-install-all-platforms.sh

4. Agent Count Auto-Update

# Current: Manual count updates in docs
# Opportunity: Extract counts from filesystem, update docs automatically
# Script: scripts/update-doc-counts.js

5. Marketplace.json Sync

# Current: Manual updates to .claude-plugin/marketplace.json
# Opportunity: Generate from plugins/ directory structure
# Script: scripts/sync-marketplace-manifest.js

If you identify more automation opportunities, ADD THEM HERE.

Your Responsibilities (Agent Using This Skill)

Before Push

1. Run validations:

``bash npm run validate `` Fix any issues found.

1. If modified enhanced content (agents/skills/hooks/prompts):

``bash /enhance `` Address HIGH certainty findings.

1. Check for misalignments in this skill:

- New script added but not documented here? - New platform difference discovered? - New validation pattern needed? - UPDATE THIS FILE if yes

1. Think about automation:

- Can this manual step be automated? - Is there a pattern we're repeating? - ADD to "Potential Improvements" section

Before Release

1. Read release checklist:

``bash cat checklists/release.md ``

1. Update all 11 version fields:

- Use version bump script (if exists) or manual find/replace - Validate: npm run validate:counts

1. Update CHANGELOG.md:

- Add entry at top with date - Categorize: Added/Changed/Fixed/Removed

1. Run full validation:

``bash npm test # 1400+ tests npm run validate # All 6 validators npm pack --dry-run # Package builds ``

1. Test cross-platform install:

``bash npm pack npm install -g ./agentsys-*.tgz echo "1 2 3" | agentsys # Test installer ``

1. Commit and tag:

``bash git add -A git commit -m "chore: release v3.X.0-rc.N" git tag v3.X.0-rc.N git push origin main --tags ``

1. Verify npm publish:

``bash # Wait for GitHub Actions release workflow npm view agentsys@rc version # For RC npm view agentsys version # For production ``

Update Misalignments

If you find any of these while working:

New script not documented here:

1. Read the script to understand what it does
2. Add to relevant section (Validation Suite, Installation, etc.)
3. Commit: "docs(maintain-cross-platform): document {script-name}"

New platform difference discovered:

1. Test on all 3 platforms to confirm
2. Add to "Platform Differences" matrix
3. Add to "Common Pitfalls" if it causes issues
4. Update relevant validation script if needed

New validation pattern needed:

1. Consider: Can existing validator be extended?
2. If new validator needed, create in scripts/validate-{name}.js
3. Add to package.json validate script
4. Document in "Validation Suite" section
5. Update "Pre-Push Hook" section if relevant

Automation opportunity identified:

1. Add to "Potential Improvements" with description
2. Estimate effort (simple/medium/complex)
3. Note dependencies (tools needed, testing required)

Quick Reference: File Counts

Plugins: 9

1. next-task
2. enhance
3. ship
4. perf
5. audit-project
6. deslop
7. drift-detect
8. repo-intel
9. sync-docs

Agents: 39 total = 29 file-based + 10 role-based

File-based (29): Count files in plugins//agents/.md

• next-task: 12
• enhance: 9
• perf: 6
• drift-detect: 1
• repo-intel: 1

Role-based (10): Defined inline in audit-project command

• code-quality-reviewer, security-expert, performance-engineer, test-quality-guardian
• architecture-reviewer, database-specialist, api-designer
• frontend-specialist, backend-specialist, devops-reviewer

Skills: 23 - Count SKILL.md in plugins//skills//SKILL.md

• next-task: 1 (discover-tasks)
• prepare-delivery: 4 (prepare-delivery, check-test-coverage, orchestrate-review, validate-delivery)
• enhance: 10 (orchestrator, reporter, agent-prompts, claude-memory, docs, plugins, prompts, hooks, skills)
• perf: 8 (analyzer, baseline, benchmark, code-paths, investigation-logger, profile, theory, theory-tester)
• drift-detect: 1 (drift-analysis)
• repo-intel: 1 (repo-intel)

Version Fields: 11 files

• 1x package.json
• 1x .claude-plugin/plugin.json
• 9x plugins/*/.claude-plugin/plugin.json
• 1x mcp-server/index.js (MCPSERVERVERSION constant)

Constraints

• NEVER break existing functionality - Production project with real users
• ALWAYS test on all 3 platforms - At least smoke test
• ALWAYS update this skill - If you find gaps or improvements
• ALWAYS run validation - Pre-push hook enforces this
• Documentation must stay accurate - Validators enforce this

Output Format

When using this skill, output:

## Cross-Platform Compatibility Check

### Validations Run
- [OK/ERROR] validate:plugins
- [OK/ERROR] validate:cross-platform
- [OK/ERROR] validate:consistency
- [OK/ERROR] validate:paths
- [OK/ERROR] validate:counts
- [OK/ERROR] validate:platform-docs

### Issues Found
[List any issues with file:line references]

### Misalignments in This Skill
[List any outdated information found in this skill]

### Automation Opportunities
[List any manual steps that could be automated]

### Actions Taken
[List files updated/created]

### Next Steps
[List remaining work]

Version

Skill Version: 1.0.0 Last Updated: 2026-01-30 Covers: AgentSys v5.0.0 architecture

Update this skill when:

• New platform added
• New validation script created
• Installation process changes
• New automation implemented
• Platform differences discovered