How-To Guides

These guides assume you have a brainstorm session open (ait brainstorm <task_num>). All operations run background agents; watch their progress on the Running tab (r) and return to Browse (b) when a result lands.

How to Start a Brainstorm Session

You can start from a blank seed or from an existing draft.

From scratch:

1. Run ait brainstorm <task_num>.
2. If no session exists yet, the TUI prompts you to initialize one — confirm, and a seed (bootstrap) node is created.

From an existing markdown draft:

1. Run ait brainstorm init <task_num> --proposal-file path/to/draft.md.
2. An initializer agent reformats the draft into the first graph node. Watch it on the Running tab; if it needs re-applying, press Ctrl+R on the Running tab.
3. Run ait brainstorm <task_num> to open the studio.

From the board:

1. In ait board, focus the task card.
2. Press b (or open the task detail dialog and click Brainstorm).
3. Choose Run or Run in tmux. If a brainstorm-<num> window already exists, the board switches to it instead of starting a second session.

How to Explore Design Variants

1. On the Browse tab, focus the node you want to branch from (arrow keys in graph view).
2. Press A to open the Operations dialog and choose Explore.
3. In the wizard, set how many parallel explorers to run and any guidance, then launch.
4. Each explorer produces a new variant node branching from the base. They appear in the graph (cyan badge) as the agents complete.

How to Compare and Synthesize Nodes

Compare runs an agent that contrasts a set of nodes; Synthesize merges them into one proposal.

1. Mark the nodes you want to work with: focus each and press space (a filled checkbox appears). Your marked set is shown in the Browse detail pane.
2. Press A → Compare to run an agent comparison across the marked nodes (yellow badge result), or A → Synthesize to merge them into a single synthesized proposal (magenta badge result).
3. For a quick side-by-side without spawning an agent, press c to open the dimension-comparison matrix over the marked set.

How to Decompose a Proposal into Modules

Module decompose forks a large proposal into smaller, independently-evolvable module subgraphs.

1. Focus the umbrella node and press A → Module Decompose.
2. Pick a mode:
   • Manual — I type the names: enter the module names yourself.
   • Agent-proposed — infer from the Plan: leave the names blank and write a free-text decomposition plan; the agent proposes the module set.
   • From section markers: derive modules from the proposal’s <!-- section: --> markers (deterministic, no agent).
3. Leave Review before apply checked (the default) to inspect the result before it commits.
4. Launch. The decomposed module nodes are added as new subgraph roots (green badge). The umbrella proposal is left whole — decompose forks, it does not prune.

To split a single module off to implementation while the rest of the design keeps evolving, use the fast-track preset, which pairs a single-module decompose with a “create linked child tasks” step.

How to Review and Steer a Module Decomposition

When Review before apply is on, the proposed decomposition opens in a preview before anything commits to the graph:

• Accept — apply the proposed modules to the graph.
• Re-run — supply a free-text steering note and run again. The note refines the previous attempt: it overrides the original decomposition plan wherever they conflict, and across multiple re-runs the later revision wins.
• Cancel — discard the proposal; the graph is untouched.

Turn the checkbox off to skip the preview and auto-apply immediately.

How to Bring a Module’s Design Back

Because decompose forks rather than prunes, a module’s evolved design has to be merged back deliberately:

• Module Merge (A → Module Merge) merges a module up into an ancestor node (orange badge).
• Module Sync (A → Module Sync) pulls a linked module’s as-implemented design back into the graph (purple badge) — useful once a fast-tracked module has been built.

How to Inspect Operation Provenance

Every node records how it was produced.

1. Focus a node. The Browse detail pane shows a Generated by block (operation, agent group, agents, timestamp).
2. Press o to open the Operation screen for that node.
3. The Overview tab summarizes the operation; each agent in the operation has its own Input / Output / Log tabs so you can see exactly what it was given, what it returned, and how it ran.

How to Set HEAD and Finalize

HEAD marks the current design tip — the node that finalize exports.

1. Navigate to the node you want as the chosen design and press h to set it as HEAD (its box border turns green).
2. Switch to the Session tab (s).
3. Choose Finalize. The HEAD proposal is exported to aiplans/ and the session is marked completed — this is how a brainstorm becomes an implementation plan.

How to Manage Sessions

The Session tab (s) exposes lifecycle actions:

• Pause / Resume — stop and restart the session’s agent activity.
• Archive — mark a completed session as archived.
• Delete — permanently remove the session, its worktree, and its branch.

The same actions are available from the command line: ait brainstorm status <task_num>, ait brainstorm list, and ait brainstorm archive <task_num>.

tmux integration

When you run ait brainstorm inside tmux, press j to open the TUI switcher and jump to another integrated TUI (Monitor, Board, Code Browser, Settings, Syncer, or a running agent window). A typical flow: shape a design here, press j to switch to monitor and watch the explorer/synthesizer agents run, then come back when they land.

Next: Reference — full keybinding tables, the color legend, and session file layout.