Astral Orchestrator
GitHub

Docs · Contributing

Keep every change verifiable and portable.

Work from the repository root, preserve exact lane contracts and attribution, and treat testing, packaging, publishing, and deployment as separate gates.

Essential repository checks

After behavior, documentation, or packaging changes, run the relevant checks from the repository root. The baseline contributor sequence is:

python3 -B -m unittest discover -s tests -v
sh plugins/astral-orchestrator/scripts/verify.sh
sh scripts/setup.sh --dry-run
git diff --check

Use PYTHONDONTWRITEBYTECODE=1 when you need test runs that leave no bytecode artifacts. A green test suite validates the exercised contracts; it is not proof that a package was published or a website deployed.

Skill and plugin validation

The repository guide also defines dedicated validators:

uv run --no-project --with pyyaml python "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" plugins/astral-orchestrator/skills/astral-orchestrator
uv run --no-project --with pyyaml python "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" skills/track-astral-releases
uv run --no-project --with pyyaml python "$HOME/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py" plugins/astral-orchestrator

Keep the core skill concise and place detailed templates in references. Runtime must use built-in local tools only; do not add secrets, analytics, network calls, paid dependencies, or destructive setup.

Change and release boundaries

  • Keep the detected Sol, Luna, or Astra session as primary at its observed effort. Require exact Astra, Luna, Sol, and reviewer routes at their configured efforts; never silently substitute.
  • Keep Comet as the explicit tiny-work single-session option, Singularity as the verified context-disciplined one-primary route, and Hypernova as exact native selected-worker throughput.
  • Show the Astral status before work, around every child launch, when route state changes, and in the final handoff. Preserve truthful requested-versus-observed evidence.
  • Ask before pushing, publishing, deploying, or changing a user's global Codex configuration.
  • Track source, GitHub release, marketplace, Vercel, OpenAI submission, and public directory as independent publication surfaces.

Evidence contributions

Do not convert a test count, context-footprint measurement, or exploratory pilot into an outcome claim. Follow the evidence and benchmark guide, preserve invalid disclosures, record identical acceptance checks, and keep route correctness visible.

The pinned and reproducible state-tracking method was inspired by Ori Eval; Astral has no Ori or OpenRouter runtime dependency.

License and preserved attribution

Astral Orchestrator is distributed under the MIT License. The original notices are preserved in NOTICE.md.

Astral is an independent adaptation inspired by DannyMac180/sol-advisor, revision 92f0fb105854e0fa606bdc98bfe688411e1db989. Preserve the original Sol Advisor MIT notice and copyright.

Singularity's scope-control and verification patterns are adapted from single-agent-skills at commit 7fc169557e84e0d27fe22e7d4fc2a6bffeefe4b2. That external plugin and runtime are not bundled or required. Astral is not endorsed by or affiliated with those projects, OpenAI, or OpenRouter.