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\"."
license: "MIT"
---

# 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**:
   ```bash
   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`**
```bash
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**
```bash
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>`)