AI Overview

Epics & Stories includes several AI subsystems that cover:

Board-level planning and cleanup
Per-note authoring and structured artifact generation
Document ingestion and note extraction
Inline rewrite and review workflows
Jira-style backlog generation

Why multiple subsystems

Each workflow has different requirements:

Subsystem	Why it's separate
Board chat	Must safely mutate global state via tool calls
Note AI	Must write long-form streamed content per note
Document-to-notes	Must produce validated structured JSON
Jira generation	Needs stepwise structured output with stable schemas
Jira analyze / rewrite	Field-level rewrites and inline suggestions

Splitting subsystems keeps prompts focused, allows per-feature quota gating, and makes it easier to reason about safety guarantees.

All AI subsystems

Subsystem	Entry point	Output type
Board Chat	AI panel slide-out (right)	Streamed UIMessages + tool calls
Subagent	Floating subagent panel	Streamed UIMessages + 3 suggested actions
Note AI (free-form)	Note overlay prompt bar	Streamed Markdown text
Slash Commands	`/command` in note prompt bar	Streamed Markdown text
Document-to-Notes	Upload modal	Structured JSON (Zod-validated)
Jira AI	Jira Action Bar + work item editor	Structured JSON or streamed text

Safety principles

Schema validation

All tool calls and structured outputs are validated with Zod schemas before being applied. Invalid AI outputs are rejected, not silently accepted.

Access and quota gating

Every AI endpoint:

Requires a valid authenticated session
Enforces a per-user rate limit (requests per minute)
Enforces a monthly AI credit quota based on the user's plan

A 429 response is returned when either limit is exceeded.

Progressive context disclosure

As boards grow, dumping all note content into every AI prompt would be expensive and noisy. The system instead uses:

Active note: only the current note's title, body, and recent comments
Explicit references: user-mentioned notes (e.g. #Epic-Title hashtag)
On-demand tools: AI can call searchNotes and readNote tools to fetch additional context only when needed

This keeps individual prompt sizes small while still allowing the AI to access the full board when relevant.

Tool-driven mutations

Board-level mutations (create, update, delete notes) are executed through validated tool calls, not by parsing free-form text. The client applies tool results to the Zustand store, which then syncs to D1.

Model

All AI routes use Google Gemini (gemini-3-flash-preview) via @ai-sdk/google.