CORE CONCEPTS

The Floww Prompt

A living project document that captures intent and evolves with your workflow.

Every Floww project has a Floww Prompt—a structured markdown document embedded in your .floww file that describes what your project does, why it exists, and how it works. Think of it as a project brief that stays synchronized with your workflow as it grows and changes.

What Is the Floww Prompt?

The Floww Prompt is a markdown document stored in the prompt field of your .floww file. It serves multiple purposes:

• Intent declaration — Describes the goal of your workflow in plain language. What problem does this workflow solve? What does it produce?
• Context for AI nodes — AI nodes in your workflow can read the Floww Prompt to understand the broader context of the project. This helps them generate more relevant and consistent outputs.
• Onboarding document — When a teammate opens your project, the Floww Prompt gives them an immediate understanding of what the workflow does without having to trace through every node.
• Version-controlled history — Because the prompt lives inside the .floww file, changes to it are tracked by Git alongside your workflow changes.

To open the Floww Prompt editor, click the Prompt button in the top toolbar or press P. The editor opens as a panel above the canvas with full markdown editing support.

Writing a Good Prompt

An effective Floww Prompt is specific, structured, and actionable. Here is a recommended structure:

1. Project Summary

Start with one or two sentences that describe the core purpose of the workflow. Be specific about what it does and what it produces.

This workflow processes incoming customer support emails,
classifies them by urgency and topic, and routes them to
the appropriate team channel in Slack.

2. Inputs and Outputs

Describe what data the workflow expects to receive and what it produces.

## Inputs
- Email messages received via IMAP from support@company.com
- Each email has: subject, body (plain text), sender address, timestamp

## Outputs
- Classified email posted to the correct Slack channel
- CSV log entry appended to ~/support-log.csv

3. Constraints and Rules

State any business rules, quality requirements, or boundaries that the workflow (and its AI nodes) should respect.

## Constraints
- Urgent emails (billing issues, outages) must be routed within 60 seconds
- Never include customer PII in Slack messages; use ticket IDs only
- If classification confidence is below 70%, route to the general queue

4. Tone and Style (for AI nodes)

If your workflow generates text (summaries, replies, reports), describe the desired tone.

## Tone
- Professional but friendly
- Use short sentences
- Avoid jargon; the audience is non-technical

How It Evolves

The Floww Prompt is designed to be a living document that grows with your project. It evolves in two ways:

Manual Updates

As you add nodes, change logic, or refine your workflow's purpose, update the prompt to match. Open the prompt editor, make your changes, and save. The updated prompt is persisted in the .floww file immediately.

AI-Assisted Refinement

Floww can analyze your current workflow graph and suggest updates to the prompt. After significant changes to your workflow:

1. Open the Floww Prompt editor (P).
2. Click Suggest Updates in the editor toolbar.
3. Floww examines your node graph, their configurations, and connections.
4. It presents a diff showing proposed additions and changes to the prompt.
5. Review the suggestions, accept or reject each one, and save.

For example, if you add a new Conditional node that filters emails by language, Floww might suggest adding a constraint like: "Non-English emails are forwarded to the international support queue."

Examples

Here is a concrete before-and-after example showing how a Floww Prompt evolves with a project.

Initial Prompt (Day 1)

When you first create the project and add a few nodes:

# Email Classifier

Classify incoming support emails and route them to the right team.

Evolved Prompt (Week 2)

After building out the full workflow with error handling, logging, and multiple classification categories:

# Email Support Router

This workflow monitors the support@acme.com inbox via IMAP,
classifies each email by urgency (critical, high, normal, low)
and topic (billing, technical, account, general), then posts
a formatted summary to the appropriate Slack channel.

## Inputs
- IMAP inbox: support@acme.com (polled every 60 seconds)
- Each email: subject, body (plain text extracted from HTML),
  sender, timestamp, attachments (filenames only)

## Outputs
- Slack message to #support-{topic} channel with ticket summary
- Row appended to ~/logs/support-log.csv
- If critical urgency: additional @channel mention and PagerDuty alert

## Classification Rules
- "Billing" if email mentions invoices, payments, charges, refunds
- "Technical" if email mentions errors, bugs, crashes, API
- "Account" if email mentions login, password, access, permissions
- "General" for everything else
- Urgency is "critical" if subject contains [URGENT] or mentions outage

## Constraints
- Never include customer email addresses or names in Slack messages
- Use ticket ID (auto-generated) as the only identifier
- If classification confidence < 70%, route to #support-general
- Rate limit: max 10 Slack messages per minute to avoid flooding

## Tone
- Slack summaries: concise, factual, one-paragraph max
- Auto-replies (if enabled): warm, professional, reference ticket ID

Best Practices

Follow these guidelines to get the most value from your Floww Prompt:

Keep It Concise

The prompt should be scannable in under a minute. Use bullet points, short paragraphs, and clear headings. If you find yourself writing multiple pages, consider whether some of that detail belongs in individual node configurations instead.

Make It Version-Control Friendly

Because the prompt is stored in the .floww file (as a JSON string), line breaks and formatting are preserved. Write in plain markdown without embedded images or complex formatting. This produces clean diffs when reviewing changes in Git.

# Viewing prompt changes in Git
git diff -- project.floww | grep '"prompt"'

Use It for Onboarding

Write the prompt as if someone new is reading it for the first time. Answer these questions:

• What does this workflow do?
• What triggers it?
• What does it produce?
• What external services does it depend on?
• Are there any non-obvious constraints or edge cases?

Reference It in AI Nodes

To give an AI node access to the project-level context, include {{floww.prompt}} in its system prompt or user prompt:

You are classifying support emails for the following project:

{{floww.prompt}}

Classify this email:
{{input}}

This keeps your AI nodes aligned with the project's evolving goals without manually duplicating context in every node.

Review Prompt Diffs in PRs

When you review pull requests that modify a .floww file, pay attention to prompt changes. They often explain why the workflow was changed, complementing the node-level diffs that show what changed.