Product & development playbooks

Declare inputs and outputs separately

This selected excerpt comes from the requirements playbook definition. Imports and the remaining definition are omitted:

preconditions: [
  { kind: MetaWorkflow_PredicateKind.ARTIFACT_VALID, selector: { family: 'vision-brief' } },
  { kind: MetaWorkflow_PredicateKind.ARTIFACT_VALID, selector: { family: 'market-snapshot' } },
],
inputs: [
  { family: 'vision-brief' },
  { family: 'market-snapshot', intent: MetaWorkflow_ArtifactIntent.VALUE },
],
outputs: [{
  family: 'requirements',
  schemaRef: 'saas-specifications:RequirementsSnapshot',
}],
method: {
  skillRefs: ['journey-status', 'journey-report'],
},

The excerpt omits the output’s descriptive metadata for clarity. A precondition asks whether the work may start; an input selects information for that work; an output names the artifact contract. A skill supplies instructions. These declarations answer different questions even when they refer to the same family.

Author the method where it belongs

Each catalog folder holds playbook.definition.ts beside method.md. The generator evaluates supported declarative syntax without executing the definition, expands method references and validates the compiled playbook. method.guidance comes from the Markdown rather than a second inline copy.

Review the connected result

A valid definition establishes a method contract. The method still needs useful instructions, appropriate skills and an executor capable of producing its declared result. Review those together when adding a playbook; a phase label alone establishes no dependency order.

The connected requirements example follows this registered method through its HTTP invocation, response and specification files.

Select computed context deliberately

The document-facts method contains this selected configuration:

method: {
  contextSources: [
    MetaWorkflow_ContextSource.COMPLIANCE_PRIMARY_FACTS,
    MetaWorkflow_ContextSource.DOCUMENT_FACT_OBLIGATIONS,
  ],
  skillRefs: ['journey-status'],
},

Its method prose includes the following literal placeholder:

{{CONTEXT_SOURCE:compliance_primary_facts}}

During framework-knowledge compilation, expandContextSourcePlaceholders checks the named member and the method’s own declaration before replacing a supported placeholder. Unknown members and undeclared sources are refused. The catalog audit reports corresponding mismatches.

Keep inputs and context distinct

Artifact inputs select specification families. contextSources requests computed sections or catalogs, such as application declarations and document obligations. The source vocabulary carries the meaning of each supported section, and the companion composes the sections requested by the method.

Adapt context without changing the method permanently

For supported generation runs, briefAdequacyGate optionally checks whether the composed brief is sufficient. An insufficient result can add permitted sources for that run and trigger one recomposition. briefAdequacyExcludedSources keeps deliberately excluded sections out of this widening.

The widening preserves declared sources. If the auxiliary check fails, generation retains the static brief. This check helps context selection; it does not establish that every source is complete or that the generated answer used it correctly. Review evidence in the resulting artifact as well as the source declaration.

Read the evaluated contract

The current eligibility result exposes these selected fields:

readonly playbookRef: string;
readonly intent: string;
readonly eligible: boolean;
readonly preconditions: readonly PlaybookPreconditionVerdict[];
readonly unmet: readonly string[];
readonly blockedOnlyBySequencing: boolean;
readonly requiresElicitation: boolean;
readonly wouldReplace: readonly string[];
readonly unlandableFamilies: readonly string[];
readonly staleOutputs: readonly {
  readonly family: string;
  readonly changedInputs: readonly string[];
}[];

This is an interface excerpt, not an application configuration. The evaluator combines the playbook, artifact state and the set of families the runtime can land. Each unsatisfied condition contributes an actionable explanation to unmet.

Keep annotations useful

wouldReplace exposes existing output content. staleOutputs describes changed inputs using the supplied Git freshness facts. Neither is a claim that the old result is semantically wrong. They help a person or selector decide whether another run is worth doing.

An already executed build plan can also make decomposition a sequencing concern when its upstream inputs are unchanged. Editing an upstream family reopens that reason to work.

Inspect current readiness

wildo context journey presents the board through the companion. The companion also exposes GET /playbooks and POST /playbooks/refresh-board. Treat a displayed board as the state evaluated at that time: the unattended loop reads again before each iteration. Eligibility establishes that declared prerequisites hold; it does not predict the quality of the result.

See the work a composite can affect

Replacement, freshness and unavailable-renderer annotations include the outputs declared by a composite’s children. outputOwners identifies the declaring playbooks; unresolvedPlaybookRefs identifies missing child definitions. These details describe possible effects, while the parent’s readiness continues to follow its own declared conditions. A child warning alone does not disable the parent.

Read current state for every iteration

This selected runtime excerpt shows the boundary between state evaluation and unattended selection:

for (let iteration = 1; iteration <= input.maximumIterations; iteration += 1) {
  const state = await input.readArtifactState();
  const board = evaluatePlaybookCatalogEligibility({
    playbooks: input.playbooks,
    state,
    landableFamilies: input.landableFamilies,
  });
  const eligible = board.playbooks.filter(
    (entry) => entry.eligible && !entry.requiresElicitation,
  );
  // Selection and execution follow for this iteration.
}

The excerpt shortens the surrounding trace and execution code. Methods requiring creator answers are excluded from unattended selection. They remain available through the explicit run path, where the required interaction can occur.

Separate selection from admission

The selector receives eligible references, intent and useful state annotations. Its structured response bounds the number of lanes, rejects duplicate choices and makes stop an exclusive choice. The runtime then checks proposed lanes for overlapping declared write scopes and records any lane held back.

Admitted lanes settle independently. The next iteration rereads project artifacts, so new landed information becomes available through the normal state reader.

Set the scope of an unattended attempt

The companion’s POST /playbooks/loop accepts a goal and iteration/lane settings. One loop is active per companion; a second request receives an explicit refusal. An explicit individual run is a separate path.

The loop’s iteration and fan-out settings are execution ceilings, not token or financial budgets. Completion of an iteration means its lanes settled; it does not establish that every application concern is resolved. Use the recorded outcomes and resulting product artifacts to review the work.

Admit children without prescribing a sequence

This selected configuration comes from the market-analysis umbrella:

outputs: [],
method: {
  choreography: {
    admits: [
      'top_down.market-snapshot-produce',
      'top_down.market-research',
      'top_down.market-evidence-adequacy',
    ],
    maximumIterations: 10,
    maximumLanesPerIteration: 3,
    maximumDurationMs: 2_400_000,
  },
},

The producer appears first intentionally: admits is membership, not execution order. The parent declares no artifact output of its own. Its children land the result, and write-scope admission includes their outputs when considering concurrent work.

Gate production on the result of the check

The producer’s selected precondition requires a specific verdict:

{
  kind: MetaWorkflow_PredicateKind.STEP_AVAILABLE,
  ref: 'evidence-adequacy',
  requires: { path: 'verdict', equals: 'adequate' },
},

A check having run is insufficient: its schema-validated return must contain the required value. When new research arrives, the runtime removes verdicts that depend on it, including indirect dependencies. Production becomes eligible again after reassessment returns the required verdict. A round also separates a step writer from siblings that need its result, so a producer cannot race new research using an older assessment.

Research and adequacy results are stepOutputs in the run’s context; they remain separate from persisted specification families.

Understand repetition and completion

The runtime reads artifact state together with current step results each iteration. A child that lands an artifact enters the delivered set and is removed from subsequent selection. A child returning only a step result can run again, which supports another research or assessment pass.

Research contributions accumulate as attributed text under their shared step reference, preserving earlier sources across parallel and later rounds. Structured assessment results replace their previous verdict. The selector, assessor and producer receive the retained evidence.

Successful siblings retain their results when another child fails. Checkpoints preserve the completed iteration count and returned work used by a resumed run. Iteration, duration and lane ceilings bound the attempt; a stop reason identifies whether work exhausted its options, chose to stop, reached a ceiling or saw every child in a round fail.

Those outcomes describe execution, not a blanket quality approval. An adequacy result and a landed artifact answer different questions and should remain visible separately.

Include children in the scope

This selected runtime implementation walks admitted descendants as well as the parent:

const families = new Set<string>();
const unresolvedRefs: string[] = [];
const visited = new Set<string>();
const pending: string[] = [playbookRef];
while (pending.length > 0) {
  const ref = pending.shift()!;
  if (visited.has(ref)) continue;
  visited.add(ref);
  const playbook = playbooksByRef.get(ref);
  if (playbook === undefined) {
    unresolvedRefs.push(ref);
    continue;
  }
  (playbook.outputs ?? []).forEach((output) => families.add(output.family));
  pending.push(...(playbook.method?.choreography?.admits ?? []));
}

