Getting Started

Language: English | 日本語 Last updated: 2026-04-18 Audience: New users

This page covers everything you need to start using Aphelion: platform-specific setup, first-run walkthrough, usage scenarios, command reference, and troubleshooting.

Prerequisites
Quick Start by Platform
First Run Walkthrough
Usage Scenarios
Command Reference
What to Expect: A Typical Session
Troubleshooting
Related Pages
Canonical Sources

Prerequisites

Platform	Requirement
Claude Code	Claude Code CLI installed and authenticated
GitHub Copilot	GitHub Copilot extension in VS Code, JetBrains, or Neovim
OpenAI Codex	Access to OpenAI Codex environment

All platforms require access to the Aphelion repository. Clone it first:

git clone https://github.com/kirin0198/aphelion-agents.git

Quick Start by Platform

Claude Code (Canonical)

Copy the .claude/ directory to your project and start Claude Code:

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

/discovery-flow I want to build a TODO app

GitHub Copilot

Copy the generated Copilot agent files to your project’s .github/ directory:

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

Then use GitHub Copilot’s agent mode in your IDE. Copilot agents are placed in .github/agents/.

OpenAI Codex

Copy the generated Codex files to your project root:

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

Codex uses the AGENTS.md file as global instructions. Skills are available as individual utilities.

Note: Codex does not support sub-agent orchestration. Full multi-phase flows are only available on Claude Code and GitHub Copilot. See Platform Guide for details.

First Run Walkthrough

This walkthrough uses Claude Code for a new project.

Step 1: Copy Aphelion to your project

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

Step 2: Start Discovery

/discovery-flow I want to build a task management web app with user authentication

The orchestrator will ask you several triage questions to determine the plan. For a web app with authentication, it will likely select Standard or Full.

Step 3: Review Discovery output

After all Discovery phases complete, review DISCOVERY_RESULT.md. If you are satisfied, proceed to Delivery.

Step 4: Start Delivery

/delivery-flow

The orchestrator reads DISCOVERY_RESULT.md and performs triage again for the implementation phase.

Step 5: Review and iterate

At each phase, the orchestrator shows you what was generated and asks for approval. You can approve, request modifications, or stop.

Step 6: Start Operations (service only)

/operations-flow

Only needed if PRODUCT_TYPE: service. Builds Dockerfile, CI/CD, and operations plan.

Usage Scenarios

Scenario 1: New Project (Full Flow)

Start from scratch — requirements through deployment:

/discovery-flow I want to build a blog management system

After Discovery completes and you review DISCOVERY_RESULT.md:

/delivery-flow

After Delivery completes (for service projects):

/operations-flow

Scenario 2: Quick Build (Delivery Only)

When you already know what to build:

/pm I want to build a REST API for managing contacts

Or equivalently:

/delivery-flow

The orchestrator will interview you directly since there is no DISCOVERY_RESULT.md.

Scenario 3: Existing Project with Docs (Bug Fix or Feature)

Your project has SPEC.md and ARCHITECTURE.md:

/analyst There's a 500 error on the login endpoint when the email contains special characters

After analyst generates the GitHub issue and approach document:

/delivery-flow

The flow joins from Phase 3 (architecture), skipping spec and UI design.

Scenario 4: Existing Project without Docs

Reverse-engineer the specification first:

/codebase-analyzer Analyze this project and generate SPEC.md and ARCHITECTURE.md

After review and approval:

/analyst I want to add OAuth2 social login
/delivery-flow

Scenario 5: Standalone Agents

You can invoke any agent directly without a flow:

/security-auditor  (run security audit on existing code)
/reviewer          (run code review only)
/doc-writer        (generate README and CHANGELOG)

Command Reference

Command	Purpose	Entry Point
`/discovery-flow {description}`	Start requirements exploration	New projects
`/delivery-flow`	Start design & implementation	After Discovery, or with existing SPEC.md
`/pm {description}`	Start Delivery directly (shorthand)	When requirements are clear
`/operations-flow`	Start deployment & operations	After Delivery, service type only
`/analyst {issue}`	Analyze bugs/features for existing projects	Projects with SPEC.md
`/codebase-analyzer {instruction}`	Reverse-engineer specs from existing code	Projects without SPEC.md

These commands are defined as slash commands in .claude/commands/*.md (Claude Code) or invoked through the agent mode interface (Copilot).

What to Expect: A Typical Session

Triage Questions

At flow start, the orchestrator asks 4-6 questions about your project. Answer as accurately as possible — these determine which agents run.

Phase Approvals

After each agent completes, the orchestrator shows a summary and asks:

Approve and continue — proceed to the next phase
Request modification — describe changes and the agent re-runs
Stop — end the flow

Artifact Files

Each agent generates one or more files:

Phase	Files Generated
Discovery	INTERVIEW_RESULT.md, RESEARCH_RESULT.md, POC_RESULT.md, SCOPE_PLAN.md, DISCOVERY_RESULT.md
Delivery	SPEC.md, UI_SPEC.md, ARCHITECTURE.md, TASK.md, implementation code, TEST_PLAN.md, SECURITY_AUDIT.md, README.md
Operations	Dockerfile, docker-compose.yml, .github/workflows/ci.yml, DB_OPS.md, OBSERVABILITY.md, OPS_PLAN.md

Session Resume

If a session is interrupted (especially during developer), you can resume:

/developer  (resume from TASK.md)

Or restart the entire flow — it will detect existing files and ask if you want to continue or start over.

Troubleshooting

”DISCOVERY_RESULT.md is missing required fields”

Delivery Flow validates DISCOVERY_RESULT.md at startup. If it reports missing fields (PRODUCT_TYPE, “プロジェクト概要”, “要件サマリー”), edit the file to add the missing sections, then re-run /delivery-flow.

”Agent returned STATUS: error”

The orchestrator will present options:

Retry — re-run the same agent
Retry with instruction — describe what to fix before retrying
Skip — skip this agent and continue
Stop — abort the flow

”Developer is stuck / taking too long”

developer uses TASK.md to track progress. If a task is taking too long, you can interrupt and resume later. The next run will start from the first incomplete task in TASK.md.

Copilot: Agents not appearing

Ensure the agent files are in .github/agents/ (not .github/copilot-agents/). Also verify that the Copilot extension has access to the project’s .github/ directory.

Codex: Flow commands not working

Codex does not support multi-agent orchestration. Use individual skills (/vuln-scan, /secrets-scan) instead of flow commands. For full orchestration, use Claude Code or Copilot.

Canonical Sources

README.md — Project overview and Quick Start
.claude/commands/ — Slash command definitions
.claude/agents/discovery-flow.md — Discovery flow startup procedure
.claude/agents/delivery-flow.md — Delivery flow startup procedure