v0.8.67 Setup: build a guided localized constitution creator, not a blank prompt editor

[Hmbown]

Constitution creator UX update (2026-06-29)

The creator should support the language-first, guided-plus-open-canvas shape, with one important correction: autonomy/risk posture is not allowed to directly flip runtime security settings from inside the constitution file.

Creator flow:

1. Framing screen: localized explanation, with Guided, Preset, and Skip/use bundled as valid on-ramps.
2. Must-know calibration: verification bar, escalation triggers, work context, communication style, privacy/memory stance, and an autonomy preference as model-facing guidance.
3. Runtime posture bridge: if the autonomy answer implies a different default mode/approval/sandbox posture, show a separate suggested config change owned by v0.8.67 Setup: trust, approvals, sandbox, network, and privacy step #3406. Do not apply it silently.
4. Open canvas: bounded free prose in the user’s chosen language for purpose, values, tone, and extra principles. Render it as subordinate user-global law, not a raw system-prompt replacement.
5. Live preview: show the exact rendered <codewhale_user_constitution> prose and the surrounding layer order.
6. Save/revise: /constitution (v0.8.67 Setup: make /constitution the primary constitution management surface #3806) reopens this surface; rollback to bundled/default must be one clear action.

AI-assisted drafting/polish can be offered only after provider/model connectivity exists and must remain optional. The deterministic renderer is the v0.8.67 must-have; AI polish is not required for checkpoint completion.

Security boundary: the structured constitution may guide model behavior but must not bypass or mutate enforced runtime controls without a separate explicit config action.

---

Maintainer direction update (2026-06-29)

This supersedes older wording below that frames the guided creator as writing the full prompts/constitution.md base-prompt override.

The v0.8.67 guided creator should make the user-global constitution a structured policy file rendered to prose, not a blank Markdown system-prompt editor and not a full replacement for the bundled Constitution.

Target architecture:

• Bundled global Constitution Markdown: crates/tui/src/prompts/constitution.md remains the shared identity/judgment frame and is still compiled into the binary.
• User-global constitution: setup writes a structured file under $CODEWHALE_HOME such as $CODEWHALE_HOME/constitution.json (or a clearly named TOML equivalent if implementation chooses config-native storage). It captures guided answers: purpose, authority order, protected invariants, autonomy/risk posture, verification bar, communication style, privacy/memory stance, and escalation rules.
• Renderer: CodeWhale renders that structured user-global policy into a concise prose <codewhale_user_constitution> block that is injected after the bundled Constitution and before repo/project context. The model reads prose; setup/doctor/tests inspect structured data.
• Advanced full-prompt override: $CODEWHALE_HOME/prompts/constitution.md plus CODEWHALE_ALLOW_BASE_PROMPT_OVERRIDE=1 remains an advanced escape hatch from exposed main prompt for broader use cases #3638, not the normal setup output.
• Repo constitution: .codewhale/constitution.json remains repo-local law and should not be edited by this global creator except through a separate project/repo setup flow.

Why: the model is best served by stable prose in the final system prompt, while users and setup are best served by structured, safe, inspectable fields. JSON should not point the model at Markdown, and Markdown should not point the model at JSON; the runtime should render the structured policy into the final prompt.

This issue should therefore build the creator around structured answers + previewed rendered prose, with bundled/default as the one-key safe path.

Related cleanup: remove WHALE.md as an active setup/context surface in #3798.

---

Constitution surfaces — what this creator is (and is not)

The guided creator produces exactly one thing: the user-global constitution override (the prompts/constitution.md override path in crates/tui/src/prompts.rs, CONSTITUTION_OVERRIDE_FILE). It is deliberately distinct from every other instruction surface:

• Bundled constitution (prompts/constitution.md, BASE_PROMPT): the shipped English single-source law. "Use bundled" means no override file; the creator never edits the in-tree file.
• User-global constitution override (this issue): the user's standing personal law across all projects, generated from presets/answers.
• Repo .codewhale/constitution.json: per-repo law for this checkout only — not touched by the global creator.
• AGENTS.md / CLAUDE.md: repo agent guidance — a separate surface.
• Memory: recalled facts, not standing law.
• --append-system-prompt: a per-launch ad-hoc addition, not a durable constitution.

The creator must name which surface it is writing and never blur the line (see acceptance below and the #3412 docs table).

Non-goals

• Not editing the shipped bundled constitution.md; "use bundled" means no override file is created.
• Not per-locale-branching the bundled law — the creator UI and presets are localized; the generated override is rendered prose the model follows.
• Not replacing --append-system-prompt, repo constitution, AGENTS.md, or memory.
• Not forcing custom prompt authoring — bundled/default is a first-class valid result.

Product shape

A CodeWhale constitution is not just a long prompt and not just a preferences page. It is the user's stable standing law for CodeWhale: the rules that should survive across projects, models, sessions, and momentary task wording.

A good constitution answers four questions:

1. Who is CodeWhale supposed to be for this user?
2. Which instructions and evidence win when sources conflict?
3. What should CodeWhale protect even when moving fast?
4. What does “done” mean before CodeWhale claims success?

Setup should turn those answers into a readable constitution through guided questions, presets, and preview. The default path should be “use bundled constitution”; the custom path should feel like choosing a character class/play style and house rules, not editing a hidden system prompt.

For v0.8.67, this creator also feeds the required update checkpoint in #3794. Existing users must make an explicit constitution choice after updating, but choosing the bundled/default constitution is a valid completion path.

What makes a constitution a constitution

A constitution should have stable articles, not ad hoc advice:

• Identity and purpose: coding assistant, research assistant, writing partner, operations helper, mixed workbench.
• Authority order: current user request, live tool evidence, repo instructions, memory, old handoffs, generated plans.
• Protected invariants: secrets, user files, git history, production data, budget, brand voice, language, accessibility.
• Autonomy default: ask-first, normal agent, high-trust local mode, or task-specific escalation.
• Verification bar: tests, build, screenshots, docs, citations, human approval, or “explain uncertainty.”
• Communication style: concise, teaching, bilingual, formal, direct, exploratory, low-jargon.
• Tool and risk posture: when to browse, run commands, edit files, install dependencies, spawn agents, or stop and ask.
• Memory and privacy stance: what can be remembered, what should never be retained, and what belongs only in the current project.
• Escalation rules: when CodeWhale must ask before continuing.

It should be structured enough for setup, doctor, and context reports to inspect, but rendered as prose clean enough for the model to follow.

Questions the setup wizard should ask

Use a small guided builder with presets first and advanced editing second.

Starter questions:

• What will you mostly use CodeWhale for? Coding, research, writing, ops, mixed, or custom.
• How should CodeWhale behave by default? Careful collaborator, fast builder, reviewer, teacher, creative partner, or quiet operator.
• How much should it do before asking? Ask before edits, ask before risky actions, proceed inside the workspace, or high-trust local work.
• What should it protect? Secrets, git history, uncommitted changes, production systems, cost, privacy, tone/brand, time.
• What counts as finished? Tests pass, build passes, screenshots checked, docs updated, cited sources, or concise summary with known gaps.
• How should it talk? Concise, explanatory, direct, bilingual, formal, casual, or domain-specific.
• When should it stop and ask you? Destructive action, missing credentials, unclear product choice, legal/security risk, high cost, or conflicting instructions.
• Should this be global for all CodeWhale sessions, or should this repo get its own .codewhale/constitution.json later?

Advanced questions:

• Which sources should outrank memory and old handoffs?
• Should web/current information be verified by default for unstable facts?
• Should CodeWhale prefer minimal patches, broad refactors, or ask case-by-case?
• Are there project types where this constitution should not apply?

Localization requirements

All constitution creator questions, presets, explanations, warnings, validation errors, preview labels, and completion states must be localized through the same setup localization layer used by the v0.8.67 wizard.

The flow needs localized copy for:

• bundled/default constitution,
• preset-generated constitution,
• existing custom constitution review,
• disable/restore bundled constitution,
• global constitution vs repo .codewhale/constitution.json,
• AGENTS.md vs constitution vs memory,
• “required after update” explanation from v0.8.67 Setup: require a localized constitution checkpoint after update #3794,
• generated constitution preview and confirm/cancel actions,
• repair states for missing, unreadable, empty, or flag-disabled overrides.

Do not ship this as an English-only wizard with translated docs around it.

Current behavior

The underlying capability exists from #3638, but it is not part of the v0.8.67 setup journey yet.

Evidence from the current tree and issue history:

• README documents the instruction hierarchy: the global constitution is the compiled base law, while .codewhale/constitution.json is repo-local law.
• docs/CONFIGURATION.md documents the exposed main prompt for broader use cases #3638 per-user override path: ~/.codewhale/prompts/constitution.md under $CODEWHALE_HOME plus the explicit CODEWHALE_ALLOW_BASE_PROMPT_OVERRIDE=1 opt-in.
• v0.8.66: Repo constitution and context-policy drift guard #3486 covered repo constitution drift guards, not user-global constitution onboarding.
• v0.8.67 EPIC: Setup wizard and user-global constitution #3402 covers the guided setup hub, and now tracks the v0.8.67 update checkpoint through v0.8.67 Setup: require a localized constitution checkpoint after update #3794.

Desired behavior

Add a setup/onboarding step for global CodeWhale constitution customization that builds on #3638 rather than inventing a second prompt path:

1. Detect whether the active base constitution is bundled or user-global, and show the source path and opt-in state clearly.
2. Offer deliberate actions: keep bundled, pick a preset, answer guided questions, preview the generated constitution, save it, edit/inspect the existing user-global constitution, disable the override, or repair an invalid/empty override.
3. Write only under $CODEWHALE_HOME/prompts/constitution.md or ~/.codewhale/prompts/constitution.md; do not edit repo .codewhale/constitution.json unless the user is in a separate project-setup flow.
4. Preserve the two-step trust boundary from exposed main prompt for broader use cases #3638: a file alone is ignored until the user explicitly opts in through the supported flag or any future approved config gate.
5. Make /context report, setup reports, and doctor output show whether a user-global constitution was loaded, ignored, missing, malformed, or disabled.
6. Keep runtime enforcement separate: a custom constitution may change persona and general guidance, but it must not bypass sandbox, approvals, managed config, tool gates, or other policy enforced in code.
7. Support both new-user first-run setup and the required v0.8.67 update checkpoint.

UX guardrails

• Do not lead with a raw text editor. Lead with presets and short questions.
• Show a readable preview before enabling the generated constitution.
• Keep “start now with bundled constitution” as a one-key escape hatch.
• Make the global/repo distinction explicit: global constitution is user-wide; .codewhale/constitution.json is repo-local law; AGENTS.md is project working instructions; memory is not law.
• Include a revert path that disables the override and returns to the bundled constitution.
• Localized copy should explain the checkpoint without sounding like an error or punishment for updating.

Acceptance criteria

• /setup includes a global constitution/personality step, marked optional for normal first-run users and required as the v0.8.67 update checkpoint.
• The step can generate a constitution from presets plus guided answers without requiring raw prompt editing.
• A clean CODEWHALE_HOME can scaffold a user-global constitution file from the bundled prompt or generated template.
• Existing override states are handled explicitly: no file, file present with flag off, file present with flag on, unreadable file, empty file, and malformed/too-large content.
• The setup report and /context report show the active constitution source without leaking unrelated local paths beyond the relevant CodeWhale config path.
• Tests cover $CODEWHALE_HOME resolution, flag-off ignore behavior, flag-on load behavior, generated-template load behavior, update-checkpoint completion behavior, and secret/log redaction around setup diagnostics.
• All user-visible constitution creator strings are localizable; at least one non-English test/snapshot proves the creator is not mostly English.
• Docs in v0.8.67 Setup: docs, screenshots, localization, and constitution copy refresh #3412 explain the difference between global constitution override, repo .codewhale/constitution.json, AGENTS.md, memory, and --append-system-prompt.

Related

• Setup epic: v0.8.67 EPIC: Setup wizard and user-global constitution #3402
• Complete onboarding path: v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792
• Required update checkpoint: v0.8.67 Setup: require a localized constitution checkpoint after update #3794
• Existing base prompt override request: exposed main prompt for broader use cases #3638
• Repo constitution drift guard: v0.8.66: Repo constitution and context-policy drift guard #3486
• Persistence and rollback: v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410
• Verification/doctor: v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411
• Docs/localization/copy: v0.8.67 Setup: docs, screenshots, localization, and constitution copy refresh #3412

Safe fallback

• If the user closes the creator without choosing, the bundled constitution stays active and the step is marked needs-action/deferred (not failed).
• A malformed/unreadable existing override is detected and routed to repair choices (keep bundled / regenerate / edit), never silently loaded.
• Generated or edited overrides are previewed before write and reversible via the v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410 persistence path (disable override → remove/flag-off → bundled law returns).