This is an excerpt from resolvePlaybookWriteScope, not an application extension point. A composite with outputs: [] is therefore not assumed to write nothing when its children produce artifacts.

Admit a compatible portfolio

The admission function walks proposed lanes in order. It holds back a later lane whose families overlap those already admitted and returns a reason for that decision. If a referenced child cannot be resolved, its scope is unknown: it can run alone, but is not treated as safe to combine with another lane.

The outer loop bounds its portfolio, and composites also bound child concurrency. Child results are collected before the next selection round.

Keep concurrency claims precise

This mechanism compares declared artifact outputs within the managed round. It is not a filesystem sandbox or a branch-and-merge service, and it does not turn unrelated manual writers into coordinated lanes.

Several independently managed, long-running choreographies with their own goals and merge lifecycle remain a distinct design target. The available mechanism is parallel work inside a controlled round; application authors should plan around that concrete boundary.

Declare questions with stable references

This excerpt comes from the brand method’s declared interview. It shows a free-text answer and a choice whose values are explicit:

{
  "questions": [
    {
      "ref": "brand-name",
      "question": "What is the exact, case-sensitive brand name the logo should render?",
      "kind": "free_text"
    },
    {
      "ref": "brand-tagline",
      "question": "Is there a tagline? Answer none if not.",
      "kind": "free_text"
    },
    {
      "ref": "logo-mark-type",
      "question": "Which logo archetype fits the brand?",
      "kind": "choice",
      "options": ["combination_mark", "wordmark", "lettermark", "pictorial_mark", "abstract_mark", "emblem", "mascot"]
    }
  ]
}

Question wording is shortened here for readability; the actual method declares the full interview in method.elicitation. A host must submit answers for the complete declared question set, using questionRef and answer, not only this excerpt.

Validate the answer before composing the brief

composeElicitationSection matches each answer to its question, rejects duplicate or unknown references, trims text and refuses empty answers. It then requires every declared question to have an answer.

Nuance belongs in an accompanying free-text answer. An ambiguous confirmation is refused rather than interpreted as consent or a product fact.

Carry the answer into the work

The companion composes the validated interview into the method brief. Composite work passes the parent’s rendered answers into its child context, so related methods can reason from the same supplied decisions.

Declare a question when the answer genuinely requires the creator. Existing specifications and gathered evidence should supply facts already available to the method. Compliance posture, for example, derives from evidence and adequacy work rather than a fixed questionnaire asking the creator to reconstruct obligations.

An upfront interview establishes known inputs. The clarification channel handles a consequential question discovered during generation preparation.

Opt the method into clarification

A method declares suspendsForClarification: true. The companion supplies a clarification port to the generation runner, with prior answers and a bounded round budget.

The model receives the same brief used for generation and is asked only about decisions that cannot be derived from supplied context and would change the artifact. Routine preferences and information already available in the framework should not interrupt work.

