sol-luna-setup

Sol + Luna Layered Sub-Agents Setup Skill

Install: npx skills add Yuri-NagaSaki/subagent-skills -g -y
Repo: https://github.com/Yuri-NagaSaki/subagent-skills
Guide: https://catcat.blog/2026/08/sol-luna-layered-subagents-codex-claude-pi.html

Goal

Undernot writing keys into the repositorythe premise, make the project have:

Main session gpt-5.6-sol(lead)
workers gpt-5.6-luna（scout / worker / critic / tester）
Project-level config can be shared via git
Verifiable smoke-test results

Hard security rules

Neverwrite API keys, host IPs, SSH passwords, private keys into config.toml、AGENTS.md, README, article body or git commit.
Use only environment variables for keys:OPENAI_API_KEY / GATEWAY_API_KEY / ANTHROPIC_API_KEY etc.
model_providers.*.env_key Only write the variablename。
Large files models-v1.json are gitignored by default and generated by a script.

Prerequisites

Linux / macOS，Node.js 20+
Accessible OpenAI-compatible Responses endpoint (wire_api = "responses"）
enable on the account side gpt-5.6-sol and gpt-5.6-luna

Standard flow (Agent must execute in order)

0. Probe

node -v && npm -v
command -v codex || true
command -v claude || true
command -v pi || true
test -n "${OPENAI_API_KEY:-}" && echo "OPENAI_API_KEY=set" || echo "OPENAI_API_KEY=MISSING"

If the Key is missing: stop and ask the user to export,do notwrite plaintext to disk outside the conversation.

1. Install CLI

npm i -g @openai/codex @anthropic-ai/claude-code
# 可选
npm i -g @earendil-works/pi-coding-agent
# 或 curl -fsSL https://pi.dev/install.sh | sh
pi install npm:@kky42/pi-flow   # 可选，需已装 pi

2. Global personal default (optional)

Write to ~/.codex/config.toml(personal default only):

model = "gpt-5.6-sol"
default_subagent_model = "gpt-5.6-luna"
[features] multi_agent = true，multi_agent_v2 = false(with V1 catalog)
[model_providers.gateway] + env_key = "OPENAI_API_KEY"

Do notcopy the user's real Key into the file.

3. Project-level template

Run at the project root:

bash /path/to/subagent-skills/scripts/bootstrap.sh "$(pwd)"
# 或安装 skill 后:
# bash ~/.claude/skills/sol-luna-setup/scripts/bootstrap.sh "$(pwd)"

Will create/update:

.codex/config.toml
.codex/agents/luna_{scout,worker,critic,tester}.toml
AGENTS.md
.claude/agents/luna-{scout,worker,critic}.md
CLAUDE.md
scripts/prepare-luna-catalog.sh
.gitignore 条目：.codex/models-v1.json、.env

Keep the user's existing unrelated config; on conflict merge rather than blindly overwrite.

4. Fix Sol → Luna spawn (required)

Symptoms:

Unknown model `gpt-5.6-luna` for spawn_agent.
Available models: gpt-5.6-sol, gpt-5.6-terra

Cause: in the catalog Sol/Terra are often multi-agent v2, Luna is v1, V2 filters out Luna.

Handling:

bash scripts/prepare-luna-catalog.sh "$(pwd)/.codex/models-v1.json"
# 将 model_catalog_json 设为该文件的绝对路径
# multi_agent_v2 = false

5. Verification (all must pass before declaring completion)

# 单模型（注意 </dev/null）
codex exec --sandbox read-only -c 'model="gpt-5.6-sol"' \
  "Reply with exactly: SOL_SMOKE_OK" </dev/null

codex exec --sandbox read-only -c 'model="gpt-5.6-luna"' \
  "Reply with exactly: LUNA_SMOKE_OK" </dev/null

# 多代理
codex exec --sandbox read-only \
  "按 AGENTS.md spawn luna_scout 只读说明仓库结构，输出以 SCOUT_DONE 开头" </dev/null

# 可选 Pi
export GATEWAY_API_KEY="${OPENAI_API_KEY}"
pi --print --provider gateway --model gpt-5.6-sol --no-session --no-tools "Reply: PI_SOL_OK"
pi --print --provider gateway --model gpt-5.6-luna --no-session --no-tools "Reply: PI_LUNA_OK"

Claude Code：

A non-root user is more reliable
Do one claude -p smoke test against haiku; if the gateway Anthropic channel returns 502, record it as a vendor issue and you can still commit the agents file

6. Delivery report template

## Sol-Luna Setup Report
- Host OS / Node / Codex / Claude / Pi versions:
- Project path:
- Files created:
- Catalog fix applied: yes/no
- SOL_SMOKE: pass/fail
- LUNA_SMOKE: pass/fail
- MULTI_AGENT SCOUT_DONE: pass/fail
- Pi SOL/LUNA: pass/fail/skip
- Secrets in git: none (confirmed)
- Next user action:

Role policy (write into AGENTS.md)

Role	Model	Permissions
Main session Sol	gpt-5.6-sol	Planning, review, commit/PR
luna_scout	gpt-5.6-luna	read-only
luna_worker	gpt-5.6-luna	workspace-write, commit prohibited
luna_critic	gpt-5.6-luna	read-only adversarial review
luna_tester	gpt-5.6-luna	Run specified tests, return evidence

Common failures

Symptom	Handling
spawn has no Luna	V1 catalog + multi_agent_v2=false
codex swallows subsequent shell	`codex exec ... </dev/null`
wire_api reports an error	Use `responses`; confirm the gateway implements `/v1/responses`
Claude root refuses bypass	Switch to non-root or lower the permission mode
Worker write conflicts	Reduce concurrency, partition by file
Keys in diff	Remove immediately, rotate keys

Reference files

scripts/bootstrap.sh — Project scaffolding
scripts/prepare-luna-catalog.sh — Model catalog fix
references/project-template/ — Copyable template
Blog long-form article:https://catcat.blog/2026/08/sol-luna-layered-subagents-codex-claude-pi.html
Source repository:https://github.com/Yuri-NagaSaki/subagent-skills

Agent Code of Conduct

Probe first, then install, then write project files, then fix the catalog, then verify.
Show key diffs; do not overwrite unrelated user configuration.
When verification fails, provide an actionable fix; do not pretend success.
If the user requests “configure only Sol and Luna”: do not enable Terra as the default; the Terra entry may remain in the catalog for compatibility only.