with one click
maintain-cross-platform
// Use when preparing releases, validating cross-platform compatibility, or updating installation infrastructure. Meta-skill for maintaining AgentSys's 3-platform architecture.
// Use when preparing releases, validating cross-platform compatibility, or updating installation infrastructure. Meta-skill for maintaining AgentSys's 3-platform architecture.
Use when user asks to "discover tasks", "find next task", "prioritize issues", "what should I work on", or "list open issues". Discovers and ranks tasks from GitHub, GitLab, local files, and custom sources.
Use when user asks to "run repo intel", "generate repo map", "analyze repo", "query hotspots", "check ownership", or "bus factor". Unified static analysis - git history, AST symbols, project metadata.
Use when mapping code paths, entrypoints, and likely hot files before profiling.
Use when generating performance hypotheses backed by git history and code evidence.
Structured AI debate templates and synthesis. Use when orchestrating multi-round debates between AI tools, 'debate topic', 'argue about', 'stress test idea', 'devil advocate'.
Use when user wants to clean AI slop from code. Use for cleanup, remove debug statements, find ghost code, repo hygiene.
| 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"} |
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.
| 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 | 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/ |
| 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 |
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 | 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 |
| 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 |
Search markers in bin/cli.js:
PLUGINS_ARRAY - Line 138 - Plugins to install for Claude CodeOPENCODE_COMMAND_MAPPINGS - Line 242 - Commands to copy for OpenCodeCODEX_SKILL_MAPPINGS - Line ~280 - Skills to create for CodexOPENCODE_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"']
All must have SAME version for releases:
package.json - Line 3.claude-plugin/plugin.json - Root plugin.claude-plugin/marketplace.json - 9 plugin entriesmcp-server/index.js - Search: MCP_SERVER_VERSION
5-13. plugins/*/. claude-plugin/plugin.json - All 9 pluginsQuick check:
grep -r '"version"' package.json plugins/*/.claude-plugin/plugin.json .claude-plugin/plugin.json
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
Same as RC but:
-rc.N suffix from versionv3.X.0 (no suffix)latest tag automaticallynpm run validate (includes all 6 validators)npm test (1400+ tests)npm pack --dry-runplugins/*/ with .claude-plugin/plugin.jsonplugins/*/commands/*.md filescodex-description frontmatter in command files/plugin install <name>@agentsys lineplugins array~/.config/opencode/agents/mcpServer.tools array./scripts/sync-lib.sh (or agentsys-dev sync-lib) copies lib/ to all 9 plugins1. 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.
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
File: scripts/validate-plugins.js
Checks:
Exit 1 if: Invalid plugin.json
File: scripts/validate-cross-platform.js
Checks:
Exit 1 if: Platform-specific code detected
File: scripts/validate-repo-consistency.js
Checks:
Exit 1 if: Inconsistencies found
File: scripts/check-hardcoded-paths.js
Checks:
.claude/ paths in agents/commands/skillsPatterns detected:
/\.claude\/(?!.*\(example\)|.*Platform|.*State directory)/
/\.opencode\/(?!.*\(example\)|.*Platform)/
/\.codex\/(?!.*\(example\)|.*Platform)/
Safe contexts (skipped):
| State Dir |)Exit 1 if: Hardcoded paths found outside safe contexts
File: scripts/validate-counts.js
Checks:
Actual counts (filesystem):
plugins/plugins/*/agents/plugins/*/skills/*/SKILL.mdSmart validation:
Exit 1 if: Count mismatches or version misalignment
File: scripts/validate-cross-platform-docs.js
Checks:
Smart validation:
enhance-claude-memory)Exit 1 if: Platform conflicts or missing features
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/*.mdskills/*/SKILL.mdhooks/*.mdprompts/*.mdPrompts: "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*):
npm testnpm pack --dry-runSkip hook: git push --no-verify (use with caution)
~/.agentsys/ if exists~/.agentsys/npm install --production in package and mcp-serverinstallForClaude() - Line 116
claude plugin marketplace add agent-sh/agentsysclaude plugin install {plugin}@agentsysinstallForOpenCode(installDir, options) - Line 165
~/.config/opencode/commands/, ~/.config/opencode/plugins/agentsys.tsadapters/opencode-plugin/OPENCODE_COMMAND_MAPPINGS~/.config/opencode/opencode.json with MCP configinstallForCodex(installDir) - Line 330+
~/.codex/skills/CODEX_SKILL_MAPPINGS~/.codex/config.toml with MCP configOPENCODE_COMMAND_MAPPINGS - 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']
];
CODEX_SKILL_MAPPINGS - 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
];
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) OPENCODE_COMMAND_MAPPINGS:
// Line ~242
['my-command.md', 'my-plugin', 'my-command.md'],
c) CODEX_SKILL_MAPPINGS:
// 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 commandREADME.md - Add to commands table6. Validate:
npm run validate # Will catch missing mappings
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:
~/.config/opencode/agents/my-agent.md3. No Codex changes needed - Codex uses MCP, not agents
4. Validate:
npm run validate:counts # Will update agent count if added
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 CODEX_SKILL_MAPPINGS in bin/cli.js
3. Validate:
npm run validate:counts # Will check skill count matches
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# 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
# 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
# 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
# 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
# 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
# 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"
--strip-models flag for OpenCode1. 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.
Run validations:
npm run validate
Fix any issues found.
If modified enhanced content (agents/skills/hooks/prompts):
/enhance
Address HIGH certainty findings.
Check for misalignments in this skill:
Think about automation:
Read release checklist:
cat checklists/release.md
Update all 11 version fields:
npm run validate:countsUpdate CHANGELOG.md:
Run full validation:
npm test # 1400+ tests
npm run validate # All 6 validators
npm pack --dry-run # Package builds
Test cross-platform install:
npm pack
npm install -g ./agentsys-*.tgz
echo "1 2 3" | agentsys # Test installer
Commit and tag:
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
Verify npm publish:
# Wait for GitHub Actions release workflow
npm view agentsys@rc version # For RC
npm view agentsys version # For production
If you find any of these while working:
New script not documented here:
New platform difference discovered:
New validation pattern needed:
scripts/validate-{name}.jspackage.json validate scriptAutomation opportunity identified:
Plugins: 9
Agents: 39 total = 29 file-based + 10 role-based
File-based (29): Count files in plugins/*/agents/*.md
Role-based (10): Defined inline in audit-project command
Skills: 23 - Count SKILL.md in plugins/*/skills/*/SKILL.md
Version Fields: 11 files
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]
Skill Version: 1.0.0 Last Updated: 2026-01-30 Covers: AgentSys v5.0.0 architecture
Update this skill when: