Files

Zhongwei Li 169a5fc5cd Initial commit

2025-11-30 09:07:10 +08:00

22 KiB

Raw Blame History

description, allowed-tools

description	allowed-tools
notion	Bash, Read, Edit, Write, Glob, Grep

notion

Export AgileFlow epics, stories, and ADRs to Notion with detailed summaries via Model Context Protocol (MCP).

Key Feature: Automatically generates comprehensive summaries for EVERY epic, story, and ADR exported to Notion, including full content, metadata, relationships, and progress tracking.

Prompt

ROLE: Notion Integration Agent (MCP-based)

OBJECTIVE Bidirectional sync between AgileFlow markdown docs and Notion databases using Model Context Protocol. Automatically generates detailed summaries for ALL epics, stories, and ADRs during export, ensuring complete context is available in Notion. Supports initial setup, export with summaries, import, and incremental sync.

CRITICAL: Every item exported to Notion includes a comprehensive summary with:

Full content from markdown files (descriptions, acceptance criteria, technical notes, etc.)
Metadata (status, dates, owners, estimates)
Relationships (epic-story links, related ADRs)
Progress tracking (for epics: story completion percentage)

This ensures Notion serves as a complete, searchable knowledge base for stakeholders and team members.

PREREQUISITES

1. Notion Integration Token

CRITICAL: You need a Notion API token before using this command.

# Create integration at https://www.notion.so/my-integrations
# 1. Click "New integration"
# 2. Give it a name (e.g., "AgileFlow")
# 3. Copy the "Internal Integration Token" (starts with secret_)
# 4. Share your databases with this integration

2. Environment Setup

CRITICAL: Add your token to .env (gitignored, never commit):

# Add to .env file in project root
echo "NOTION_TOKEN=secret_your_token_here" >> .env

# Verify .env is in .gitignore
grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore

3. MCP Server Configuration

CRITICAL: MCP config must be in PROJECT ROOT (.mcp.json):

# Check if MCP is configured
cat .mcp.json 2>/dev/null || echo "MCP not configured"

# If missing, run setup
/AgileFlow:setup-system
# Select "yes" for Notion integration

Your .mcp.json should contain:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}

IMPORTANT:

.mcp.json must be in project root (not ~/.claude-code/ or ~/.config/)
Uses @notionhq/notion-mcp-server package (NOT mcp-remote)
Token referenced via ${NOTION_TOKEN} from .env
.mcp.json should be gitignored
.mcp.json.example committed as template for teams

4. Restart Claude Code

CRITICAL: MCP servers only load on startup:

# After creating/updating .mcp.json, restart Claude Code
# Tools will be available as mcp__notion__* after restart

5. Database Setup (First Time Only)

Run this command with MODE=setup to create the three required databases:

/AgileFlow:notion MODE=setup

This will:

Use MCP tools to create AgileFlow Epics database
Create AgileFlow Stories database
Create AgileFlow ADRs database
Store database IDs in docs/08-project/notion-sync-map.json

USAGE

# Initial setup (create databases)
/AgileFlow:notion MODE=setup

# Preview export without writing to Notion
# Shows detailed summaries that will be created for each item
/AgileFlow:notion DRY_RUN=true

# Export all docs to Notion WITH DETAILED SUMMARIES
# Automatically generates comprehensive summaries for ALL epics, stories, and ADRs
/AgileFlow:notion

# Export specific type only (with summaries)
/AgileFlow:notion TYPE=epics      # Exports all epics with full content summaries
/AgileFlow:notion TYPE=stories    # Exports all stories with AC, notes, testing strategy
/AgileFlow:notion TYPE=adrs       # Exports all ADRs with context, decisions, consequences

# Import from Notion back to markdown
/AgileFlow:notion MODE=import

# Bidirectional sync (smart merge)
/AgileFlow:notion MODE=sync

# Force overwrite (export wins - includes updated summaries)
/AgileFlow:notion MODE=export FORCE=true

# Force overwrite (import wins)
/AgileFlow:notion MODE=import FORCE=true

Note on Summaries: Every export automatically includes detailed summaries. You don't need any special flags - summaries are generated for ALL items by default.

Environment Variables

MODE: setup | export | import | sync (default: export)
TYPE: epics | stories | adrs | all (default: all)
DRY_RUN: true | false (default: false) - Preview only
FORCE: true | false (default: false) - Overwrite without merge

MCP TOOLS REFERENCE

This command uses the following Notion MCP tools (via @notionhq/notion-mcp-server):

Database Operations

mcp__notion__create_database - Create AgileFlow databases during setup
mcp__notion__update_database - Modify database properties
mcp__notion__query_database - Read database structure and pages

Page Management

mcp__notion__create_page - Export stories/epics/ADRs to Notion
mcp__notion__update_page - Sync changes back to existing pages
mcp__notion__retrieve_page - Read page content for import

Search & Retrieval

mcp__notion__search - Find existing AgileFlow databases
mcp__notion__retrieve_block_children - Read page content blocks

ARCHITECTURE

File Structure

docs/08-project/
├── notion-sync-map.json    # Database IDs and sync state
└── notion-sync-log.jsonl   # Audit trail (created on first sync)

Sync Map Schema

{
  "last_sync": "2025-01-15T10:30:00Z",
  "databases": {
    "epics": "notion-database-id-1",
    "stories": "notion-database-id-2",
    "adrs": "notion-database-id-3"
  },
  "pages": {
    "docs/05-epics/AG-001-authentication.md": {
      "notion_id": "page-id-1",
      "last_synced": "2025-01-15T10:30:00Z",
      "checksum": "abc123def456"
    },
    "docs/06-stories/AG-API-001-login-endpoint.md": {
      "notion_id": "page-id-2",
      "last_synced": "2025-01-15T10:30:00Z",
      "checksum": "xyz789uvw012"
    }
  },
  "config": {
    "auto_sync": false,
    "conflict_resolution": "manual",
    "workspace_url": "https://www.notion.so/your-workspace"
  }
}

IMPLEMENTATION

Key Features

1. Detailed Summary Generation

For EVERY epic, story, and ADR exported to Notion, the command automatically generates a comprehensive summary that includes:

Epics:

Epic ID and title
Description (full text)
Goals and objectives
All linked stories with their status
Progress percentage (completed vs total stories)
Key dates (created, updated)
Dependencies
Related ADRs

Stories:

Story ID and title
Epic parent (linked)
Description and acceptance criteria (full text)
Status, priority, estimate
Owner/assignee
Technical notes
Testing strategy
All files modified (from implementation)
Dependencies
Created/updated dates

ADRs (Architecture Decision Records):

ADR ID and title
Status (proposed, accepted, superseded)
Context (why this decision was needed)
Decision (what was decided)
Consequences (positive and negative)
Alternatives considered
Related epics/stories
Created/updated dates

Why Detailed Summaries?

Notion pages are searchable - full content makes finding information easier
Team members can review details without switching to markdown files
Stakeholders can read complete context in Notion
Better integration with Notion's AI features (Q&A, summarization)
Preserves all critical information even if markdown files are updated

How It Works:

Command reads each markdown file (epic/story/ADR)
Extracts frontmatter metadata (YAML)
Parses markdown content sections
Builds comprehensive summary with all relevant details
Creates/updates Notion page with summary as page content
Links related items (epic ↔ stories, ADR ↔ epics)

Export Process

# For each file type (epics, stories, ADRs):
# 1. Find all markdown files in docs/05-epics/, docs/06-stories/, docs/03-decisions/
# 2. Read file content and parse frontmatter
# 3. Extract all sections (Description, AC, Technical Notes, etc.)
# 4. Generate detailed summary with full content
# 5. Check if page exists in Notion (via sync map)
# 6. Create new page OR update existing page with summary
# 7. Update sync map with page ID and checksum
# 8. Link related items (epic-story relationships, etc.)

Summary Format Example

Epic Summary in Notion:

📋 Epic: EP-0001 - User Authentication System

Status: In Progress (3/5 stories completed)
Created: 2025-01-15
Updated: 2025-01-20

## Description
[Full description from markdown file]

## Goals
- Enable secure user login
- Support password reset
- Implement session management

## Stories (5 total, 3 completed)
✅ US-0001: User Login API
✅ US-0002: Password Reset Flow
✅ US-0003: Session Token Management
🔄 US-0004: OAuth Integration
📝 US-0005: Multi-Factor Authentication

## Dependencies
- Depends on: None
- Blocks: EP-0002 (User Profile Management)

## Related ADRs
- ADR-0001: JWT vs Session-based Auth (Accepted)
- ADR-0002: Password Hashing Strategy (Accepted)

Implementation Details

The command uses MCP tools to interact with Notion:

Setup Phase (MODE=setup):

Use mcp__notion__create_database to create three databases
Store database IDs in docs/08-project/notion-sync-map.json

Export Phase (default):

Use mcp__notion__query_database to find existing pages
Use mcp__notion__create_page for new items with full summary
Use mcp__notion__update_page for existing items with updated summary
All summaries include complete content from markdown files

Import Phase (MODE=import):

Use mcp__notion__retrieve_page to read Notion page content
Parse Notion blocks back to markdown format
Update local markdown files with changes

Sync Phase (MODE=sync):

Compare checksums between local and Notion
Detect conflicts (both changed since last sync)
Offer merge strategies or manual resolution

Parallel Execution Architecture

🚀 NEW: Parallel Export with Specialized Agents

The /AgileFlow:notion command now uses parallel agent execution for significantly faster exports:

How It Works:

Scan Phase: Main command scans docs/ for all epics, stories, and ADRs
Spawn Phase: Spawns one agileflow-notion-exporter agent per item
Parallel Execution: All agents run simultaneously (haiku model for speed)
Collection Phase: Collect results from all agents
Sync Map Update: Update notion-sync-map.json with all page IDs

Performance:

Sequential (old): ~2-3 seconds per item = 100 items in 3-5 minutes
Parallel (new): All items processed simultaneously = 100 items in 10-30 seconds

Batching for Rate Limits:

Notion API has rate limits (~3 requests/second)
Command batches agents in groups of 10
Batch 1: Items 1-10 (spawn, wait for completion)
Batch 2: Items 11-20 (spawn, wait for completion)
etc.

Agent Specification:

Agent: agileflow-notion-exporter
Model: haiku (fast for summarization)
Tools: Read, Bash (+ MCP tools automatically available)
Input: item_path, item_type, database_id, dry_run flag
Output: JSON with page_id, status, checksum

Error Handling:

If agent fails: Logged and reported, other agents continue
After all batches complete: Report failed items for retry
Partial success: Update sync map for successful items only

Progress Tracking:

📤 Exporting to Notion...

   Batch 1/5 (items 1-10):
   ✅ EP-0001-authentication.md → Notion
   ✅ EP-0002-authorization.md → Notion
   ...
   Batch 1 complete: 10/10 successful

   Batch 2/5 (items 11-20):
   ✅ US-0001-login-api.md → Notion
   ❌ US-0002-logout-api.md → Error: Rate limit
   ...
   Batch 2 complete: 9/10 successful

   ...

   📊 Export Summary:
   ✅ Successful: 48/50 items
   ❌ Failed: 2/50 items
   ⏱️  Time: 25 seconds

DRY_RUN with Parallel Agents:

Each agent generates summary but doesn't export
Shows what WOULD be created in Notion
Validates file parsing and summary generation
No API calls made (fast preview)

Example Orchestration Flow:

# Main command execution
/AgileFlow:notion

# 1. Scan docs/ for all items
Found 50 items: 10 epics, 35 stories, 5 ADRs

# 2. Load database IDs from sync map
Epics DB: abc123
Stories DB: def456
ADRs DB: ghi789

# 3. Spawn agents in batches of 10
Spawning batch 1 (10 agents)...
  → agileflow-notion-exporter (EP-0001)
  → agileflow-notion-exporter (EP-0002)
  → agileflow-notion-exporter (US-0001)
  ...

# 4. Wait for batch completion
Batch 1: 10/10 complete (8 seconds)

# 5. Spawn next batch
Spawning batch 2 (10 agents)...
  ...

# 6. Collect all results
Collected 50 results: 48 success, 2 failed

# 7. Update sync map
Updated notion-sync-map.json with 48 page IDs

# 8. Report summary
✅ Export complete: 48/50 items (96% success rate)

EXAMPLE WORKFLOWS

First-Time Setup

# 1. Create Notion integration
# Visit https://www.notion.so/my-integrations
# Create new integration, copy token

# 2. Add token to .env
echo "NOTION_TOKEN=secret_your_token_here" >> .env

# 3. Run system setup
/AgileFlow:setup-system
# Select "yes" for Notion integration
# This creates .mcp.json.example and copies to .mcp.json

# 4. Restart Claude Code
# MCP server loads on startup

# 5. Create databases
/AgileFlow:notion MODE=setup

# 6. Share databases with integration
# In Notion: Click "..." → "Add connections" → Select your integration

# 7. Preview export
/AgileFlow:notion DRY_RUN=true

# 8. Perform initial export
/AgileFlow:notion

# 9. Visit Notion to verify
# Open https://notion.so/your-workspace

Daily Workflow

# Export new/changed docs to Notion
/AgileFlow:notion

# Or just export stories
/AgileFlow:notion TYPE=stories

# Import changes from Notion (team members edited in Notion)
/AgileFlow:notion MODE=import

# Bidirectional sync (smart merge)
/AgileFlow:notion MODE=sync

Team Member Onboarding

# 1. Pull latest code (includes .mcp.json.example)
git pull

# 2. Create their own Notion integration
# Visit https://www.notion.so/my-integrations

# 3. Copy template to active config
cp .mcp.json.example .mcp.json

# 4. Add their token to .env
echo "NOTION_TOKEN=secret_their_token_here" >> .env

# 5. Restart Claude Code

# 6. Share databases with their integration
# In Notion: Click "..." → "Add connections" → Select their integration

# 7. Start syncing!
/AgileFlow:notion

Conflict Resolution

# Check for conflicts first
/AgileFlow:notion MODE=sync DRY_RUN=true

# Manual conflict resolution (default)
# Script will list conflicts and prompt for each

# Or force local version to win
/AgileFlow:notion MODE=export FORCE=true

# Or force Notion version to win
/AgileFlow:notion MODE=import FORCE=true

ADVANTAGES OF MCP APPROACH

🚀 Developer Experience

✅ Standardized tool interface - MCP provides unified API across services
✅ Better error handling - Improved over raw Notion API calls
✅ Automatic rate limiting - MCP handles throttling
✅ Native Claude Code integration - Tools available as mcp__notion__*

👥 Team Collaboration

✅ Template-based setup - .mcp.json.example committed to git
✅ Individual tokens - Each team member uses their own NOTION_TOKEN
✅ No token sharing - Tokens stay in .env (gitignored)
✅ Consistent setup - Same .mcp.json template for everyone

🔒 Security

✅ Tokens in .env - Gitignored, never committed
✅ Project-level config - .mcp.json in repo root (not user-level)
✅ Easy revocation - Just delete token from Notion integrations page

🛠️ Maintenance

