galaxy/specs/APP-3575/PRODUCT.md

Finalize TOML Schema for Tab Configs

Linear: APP-3575

Summary

Replace the recursive [layout] / [[layout.panes]] TOML nesting in tab configs with a flat [[panes]] array where nodes reference children by string ID. This makes deeply nested split layouts readable and hand-editable, and ships a bundled Oz skill so users can generate tab configs from natural language.

Problem

The existing tab config layout format uses recursive TOML tables ([[layout.panes]], [[layout.panes.panes]], etc.). At depth 3+ this becomes unreadable and error-prone for hand-editing. Users who want a 2x2 grid or deeper nesting have to mentally track nested array-of-tables syntax, which is a significant barrier to adoption.

Additionally, there is no guided way for users to create tab configs — they must hand-author TOML from scratch.

Goals

• A flat, ID-referenced pane tree format that supports arbitrarily deep nesting while remaining readable.
• A bundled Oz skill (tab-configs) that generates valid tab config TOML from natural language descriptions.
• A default template that is ready to use out of the box (single terminal pane, uncommitted, with commands = [] pre-populated).
• Tab color support (color field) matching launch config parity.

Non-goals

• Supporting non-terminal pane types beyond agent and cloud (notebook, code, settings, etc.).
• Multi-tab or multi-window configs (tab configs define a single tab by design).
• Proportional/flex sizing of children within a split.
• Converting existing launch configs to the new tab config format.

Figma

Figma: none provided. This feature has no new UI — it changes the file format and adds an Oz skill.

User experience

Creating a new tab config

1. User clicks + → "Create new tab config..." in the tab bar menu.
2. Warp writes the default template to ~/.warp/tab_configs/my_tab_config.toml and opens it in the user's configured editor.
3. The template contains an active single-pane config with commands = [], and commented-out examples for two-pane split, 2x2 grid, and parameterized configs.
4. The template header mentions the Oz skill: "Ask Oz to generate a tab config for you!"

Using the Oz skill

• User invokes /skills → tab-configs or asks Oz naturally (e.g. "create me a 2x2 tab config with one pane running my dev server").
• Oz generates a valid .toml file and writes it to ~/.warp/tab_configs/.
• The file immediately appears in the + menu (the filesystem watcher picks it up).

Opening a tab config

• User clicks + → "New Tab: ".
• If the config has [params], a modal appears for the user to fill in values.
• Warp opens a new tab with the specified pane layout, running any configured commands.
• If the config has a color field, the tab gets that color.

Format behavior

• Pane layout is defined with a flat [[panes]] array.
• The first [[panes]] entry is the root of the tree.
• Split nodes have split (horizontal/vertical) and children (ordered array of child IDs).
• Leaf nodes have id, required type ("terminal", "agent", or "cloud"), optional cwd, optional commands, and optional is_focused.
• terminal opens a standard shell session. agent opens a terminal in Agent Mode. cloud opens a cloud mode (ambient agent) pane with no local shell.
• cwd and commands apply to terminal and agent types; they are ignored for cloud.
• worktree_name_autogenerated (optional, bool, default false): when true, Warp auto-generates the worktree branch name instead of prompting the user. The app detects worktree configs by scanning commands for git worktree.
• All children within a split are equally sized.
• If no pane has is_focused = true, the first leaf pane gets focus automatically.

Error handling

• If the flat pane tree has validation errors (missing child references, duplicate IDs, fewer than 2 children in a split), the config falls back to a single empty terminal pane and logs a warning.
• Invalid TOML or missing name field causes the file to be skipped with a warning logged.

Success criteria

1. A tab config using the flat [[panes]] format with a horizontal 2-pane split opens correctly: two side-by-side terminal panes, each with the specified cwd and commands.
2. A tab config using the flat format with a 2x2 grid (horizontal split → two vertical splits → four terminals) opens correctly with four equal-sized panes.
3. A tab config with color = "blue" opens with a blue tab.
4. A tab config with is_focused = true on a specific pane gives that pane initial focus.
5. A tab config with no is_focused gives focus to the first (leftmost/topmost) leaf pane.
6. A tab config with [params] shows the param-fill modal before opening.
7. A tab config with a [[panes]] format that has an invalid child reference logs a warning and opens a single empty terminal pane.
8. The tab-configs bundled skill appears in /skills in Warp.
9. The default template, when uncommitted and left as-is, parses as a valid single-pane tab config named "My Tab Config".

Validation

• Unit tests for parsing and rendering the flat format (single pane, split, 2x2, focus handling, error cases).
• Manual verification: create a 2x2 tab config TOML, open it from the + menu, confirm four panes appear with correct cwd and commands.
• Manual verification: invoke the tab-configs skill and confirm it generates a valid TOML file that opens correctly.

Open questions

(None outstanding.)