Platform Guide

Language: English | 日本語 Last updated: 2026-04-18 Audience: Platform porters

This page explains how Aphelion is adapted for each supported platform, what the generator script does, and how to port Aphelion to a new platform.

Platform Overview
Claude Code (Canonical)
GitHub Copilot
OpenAI Codex
Sandbox & Permission Modes
Generating Platform Files
Feature Matrix
Porting to a New Platform
Related Pages
Canonical Sources

Platform Overview

Aphelion has one canonical source (Claude Code) and two generated targets (GitHub Copilot, OpenAI Codex). The canonical source lives in .claude/. Platform-specific files are generated by scripts/generate.mjs and stored in platforms/.

Platform	Config location	Entry point	Multi-agent orchestration
Claude Code	`.claude/agents/`, `.claude/rules/`	Slash commands (`/discovery-flow`)	Full (sub-agent calls)
GitHub Copilot	`.github/agents/`	Agent mode in IDE	Full (agent-to-agent via Copilot)
OpenAI Codex	`AGENTS.md`, `skills/`	`AGENTS.md` global instructions	Not supported

Claude Code (Canonical)

Claude Code is the authoritative platform. All agent definitions, rules, and orchestrator behavior are maintained here. Other platforms are generated from this source.

File structure:

.claude/
  CLAUDE.md                # Workflow overview (auto-loaded)
  orchestrator-rules.md    # Triage, approval gates, rollback rules (read on-demand)
  agents/
    discovery-flow.md      # Flow orchestrators
    delivery-flow.md
    operations-flow.md
    interviewer.md         # Discovery domain agents
    researcher.md
    ...                    # (27 agents total)
  rules/
    agent-communication-protocol.md
    build-verification-commands.md
    ...                    # (9 rules total)
  commands/
    discovery-flow.md      # Slash command definitions
    delivery-flow.md
    pm.md
    ...

Slash commands (defined in .claude/commands/):

Command	Launches
`/discovery-flow {description}`	`discovery-flow` orchestrator
`/delivery-flow`	`delivery-flow` orchestrator
`/pm {description}`	`delivery-flow` (shorthand)
`/operations-flow`	`operations-flow` orchestrator
`/analyst {issue}`	`analyst` standalone agent
`/codebase-analyzer {instruction}`	`codebase-analyzer` standalone agent

Setup:

cp -r /path/to/aphelion-agents/.claude /path/to/your-project/
cd /path/to/your-project && claude

GitHub Copilot

The Copilot platform files are generated from Claude Code canonical agents by scripts/generate.mjs. They are stored in platforms/copilot/ and users copy them to .github/ in their project.

File structure (in user’s project):

.github/
  copilot-instructions.md  # Global workflow instructions (from .claude/CLAUDE.md)
  orchestrator-rules.md    # Inlined into orchestrator agents
  agents/
    discovery-flow.agent.md
    delivery-flow.agent.md
    ...                    # (27 agents total)

Key differences from Claude Code:

Aspect	Claude Code	GitHub Copilot
Frontmatter format	`---\nname: ...\ndescription: ...\ntools: Read, Write, Bash, ...`	`---\nname: ...\ndescription: ...\ntools:\n - read\n - edit\n - execute\n - ...`
Tool names	`Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`	`read`, `edit`, `execute`, `search`
Orchestrator rules	Separate file (read on-demand)	Inlined into each orchestrator agent file
Global instructions	`.claude/CLAUDE.md` (auto-loaded)	`.github/copilot-instructions.md`
Model selection	Specified in frontmatter	Copilot’s own model selection (omitted)

Tool name mapping (applied by generate.mjs):

Claude Code	Copilot
`Read`	`read`
`Write`	`edit`
`Edit`	`edit`
`Bash`	`execute`
`Glob`	`search`
`Grep`	`search`
`Agent`	`agent`
`WebSearch`, `WebFetch`	`web`

Setup:

