Multi-Platform Architecture

The design principle: write tools once, run everywhere. AI models already have their strengths—code generation, reasoning, analysis. The bottleneck is orchestration, state management, and platform integration. This architecture handles those parts so the models can do what they're good at.

Quick Navigation

Section	Jump to
Overview	Platform support
Architecture	Directory structure
Cross-Platform Library	Shared utilities
State Directories	Where state lives
Core Capabilities	Command reference
Platform Details	Per-platform setup
Knowledge Base	Research docs

Overview

AgentSys supports five AI coding assistants through a unified architecture:

Claude Code - Anthropic's official CLI (primary target)
OpenCode - Multi-model AI coding assistant
Codex CLI - OpenAI's command-line interface
Cursor - AI-native code editor
Kiro - Amazon's agentic IDE

Quick Install

npm install -g agentsys
agentsys
# Select platforms: 1,2,3 for all

Architecture

Core Components

agentsys/
├── lib/                          # Shared library (vendored to plugin repos via agent-core sync)
│   ├── cross-platform/           # Platform utilities
│   │   ├── index.js              # Platform detection, MCP helpers
│   │   └── RESEARCH.md           # Research documentation
│   ├── enhance/                  # Quality analyzers (agent, plugin, docs, hooks, skills)
│   ├── perf/                     # Performance investigation workflow
│   ├── patterns/                 # Code analysis
│   │   ├── pipeline.js           # 3-phase slop detection
│   │   ├── slop-patterns.js      # Pattern definitions
│   │   └── slop-analyzers.js     # Multi-pass analyzers
│   ├── state/                    # Workflow state
│   └── sources/                  # Task source discovery
├── bin/                          # CLI installer
│   └── cli.js                    # Interactive installer (fetches plugins from GitHub)
├── .claude-plugin/
│   └── marketplace.json          # Plugin registry (name, repo, requires)
├── meta/
│   └── skills/
│       └── maintain-cross-platform/  # Cross-platform compatibility skill
│           └── SKILL.md
├── scripts/
│   ├── setup-hooks.js            # Git hooks installer (npm prepare)
│   └── graduate-plugin.js        # Extract a plugin to a new standalone repo
├── docs/                         # User documentation
│   ├── CROSS_PLATFORM.md
│   ├── INSTALLATION.md
│   └── USAGE.md
└── agent-docs/                   # Knowledge base (research)
    ├── KNOWLEDGE-LIBRARY.md      # Index
    └── *-REFERENCE.md            # Research documents

NOTE: plugins/ has been removed. All 19 plugins are now standalone repos
under the agent-sh org. The installer fetches them from GitHub at install time.
Plugin repos: agent-sh/{next-task,prepare-delivery,gate-and-ship,ship,deslop,
              audit-project,enhance,perf,drift-detect,sync-docs,repo-intel,
              learn,consult,debate,agnix,web-ctl,skillers,onboard,can-i-help}

Cross-Platform Library (`lib/cross-platform/`)

Provides unified utilities for all platforms:

const { xplat } = require('agentsys/lib');

// Platform detection
xplat.detectPlatform();  // 'claude-code' | 'opencode' | 'codex-cli'
xplat.getStateDir();     // '.claude' | '.opencode' | '.codex'

// MCP response helpers
xplat.successResponse({ data: 'result' });
xplat.errorResponse('Something failed', { details: '...' });

// Tool schema creation
xplat.createToolDefinition('my_tool', 'Description', { param: { type: 'string' } });

// Prompt formatting (cross-model compatible)
xplat.formatBlock('context', 'XML tags for Claude');
xplat.formatSection('Title', 'Markdown for GPT-4');

State Directory by Platform

Platform	State Directory	Override
Claude Code	`.claude/`	`AI_STATE_DIR=.claude`
OpenCode	`.opencode/`	`AI_STATE_DIR=.opencode`
Codex CLI	`.codex/`	`AI_STATE_DIR=.codex`

State files:

{state-dir}/tasks.json - Active task registry
{state-dir}/flow.json - Workflow progress (in worktree)
{state-dir}/sources/preference.json - Cached task source
{state-dir}/repo-map.json - Cached symbol map (generated by agent-analyzer)

Core Capabilities

The package provides these capabilities through commands, agents, and skills:

Capability	Command	Description
Workflow orchestration	`/next-task`	Task discovery through PR merge
Pre-ship quality gates	`/prepare-delivery`	Deslop, review, validation, docs sync
Quality gates + ship	`/gate-and-ship`	/prepare-delivery + /ship combined
PR workflow	`/ship`	Commit, push, CI monitor, merge
Versioned release	`/release`	Release with automatic ecosystem detection
Code quality	`/deslop`	AI slop detection and cleanup
Enhancement	`/enhance`	Analyze plugins, agents, docs, prompts
Performance	`/perf`	Performance investigation workflow
Repo intel	`/repo-intel`	Unified static analysis - git history, AST symbols, project metadata
Documentation	`/sync-docs`	Sync docs with code changes
Drift detection	`/drift-detect`	Plan vs implementation analysis
Code review	`/audit-project`	Multi-agent code review
Config linting	`/agnix`	Lint agent configurations (342 rules)
Research	`/learn`	Research topics, create learning guides
AI consultation	`/consult`	Cross-tool AI consultation
AI debate	`/debate`	Structured debate between AI tools
Browser automation	`/web-ctl`	Browser automation for AI agents
Workflow learning	`/skillers`	Workflow pattern learning and automation
Onboarding	`/onboard`	Codebase orientation for newcomers
Contributor guidance	`/can-i-help`	Match contributor skills to project needs

Slop detection uses the full 3-phase pipeline:

Phase 1: Regex patterns (HIGH certainty)
Phase 2: Multi-pass analyzers (MEDIUM certainty)
Phase 3: CLI tools (LOW certainty, optional)

Platform Installation Details

Claude Code

# Via marketplace (recommended)
/plugin marketplace add agent-sh/agentsys
/plugin install next-task@agentsys

# Via CLI installer
agentsys  # Select option 1

Location: ~/.claude/plugins/agentsys/

Commands: /next-task, /prepare-delivery, /gate-and-ship, /ship, /release, /deslop, /audit-project, /drift-detect, /repo-intel, /enhance, /perf, /sync-docs, /agnix, /learn, /consult, /debate, /web-ctl, /skillers, /onboard, /can-i-help

OpenCode

agentsys  # Select option 2

Locations:

Commands: ~/.config/opencode/commands/
Agents: ~/.config/opencode/agents/
Skills: ~/.config/opencode/skills/
Native plugin: ~/.config/opencode/plugins/agentsys.ts

Native Plugin Features:

Auto-thinking selection per agent
Workflow enforcement
Session compaction

Codex CLI

agentsys  # Select option 3

Locations:

Config: ~/.codex/config.toml
Skills: ~/.codex/skills/

Skills: $next-task, $prepare-delivery, $gate-and-ship, $ship, $release, $deslop, $audit-project, $drift-detect, $repo-intel, $enhance, $perf, $sync-docs, $agnix, $learn, $consult, $debate, $web-ctl, $skillers, $onboard, $can-i-help

Internal skill: orchestrate-review (Phase 9 review pass definitions used by /next-task and /audit-project)

Note: Codex uses $ prefix instead of /.

SKILL.md Format:

---
name: next-task
description: Master workflow orchestrator for task-to-production automation
---
[skill content]

Command Compatibility

Command	Claude Code	OpenCode	Codex CLI	Notes
`/next-task`	[OK] Full	[OK] Full	[OK] Full	Master workflow
`/prepare-delivery`	[OK] Full	[OK] Full	[OK] Full	Pre-ship quality gates
`/gate-and-ship`	[OK] Full	[OK] Full	[OK] Full	/prepare-delivery + /ship
`/ship`	[OK] Full	[OK] Full	[OK] Full	Requires `gh` CLI
`/release`	[OK] Full	[OK] Full	[OK] Full	Versioned release
`/deslop`	[OK] Full	[OK] Full	[OK] Full	Uses pipeline.js
`/audit-project`	[OK] Full	[OK] Full	[OK] Full	Multi-agent review
`/drift-detect`	[OK] Full	[OK] Full	[OK] Full	JS collectors + Opus
`/repo-intel`	[OK] Full	[OK] Full	[OK] Full	Unified static analysis
`/enhance`	[OK] Full	[OK] Full	[OK] Full	Orchestrates all enhancers
`/perf`	[OK] Full	[OK] Full	[OK] Full	Performance investigations
`/sync-docs`	[OK] Full	[OK] Full	[OK] Full	Documentation sync
`/agnix`	[OK] Full	[OK] Full	[OK] Full	Requires `agnix` CLI
`/learn`	[OK] Full	[OK] Full	[OK] Full	Research and learning
`/consult`	[OK] Full	[OK] Full	[OK] Full	Cross-tool consultation
`/debate`	[OK] Full	[OK] Full	[OK] Full	Multi-round AI debate
`/web-ctl`	[OK] Full	[OK] Full	[OK] Full	Browser automation
`/skillers`	[OK] Full	[OK] Full	[OK] Full	Workflow pattern learning
`/onboard`	[OK] Full	[OK] Full	[OK] Full	Codebase orientation
`/can-i-help`	[OK] Full	[OK] Full	[OK] Full	Contributor guidance

