Generate Plan

This repository-native skill is adapted from the gen-plan flow in PolyArch Humanize. It turns an episode draft into a complete implementation plan without modifying source code or starting the implementation.

Arguments

• --input <path>: required draft document.
• --output <path>: required new plan document.
• --direct: generate a one-shot plan without asking questions.
• --discussion: ask for decisions that materially change the plan. This is the default when no mode is supplied.

--direct and --discussion are mutually exclusive.

Episode mode

Python supplies ATREX_EPISODE_MODE (default: full). Fast/full plans must contain exactly one coherent optimization category. Goal plans may cover multiple evidence-backed directions, including interacting algorithm, layout, and kernel changes; validate the combined result. The campaign selects the mode and reviewer configuration. Both reviewers default off for V1, fast episodes, and full episodes. Enable the desired reviewer with the stage-specific --v1-ask-*, --fast-episode-ask-*, or --full-episode-ask-* flag. When invoking the shell helpers outside a campaign, explicitly set ATREX_PLAN_REVIEW_CODEX_ENABLED=1 or ATREX_PLAN_REVIEW_QODER_ENABLED=1 to enable that reviewer; otherwise it stays disabled.

Hard boundaries

• During this workflow, persist only the requested plan file. Consultation helpers may use automatically removed process scratch for isolation.
• Do not edit source, run implementation tasks, create commits, or start another workflow.
• Enabled ask_codex and ask_qoder consultations are read-only. They are non-persistent by default; an explicitly configured long Codex or Qoder reviewer session remains read-only and campaign-private. Give every enabled reviewer the same candidate proposal and bounded evidence packet, isolate both from the project, and disable Qoder tools.
• Preserve every requirement, constraint, measurement, search result, and rejected direction from the draft. The structured plan must be a superset of the draft.
• Keep the original draft verbatim at the bottom of the plan between the template markers.

Workflow

Execute these phases sequentially.

1. Validate input and output

From the campaign workspace, run:

bash skills/gen-plan/scripts/validate-gen-plan-io.sh \
  --input <input> --output <output> <mode>

Stop on a nonzero exit. The script reports the resolved input, output, template, and mode. It never creates the output file.

2. Check relevance

Read the draft and quickly inspect the workspace README, goal, current kernel, prior memory, and any paths named by the draft. Reject only a draft that is clearly unrelated to this repository. Be lenient with informal drafts and mixed languages.

3. Analyze the draft

Build an evidence-to-action chain:

1. Identify the measured bottleneck or failure.
2. Connect the evidence to a concrete inference.
3. Select exactly one coherent optimization category for fast/full, or an evidence-backed roadmap for goal.
4. Identify the smallest concrete file changes that test that inference.
5. Define correctness, performance, rollback, and stop conditions.

Before consulting either reviewer, populate skills/gen-plan/templates/candidate-proposal-template.md in automatically removed process scratch. This frozen candidate proposal is not the final plan. It must state the selected evidence-to-action chain, the episode mode and permitted optimization categories, target paths and symbols, the expected mechanism, scope constraints, rejected directions, validation and falsification conditions, and unresolved assumptions. Do not persist the candidate proposal in the campaign workspace.

Check the draft for unclear scope, contradictions, missing dependencies, infeasible changes, and quantitative targets. Treat numeric performance targets as trends unless the draft explicitly marks them as hard acceptance thresholds.

In direct mode, make conservative assumptions and record unresolved material choices under Pending Decisions; do not pause for questions. In discussion mode, ask only questions whose answers materially change scope, correctness, or acceptance.

4. Obtain configured independent reviews

The campaign independently configures Codex and Qoder for fast and full episodes. It probes a reviewer only when that reviewer is first enabled for the current episode mode, then caches the availability decision in private runtime state. A reviewer disabled by configuration or by its availability probe must not be retried; retain the helper's disabled status and recorded reason. Campaign restarts reuse cached availability decisions.

After completing the initial analysis, freeze one evidence packet and use the bundled review helper before finalizing the plan direction. Give every enabled reviewer the candidate proposal, original draft, and the same small set of directly relevant text files, normally README.md, kernel.py, the latest canonical memory entry, and source or profile summaries cited by the draft. The candidate is the primary review target; the draft and context are evidence for testing its claims. Never include credentials, raw secrets, unrelated files, or large binary profile artifacts.

bash skills/gen-plan/scripts/ask-reviewers.sh \
  --input <input> \
  --proposal <temporary-candidate-proposal> \
  --context README.md \
  --context kernel.py

--proposal is required and must name the non-empty frozen candidate proposal in process scratch. Add other --context arguments only when they materially affect the plan. The helper starts the enabled external reviewers concurrently so neither can see or anchor on the other's response. When proposal, draft, and context would exceed Qoder's five-attachment limit, the helper folds all context files into one labeled temporary bundle and gives that identical bundle to every enabled reviewer. Do not manually remove evidence or issue a second full review call. For an eligible transient failure, the helper retries only the failed reviewer once; it does not rerun a successful reviewer and does not retry quota, authentication, timeout, disabled, or missing-CLI failures. Enabled external reviewer processes always use maximum reasoning effort; episode/session settings, reviewer effort environment variables, and legacy --reasoning-effort arguments cannot lower it. By default each external review is ephemeral. --long-reviewer-session codex or --long-reviewer-session qoder resumes one campaign-private, read-only reviewer thread across episodes while continuing to send the complete current candidate proposal, draft, and bounded context on every call. Long Claude reviewer sessions are not implemented and fail explicitly. Session state lives under .atrex_long_horizon/ and must never enter a candidate commit. Because qodercli only resolves resumable sessions within the current working directory's project, a persistent Qoder reviewer runs from a dedicated directory alongside its state file, which also keeps it isolated from the candidate project. Each review returns its backend-specific summary marker followed by the same five assessment sections:

• CODEX_SUMMARY or QODER_SUMMARY
• RISKS
• MISSING_REQUIREMENTS
• DIRECTION_RECOMMENDATIONS
• VALIDATION_RECOMMENDATIONS
• QUESTIONS_OR_ASSUMPTIONS

If the current episode backend is Codex or Qoder and its matching ATREX_PLAN_REVIEW_*_ENABLED value is not 0, first review the frozen candidate proposal and retain that backend's review in the current session using the same sections. Only then run the helper; it skips the matching nested process and obtains any other enabled backend's independent review. Mark the retained review status current_codex_session or current_qoder_session. Do not revise it after seeing the external review; resolve new information only during synthesis. If the matching reviewer is disabled, do not create an in-session substitute review; let the helper record disabled.

After the helper's selective retry, if an enabled reviewer is unavailable, times out, or fails, do not fabricate its advice or rerun the successful reviewer. In direct mode, continue with the available review and conservative analysis, recording each status and failure reason. If every enabled reviewer fails, continue using only the primary analysis and label the result as unreviewed. In discussion mode, ask whether to retry only the failed reviewer or continue with partial or no independent review. A reviewer explicitly marked disabled is not a failure and must not trigger a retry question. If every reviewer is disabled, continue with primary analysis and label the plan as intentionally unreviewed.

5. Synthesize available reviews and generate the plan

Compare all available reviews only after the helper has completed. When both are enabled, treat agreement as a useful confidence signal, not proof, and resolve disagreement from the original draft and repository evidence rather than by majority vote. Evaluate every recommendation as follows:

1. Adopt a suggestion only when it strengthens the selected evidence-to-action chain, closes a correctness gap, or makes validation more deterministic.
2. Reject suggestions that contradict measured evidence, violate campaign constraints, or introduce another optimization category in fast/full mode.
3. Defer suggestions that are plausible but need evidence outside the current plan.
4. Resolve conflicting suggestions explicitly, stating the evidence that selected one or rejected both.
5. Convert unresolved reviewer questions into conservative assumptions or pending decisions according to the selected direct/discussion mode.

Record how the frozen candidate changed after review. Every material correction must identify the reviewer and supporting evidence; if the candidate remains unchanged, state why the reviews did not justify a change.

Available reviewers are advisory, not authoritative. The final plan must remain a superset of the human draft and must still contain exactly one optimization category in fast/full mode.

Use skills/gen-plan/templates/gen-plan-template.md as the output schema. Replace every placeholder with concrete content. The plan must include:

• the goal and the profile/research evidence that motivates it;
• Codex and Qoder consultation status (including configured-disabled status), available material findings, agreements, disagreements, and the suggestions adopted, rejected, or deferred with reasons;
• the episode mode, its permitted optimization categories, and evidence-to-inference-to-action chains;
• acceptance criteria in AC-N form, each with positive and negative tests;
• upper and lower scope boundaries plus allowed and prohibited choices;
• exact target paths and a dependency-ordered implementation sequence;
• full-workload correctness, multi-seed correctness, and comparable performance validation;
• measurable success, rollback, and direction-exhaustion conditions;
• any assumptions or pending decisions; and
• the original draft, unchanged, at the bottom.

Use milestones, phases, and steps rather than time estimates. Refer to code by path and symbol, not by line range. Plan terminology such as AC-N, Milestone, and Phase belongs in the plan only and must not be prescribed as implementation naming.

6. Review and write

Before writing, verify that the plan:

• does not omit or contradict the draft;
• uses available reviews selectively and records the disposition of material suggestions and conflicts;
• records the frozen candidate and the evidence-based changes made after review;
• proposes only one attributable optimization category in fast/full mode, or an attributable roadmap in goal mode;
• names concrete files and validation commands;
• distinguishes correctness from performance evidence;
• has deterministic, measurable acceptance and rollback conditions; and
• contains no implementation changes made during planning.

Write the complete plan to the validated output path, then read it back and fix any remaining placeholder, inconsistency, or missing draft content. Report the output path, optimization category, both consultation statuses, adopted-suggestion count, acceptance-criteria count, and pending-decision count.

Validation exit codes

Exit code	Meaning
0	Validation passed
1	Input file not found
2	Input file is empty
3	Output directory does not exist
4	Output path already exists
5	Output directory is not writable
6	Invalid arguments
7	Plan template is missing

Reviewer consultation exit codes

Exit code	Meaning
0	Consultation completed, or nested invocation intentionally skipped for the matching backend
1	Draft, candidate proposal, or context input is invalid
2	Helper arguments or environment configuration are invalid
3	Reviewer response is missing one or more required review sections
124	Reviewer consultation timed out
127	Reviewer CLI could not be found or started

ask-reviewers.sh reports the exit status of each child consultation in its structured output and returns successfully once both attempts finish, allowing direct mode to retain a surviving review.