Cross-Platform Integration Guide

Build tools once, run everywhere. The core workflows are the same regardless of which AI assistant you use. Platform differences are abstracted away—state files, configuration paths, and command syntax adapt automatically. You get the same automation whether you're using Claude Code, OpenCode, or Codex CLI.

---

Quick Navigation

---

Supported Platforms

Note: Codex CLI uses $ prefix for skills (e.g., $next-task, $ship) instead of / slash commands.

Common Architecture

All five platforms share:

1. Agent/Subagent systems - Specialized assistants with tool restrictions
2. Slash commands - User-invoked actions
3. Configuration files - JSON/YAML/Markdown formats
4. Platform-aware state directories - Automatic state isolation

Command Arguments ($ARGUMENTS)

Claude Code passes a raw $ARGUMENTS string into commands. Commands should parse the raw string locally (including quoted values) to match Claude Code behavior.

For OpenCode and Codex CLI, the installer adapts the platform argument handling to preserve $ARGUMENTS as a raw string. This keeps parsing consistent across platforms without changing command content.

Claude Code (Native)

Option 1: Marketplace (Recommended)

# Add the marketplace
/plugin marketplace add agent-sh/agentsys

# Install plugins
/plugin install next-task@agentsys
/plugin install ship@agentsys

Option 2: npm Global Install

npm install -g agentsys@latest
agentsys  # Select option 1 for Claude Code

# Or non-interactive:
agentsys --tool claude

Option 3: Development Mode (Testing RC Versions)

Install directly to ~/.claude/plugins/ bypassing the marketplace:

agentsys --development

Option 4: Plugin Directory (Local Development)

claude --plugin-dir /path/to/agentsys/plugins/next-task

Available Commands

• /next-task - Master workflow orchestrator
• /prepare-delivery - Pre-ship quality gates
• /gate-and-ship - Quality gates then ship
• /ship - Complete PR workflow
• /release - Versioned release with ecosystem detection
• /deslop - AI slop cleanup
• /audit-project - Multi-agent code review
• /drift-detect - Plan drift detection
• /repo-intel - Unified static analysis
• /enhance - Enhancement analyzer suite
• /sync-docs - Documentation sync
• /perf - Performance investigation
• /learn - Research topics and create learning guides
• /agnix - Lint agent configuration files
• /consult - Cross-tool AI consultation
• /debate - Structured AI debate
• /web-ctl - Browser automation
• /skillers - Workflow pattern learning
• /onboard - Codebase onboarding
• /can-i-help - Contributor guidance

Available Agents (47 total: 37 file-based agents + 10 role-based)

Key agents shown below:

next-task: Core Workflow (10 agents)

Note: Phase 9 review loop uses inline orchestration (orchestrate-review skill) to spawn parallel Task agents

enhance: Quality Analyzers (9 agents)

perf: Performance Investigation (6 agents)

audit-project: Code Review (10 role-based agents)

Always active: code-quality-reviewer, security-expert, performance-engineer, test-quality-guardian

Conditional: architecture-reviewer, database-specialist, api-designer, frontend-specialist, backend-specialist, devops-reviewer

drift-detect: Drift Detection (1 agent)

Data collection uses JavaScript collectors (77% token reduction vs multi-agent)

repo-intel: Unified Static Analysis (1 agent)

OpenCode Integration

Option 1: npm Global Install (Recommended)

npm install -g agentsys@latest
agentsys  # Select option 2 for OpenCode

# Or non-interactive:
agentsys --tool opencode

By default, model specifications (sonnet/opus/haiku) are stripped from agents. This prevents errors when your OpenCode setup doesn't have matching model aliases. If you have proper model mappings configured, use --no-strip to include them:

agentsys --tool opencode --no-strip

This installs:

• Slash commands (/next-task, /prepare-delivery, /gate-and-ship, /ship, /release, /deslop, /audit-project, /drift-detect, /repo-intel, /enhance, /sync-docs, /perf, /learn, /agnix, /consult, /debate, /web-ctl, /skillers, /onboard, /can-i-help)
• Native OpenCode plugin with advanced features:

Native Plugin Features

The native plugin (~/.config/opencode/plugins/agentsys.ts) provides deep integration:

Agent Thinking Tiers:

Provider-Specific Thinking:

The plugin auto-detects your model provider and applies the correct thinking config:

// Anthropic → thinking.budgetTokens
// OpenAI → reasoningEffort ("high"/"medium"/"low")
// Google → thinkingConfig.thinkingBudget

Option 2: Agent Configuration

Create agent definitions in OpenCode format:

# Global agents
mkdir -p ~/.config/opencode/agent/

# Agent files follow OpenCode markdown format (see below)

OpenCode Agent Format (.opencode/agents/workflow.md):

---
name: workflow-orchestrator
model: claude-sonnet-4-20250514
tools:
  read: true
  write: true
  bash: true
  glob: true
  grep: true
---