✅ Standard protocol - MCP is consistent across tools
✅ Better debugging - Clearer error messages from MCP tools
✅ No API version pinning - MCP package handles compatibility

⚡ Parallel Execution (NEW in v2.19.3)

✅ 10-30x faster exports - Process 100 items in 10-30 seconds instead of 3-5 minutes
✅ Parallel agent architecture - One agileflow-notion-exporter agent per item
✅ Haiku model for speed - Fast summarization without sacrificing quality
✅ Batched rate limiting - Respects Notion API limits with automatic batching
✅ Resilient error handling - Failed items don't block successful exports
✅ Detailed progress tracking - See real-time batch completion status
✅ Scalable architecture - Handles 10 items or 1000 items efficiently

MIGRATION FROM DIRECT API APPROACH

If you previously used direct Notion API calls (curl-based):

Step 1: Backup

# Backup your sync map (database IDs are preserved!)
cp docs/08-project/notion-sync-map.json docs/08-project/notion-sync-map.json.backup

Step 2: Set Up MCP

# Your NOTION_TOKEN can stay in .env (no change needed!)

# Run setup to create .mcp.json
/AgileFlow:setup-system
# Select "yes" for Notion integration

# This creates .mcp.json with:
# {
#   "mcpServers": {
#     "notion": {
#       "command": "npx",
#       "args": ["-y", "@notionhq/notion-mcp-server"],
#       "env": {
#         "NOTION_TOKEN": "${NOTION_TOKEN}"
#       }
#     }
#   }
# }

Step 3: Restart Claude Code

# MCP servers only load on startup
# Restart Claude Code to load @notionhq/notion-mcp-server

Step 4: Verify and Resume

# Your existing database IDs work with MCP!
# No need to recreate databases

# Verify connection
/AgileFlow:notion DRY_RUN=true

# Resume syncing
/AgileFlow:notion

TROUBLESHOOTING

MCP Server Not Configured

Error: "notion MCP server not found" or "mcp__notion__* tools not available"

Fix:

# Run setup
/AgileFlow:setup-system

# Or manually create .mcp.json in project root:
cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "${NOTION_TOKEN}"
      }
    }
  }
}
EOF

# CRITICAL: Restart Claude Code after creating .mcp.json

Token Not Found

Error: "NOTION_TOKEN not set" or "Unauthorized"

Fix:

# Add token to .env in project root
echo "NOTION_TOKEN=secret_your_token_here" >> .env

# Verify it's there
grep NOTION_TOKEN .env

# Restart Claude Code

Wrong MCP Package

Error: "mcp-remote not found" or connection errors

Fix:

# Check .mcp.json uses correct package
cat .mcp.json

# Should say "@notionhq/notion-mcp-server"
# NOT "mcp-remote"

# If wrong, update .mcp.json and restart Claude Code

Project-Level Config Not Working

Error: MCP config not loading

Fix:

# CRITICAL: .mcp.json must be in PROJECT ROOT
pwd  # Should show /path/to/your/project
ls -la .mcp.json  # Should exist in current directory

# NOT in ~/.claude-code/ or ~/.config/claude-code/
# Those locations won't work for project-specific MCP servers

Databases Not Found

Error: "Database IDs missing in sync map"

Fix:

/AgileFlow:notion MODE=setup

Rate Limiting

Error: "Rate limit exceeded"

Fix: MCP handles this automatically with exponential backoff. Wait a few seconds and retry.

Sync Conflicts

Error: "Conflict detected: both local and Notion changed"

Fix:

# Review conflict details
/AgileFlow:notion MODE=sync DRY_RUN=true

# Choose resolution strategy
/AgileFlow:notion MODE=sync  # Manual prompts
# or
/AgileFlow:notion MODE=export FORCE=true  # Local wins
# or
/AgileFlow:notion MODE=import FORCE=true  # Notion wins

Database Not Shared With Integration

Error: "object not found" or "insufficient permissions"

Fix:

# In Notion, for each database:
# 1. Click "..." (three dots) in top right
# 2. Click "Add connections"
# 3. Select your integration name
# 4. Try sync again

FUTURE ENHANCEMENTS

Auto-sync on file changes (watch mode)
Conflict resolution UI in Claude Code
Comment syncing (mcp__notion__create_comment)
Attachment support
Webhook integration (Notion → AgileFlow)
Multi-workspace support
Custom property mappings
Rollback support (restore from log)

/AgileFlow:setup-system - Initial AgileFlow + MCP configuration
/AgileFlow:github-sync - Sync with GitHub Issues (uses GitHub CLI)
/AgileFlow:story-new - Create new story (auto-exports if Notion enabled)
/AgileFlow:epic-new - Create new epic (auto-exports if Notion enabled)
/AgileFlow:adr-new - Create new ADR (auto-exports if Notion enabled)
/AgileFlow:board - Visualize status (can pull from Notion)

agileflow-notion-exporter - Parallel export agent (spawned by this command)
- Haiku model for fast summarization
- Processes one epic/story/ADR at a time
- Generates detailed summaries with full content
- Uses MCP tools to export to Notion
- Returns JSON with page ID and status

REFERENCES

@notionhq/notion-mcp-server - Notion MCP Package
MCP Documentation - Model Context Protocol
MCP Supported Tools - Notion MCP Tools List
Claude Code MCP Guide - MCP in Claude Code
Notion API Reference - Notion API Docs
Create Notion Integration - Get Your Token

KEY LEARNINGS (Historical: v2.3.0 Correction)

Note: This section documents a correction made during the v2.3.0 release (October 2025). It is preserved for historical context. See CHANGELOG.md for full details.

What We Got Wrong Initially:

❌ Claimed OAuth authentication via /mcp command
❌ Said "no manual token management"
❌ Used wrong package (mcp-remote instead of @notionhq/notion-mcp-server)
❌ Suggested committing .mcp.json to git (should be gitignored)

What's Actually Correct:

✅ Still uses NOTION_TOKEN in .env (token-based)
✅ Uses @notionhq/notion-mcp-server package
✅ Project-level .mcp.json in repo root (not user-level)
✅ .mcp.json gitignored, .mcp.json.example committed as template
✅ MCP provides standardized tool interface, NOT authentication
✅ Each team member needs their own token

Credit: Thank you to the user who discovered the correct approach through testing!

22 KiB Raw Blame History

notion

Prompt

PREREQUISITES

1. Notion Integration Token

2. Environment Setup

3. MCP Server Configuration

4. Restart Claude Code

5. Database Setup (First Time Only)

USAGE

Environment Variables

MCP TOOLS REFERENCE

Database Operations

Page Management

Search & Retrieval

ARCHITECTURE

File Structure

Sync Map Schema

IMPLEMENTATION

Key Features

Export Process

Summary Format Example

Implementation Details

Parallel Execution Architecture

EXAMPLE WORKFLOWS

First-Time Setup

Daily Workflow

Team Member Onboarding

Conflict Resolution

ADVANTAGES OF MCP APPROACH

🚀 Developer Experience

👥 Team Collaboration

🔒 Security

🛠️ Maintenance

⚡ Parallel Execution (NEW in v2.19.3)

MIGRATION FROM DIRECT API APPROACH

Step 1: Backup

Step 2: Set Up MCP

Step 3: Restart Claude Code

Step 4: Verify and Resume

TROUBLESHOOTING

MCP Server Not Configured

Token Not Found

Wrong MCP Package

Project-Level Config Not Working

Databases Not Found

Rate Limiting

Sync Conflicts

Database Not Shared With Integration

FUTURE ENHANCEMENTS

RELATED COMMANDS

RELATED AGENTS

REFERENCES

KEY LEARNINGS (Historical: v2.3.0 Correction)

22 KiB

Raw Blame History