cp -r platforms/copilot/* /path/to/your-project/.github/

Then use GitHub Copilot’s agent mode in VS Code, JetBrains, or Neovim. Agents appear in .github/agents/.

OpenAI Codex

The Codex platform uses a single AGENTS.md file as global instructions, plus individual skill files. It is generated by scripts/generate.mjs but with significant limitations.

File structure (in user’s project):

AGENTS.md          # Merged global instructions (all rules + workflow overview)
skills/
  vuln-scan/
    SKILL.md       # Dependency vulnerability scan
  secrets-scan/
    SKILL.md       # Hardcoded secrets detection

Key limitations:

Limitation	Detail
No sub-agent orchestration	Codex cannot invoke agents from within agents. Multi-phase flows are not available.
32 KB size limit	`AGENTS.md` is capped at 32 KB. The generator truncates if needed.
Skills only	Only `vuln-scan` and `secrets-scan` are available as individual utilities.
No slash commands	Entry is via `AGENTS.md` global instructions, not slash commands.

Available skills:

vuln-scan: Detects the project’s tech stack from package files, runs the appropriate vulnerability scanner (pip-audit, npm audit, govulncheck, cargo audit), and reports findings.
secrets-scan: Scans source code for hardcoded API keys, passwords, tokens, connection strings, AWS keys, private keys, and Bearer tokens. Excludes .env and test fixtures.

Setup:

cp platforms/codex/AGENTS.md /path/to/your-project/
cp -r platforms/codex/skills/ /path/to/your-project/

For full multi-phase orchestration, use Claude Code or GitHub Copilot.

Sandbox & Permission Modes

Aphelion agents execute shell commands via the Bash tool on behalf of the user. The sandbox system provides a structured way to classify risky commands and route them through platform-native permission controls before execution.

For the full policy reference, see .claude/rules/sandbox-policy.md. For the executor agent, see .claude/agents/sandbox-runner.md.

Platform Sandbox Capability Comparison

Capability	Claude Code	GitHub Copilot	OpenAI Codex
Container isolation via devcontainer	Yes (`container` mode — highest priority)	Yes (when Docker available)	No
Native permission gate	Yes (permission mode)	Partial (IDE confirmation prompt)	No
Allow / Ask / Deny tiers	Yes	Ask only	No
Persistent settings	`.claude/settings.json`	IDE config	N/A
Session-local override	`.claude/settings.local.json`	Per-session	N/A
sandbox-runner integration	Auto-insert (Standard+) + explicit	Explicit only	Advisory only
Recommended fallback	—	Manual review before execution	Manual review before execution

Container Isolation Mode

Aphelion supports a container isolation mode in addition to platform permission modes. When .devcontainer/devcontainer.json exists and Docker is available, sandbox-runner executes high-risk commands inside the project’s devcontainer rather than relying solely on permission gates.

Key properties of container mode:

Provides real physical isolation — the command runs in a separate container process with a restricted filesystem view.
Effective even in auto/allow mode — even when Claude Code’s permission mode would normally execute commands without prompting, container mode still enforces a structural boundary.
infra-builder generates .devcontainer/devcontainer.json and docker-compose.dev.yml on Light plans and above.
If Docker is unavailable at runtime (Standard/Full plans), sandbox-runner degrades gracefully to platform_permission and records FALLBACK_REASON in AGENT_RESULT.

Priority order: container > platform_permission > advisory_only > blocked

For the full policy, see .claude/rules/sandbox-policy.md §3–§5. For the execution path selection logic, see .claude/agents/sandbox-runner.md §Workflow Step 2.

Claude Code Permission Mode

Claude Code offers three permission levels for Bash commands:

Mode	Behavior
`allow`	Execute automatically without confirmation
`ask`	Pause and request user confirmation before executing
`deny`	Refuse execution entirely

Settings persistence:

Persistent — Stored in .claude/settings.json (can be committed to the repository and shared across the team).
Session / local — Stored in .claude/settings.local.json (gitignored by default; for personal or per-environment overrides).

Priority: Session-local settings take precedence over persistent settings.

Relationship with sandbox-runner: sandbox-runner respects whichever permission mode is in effect. It does not replace or bypass Claude Code’s permission system — it calls into it. Aphelion never modifies .claude/settings.json or .claude/settings.local.json directly; users configure these files themselves.

Recommended Permission Profiles

The following profiles are recommendations only. Configure them in your own .claude/settings.json or .claude/settings.local.json as appropriate for your environment.

Environment	destructive_fs	prod_db	external_net	privilege_escalation	secret_access	Notes
dev (local developer)	ask	deny	ask	ask	ask	All `required` categories require confirmation; external network also asks
CI	deny	deny	allow (allowlist)	deny	deny	Network permitted only for known registries; all destructive ops denied
near-production	deny	deny	deny	deny	deny	Full deny; human-in-the-loop required for any exception

How sandbox-runner Fits In

Triage determines activation level — Minimal plan: advisory warnings only. Light: explicit delegation. Standard/Full: orchestrator auto-inserts sandbox-runner before required-tier commands.
sandbox-runner re-classifies — Even when an agent provides a risk_hint, sandbox-runner independently re-classifies the command against sandbox-policy.md.
Platform mode is applied — On Claude Code, the appropriate permission mode is invoked. On Copilot/Codex, an advisory warning is shown.
Audit trail returned — AGENT_RESULT from sandbox-runner always includes DETECTED_RISKS and DECISION, regardless of whether execution was allowed or denied.

Generating Platform Files

Platform files are generated from the Claude Code canonical source using scripts/generate.mjs.

Usage:

# Generate all platforms
node scripts/generate.mjs

# Copilot only
node scripts/generate.mjs --platform copilot

# Codex only
node scripts/generate.mjs --platform codex

# Remove generated files
node scripts/generate.mjs --clean

What the generator does for each platform:

For Copilot:

Reads each .claude/agents/{name}.md file
Converts YAML frontmatter (tool names, removes model field)
Inlines orchestrator-rules.md content into orchestrator agents (discovery-flow, delivery-flow, operations-flow)
Writes output to platforms/copilot/agents/{name}.agent.md
Copies .claude/CLAUDE.md to platforms/copilot/copilot-instructions.md

For Codex:

Merges .claude/CLAUDE.md and all .claude/rules/*.md files into AGENTS.md
Appends the full orchestrator-rules.md content
Truncates to 32 KB if needed
Converts .claude/commands/vuln-scan.md and secrets-scan.md to platforms/codex/skills/ format

When to re-run:

Run node scripts/generate.mjs whenever .claude/agents/, .claude/rules/, or .claude/orchestrator-rules.md is modified. Platform files in platforms/ should never be edited directly — they are generated artifacts.

Feature Matrix

Feature	Claude Code	GitHub Copilot	OpenAI Codex
Full 3-domain flow	Yes	Yes	No
Discovery flow	Yes	Yes	No
Delivery flow	Yes	Yes	No
Operations flow	Yes	Yes	No
Individual agents (standalone)	Yes	Yes	Partial (skills only)
Triage system	Yes	Yes	No
Session resume (TASK.md)	Yes	Yes	No
Vuln scan	Yes (`security-auditor`)	Yes (`security-auditor`)	Yes (`/vuln-scan` skill)
Secrets scan	Yes (`security-auditor`)	Yes (`security-auditor`)	Yes (`/secrets-scan` skill)
Slash commands	Yes	Via agent mode	No

Porting to a New Platform

To add support for a new AI coding platform:

Understand the platform’s agent model: Does it support sub-agent invocation? What is the instruction file format? Is there a size limit?
Add a generator function to scripts/generate.mjs: Follow the pattern of generateCopilot() or generateCodex(). The generator should:
- Read from .claude/agents/ and .claude/rules/
- Apply platform-specific transformations (frontmatter, tool names, etc.)
- Write to platforms/{platform-name}/
Create the platform directory structure in platforms/{platform-name}/.
Add CLI support: Add --platform {name} to the generate.mjs argument parser.
Document the platform in this wiki page (Platform-Guide) with a new section following the Claude Code / Copilot / Codex pattern.
Update the feature matrix table above.

If the platform does not support sub-agent orchestration, implement skills/utilities for vuln-scan and secrets-scan at minimum (matching the Codex skills pattern).

Canonical Sources

.claude/agents/ — Claude Code canonical agent definitions
platforms/copilot/ — Generated Copilot platform files
platforms/codex/ — Generated Codex platform files
scripts/generate.mjs — Platform file generator

Platform Guide

Table of Contents

Platform Overview

Claude Code (Canonical)

GitHub Copilot

OpenAI Codex

Sandbox & Permission Modes

Platform Sandbox Capability Comparison

Container Isolation Mode

Claude Code Permission Mode

Recommended Permission Profiles

How sandbox-runner Fits In

Generating Platform Files

Feature Matrix

Porting to a New Platform

Related Pages

Canonical Sources