This source excerpt shows the interrupt returning before the generation attempt loop:

  if (requests.length > 0) {
    await trace.event({
      type: PlaybookExecutionTraceEvent.CLARIFICATION_REQUESTED,
      summary: `"${output.family}" stopped for ${requests.length} decision(s) only the creator can make`,
      payload: { family: output.family, requests: requests.map((request) => ({ ref: request.ref, question: request.question })) },
    });
    return { suspended: true, playbookRef: input.playbookRef, family: output.family, requests };
  }
}
const rejectedFindings: string[] = [];
let accepted: unknown;
let attempts = 0;
while (attempts < maximumAttempts) {
  attempts += 1;
  const prompt = attempts === 1

The pause belongs to this participating artifact-generation invocation. It is not a promise that an enclosing choreography has performed no earlier work.

Continue through the companion

The host lists waiting work at GET /api/companion/playbooks/suspended and resumes a selected run at POST /api/companion/playbooks/runs/:runId/resume.

The resume request carries action and, for an answer, answers containing ref and answer. References identify the questions shown by the suspended run. Reuse those references rather than inventing labels when submitting responses.

Understand what resume preserves

The checkpoint keeps the creator brief, declared interview answers, accumulated clarification questions and answers, and the rounds spent. Resume calls the playbook again with that context; it does not restore an in-memory model call. The old checkpoint is consumed after continuation returns, while another suspension saves its successor.

Questions are accumulated by reference with their original wording. The generation landing carries the exchange beside the artifacts it shaped. A declined decision should be visible as an assumption wherever the artifact can express it, rather than being presented as an answer the creator supplied.

Treat clarification as guidance, not authorization

The clarification check fails softly: a model error or unparsable response lets generation proceed. The question and round bounds also prevent repeated interruption from becoming an endless interview. This mechanism improves the information used for a derivation; it is not an approval gate or an independent safety check.

Preserve decisions across a pause

Accepted answers must match the outstanding questions: duplicates, unknown references, blank text and invalid choices are refused without consuming the waiting run. Confirmation answers use the same yes/no interpretation as declared interviews. Declining a later question delegates that question while preserving earlier answers as the creator’s decisions.

A dry run stays a preview after clarification. Resuming does not turn it into file writes, even if the caller sends dryRun: false; start a new ordinary run when ready to produce files. Older disposable checkpoints without a recorded mode resume as previews.

A playbook declares an output family and schema reference. The runtime resolves every output binding before invoking generation and rejects unknown families or mismatched schema references. The host supplies the generation adapter, including provider configuration and call handling.

A family can declare a stricter generation schema alongside its stored schema. The runtime selects it here:

      const generated = await input.model.generate({
        prompt,
        schema: binding.generation?.schema ?? binding.snapshotSchema,
        label: `${input.playbookRef}:${output.family}`,
      });

The distinction allows generation-specific requirements, such as a meaningful minimum collection, while retaining the application’s stored representation. It is a request and validation contract, not a claim that a model can never produce an invalid response.

Normalize the answer, then test its meaning

A family normalizer can assign stable reference shapes and versions before semantic validation. The run supplies its recorded time to normalizers that need it, so related outputs share the same observation instant.

This excerpt shows normalization failures becoming correction findings:

      let candidate: unknown;
      try {
        candidate = binding.generation ? binding.generation.normalize(generated.output, { recordedAt, nextReviewOn: input.nextReviewOn }) : generated.output;
      } catch (error) {
        const findings = error instanceof z.ZodError
          ? error.issues.slice(0, 20).map((issue) => `${issue.path.map(String).join(".") || "<root>"}: ${issue.message}`)
          : [error instanceof Error ? error.message : String(error)];
        await trace.event({
          type: PlaybookExecutionTraceEvent.GENERATION_REJECTED,
          summary: `"${output.family}" failed its strict generation contract on attempt ${attempts}`,
          payload: { family: output.family, attempt: attempts, errorDetails: findings },
        });
        rejectedFindings.push(findings.join("\n"));
        accepted = undefined;
        continue;
      }

Provider-side schema findings are also retained when no output object is returned. Generation uses bounded findings-guided retries, then reports failure rather than treating a malformed answer as a finished artifact.

Keep the boundaries connected

Some families use their stored schema directly. Read the registered binding to know which normalization and extra generation constraints apply. A valid object still needs product judgment and implementation evidence; structured generation makes it consumable, not automatically correct.

The semantic binding first parses the stored schema, then runs the family’s validator. Errors and warnings have different effects. This source excerpt is the result mapping after successful schema parsing:

      const result = input.runValidator(parsed.data);
      const errors = result.issues.filter(input.isErrorSeverity);
      const warnings = result.issues.filter((issue) => !input.isErrorSeverity(issue));
      return {
        validation: errors.length === 0 ? JourneyArtifactValidationState.VALID : JourneyArtifactValidationState.INVALID,
        errorCount: errors.length,
        warnCount: warnings.length,
        errorDetails: errors.map((issue) => `[${issue.kind}] ${issue.path}: ${issue.message}`),
        errors: errors.map((issue) => ({ kind: issue.kind, path: issue.path, message: issue.message })),
      };

A schema error identifies a field or shape problem. Family findings can explain repeated references, inconsistent links or invalid relationships. The generation loop includes reported errors in its bounded correction attempts; a warning remains information to inspect.

Supply the context the check requires

A family validator called without optional external resolution sets cannot prove that every external reference resolves. The generation and landing paths have explicit cross-artifact helpers for supported relationships. A missing context input and an intentionally empty set are different conditions; callers must provide the application context they expect to validate.

Check the result that will actually be written

Landing validates the produced value before rendering. Where one produced document is merged into a document set, the merged result is also checked. The supported dangling-reference comparison overlays the candidate on loaded families and reports newly introduced citing-side references; it does not refuse every pre-existing inconsistency or every old reference orphaned by a legitimate replacement.

The broader coherence report remains useful after changes. These checks establish supported structural relationships, not whether a requirement is desirable or whether the implementation satisfies it. Those questions need review and execution evidence.

Read the current application’s report

Run the command from an application scope with its development companion available:

wildo context health
wildo context coherence

The CLI requests /api/companion/playbooks/coherence and prints the companion’s Markdown report. The source header identifies the companion and the working-tree/export basis, which matters when comparing a report with an edit that has not reached compiled exports yet.

Interpret findings before acting

An empty findings list is meaningful together with the input lists. It is not evidence that every possible product relationship was checked.

See a concrete cross-family check

This source excerpt compares roadmap requirement references with declared requirements:

if (roadmap && requirements) {
  const dangling = difference([...roadmapDeliveredRequirements], requirementRefSet);
  if (dangling.length > 0) {
    findings.push({
      ref: "roadmap-delivers-unknown-requirement",
      kind: ApplicationCoherenceFindingKind.DANGLING,
      summary: `${dangling.length} roadmap phase reference(s) to a requirement that does not exist.`,
      refs: dangling,
    });
  }
}

The semantic authority supplies the family universe and schemas. The coherence owner explicitly partitions supported families into those with checks and those with a documented reason for exclusion. Adding a family therefore requires a deliberate coverage decision, rather than a second forgotten inclusion list.

Connect the report to production and review

The companion serves the report for interactive inspection; methods can request coherence context when preparing work. Generation also checks a candidate against landed related artifacts and can reject new dangling references. That candidate check and the advisory report are different consumers of the same relationships.

For governed documents, reference and section coverage establishes declared connections. It does not establish that the writing adequately satisfies a legal obligation. Review substantive meaning with the relevant evidence as well as inspecting the report.

The choreography result carries a provenance entry for a child that lands content when source URLs are present in step results accumulated before that round starts. evidenceUrlCount is the distinct collected-address count; citedUrlCount is the intersection with addresses found in the child’s landed values.

Before dispatching the round, the runtime snapshots source addresses with const priorEvidenceUrls = collectProvenanceUrls([...stepResults.values()]). Every child in that round is compared with this same set, so its own returned sources and concurrent sibling results cannot count retroactively.

This selected excerpt shows the subsequent comparison:

      if (childLanded.length > 0) {
        const evidenceUrls = priorEvidenceUrls;
        if (evidenceUrls.size > 0) {
          const citedUrls = collectProvenanceUrls(settlement.value.landedValues ?? []);
          provenance.push({
            playbookRef: child.playbookRef,
            evidenceUrlCount: evidenceUrls.size,
            citedUrlCount: [...citedUrls].filter((url) => evidenceUrls.has(url)).length,
          });
        }
      }

collectProvenanceUrls scans serialized values rather than relying on one family’s citation property. An address anywhere in the value can count. This accommodates different artifact shapes, while making the signal broader than clause-level citation validation.

Read the numbers as a prompt to investigate

The observation does not reject a run. Some outputs legitimately have no place for citations; a creator’s own requirements may also be sufficient input. The result should lead the reader back to the source material and the actual artifact.

This is an address-presence check over prior-round returned values. It does not certify when a source was discovered, whether the source was read, or whether its contents are reliable. Use claim-level evidence review for those questions, alongside the advisory reviewer.

A playbook’s evaluation treatment owns its criteria, instructions and verdict guidance. Describe observable differences between a pass, concern, indeterminate result and gap. The runtime builds a structured output contract from those declared criterion references.

The brief combines landed family values with creator input when available. Computed context, such as the coherence report, is supplied separately and identified as deterministic evidence. The reviewer should interpret what those facts mean, not invent a replacement calculation.

Keep every criterion visible

This runtime excerpt shows how an omitted answer remains visible and how the overall verdict is derived:

    // One verdict per declared criterion; a criterion the model skipped is INDETERMINATE, honestly.
    const byRef = new Map<string, PlaybookJudgeCriterionVerdict>();
    for (const entry of parsed.criteria) {
      const previous = byRef.get(entry.criterionRef);
      // A repeated criterion is not permission to erase an adverse assessment. Preserve every
      // rationale and the most severe verdict, independent of the provider's answer order.
      byRef.set(entry.criterionRef, previous ? {
        criterionRef: entry.criterionRef,
        verdict: VERDICT_SEVERITY[entry.verdict] > VERDICT_SEVERITY[previous.verdict] ? entry.verdict : previous.verdict,
        rationale: `${previous.rationale}\n\nAdditional verdict (${entry.verdict}): ${entry.rationale}`,
      } : entry);
    }
    const criteria: PlaybookJudgeCriterionVerdict[] = criterionRefs.map((criterionRef) => {
      const entry = byRef.get(criterionRef);
      return entry
        ? { criterionRef, verdict: entry.verdict, rationale: entry.rationale }
        : { criterionRef, verdict: MetaWorkflow_EvaluationVerdict.INDETERMINATE, rationale: "The judge returned no verdict for this criterion." };
    });
    const overall = criteria.reduce<MetaWorkflow_EvaluationVerdict>(
      (worst, entry) => (VERDICT_SEVERITY[entry.verdict] > VERDICT_SEVERITY[worst] ? entry.verdict : worst),
      MetaWorkflow_EvaluationVerdict.PASS,
    );
    const result: PlaybookJudgeResult = { judged: true, definitionRef: input.treatment.definitionRef, criteria, overall };

Repeated entries for one criterion retain the most severe verdict and all their explanations, regardless of order. An unknown criterion is refused by the output schema.

INDETERMINATE means the review did not establish an answer. It must not disappear from the report or become a pass by omission. The overall result follows the runtime severity ordering, while the per-criterion rationale remains the useful material for a correction.

Read the result in the right place

The generation host invokes the judge after landing, and the companion also exposes a dedicated judge route. Failures inside the model-review path return a skipped result. A missing creator brief leaves less evidence for questions about intent; neither a confident rationale nor a passing verdict establishes facts the reviewer never received.

Use family validation for checks that can be computed and source observations to inspect citation presence.

The framework role template declares the profession’s responsibilities, shaping inputs and permitted review domains. The application charter supplies its specific persona prose, ordered priorities, taboos and optional review procedure.

These fields come directly from ExpertPersonaCharterSchema:

  priorities: z.array(NonEmptyStringSchema).min(1),
  taboos: z.array(NonEmptyStringSchema).default([]),
  qualityBar: z.array(NonEmptyStringSchema).optional(),
  reviewProtocol: z.array(NonEmptyStringSchema).optional(),

priorities guide what matters most; qualityBar describes what strong work looks like; reviewProtocol describes how to examine it. They have different jobs. A long persona description is not a substitute for concrete criteria.

Derive, review and promote

The companion’s derivation service loads the required shaping artifacts and refuses missing inputs. It stages a proposed charter under .wildo-saas/generated/expert-personas/, with a quality report. The accept operation validates the resulting charter set before writing the application persona module and regenerating its aggregator.

The accept guard checks both loaded charters and the on-disk source for human-edit metadata. Accept promotes a proposal into source files; it does not create a Git commit.

Make the expert available to a panel

The companion builds expert agents from accepted charters at startup. After accepting a new role, restart the companion through the normal development workflow before selecting it in a panel. A missing role is reported rather than silently replaced with a generic reviewer.

Wonder Todos contains an actual art-director charter with explicit favicon, palette and visual-restraint priorities. Its decisions belong to that application, not every Wildo product. Freshness is assessed through source history and derivedAt; charters do not carry an input digest or automatic freshness seal.

A panel names its work domain, reviewers, coordinator and rubric deriver. The role bindings are checked against accepted application charters. This structured-panel excerpt shows the distinction between reviewing a domain and owning its rubric:

    const charters = await this.deliberationComposer.readCommittedCharters();
    const charterByRole = new Map(charters.map((charter) => [charter.roleRef, charter]));
    const reviewers = panel.reviewerRoleRefs.map((roleRef) =>
      this.deliberationComposer.bindExpert(roleRef, charterByRole, { reviewDomain: panel.workDomain }));
    const coordinator = this.deliberationComposer.bindExpert(panel.coordinatorRoleRef, charterByRole, {});
    const rubricDeriverRole = panel.rubricDeriverRoleRef ?? panel.reviewerRoleRefs[0]!;
    const rubricDeriver = this.deliberationComposer.bindExpert(rubricDeriverRole, charterByRole, {
      ownDomain: panel.workDomain,
    });

The coordinator synthesizes the discussion. Reviewers must be eligible to review the work domain; the rubric deriver must be eligible to own it. The application needs those accepted charters and their registered expert agents before the panel can run.

Preserve the candidate being evaluated

Structured generation supplies a producer with produceInitial and produceRevision. The panel service persists each candidate’s JSON and keeps its actual value beside any optional human-readable projection. Reviewers therefore see the data being selected, not only a persuasive summary of different data.

The engine checks required reviewer coverage. Missing valid assessments are not silently treated as agreement. Rounds and shortlist sizes are bounded, so inspect the record’s outcome rather than assuming every panel converged.

Use the route appropriate to the work

The companion has text, structured-candidate and logo-image integrations. A playbook can opt into deliberation at the generation boundary; the selected structured value then continues through ordinary family validation and landing. A panel verdict does not bypass those checks.

Comparing alternatives requires additional generation and review calls. Use it where the choice warrants several perspectives. The resulting score expresses the configured rubric and model judgments; it is not an independent measurement of customer preference.

Inspect the working tree before committing

From the application repository, a typical review begins with:

# Inspect both new files and edits to tracked files.
git status --short
git diff --stat
git diff -- specifications/

# After reviewing, stage only the intended paths.
git add specifications/src/vision/index.ts
git diff --cached
git commit -m "Clarify the product direction"

The staged path is illustrative; use the files actually produced by the run. git diff alone does not show the contents of untracked files, so inspect new files identified by git status as well.

Understand what landing does

This source excerpt shows the final render and write step for a structured artifact:

const source = renderApplicationStructuredArtifactFamilySource({
  profile: target.renderProfile,
  exportedConstantName: target.exportedConstantName,
  value: landedValue,
});
if (input.dryRun !== true) {
  await mkdir(dirname(absolutePath), { recursive: true });
  await writeFile(absolutePath, source);
}
return {
  packageRelativePath: target.packageRelativePath,
  absolutePath,
  byteLength: source.byteLength,
  renderedSource: new TextDecoder().decode(source),
  existedBefore: previousContent !== undefined,
  ...(previousContent !== undefined ? { previousContent } : {}),
};

Before this point, the service resolves the registered target and applies schema and semantic validation. dryRun returns rendered output without writing it. The write changes the working tree; it does not create a commit or establish that a reviewer accepted the result.

Use evidence alongside the diff

Git records the accepted bytes, not the truth of every claim inside them. The creation runtime’s landing path does not commit on the person’s behalf. A host or coding agent’s permission to commit must be explicit in its own workflow.

Keep runtime records in their proper role

The companion records run writes for inspection and recovery. Those records help associate files with a run; they are not a competing accepted version of the application. Review targeted recovery separately from Git history, especially when another edit has changed the same file since the run.

Read the policy as a design contract

The journey vocabulary describes the intended supervision presets:

export enum Journey_AutonomyPreset {
  GUIDED = "guided",
  YOLO_LIGHT = "yolo_light",
  YOLO = "yolo",
}

Per-playbook approval policies describe where attention could be requested:

export enum MetaWorkflow_ApprovalPolicy {
  AUTO = "auto",
  NOTIFY = "notify",
  APPROVE_RESULT = "approve_result",
  APPROVE_BEFORE = "approve_before",
}

These enums are source declarations, not an installation example for an enforced mode switch. Setting autonomyPreset or approval does not install a dispatch gate or grant an agent permission to commit.

Keep the effective behavior explicit

The landing service writes proposed artifact changes into the working tree. It does not commit them. The current runtime does not interpret these approval policies as gates, so an APPROVE_BEFORE declaration must not be relied on to prevent execution.

A host integrating creation work should preserve the distinction between its own permissions, clarification handling and the application’s Git review workflow. The supervision vocabulary describes a future policy layer; it is not a substitute for controls the host actually enforces.

Design acceptance around inspectable work

The useful unit for review is the change with its purpose and evidence: which files moved, which checks ran and which product decision the work implements. Preserve that information when adding supervision so a request for approval is a meaningful decision.

The Git acceptance workflow and clarification channel describe the mechanisms used for those separate concerns.