You are a workflow orchestrator that manages development tasks.

When invoked, you should:
1. Check for existing workflow state in .claude/workflow-state.json
2. Continue from the last checkpoint if resuming
3. Follow the 18-phase workflow from policy selection to completion

Codex CLI Integration

Note: Codex uses $ prefix for skills instead of / slash commands (e.g., $next-task, $ship).

Option 1: npm Global Install (Recommended)

npm install -g agentsys@latest
agentsys  # Select option 3 for Codex CLI

# Or non-interactive:
agentsys --tool codex

This installs skills to ~/.codex/skills/ ($next-task, $prepare-delivery, $gate-and-ship, $ship, $release, $deslop, $audit-project, $drift-detect, $repo-intel, $enhance, $sync-docs, $perf, $learn, $agnix, $consult, $debate, $web-ctl, $skillers, $onboard, $can-i-help).

Option 2: Custom Skills

Create Codex skills in ~/.codex/skills/<name>/SKILL.md:

---
name: next-task
description: Master workflow orchestrator for task automation
---

# Next Task Workflow

Run `$next-task` to start the master workflow orchestrator.

Shared Libraries

All integrations use the same core libraries:

lib/
├── config/                    # Configuration management
├── cross-platform/            # Platform detection, utilities
├── enhance/                   # Quality analyzer logic
├── patterns/                  # 3-phase slop detection pipeline
│   ├── pipeline.js            # Orchestrates phases
│   ├── slop-patterns.js       # Regex patterns (HIGH certainty)
│   └── slop-analyzers.js      # Multi-pass analyzers (MEDIUM)
├── platform/                  # Project type detection
├── drift-detect/             # Drift detection collectors
├── schemas/                   # JSON schemas for validation
├── sources/                   # Task source discovery
├── state/                     # Workflow state management
├── types/                     # TypeScript-style type definitions
└── utils/                     # Shell escape, context optimization

Platform-Aware State Directories

State files are stored in platform-specific directories:

The plugin auto-detects the platform and uses the appropriate directory. Override with AI_STATE_DIR environment variable.

Files stored in state directory:

• tasks.json - Active task tracking (main project)
• flow.json - Workflow progress (worktree)
• sources/preference.json - Task source preferences

Platform-Specific Considerations

Claude Code

• Full plugin support with hooks, agents, commands
• State directory: .claude/
• Native state management integration
• Best experience with opus model for complex tasks

OpenCode

• Works with any model provider (Claude, OpenAI, Google, local)
• State directory: .opencode/
• Slash commands in ~/.config/opencode/commands/
• Agents in ~/.config/opencode/agents/ (47 agents)
• Skills in ~/.config/opencode/skills/ (42 skills)
• Native plugin in ~/.config/opencode/plugins/agentsys.ts
• Native plugin features:
  • Auto-thinking selection (adjusts budget per agent)
  • Workflow enforcement (blocks git push until /ship)
  • Session compaction with state preservation
  • Provider-agnostic thinking config (Anthropic, OpenAI, Google)

Codex CLI

• OpenAI-native with GPT-5-Codex
• State directory: .codex/
• Skills in ~/.codex/skills/ (invoked with $ prefix, e.g., $next-task)

Cursor

• Project-scoped installation
• State directory: .cursor/
• Skills in .cursor/skills/, commands in .cursor/commands/

Kiro

• Project-scoped installation
• State directory: .kiro/
• Steering files in .kiro/steering/ (commands with inclusion: manual)
• Skills in .kiro/skills/, agents converted to JSON in .kiro/agents/
• Reads AGENTS.md and .kiro/steering/*.md for instructions
• Subagent spawning: Experimental (max 4 agents). Primary agent invokes subagents by name from .kiro/agents/*.json. Sequential only - no parallel spawning publicly available yet.
• Parallel Task() adaptation: Workflows that spawn 4+ parallel reviewers (next-task Phase 9, audit-project Phase 2) are adapted with a try-4-then-fallback-to-2 pattern. Two combined reviewer agents (reviewer-quality-security, reviewer-perf-test) merge review passes for the sequential fallback.
• No team/swarm pattern: TeamCreate, SendMessage not supported. All orchestration is single-primary with sequential subagent delegation.

Subagent Capabilities by Platform

Migration Guide

From Claude Code to OpenCode

1. Run: npm install -g agentsys && agentsys --tool opencode
2. State files will be created fresh in .opencode/
3. Or copy state: cp -r .claude/* .opencode/

From Claude Code to Codex

1. Run: npm install -g agentsys && agentsys --tool codex
2. State files will be created fresh in .codex/
3. Or copy state: cp -r .claude/* .codex/

Using Multiple Platforms

If you use multiple AI assistants on the same project, set AI_STATE_DIR to share state:

Contributing

To add support for a new platform:

1. Create installation script in scripts/install/<platform>.sh
2. Add platform-specific configuration examples
3. Test integration with the target platform
4. Submit PR with documentation