Notion → local spec → work

Principle

Notion is never the execution source of truth. AgentFlow always works from a local snapshot under .agentflow/specs/ (or paths in sources.local.paths). Sync pulls remote content; work reads local files and SQLite state.

Product and design stakeholders can therefore keep authoring in Notion while engineering replay runs from immutable filesystem snapshots—a split that avoids surprise behaviour when editors rename properties or reorganize databases mid-flight.

Configure Notion

YAML mirrors the authoritative schema: enable the connector, declare which environment variable exposes the PAT, tie it to your specs database identifier, and point imports at .agentflow/specs (overridable elsewhere if your layout differs).

sources:
  notion:
    enabled: true
    token_env: NOTION_TOKEN
    specs_database_id: "<your-database-id>"
    import_path: .agentflow/specs

Export the token:

export NOTION_TOKEN="ntn_..."

Sync

sync notion can target a canonical page URL, while sync all fans out across every configured source so auxiliary streams stay coherent.

agentflow sync notion --page "https://www.notion.so/..."
# or list + sync all enabled sources:
agentflow sync all

Dry-run preview:

agentflow --dry-run sync notion --page "https://www.notion.so/..."

Interactive mode may prompt before overwriting a modified local spec.

Work from local snapshot

Listing plus execution both consult the synced tree under .agentflow/specs:

agentflow inbox --source notion
agentflow work "develop billing-v2" --source notion

Trade-offs

Related

• Notion configuration
• CLI: sync
• CLI: inbox