AI system prompt editor

ai-ui specs/ai-ui/system-prompt-editor.kmd

Advanced power-user editor for system prompts (Claude Projects style / ChatGPT Custom GPTs). Markdown editor + templating helpers (variables, conditions, includes) + test-run sandbox + version history + share workspaces. Builds on services/ai/kortex/rules/ backend.

When this spec applies

Primary triggers

Edit system prompt / persistent rules / custom instructions

All triggers

Build advanced AI customization surface
Implement Kortex Custom rules editor

Spec — AI system prompt editor

Backend: services/ai/kortex/rules/. Power-user feature; pode ser opt-in per produto. Companion: prompt-gallery.kmd (#114 — share path entre prompts e system rules).

Princípios

Markdown native — system prompt é markdown; preview side-by-side.
Templating — variables, conditions, includes reduce repetition.
Test sandbox — preview behavior before commit.
Versioned — linear history + rollback (similar artifact-panel R5).
Permission gated — admin-only em workspaces shared.

R1 — Anatomia

┌────────────────────────┬────────────────────────┐
│ Editor (split-left)    │ Preview (split-right)  │
│                        │                        │
│ ```markdown            │ Rendered preview...    │
│ You are a coding       │                        │
│ assistant for the      │                        │
│ Koder Stack.           │                        │
│                        │                        │
│ {if language == "go"}  │                        │
│   Focus on idiomatic   │                        │
│   Go patterns.         │                        │
│ {end}                  │                        │
│ ```                    │                        │
├────────────────────────┼────────────────────────┤
│ Variables:             │ Test run:              │
│ language = "go"        │ User: "Help me with X" │
│                        │ [Run]                  │
│                        │                        │
│                        │ Assistant: ...         │
└────────────────────────┴────────────────────────┘
[ Save ] [ Version history ] [ Share workspace ]

Sub-areas:

Area	Function
Editor (left)	Markdown editor with syntax highlight + autocomplete for `{var}` `{if}`
Preview (right)	Rendered system prompt with vars substituted
Variables panel	Schema-driven var inputs
Test sandbox	Type user message + Run → preview assistant response
Footer actions	Save (creates new version) / Version history / Share / Delete

R2 — Templating helpers

Mustache-style + control flow:

Helper	Syntax
Variable	`{var_name}`
Conditional	`{if condition} ... {else} ... {end}`
Loop	`{for item in list} ... {end}`
Include	`{include other_prompt_slug}`
Comment	`{# this is a comment, ignored #}`

Auto-complete em editor sugere helpers + var names.

Variables declared in frontmatter (similar prompt-gallery.kmd R3):

---
title: Koder coding assistant
variables:
  language:
    type: string
    enum: [python, dart, go, rust]
    default: go
  formality:
    type: string
    enum: [casual, formal]
    default: casual
---

R3 — Includes / composition

{include other_prompt_slug} resolves to content of other_prompt_slug system prompt (same workspace OR shared via Hub).

Compose-able: small reusable rules combined into bigger prompts. Cross-link prompt-gallery.kmd (#114) for shared snippets.

Circular references rejected at save-time.

R4 — Test sandbox

Below editor + preview:

Text area: type test user message.
Run button: invoke gateway with current draft system prompt + test message.
Response area: render assistant output.
Model selector embedded for quick swap.
Doesn't persist as real conversation (sandbox isolation).

R5 — Version history

Per save: new version with timestamp + author + commit message (optional).

View versions: list with date + author + message.
Diff: side-by-side (similar artifact-panel.kmd R6 diff).
Rollback: creates new version pointing to old content (linear).

Max 50 versions retained; older snapshot-pruned.

Workspace sharing (multi-user workspaces):

Private (default): owner only.
Workspace public: all workspace members can use; admin can edit.
Hub public: shareable via hub.koder.dev/rules/<slug>; install creates copy.

R7 — Permission

Edit gated by role:

Workspace admin: can edit any workspace-public rule.
Workspace member: can edit only private + own rules.
Hub public install: creates per-user private copy; user can edit copy without affecting original.

R8 — Surface bindings

Surface	API
Flutter	`KoderSystemPromptEditor({rule, onSave, onTest, onShare})` em `koder_kit/lib/src/ai/system_prompt_editor.dart`
Web	`<koder-system-prompt-editor>`
Compose/SwiftUI	futuro
CLI / TUI	`koder rules edit <slug>` opens em `$EDITOR`; `koder rules test <slug>`

R9 — Acessibilidade

Editor + preview: split-pane keyboard switching.
Forms: standard labels + aria.
Version history: list semantically <ol>.
Reduced-motion: no animations.

R10 — i18n

Key	en-US	pt-BR
`ai.rules.editor.title`	"System prompt"	"Prompt do sistema"
`ai.rules.editor.preview`	"Preview"	"Visualização"
`ai.rules.editor.variables`	"Variables"	"Variáveis"
`ai.rules.editor.test_run`	"Test"	"Testar"
`ai.rules.editor.test_message_placeholder`	"Type a test message..."	"Digite uma mensagem de teste..."
`ai.rules.action.save`	"Save"	"Salvar"
`ai.rules.action.history`	"Version history"	"Histórico de versões"
`ai.rules.action.share`	"Share to workspace"	"Compartilhar no workspace"
`ai.rules.action.rollback`	"Rollback to this version"	"Reverter para esta versão"
`ai.rules.permission.denied`	"Only workspace admin can edit shared rules"	"Apenas admin do workspace pode editar regras compartilhadas"

R11 — Multi-tenant

Rules scoped per (koder_user_id, workspace_id, rule_id).

Hub public rules cross-tenant visible but install creates per-workspace copy.

T-suite

T1 Mount: editor + preview render with split-pane.
T2 Edit: type → preview updates with var substitution.
T3 Variables: schema-driven form; preview reflects values.
T4 Conditional: {if language == "go"} block hides/shows based on var.
T5 Include: {include other} → resolves at preview.
T6 Circular include: A includes B, B includes A → save-time rejection.
T7 Test sandbox: type user message + Run → gateway invoked with current draft.
T8 Save → new version v2.
T9 Version history: list shows versions + diff button.
T10 Rollback: tap v1 → confirm → new v3 == v1 content.
T11 Share workspace: workspace public → other members can use.
T12 Hub share: install → per-user copy created.
T13 Permission: non-admin tries to edit workspace-public → blocked + announce.
T14 A11y: keyboard nav full.

Cross-link

Companion: prompt-gallery.kmd (#114 — share path + includes), chat-message-bubble.kmd (rules apply to conversations)
Backend: services/ai/kortex/rules/
Hub: products/dev/hub/
Policies: multi-tenant-by-default.kmd
Refs: Claude Projects custom instructions, ChatGPT Custom GPTs builder

References

meta/docs/stack/specs/ai-ui/prompt-gallery.kmd
meta/docs/stack/specs/ai-ui/chat-message-bubble.kmd
meta/docs/stack/policies/multi-tenant-by-default.kmd