bs

name	bs
description	Generate rich visual plans with diagrams and structured layouts. Saves locally via fp CLI. Triggers on "brainstorm", "bs", or "create a plan".

bs — brainstorm

Purpose

Generate structured plans in markdown with directives. The renderer handles all styling and theming — the skill only produces content.

Output Format

Brainstorms are written as markdown with directives. Do not produce HTML, CSS, or inline styles.

Directive Vocabulary

Callout blocks

:::callout{type="info"}
Key context or background information.
:::

:::callout{type="warning"}
Risk or caveat to highlight.
:::

:::callout{type="decision"}
A decision that was made and its rationale.
:::

:::callout{type="question"}
An open question that needs resolution.
:::

Cards

:::card{title="Component Overview"}
Grouped content goes here — paragraphs, lists, tables, code blocks.
:::

Inline labels

:label[Active]{color="green"}
:label[Blocked]{color="red"}
:label[In Review]{color="orange"}
:label[Planned]{color="blue"}
:label[Deprecated]{color="purple"}

Mermaid diagrams

```mermaid
graph TD
  A --> B
```

Read references/mermaid-guide.md before writing any mermaid markup — it covers syntax pitfalls that cause parse failures.

File trees

Use ASCII tree-drawing characters (├──, └──, │) for hierarchy — do NOT use space-based indentation. The filetree parser only recognizes tree-drawing characters for structure. Space-indented entries render flat with no visible hierarchy.

```filetree
src/
├── components/
│   ├── Button.tsx     # Primary action component
│   └── Dialog.tsx     # Modal overlay
└── utils/
    └── format.ts      # String formatting helpers
```

Annotations: # new (green), # modified (orange), # deprecated (muted + strikethrough).

Standard GFM

• Tables, task lists, headings, code blocks, inline code — all supported.
• Use tables for comparisons and structured data.
• Use task lists for implementation checklists.

Content Guidelines

• Be concise — focus on visual structure over large blocks of text.
• Use Mermaid diagrams for architecture, flows, and sequences.
• Use cards and tables for information density.
• Use callouts sparingly to highlight decisions, risks, and open questions.
• Use labels for status indicators inline with text.

Local brainstorm workflow (fp CLI)

When .fp/ exists and fp is installed, use the CLI to store brainstorms locally.

Create

1. Write markdown to a temp file: /tmp/bs-output.md
2. Save to project:

   fp brainstorm create /tmp/bs-output.md --title '<title>'
   

Revise

1. Revise markdown and write to temp file
2. Update: fp brainstorm update <id> /tmp/bs-revised.md

fp CLI commands

fp brainstorm create <file.md> [--title "..."]       # Create from markdown file
fp brainstorm show <id>                               # Dump markdown to stdout
fp brainstorm update <id> <file.md>                   # Update with new markdown
fp brainstorm delete <id>                             # Soft delete
fp brainstorm list                                    # List brainstorms
fp brainstorm versions <id>                           # List version history
fp brainstorm comments add <id> "comment text"        # Add a comment
fp brainstorm comments resolve <id> <commentId>       # Resolve a comment
fp brainstorm comments delete <id> <commentId>        # Delete a comment

All commands accept both fp brainstorm and fp bs.

Reading & iterating on brainstorms

When reviewing or iterating on an existing brainstorm, you need to read both the content and any comments left on it.

Preferred: single command with --with-comments

fp bs show <id> --with-comments

This prints the full markdown followed by all comments (with IDs, authors, and anchor blocks) below the fold.

Alternative: two commands

fp bs show <id>
fp bs comments <id>

Concatenate both outputs to get the complete picture. Use this if you only need comments separately.

Important for agents: Always read comments before editing a brainstorm. Comments contain review feedback, design decisions, and requested changes that must be addressed. When iterating:

1. Read the brainstorm with comments (fp bs show <id> --with-comments)
2. Address the feedback in your edits
3. After updating, resolve addressed comments (fp bs comments resolve <id> <commentId>)