Knowledge Base

Research documents informing the implementation (in agent-docs/):

Document	Topic
`CONTEXT-OPTIMIZATION-REFERENCE.md`	Token efficiency strategies
`PROMPT-ENGINEERING-REFERENCE.md`	Cross-model prompt design
`FUNCTION-CALLING-TOOL-USE-REFERENCE.md`	MCP and tool patterns
`MULTI-AGENT-SYSTEMS-REFERENCE.md`	Agent orchestration
`LLM-INSTRUCTION-FOLLOWING-RELIABILITY.md`	Instruction adherence
`CLAUDE-CODE-REFERENCE.md`	Claude Code specifics
`AI-AGENT-ARCHITECTURE-RESEARCH.md`	Agent design patterns
`KNOWLEDGE-LIBRARY.md`	Index and overview
`lib/cross-platform/RESEARCH.md`	Platform comparison

Implementation Status

Core Infrastructure [OK]

CLI installer (bin/cli.js)
MCP server with pipeline integration
Cross-platform library (lib/cross-platform/)
Platform-aware state directories
Knowledge base documentation

Platform Support [OK]

Claude Code (marketplace + CLI)
OpenCode (MCP + commands)
Codex CLI (MCP + skills)

Testing [OK]

All 3,445+ tests passing
npm pack creates valid package (~400 KB)
Interactive installer works for all platforms

Maintenance

Update workflow:

Edit files in lib/ (canonical source in this repo)
Push to main — agent-core sync pipeline automatically opens PRs in all 19 plugin repos
Merge those PRs in each plugin repo
Publish agentsys: npm version patch && npm publish

To extract a new plugin to its own repo:

node scripts/graduate-plugin.js <plugin-name>

User update:

npm update -g agentsys
agentsys  # Re-run installer

Design Decisions

Why MCP Server?

MCP (Model Context Protocol) provides:

Standardized tool interface across platforms
No format translation needed
Single implementation, multiple consumers
Platform-specific env vars for state isolation

Why Shared Library?

Each plugin repo needs its own lib/ copy because Claude Code installs plugins separately and cannot share code across plugin boundaries. The agent-core sync pipeline (CI-driven) propagates lib/ changes to all plugin repos automatically whenever main is updated.

Why Research Docs?

The knowledge base documents best practices from official sources, ensuring the implementation follows recommended patterns for each platform.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Multi-Platform Architecture

Quick Navigation

Overview

Quick Install

Architecture

Core Components

Cross-Platform Library (`lib/cross-platform/`)

State Directory by Platform

Core Capabilities

Platform Installation Details

Claude Code

OpenCode

Codex CLI

Command Compatibility

Knowledge Base

Implementation Status

Core Infrastructure [OK]

Platform Support [OK]

Testing [OK]

Maintenance

Design Decisions

Why MCP Server?

Why Shared Library?

Why Research Docs?

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Multi-Platform Architecture

Quick Navigation

Overview

Quick Install

Architecture

Core Components

Cross-Platform Library (lib/cross-platform/)

State Directory by Platform

Core Capabilities

Platform Installation Details

Claude Code

OpenCode

Codex CLI

Command Compatibility

Knowledge Base

Implementation Status

Core Infrastructure [OK]

Platform Support [OK]

Testing [OK]

Maintenance

Design Decisions

Why MCP Server?

Why Shared Library?

Why Research Docs?

Cross-Platform Library (`lib/cross-platform/`)