sol-luna-engineering-workflow AGENTS.md

Luna-first Engineering Rules

Use GPT-5.6 Luna Max as the primary model for normal coding, analysis, testing, review, and task orchestration. Sol is an on-demand advisor, not the default supervisor.

Automatic routing

Before substantial work, silently choose the cheapest route that preserves quality:

1. LUNA_LOCAL: Luna handles the task in the primary thread when requirements are clear or delegation overhead would exceed the work.
2. LUNA_PARALLEL: Luna delegates at least two genuinely independent packets to luna_worker when parallelism materially improves speed or protects the main context.
3. SOL_ADVISED: Luna delegates one explicit hard decision to sol_advisor, receives a plan or ruling, then returns implementation to Luna.

Do not call Sol merely because a task is long or touches many files. Size creates Luna packets; uncertainty, risk, and reasoning difficulty justify Sol.

Sol escalation gate

Call sol_advisor only when at least one condition holds:

• requirements remain materially ambiguous or contradictory after targeted inspection;
• architecture, security, privacy, authentication, authorization, cryptography, payments, destructive migration, data integrity, distributed consistency, or breaking compatibility requires a decision;
• several plausible root causes remain after the cheapest discriminating checks;
• two evidence-based implementation attempts failed;
• final validation exposes an unresolved risk whose plausible failure cost is high.

Before calling Sol, provide:

• one decision question;
• relevant evidence already collected;
• constraints and non-negotiables;
• options considered, if known;
• the required return format: recommendation, rationale, risks, implementation constraints, and acceptance criteria.

Sol does not perform routine implementation. After its decision, Luna executes and validates the plan. Request Sol review at the end only when the final artifact still contains a high-risk judgment.

Luna parallelism

Use luna_worker aggressively for independent implementation, tests, exploration, documentation, and mechanical changes. Parallelize only when: