--- title: internal/genesis description: Go API reference for the genesis package. --- # genesis ```go import "github.com/jbcom/radioactive-ralph/internal/genesis" ``` Package genesis implements the planning\-genesis flow described in docs/superpowers/specs/2026\-07\-16\-supervisor\-architecture\-design.md §11 $"Planning genesis"$: turning a vague prompt $or an already\-drafted markdown doc$ into a complete, validator\-clean plan document. The spec's framing is deliberate: rather than building question\- extraction machinery, a small team of agents JUXTAPOSE and CHALLENGE each other's read of the input until it converges on a plan that covers the work end\-to\-end. The refined markdown document IS the review surface \-\- headless mode emits it, TUI mode renders it for scroll/edit review $see review.go$. Users may also skip planning entirely and run their input as\-is. This file implements the orchestration SHAPE: Refine takes a pluggable Refiner so the flow is fully testable with fakes; a real multi\-agent juxtaposition implementation $dispatching real provider.Runner agents against each other$ is a Refiner value documented alongside NewProviderJuxtaposition, not baked into Refine itself. ## Index - [Variables](<#variables>) - [func Refine$ctx context.Context, input string, refiner Refiner, opts RefineOptions$ $\[\]byte, error$](<#Refine>) - [func RenderForReview$md \[\]byte, opts ReviewOptions$ $final \[\]byte, findings \[\]plan.PlanError, err error$](<#RenderForReview>) - [func Skip$input string$ \[\]byte](<#Skip>) - [type ProviderJuxtaposition](<#ProviderJuxtaposition>) - [func $j ProviderJuxtaposition$ Refine$ctx context.Context, draft string$ $next string, done bool, err error$](<#ProviderJuxtaposition.Refine>) - [type RefineOptions](<#RefineOptions>) - [type Refiner](<#Refiner>) - [type ReviewMode](<#ReviewMode>) - [type ReviewOptions](<#ReviewOptions>) ## Variables ErrRefinementDidNotConverge is returned when Refiner never reports done=true within MaxRounds with output that parses into at least one step. plan.Parse itself is extremely permissive $goldmark parses essentially any text into SOME AST$, so "valid" here means both parses cleanly AND yields a non\-empty step universe $plan.Plan.StepIDs$ \-\- otherwise a refiner could "converge" on an empty or narrative\-only document that plan.Parse happily accepts but that is not actually a plan. Advisory plan.Validate findings $ambiguous sections, etc.$ do NOT block convergence; a plan that merely has ambiguities the author should tighten up is still a usable plan, per plan.Validate's own doc comment $"advisory... never blocks Parse from running"$. ```go var ErrRefinementDidNotConverge = fmt.Errorf("genesis: refinement did not converge to a valid plan within the round budget") ``` ## func [Refine]() ```go func Refine(ctx context.Context, input string, refiner Refiner, opts RefineOptions) ([]byte, error) ``` Refine runs the agent\-juxtaposition refinement loop against input $a vague prompt OR a full markdown doc$ using refiner, and returns the final plan markdown once refiner reports done=true AND the result parses cleanly per plan.Parse $the spec's "converging on a final markdown plan \(validated by internal/plan.Validate$" requirement\). Refine itself never talks to a CLI/network \-\- refiner does. This keeps the orchestration shape $round loop, convergence check, parse\-validate gate$ testable with an in\-memory fake while a real implementation plugs in a Refiner that dispatches provider.Runner agents. ## func [RenderForReview]() ```go func RenderForReview(md []byte, opts ReviewOptions) (final []byte, findings []plan.PlanError, err error) ``` RenderForReview presents md to the operator per opts.Mode and returns the $possibly operator\-edited$ final markdown plus its plan.Validate findings, so callers can surface ambiguities either way. It never blocks on ReviewHeadless $a pure emit$; ReviewEditor blocks for the duration of the external editor process, mirroring how \`git commit\` hands off to $EDITOR. ## func [Skip]() ```go func Skip(input string) []byte ``` Skip implements the spec's "users may also skip planning and run their input as\-is" path: it returns input unchanged as the plan document, with no refinement round at all. Callers still typically run the result through plan.Validate $see review.go's RenderForReview$ so an operator sees any structural findings before dispatch, but Skip itself performs no validation \-\- "as\-is" means as\-is. ## type [ProviderJuxtaposition]() ProviderJuxtaposition is the documented REAL Refiner implementation referenced by genesis.go's package doc: it dispatches two provider agents against the current draft each round \-\- a "challenger" that looks for gaps/ambiguity and an "integrator" that folds the challenge into a tightened plan document \-\- and reports done once the challenger finds nothing left to contest. This is the "team of agents juxtapose and challenge each other" mechanism from spec §11, expressed as a Refiner so it plugs directly into Refine without Refine itself needing to know anything about providers/prompts. Bindings may be the same provider/model for both roles or different ones; using two distinct providers $e.g. claude as integrator, codex as challenger$ is the configuration that most literally realizes "juxtapose", but a single provider run twice with different system prompts is equally valid and cheaper. ```go type ProviderJuxtaposition struct { Challenger provider.Runner Integrator provider.Runner ChallengerBinding provider.Binding IntegratorBinding provider.Binding WorkingDir string } ``` ### func $ProviderJuxtaposition$ [Refine]() ```go func (j ProviderJuxtaposition) Refine(ctx context.Context, draft string) (next string, done bool, err error) ``` Refine adapts ProviderJuxtaposition to the Refiner func type so it can be passed directly to genesis.Refine. ## type [RefineOptions]() RefineOptions configures Refine. ```go type RefineOptions struct { // MaxRounds bounds how many times Refiner is invoked before Refine // gives up waiting for convergence. Must be >= 1. Defaults to 6 when // zero. MaxRounds int } ``` ## type [Refiner]() Refiner produces a candidate plan markdown document from the current best draft. Refine calls it in a loop $see RefineOptions.MaxRounds$: each round's output becomes the next round's input, so a Refiner is free to make small incremental improvements rather than needing to solve the whole problem in one call. Round 0's input is the caller's original prompt/doc verbatim. A real implementation dispatches two or more provider agents that challenge/expand round\-over\-round; see the $forthcoming, real\-CLI\- backed$ juxtaposition Refiner. Tests use a fake func value directly \-\- Refiner is a plain func type so no interface/mock boilerplate is needed to exercise Refine's convergence/validation logic. ```go type Refiner func(ctx context.Context, draft string) (next string, done bool, err error) ``` ## type [ReviewMode]() ReviewMode selects how RenderForReview presents a plan document to the operator once genesis produces it $spec §11: "headless mode \-\> emits the final markdown plan. TUI mode \-\> renders that markdown for review \(scroll, an embedded editor, or open\-in\-$EDITOR \-\- both offered$"\). ```go type ReviewMode int ``` ```go const ( // ReviewHeadless just emits the markdown (to Options.Writer or a // file) with no interactive review step. ReviewHeadless ReviewMode = iota // ReviewEditor hands the document to the operator's $EDITOR (or // Options.Editor) via a plain os/exec run, then reads the (possibly // edited) file back. This is the "open-in-$EDITOR" option; the TUI's // embedded-scroll/textarea option is a Bubble Tea concern that lives // in internal/tui, not here -- this package only owns the handoff // contract (WriteTempFile / ReadBack below) the TUI's tea.ExecProcess // wiring needs. ReviewEditor ) ``` ## type [ReviewOptions]() ReviewOptions configures RenderForReview. ```go type ReviewOptions struct { Mode ReviewMode // Writer receives the markdown in ReviewHeadless mode. Defaults to // os.Stdout when nil. Writer io.Writer // Editor overrides the command run in ReviewEditor mode. Defaults to // the $EDITOR environment variable, falling back to "vi" if unset. Editor string // TempFilePath, if set, is used instead of a freshly created temp // file for ReviewEditor mode. Primarily for tests that want to // inspect the file the "editor" was pointed at. TempFilePath string } ``` Generated by [gomarkdoc]()