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:

1. Claude Code - Anthropic's official CLI (primary target)
2. OpenCode - Multi-model AI coding assistant
3. Codex CLI - OpenAI's command-line interface
4. Cursor - AI-native code editor
5. 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 (manual: npm run setup-hooks)
│   └── 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 24 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,
              banthis,learn,consult,debate,agnix,skillers,
              skill-curator,system-prompt-curator,onboard,can-i-help,zig-lsp}

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
Negative memory	/banthis	Persist banned agent behaviors
Config linting	/agnix	Lint agent configurations (385 rules)
Research	/learn	Research topics, create learning guides
AI consultation	/consult	Cross-tool AI consultation
AI debate	/debate	Structured debate between AI tools
Workflow learning	/skillers	Workflow pattern learning and automation
Skill curation	/skill-curator	Create and improve SKILL.md files
Prompt curation	/system-prompt-curator	Create and improve autonomous agent prompts
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, /banthis, /agnix, /learn, /consult, /debate, /skillers, /skill-curator, /system-prompt-curator, /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

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

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, $banthis, $agnix, $learn, $consult, $debate, $skillers, $skill-curator, $system-prompt-curator, $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
/banthis	[OK] Full	[OK] Full	[OK] Full	Negative behavior memory; includes CLI
/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
/skillers	[OK] Full	[OK] Full	[OK] Full	Workflow pattern learning
/skill-curator	[OK] Full	[OK] Full	[OK] Full	Skill authoring and review
/system-prompt-curator	[OK] Full	[OK] Full	[OK] Full	Agent prompt curation
/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:

1. Edit files in lib/ (canonical source in this repo)
2. Push to main — agent-core sync pipeline automatically opens PRs in 19 plugin repos today (zig-lsp sync wire-up still pending; tracked in docs/ORG_ARCHITECTURE.md)
3. Merge those PRs in each plugin repo
4. 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.