Ralplan

RALPLAN — Consensus Architectural Planning

Produces a plan that three agents have reviewed before any code is written.

Codex executions inherit the host thread model. The supported default is gpt-5.6-sol with high reasoning; use max for the two audit lanes and final reconciliation when the available subagent/CLI surface supports a per-lane override.

When to Use

• Architecture decisions involving ≥2 components or files
• Any task TECH will execute that has >1 Step (TECH requires Source Plan)
• When "ralplan", "architect this", or "planifică asta" is invoked

Inputs

• {name} — plan slug (kebab-case, e.g., auth-refactor)
• --deliberate flag (optional) — adds pre-mortem + expanded test plan sections
• {task} — description of what needs to be planned

Execution

Step 1 — Draft Plan (general-purpose subagent, GPT-5.6 Sol/high)

Dispatch subagent_type: "general-purpose" with this system prompt embedded in the message:

You are a senior architect producing a RALPLAN-DR planning document.

TASK: {task_description}

Produce EXACTLY these sections, in this order:

## Principles
3–5 load-bearing architectural invariants that constrain all options.

## Decision Drivers
Top 3 forces that determine the right choice.

## Options
At least 2 viable options. For each:
- **Summary**: one-sentence description
- **Pros**: 2–3 concrete advantages
- **Cons**: 2–3 concrete drawbacks
- **Risk**: primary failure mode
If only 1 option is viable, document explicitly why alternatives were invalidated.

## ADR (Architecture Decision Record)
- **Decision**: which option was chosen
- **Rationale**: why (citing Decision Drivers)
- **Consequences**: what becomes easier, what becomes harder
- **Follow-ups**: what must be resolved next

## Implementation Sketch
3–6 actionable steps. No code — what to build/change/delete. Each step becomes a DISPATCH.md Step.

## Test Plan
How we will know this worked. Specific, verifiable conditions.

RULES:
- Anchor code references by grep pattern, NEVER line numbers.
- Be specific — no "consider X" recommendations.

Save to: {plan_path}
If file already exists: read existing, find max version N in filenames matching {name}-v*.md, save as {name}-v{N+1}.md

Step 2 — Preflight Validation

~/.nexus/scripts/plan-preflight.sh {plan_path}
EXIT_CODE=$?

• exit 0 (even with warnings printed): proceed — warnings are informational
• exit ≥1: STOP. Show the error output. Fix the plan (re-invoke Step 1 subagent with error as context). Re-run preflight. Do NOT proceed to audit with exit ≥1.

Step 3 — Parallel Audit (single message, two GPT-5.6 Sol/max Task calls)

Launch BOTH in a single assistant message turn:

Task A: subagent_type: "forge-auditor", prompt: FORGE-AUDIT plan at {plan_path}. Tier: DEEP. Focus: completeness of options, ADR rationale, verifiable test plan, actionable sketch. Return full NPLF report.

Task B: subagent_type: "forge-auditor-b", prompt: FORGE-AUDIT-B plan at {plan_path}. Tier: DEEP. Pragmatic lens: will this plan work in real NexusOS? Flag over-engineering, missing edge cases, integration risks with existing agents. Return full NPLF report.

Step 4 — Reconcile (GPT-5.6 Sol/max)

Dispatch subagent_type: "audit-reconciler" with both reports concatenated as input.

Step 5 — Gate Decision

Step 6 — Output

On success:

RALPLAN COMPLETE
Plan: {plan_path}
Score: {X}/4.0 — {PASS/CONDITIONAL}
Resolved conflicts: {from reconciler, or "none"}
Unfixed (if CONDITIONAL): {list}
Ready for TECH: YES — add as Source Plan in DISPATCH.md

SHORT vs DELIBERATE

• SHORT (default): Principles + Drivers + Options + ADR + Sketch + Test Plan
• DELIBERATE (--deliberate): add to Step 1 prompt: also produce ## Pre-Mortem (top 5 failure modes + mitigations) and ## Expanded Test Plan (unit/integration/manual QA matrix)