How to Build an Automated Workflow Pipeline Using Claude Code and Notion

A software engineer at a fast-growing startup recently told me something that stopped me in my tracks: “I spend more time updating Jira tickets than writing code.” He wasn’t exaggerating. Studies from Atlassian’s own research suggest that developers spend roughly 30% of their workweek on project management overhead — updating statuses, writing ticket descriptions, copying PR links into boards, and documenting what they built after they built it. That’s nearly a day and a half every week lost to administrative busywork that adds zero lines of working code to the product.

Now imagine a different reality. You open your Notion workspace, glance at the sprint board, and type a single command. An AI agent reads the task description, creates a feature branch, writes the code, runs the tests, opens a pull request, pastes the PR link back into Notion, and updates the status to “In Review” — all before you finish your morning coffee. This isn’t science fiction. This is what happens when you connect Claude Code, Anthropic’s agentic AI coding tool, to Notion, the workspace where millions of teams organize their work.

Most developers and knowledge workers live in two worlds — their code editor and their project management tool. Claude Code is revolutionizing how we write software by acting as an autonomous coding agent that can read requirements, generate code, write tests, and commit changes. Notion is where teams organize everything from product roadmaps to bug trackers to engineering wikis. Separately, they’re powerful. Together, connected through a well-designed automated pipeline, they become something genuinely transformative: a system where tasks flow from idea to deployed code with minimal human friction, while keeping humans in the loop for the decisions that matter.

In this guide, I’m going to walk you through exactly how to build this pipeline from scratch. We’ll cover the architecture, the Notion setup, the MCP (Model Context Protocol) integration, five custom Claude Code commands that handle every stage of the workflow, a complete Python orchestrator script, and advanced patterns for bug fixes, documentation, and sprint planning. By the end, you’ll have a copy-paste-ready system that turns your Notion board into a command center for AI-assisted development.

Why Claude Code + Notion?

Before we dive into the technical setup, let’s answer the fundamental question: why this particular combination? There are dozens of AI coding tools and project management platforms. What makes Claude Code and Notion uniquely suited for an automated workflow pipeline?

Claude Code: More Than a Code Autocompleter

Claude Code is Anthropic’s command-line AI coding agent. Unlike inline code completion tools that suggest the next few tokens as you type, Claude Code operates at the task level. You give it a goal — “add user authentication with JWT tokens” — and it figures out which files to create, which existing files to modify, what tests to write, and how to wire everything together. It reads your entire codebase for context, understands your project’s conventions through a CLAUDE.md file, and can execute shell commands, run tests, and create git commits autonomously.

The key capabilities that make it ideal for pipeline automation include agentic execution (it runs multi-step tasks without hand-holding), custom slash commands (you can define reusable workflows as markdown files), MCP support (it connects to external tools and APIs through Anthropic’s Model Context Protocol), and CLI mode (it can be invoked non-interactively from scripts, which is critical for automation).

Notion: The Flexible Backbone

Notion brings a fully programmable workspace to the table. Its database system lets you create structured project boards with custom properties — status columns, priority levels, assignees, URLs, dates, and rich text fields. Crucially, Notion has a robust API that lets external systems read and write data, and it supports webhooks for real-time notifications. This means your pipeline can query Notion for pending tasks, update statuses as work progresses, and write back results like PR URLs and code summaries.

Together: The Automated Dev Workflow

When you connect Claude Code to Notion, you create a closed-loop system. A task is created in Notion. Claude Code picks it up, reads the requirements, writes the code, opens a PR, and updates Notion — all through a series of automated stages. The human developer’s role shifts from manually performing every step to reviewing PRs, approving deployments, and steering the project at a higher level.

How does this compare to other popular combinations? Let’s look at the landscape:

The Claude Code + Notion stack wins on automation because Claude Code can execute entire tasks autonomously (not just suggest code snippets), and Notion’s API and database model make it straightforward to build structured workflows that other tools can interact with programmatically. Let’s see how to set it all up.

Architecture Overview

Before writing a single line of configuration, it helps to understand the full pipeline architecture. Here’s how the system flows from end to end:

The Pipeline Flow

The workflow follows a linear progression with feedback loops at each stage:

┌─────────────────────────────────────────────────────────────────┐
│                    NOTION WORKSPACE                              │
│                                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐     │
│  │  To Do   │──▶│In Progress│──▶│In Review │──▶│   Done   │     │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘     │
│       │              ▲              ▲              ▲             │
└───────┼──────────────┼──────────────┼──────────────┼─────────────┘
        │              │              │              │
        ▼              │              │              │
┌───────────────┐      │              │              │
│  /pick-task   │──────┘              │              │
│  (select +    │                     │              │
│   branch)     │                     │              │
└───────┬───────┘                     │              │
        ▼                             │              │
┌───────────────┐                     │              │
│  /work-task   │                     │              │
│  (code +      │                     │              │
│   test)       │                     │              │
└───────┬───────┘                     │              │
        ▼                             │              │
┌───────────────┐                     │              │
│ /submit-task  │─────────────────────┘              │
│  (PR + link)  │                                    │
└───────┬───────┘                                    │
        ▼                                            │
┌───────────────┐                                    │
│/complete-task │────────────────────────────────────┘
│  (merge +     │
│   archive)    │
└───────────────┘

Core Components

The pipeline relies on five key components working together:

Notion API — The data layer. Stores tasks, statuses, priorities, PR links, and documentation. Notion’s database acts as the single source of truth for what needs to be built and what has been completed.

Claude Code CLI — The execution engine. Receives task requirements, generates code, writes tests, creates commits, and interacts with git. Can be invoked interactively (developer runs slash commands) or non-interactively (orchestrator script spawns Claude Code processes).

MCP (Model Context Protocol) Servers — The bridge. MCP is Anthropic’s open standard that lets AI models connect to external tools and data sources. A Notion MCP server gives Claude Code direct access to read and write Notion databases without you writing custom API code.

Git + GitHub CLI (gh) — The version control layer. Claude Code creates branches, commits changes, and opens pull requests using standard git commands and the GitHub CLI.

Orchestrator Script — The automation glue. A Python script that polls Notion for new tasks, spawns Claude Code processes, handles errors, and manages the overall workflow lifecycle.

When to Use Webhooks vs Polling vs Manual Triggers

You have three options for triggering the pipeline, and the right choice depends on your team’s needs:

Manual triggers are the simplest starting point. A developer opens their terminal, runs /pick-task, and the pipeline executes step by step under their supervision. This gives you maximum control and is ideal when you’re first adopting the workflow.

Polling means running a script on a schedule (e.g., every 5 minutes via cron) that checks Notion for tasks in the “To Do” column and processes them automatically. This is a solid middle ground — easy to implement, easy to debug, and reliable enough for most teams.

Webhooks provide real-time triggers. Notion can send a webhook when a database entry changes, so your pipeline reacts instantly when someone creates a new task. This requires a web server to receive the webhooks, which adds complexity, but delivers the fastest response time.

Setting Up the Foundation

Now let’s get our hands dirty. This section covers the complete setup for both Notion and Claude Code, from creating your first integration to configuring MCP.

Notion Setup

First, we need to create a Notion integration and a structured project database. Here’s the step-by-step process.

Step 1: Create a Notion Internal Integration. Navigate to notion.so/my-integrations and click “New integration.” Give it a name like “Claude Code Pipeline,” select the workspace where your project lives, and set the capabilities to “Read content,” “Update content,” and “Insert content.” Once created, copy the Internal Integration Secret — this is your API key. It starts with ntn_ and you’ll need it for the MCP configuration.

Step 2: Create the Project Database. In your Notion workspace, create a new full-page database (not an inline one). This database will serve as your task board. Set up the following properties:

Step 3: Share the Database with Your Integration. Open your database page, click the three-dot menu in the upper right, select “Connections,” and add the “Claude Code Pipeline” integration you created earlier. This grants the integration permission to read and modify the database. Without this step, all API calls will return 404 errors — a common gotcha.

Step 4: Copy the Database ID. Open the database in your browser. The URL will look like https://www.notion.so/yourworkspace/abc123def456.... The 32-character hex string after the workspace name (and before any ?v= query parameter) is your database ID. You’ll need this for querying tasks.

Claude Code Setup

Next, let’s install and configure Claude Code for the pipeline workflow.

Install Claude Code globally via npm:

npm install -g @anthropic-ai/claude-code

Configure your project’s CLAUDE.md file. This file lives at the root of your repository and gives Claude Code persistent context about the project. A well-written CLAUDE.md dramatically improves code quality because Claude Code reads it before every task:

# CLAUDE.md — Project Context for Claude Code

## Project Overview
This is a [your framework] application that [brief description].

## Tech Stack
- Language: Python 3.12 / TypeScript 5.x
- Framework: FastAPI / Next.js
- Database: PostgreSQL with SQLAlchemy
- Testing: pytest / vitest

## Code Conventions
- Use type hints on all function signatures
- Follow PEP 8 / ESLint defaults
- Write docstrings for public functions
- Tests live in tests/ mirroring the src/ structure

## Key Commands
- Run tests: `pytest -v`
- Start dev server: `uv run python -m src.main`
- Lint: `ruff check .`

## Notion Integration
- Database ID: <your-database-id>
- Task statuses: To Do → In Progress → In Review → Done
- All task updates should go through the Notion MCP server

Create the custom commands directory. Claude Code looks for command definitions in .claude/commands/. Each .md file becomes a slash command you can invoke inside Claude Code:

mkdir -p .claude/commands

We’ll populate these command files in the pipeline section below. But first, we need to connect Claude Code to Notion.

Connecting Claude Code to Notion via MCP

This is where the magic happens. MCP (Model Context Protocol) is Anthropic’s open standard for connecting AI models to external tools and data sources. Think of it as a universal adapter — instead of writing custom API integration code for every service, you configure an MCP server that exposes the service’s capabilities in a format Claude Code understands natively.

What MCP Does

An MCP server is a lightweight process that runs alongside Claude Code and translates between the AI model and an external API. When Claude Code needs to read a Notion database, it sends a structured request to the MCP server, which translates it into a Notion API call, gets the response, and passes the data back in a format Claude can work with. You don’t write any of this plumbing — the MCP server handles it.

For the Notion integration, we use the official @notionhq/notion-mcp-server package, which exposes Notion operations as MCP tools that Claude Code can call.

Setting Up the Notion MCP Server

Create or edit .claude/settings.json in your project root with the following configuration:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_YOUR_API_KEY_HERE\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

An alternative approach is to use the community-driven notion-mcp server, which some developers prefer for its broader feature set:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "ntn_YOUR_API_KEY_HERE"
      }
    }
  }
}

Testing the Connection

Launch Claude Code in your project directory and test the Notion connection:

claude

# Once inside Claude Code, try:
> List all tasks in my Notion project database

# Claude Code should use the MCP server to query your database
# and return the list of tasks with their statuses

If the connection works, you’ll see Claude Code invoke the Notion MCP tools to query your database and return results. If it fails, check that your API key is correct, the database is shared with the integration, and the MCP server package is installable via npx.

Available Notion Operations via MCP

Once configured, Claude Code can perform these operations through the MCP server:

• Query databases — Filter and sort tasks by status, priority, type, or any other property
• Read pages — Get the full content of a task, including its description and acceptance criteria
• Update properties — Change a task’s status, add PR URLs, set dates, update text fields
• Create pages — Add new tasks, create documentation pages, generate sub-tasks
• Search — Find pages across the workspace by keyword
• Append blocks — Add content (text, code blocks, headings) to existing pages

These operations form the building blocks for every stage of the pipeline. Now let’s put them to work.

Building the Workflow Pipeline — Step by Step

This is the heart of the guide. We’re going to build five custom Claude Code commands, each handling one stage of the development lifecycle. Every command file below is complete and copy-paste ready — save each one to .claude/commands/ and you can start using them immediately.

Pipeline Stage 1: Task Intake — /pick-task

The first stage is selecting a task from Notion and setting up the local development environment. Create the file .claude/commands/pick-task.md:

# Pick Task from Notion

You are a development workflow assistant. Your job is to select a task
from the Notion project database and prepare the local environment.

## Steps

1. **Query Notion for available tasks:**
   - Use the Notion MCP server to query the project database
   - Filter for tasks where Status = "To Do"
   - Sort by Priority (Critical first, then High, Medium, Low)
   - Display the results as a numbered list showing:
     Title | Priority | Type

2. **Let the user select a task:**
   - If $ARGUMENTS contains a task number or title, use that
   - Otherwise, ask the user to pick from the list

3. **Update Notion status:**
   - Set the selected task's Status to "In Progress"
   - Add a note to the Claude Code Log: "Task picked up at [timestamp]"

4. **Create a git branch:**
   - Generate a branch name from the task title:
     - Lowercase, hyphens instead of spaces
     - Prefix with task type: feature/, bugfix/, refactor/, docs/
     - Example: "Add user authentication" → feature/add-user-authentication
   - Run: git checkout -b <branch-name>
   - Update the Branch Name property in Notion with the branch name

5. **Display the task details:**
   - Show the full task description and any acceptance criteria
   - Confirm the branch was created
   - Suggest running /work-task to start coding

When you run /pick-task inside Claude Code, it queries your Notion database, presents the available tasks, creates the appropriate git branch, and updates Notion — all in one fluid interaction.

Pipeline Stage 2: Code Generation — /work-task

This is where Claude Code does what it does best: writing code. Create .claude/commands/work-task.md:

# Work on Current Task

You are a senior software engineer. Your job is to implement the current
task based on the requirements stored in Notion.

## Steps

1. **Identify the current task:**
   - Check the current git branch name
   - Query Notion for the task with a matching Branch Name property
   - Read the full task page content including:
     - Description
     - Acceptance criteria
     - Any linked documents or specifications
     - Comments from team members

2. **Plan the implementation:**
   - Analyze the requirements
   - List the files that need to be created or modified
   - Identify potential edge cases
   - Present the plan to the user for approval

3. **Implement the code:**
   - Write clean, well-documented code following project conventions
   - Follow patterns established in CLAUDE.md
   - Create or modify files as needed
   - Add appropriate error handling
   - Include type hints / types where applicable

4. **Write tests:**
   - Write unit tests covering the main functionality
   - Write edge case tests
   - Ensure tests follow the project's testing patterns

5. **Run tests and iterate:**
   - Execute the test suite
   - If tests fail, fix the code and re-run
   - Continue until all tests pass

6. **Update Notion with progress:**
   - Add implementation notes to the Claude Code Log
   - Note: "Implementation complete. Tests passing. [timestamp]"

7. **Suggest next steps:**
   - Recommend running /submit-task to create a PR

Pipeline Stage 3: Code Review and PR — /submit-task

Once the code is written and tested, this command handles the submission process. Create .claude/commands/submit-task.md:

# Submit Task — Create PR and Update Notion

You are a development workflow assistant. Your job is to commit the
current changes, create a pull request, and update the Notion task.

## Steps

1. **Review changes:**
   - Run `git status` and `git diff` to see all changes
   - Summarize what was implemented

2. **Create a meaningful commit:**
   - Stage all relevant files (avoid committing .env or secrets)
   - Write a descriptive commit message following conventional commits:
     feat: Add user authentication with JWT tokens

     - Implement login and register endpoints
     - Add JWT token generation and validation middleware
     - Create user model with password hashing
     - Add comprehensive test suite

3. **Push and create PR:**
   - Push the branch to origin: `git push -u origin HEAD`
   - Create a pull request using the GitHub CLI:
     ```
     gh pr create \
       --title "feat: [task title from Notion]" \
       --body "[generated description with summary, changes list,
               test coverage, and link to Notion task]"
     ```

4. **Update Notion:**
   - Set Status to "In Review"
   - Set PR URL to the pull request URL
   - Add to Claude Code Log: "PR created: [URL] at [timestamp]"
   - Add a summary of all changes made to the task page body

5. **Notify:**
   - Display the PR URL
   - Show a summary of the submission
   - Suggest the reviewer check the PR

Pipeline Stage 4: Documentation — /doc-task

Documentation is often the first casualty of tight deadlines. This command automates it. Create .claude/commands/doc-task.md:

# Document Current Task

You are a technical writer. Your job is to generate documentation
for the changes made in the current task.

## Steps

1. **Identify the current task:**
   - Check the current git branch name
   - Query Notion for the matching task

2. **Analyze the changes:**
   - Run `git diff main...HEAD` to see all changes in this branch
   - Understand the purpose, architecture, and usage of the new code

3. **Generate documentation:**
   - Create a new page in Notion under the project's Docs section
   - Include:
     - Overview: What was built and why
     - Architecture: How the components fit together
     - API Reference: Endpoints, functions, or classes with parameters
     - Usage Examples: Code snippets showing how to use the feature
     - Configuration: Any environment variables or settings needed
     - Troubleshooting: Common issues and solutions

4. **Link documentation:**
   - Add the Docs Page relation in the original Notion task
   - Update Claude Code Log: "Documentation created at [timestamp]"

5. **Update README if needed:**
   - If the changes introduce new setup steps or commands,
     update the project README.md accordingly

Pipeline Stage 5: Completion — /complete-task

The final stage closes the loop. Create .claude/commands/complete-task.md:

# Complete Task — Close the Loop

You are a development workflow assistant. Your job is to finalize
a completed task after its PR has been merged.

## Steps

1. **Verify the PR is merged:**
   - Check the current branch or accept a task identifier from $ARGUMENTS
   - Query Notion for the task
   - Use `gh pr status` or `gh pr view` to confirm the PR was merged

2. **Update Notion:**
   - Set Status to "Done"
   - Set Completed At to the current date/time
   - Add to Claude Code Log: "Task completed at [timestamp]"

3. **Clean up the branch:**
   - Switch to main: `git checkout main`
   - Pull latest: `git pull origin main`
   - Delete the local branch: `git branch -d <branch-name>`
   - Delete the remote branch: `git push origin --delete <branch-name>`

4. **Generate a changelog entry:**
   - Create or append to a Changelog page in Notion
   - Entry format:
     **[Date] - [Task Title]**
     - Summary of changes
     - PR: [link]
     - Type: [Feature/Bug Fix/Refactor/Docs]

5. **Display completion summary:**
   - Show task title, completion time, PR link
   - Calculate time from "In Progress" to "Done" if dates are available

With these five commands, you have a complete task lifecycle managed through Claude Code and Notion. But we can take it further — let’s automate the orchestration.

Automation Script: The Orchestrator

The custom commands above work great when a developer is at the keyboard. But what if you want the pipeline to run autonomously — picking up tasks and processing them without human intervention? That’s where the orchestrator script comes in.

This Python script polls your Notion database for new tasks, spawns Claude Code in non-interactive mode to process each one, handles errors with retry logic, and logs everything back to Notion.

#!/usr/bin/env python3
"""
workflow_orchestrator.py — Automated Claude Code + Notion Pipeline

Polls Notion for "To Do" tasks and processes them using Claude Code
in non-interactive mode. Handles errors, retries, and notifications.

Usage:
    python workflow_orchestrator.py --once          # Process one batch
    python workflow_orchestrator.py --watch          # Continuous polling
    python workflow_orchestrator.py --interval 300   # Poll every 5 minutes
"""

import argparse
import json
import logging
import os
import subprocess
import sys
import time
from datetime import datetime, timezone
from dataclasses import dataclass, field
from pathlib import Path

import httpx  # pip install httpx

# ─── Configuration ───────────────────────────────────────────────

NOTION_API_KEY = os.environ["NOTION_API_KEY"]
NOTION_DATABASE_ID = os.environ["NOTION_DATABASE_ID"]
PROJECT_DIR = os.environ.get("PROJECT_DIR", os.getcwd())
MAX_RETRIES = 3
POLL_INTERVAL = 300  # seconds (5 minutes default)
NOTION_API_URL = "https://api.notion.com/v1"
NOTION_VERSION = "2022-06-28"

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler("orchestrator.log"),
    ],
)
logger = logging.getLogger(__name__)


# ─── Data Models ─────────────────────────────────────────────────

@dataclass
class NotionTask:
    page_id: str
    title: str
    status: str
    priority: str
    task_type: str
    description: str = ""
    branch_name: str = ""
    pr_url: str = ""

    @property
    def safe_branch_name(self) -> str:
        prefix_map = {
            "Feature": "feature",
            "Bug": "bugfix",
            "Refactor": "refactor",
            "Docs": "docs",
        }
        prefix = prefix_map.get(self.task_type, "task")
        slug = self.title.lower()
        slug = "".join(c if c.isalnum() or c == " " else "" for c in slug)
        slug = slug.strip().replace(" ", "-")[:50]
        return f"{prefix}/{slug}"


# ─── Notion API Client ──────────────────────────────────────────

class NotionClient:
    def __init__(self, api_key: str):
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Notion-Version": NOTION_VERSION,
        }
        self.client = httpx.Client(
            base_url=NOTION_API_URL,
            headers=self.headers,
            timeout=30.0,
        )

    def query_tasks(self, status: str = "To Do") -> list[NotionTask]:
        """Query the database for tasks with a given status."""
        payload = {
            "filter": {
                "property": "Status",
                "select": {"equals": status},
            },
            "sorts": [
                {
                    "property": "Priority",
                    "direction": "ascending",
                }
            ],
        }
        resp = self.client.post(
            f"/databases/{NOTION_DATABASE_ID}/query",
            json=payload,
        )
        resp.raise_for_status()
        results = resp.json().get("results", [])

        tasks = []
        for page in results:
            props = page["properties"]
            title_parts = props.get("Title", {}).get("title", [])
            title = title_parts[0]["plain_text"] if title_parts else "Untitled"

            tasks.append(NotionTask(
                page_id=page["id"],
                title=title,
                status=status,
                priority=self._get_select(props, "Priority"),
                task_type=self._get_select(props, "Type"),
            ))
        return tasks

    def update_status(self, page_id: str, status: str):
        """Update a task's status property."""
        self.client.patch(
            f"/pages/{page_id}",
            json={
                "properties": {
                    "Status": {"select": {"name": status}},
                }
            },
        ).raise_for_status()
        logger.info(f"Updated {page_id} status to '{status}'")

    def update_property(self, page_id: str, property_name: str,
                        value: str, prop_type: str = "rich_text"):
        """Update a text or URL property on a task."""
        if prop_type == "url":
            prop_value = {"url": value}
        elif prop_type == "date":
            prop_value = {"date": {"start": value}}
        else:
            prop_value = {
                "rich_text": [{"text": {"content": value}}]
            }
        self.client.patch(
            f"/pages/{page_id}",
            json={"properties": {property_name: prop_value}},
        ).raise_for_status()

    def append_log(self, page_id: str, message: str):
        """Append a timestamped log entry to the page body."""
        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
        self.client.patch(
            f"/blocks/{page_id}/children",
            json={
                "children": [
                    {
                        "object": "block",
                        "type": "paragraph",
                        "paragraph": {
                            "rich_text": [
                                {
                                    "type": "text",
                                    "text": {
                                        "content": f"[{timestamp}] {message}"
                                    },
                                }
                            ]
                        },
                    }
                ]
            },
        ).raise_for_status()

    @staticmethod
    def _get_select(props: dict, name: str) -> str:
        sel = props.get(name, {}).get("select")
        return sel["name"] if sel else ""


# ─── Claude Code Runner ─────────────────────────────────────────

class ClaudeCodeRunner:
    def __init__(self, project_dir: str):
        self.project_dir = project_dir

    def run_command(self, prompt: str, timeout: int = 600) -> tuple[bool, str]:
        """
        Run Claude Code in non-interactive mode with a prompt.
        Returns (success: bool, output: str).
        """
        cmd = [
            "claude",
            "--print",       # non-interactive, print output
            "--dangerously-skip-permissions",
            prompt,
        ]
        logger.info(f"Running Claude Code: {prompt[:80]}...")
        try:
            result = subprocess.run(
                cmd,
                cwd=self.project_dir,
                capture_output=True,
                text=True,
                timeout=timeout,
            )
            output = result.stdout + result.stderr
            success = result.returncode == 0
            if not success:
                logger.error(f"Claude Code failed: {output[-500:]}")
            return success, output
        except subprocess.TimeoutExpired:
            logger.error(f"Claude Code timed out after {timeout}s")
            return False, "Process timed out"
        except Exception as e:
            logger.error(f"Claude Code error: {e}")
            return False, str(e)


# ─── Pipeline Orchestrator ───────────────────────────────────────

class PipelineOrchestrator:
    def __init__(self):
        self.notion = NotionClient(NOTION_API_KEY)
        self.claude = ClaudeCodeRunner(PROJECT_DIR)

    def process_task(self, task: NotionTask) -> bool:
        """Process a single task through the full pipeline."""
        logger.info(f"Processing task: {task.title} ({task.task_type})")

        # Stage 1: Set up branch
        self.notion.update_status(task.page_id, "In Progress")
        self.notion.append_log(task.page_id, "Pipeline started")

        branch = task.safe_branch_name
        subprocess.run(
            ["git", "checkout", "-b", branch],
            cwd=PROJECT_DIR, check=True,
        )
        self.notion.update_property(
            task.page_id, "Branch Name", branch
        )

        # Stage 2: Generate code
        work_prompt = (
            f"Read the following task and implement it:\n"
            f"Title: {task.title}\n"
            f"Type: {task.task_type}\n"
            f"Priority: {task.priority}\n"
            f"Write the code, write tests, and make sure tests pass."
        )
        success, output = self.claude.run_command(work_prompt, timeout=900)
        if not success:
            self._handle_failure(task, "Code generation failed", output)
            return False

        self.notion.append_log(task.page_id, "Code generation complete")

        # Stage 3: Commit, push, create PR
        subprocess.run(
            ["git", "add", "-A"], cwd=PROJECT_DIR, check=True,
        )
        subprocess.run(
            ["git", "commit", "-m", f"feat: {task.title}"],
            cwd=PROJECT_DIR, check=True,
        )
        subprocess.run(
            ["git", "push", "-u", "origin", branch],
            cwd=PROJECT_DIR, check=True,
        )

        pr_result = subprocess.run(
            ["gh", "pr", "create",
             "--title", f"feat: {task.title}",
             "--body", f"Automated PR for: {task.title}"],
            cwd=PROJECT_DIR, capture_output=True, text=True,
        )
        if pr_result.returncode == 0:
            pr_url = pr_result.stdout.strip()
            self.notion.update_property(
                task.page_id, "PR URL", pr_url, prop_type="url"
            )
            self.notion.update_status(task.page_id, "In Review")
            self.notion.append_log(
                task.page_id, f"PR created: {pr_url}"
            )
            logger.info(f"PR created: {pr_url}")
        else:
            self._handle_failure(
                task, "PR creation failed", pr_result.stderr
            )
            return False

        # Return to main branch
        subprocess.run(
            ["git", "checkout", "main"], cwd=PROJECT_DIR, check=True,
        )
        return True

    def _handle_failure(self, task: NotionTask, stage: str, error: str):
        """Handle a pipeline failure by logging to Notion."""
        logger.error(f"Task '{task.title}' failed at: {stage}")
        self.notion.append_log(
            task.page_id, f"FAILED at {stage}: {error[:300]}"
        )
        # Return to main branch on failure
        subprocess.run(
            ["git", "checkout", "main"],
            cwd=PROJECT_DIR, capture_output=True,
        )

    def run_once(self):
        """Process all available 'To Do' tasks once."""
        tasks = self.notion.query_tasks("To Do")
        logger.info(f"Found {len(tasks)} tasks to process")

        for task in tasks:
            for attempt in range(1, MAX_RETRIES + 1):
                logger.info(
                    f"Attempt {attempt}/{MAX_RETRIES} for: {task.title}"
                )
                if self.process_task(task):
                    break
                if attempt < MAX_RETRIES:
                    logger.info("Retrying in 30 seconds...")
                    time.sleep(30)
            else:
                logger.error(
                    f"Task '{task.title}' failed after {MAX_RETRIES} attempts"
                )
                self.notion.update_status(task.page_id, "To Do")
                self.notion.append_log(
                    task.page_id,
                    f"Pipeline failed after {MAX_RETRIES} attempts. "
                    "Returning to To Do for manual review.",
                )

    def watch(self, interval: int = POLL_INTERVAL):
        """Continuously poll for new tasks."""
        logger.info(
            f"Watching for tasks every {interval} seconds. Ctrl+C to stop."
        )
        while True:
            try:
                self.run_once()
            except Exception as e:
                logger.error(f"Watch cycle error: {e}")
            time.sleep(interval)


# ─── Entry Point ─────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(
        description="Claude Code + Notion Workflow Orchestrator"
    )
    parser.add_argument(
        "--once", action="store_true",
        help="Process available tasks once and exit",
    )
    parser.add_argument(
        "--watch", action="store_true",
        help="Continuously poll for new tasks",
    )
    parser.add_argument(
        "--interval", type=int, default=POLL_INTERVAL,
        help=f"Polling interval in seconds (default: {POLL_INTERVAL})",
    )
    args = parser.parse_args()

    orchestrator = PipelineOrchestrator()

    if args.watch:
        orchestrator.watch(args.interval)
    else:
        orchestrator.run_once()


if __name__ == "__main__":
    main()

To run the orchestrator:

# Process all current "To Do" tasks once
python workflow_orchestrator.py --once

# Watch continuously, polling every 5 minutes
python workflow_orchestrator.py --watch

# Watch with a custom interval (10 minutes)
python workflow_orchestrator.py --watch --interval 600

For running the orchestrator on a schedule without the watch mode, you can use a cron job:

# Edit your crontab
crontab -e

# Add this line to run every 10 minutes
*/10 * * * * cd /path/to/your/project && /usr/bin/python3 workflow_orchestrator.py --once >> /var/log/orchestrator-cron.log 2>&1

Advanced Workflows

The five-stage pipeline covers standard feature development, but real teams need more. Here are specialized workflows for common scenarios.

Bug Fix Pipeline

Bug fixes follow a different pattern from features — they start with reproduction, then diagnosis, then fix, then regression testing. Create .claude/commands/fix-bug.md:

# Fix Bug from Notion

You are a senior debugger. A bug has been reported in Notion.
Your job is to reproduce it, find the root cause, fix it,
and write a regression test.

## Steps

1. **Read the bug report:**
   - Query Notion for the task (from $ARGUMENTS or current branch)
   - Extract: steps to reproduce, expected behavior, actual behavior,
     environment details, stack traces, and screenshots described

2. **Reproduce the issue:**
   - Write a failing test that demonstrates the bug
   - Run the test to confirm it fails with the expected error
   - If reproduction fails, add notes to Notion and ask for clarification

3. **Diagnose the root cause:**
   - Trace the code path from the reproduction test
   - Identify the exact line(s) causing the issue
   - Document the root cause in Notion

4. **Implement the fix:**
   - Make the minimal change needed to fix the bug
   - Avoid refactoring unrelated code in a bug fix branch
   - Ensure the failing test now passes

5. **Write regression tests:**
   - Add edge case tests around the fixed code
   - Ensure the full test suite passes

6. **Update Notion:**
   - Add root cause analysis to the task
   - Add the fix description
   - Log: "Bug fixed and regression test added at [timestamp]"

7. **Suggest running /submit-task to create the PR**

Documentation Pipeline

For teams that want to generate comprehensive documentation from code, create .claude/commands/generate-docs.md:

# Generate Documentation

You are a technical documentation specialist. Generate comprehensive
documentation for the specified module or feature.

## Steps

1. **Identify the target:**
   - If $ARGUMENTS specifies a module, document that module
   - Otherwise, query Notion for tasks tagged "needs docs"

2. **Analyze the codebase:**
   - Read all relevant source files
   - Understand the architecture, data flow, and public API
   - Identify configuration options and environment variables

3. **Generate documentation as a Notion page:**
   - Create a new page in the Docs section of Notion
   - Structure:
     - Overview and purpose
     - Architecture diagram (described in text)
     - API reference with parameters, return types, and examples
     - Configuration guide
     - Troubleshooting FAQ
   - Use Notion's block types: headings, code blocks,
     callouts, tables

4. **Link the documentation:**
   - If created for a specific task, add the Docs Page relation
   - Add to the project's documentation index in Notion

Sprint Planning Pipeline

Claude Code can help break down high-level user stories into actionable tasks. This workflow reads a user story from Notion, analyzes the technical requirements, and creates sub-tasks:

# Sprint Planning Assistant

You are a technical lead helping with sprint planning.

## Steps

1. **Read the user story from Notion:**
   - Query for items tagged as "Epic" or "User Story"
   - Read the full description and acceptance criteria

2. **Analyze technical requirements:**
   - Break down the story into implementation tasks
   - Estimate relative complexity (S/M/L/XL) for each
   - Identify dependencies between tasks
   - Flag any tasks that need clarification

3. **Create sub-tasks in Notion:**
   - For each identified task, create a new page in the database
   - Set properties: Title, Type, Priority, Status = "To Do"
   - Add a relation to the parent story
   - Include acceptance criteria for each sub-task

4. **Present the breakdown:**
   - Display the task tree with estimates
   - Highlight any risks or unknowns
   - Suggest a sprint ordering based on dependencies

Code Review Pipeline

When a PR is created, Claude Code can perform an initial code review and post findings back to Notion:

# Automated Code Review

You are a senior code reviewer.

## Steps

1. **Get the PR to review:**
   - If $ARGUMENTS contains a PR number, use that
   - Otherwise, query Notion for tasks in "In Review" status

2. **Review the code:**
   - Run `gh pr diff <number>` to see the changes
   - Check for:
     - Code quality and readability
     - Potential bugs or edge cases
     - Test coverage
     - Security issues
     - Performance concerns
     - Adherence to project conventions

3. **Post review comments:**
   - Use `gh pr review <number>` to submit review comments
   - Be constructive and specific
   - Suggest improvements with code examples

4. **Update Notion:**
   - Add review summary to the task's Claude Code Log
   - If changes requested, add specific items to address

Real-World Example: Building a Feature End-to-End

Let's walk through a complete example to see how all the pieces fit together. Imagine your product manager creates a new task in the Notion database: "Add user authentication with JWT tokens." The task has these properties:

• Status: To Do
• Priority: High
• Type: Feature
• Description: "Implement user registration and login endpoints with JWT-based authentication. Include password hashing with bcrypt, token refresh mechanism, and role-based access control (admin, user). Protect all existing API endpoints with auth middleware."

Here's what happens when the developer engages the pipeline:

Step 1 — Developer runs /pick-task

Claude Code queries the Notion database and presents the available tasks. The developer selects the authentication task. Claude Code updates the Notion status to "In Progress," creates a new git branch called feature/add-user-authentication-with-jwt-tokens, and writes the branch name back to Notion. The developer sees a confirmation with the full task description.

Step 2 — Developer runs /work-task

Claude Code reads the task requirements from Notion, including the description and acceptance criteria. It analyzes the existing codebase to understand the project's patterns — the framework being used, the database ORM, existing route structures. It then presents an implementation plan:

• Create src/models/user.py — User model with password hashing
• Create src/auth/jwt.py — Token generation and validation
• Create src/auth/middleware.py — Authentication middleware
• Create src/routes/auth.py — Login and register endpoints
• Modify src/routes/__init__.py — Register auth routes
• Create tests/test_auth.py — Comprehensive test suite

After the developer approves the plan, Claude Code writes all the files, runs the tests, finds two failing tests (a missing import and an incorrect assertion), fixes them, and re-runs until everything passes. It updates Notion with a progress note: "Implementation complete. 12 tests passing."

Step 3 — Developer runs /submit-task

Claude Code stages the changes, creates a descriptive commit message, pushes the branch, and opens a PR on GitHub. The PR description includes a summary of changes, the list of new files, test coverage information, and a link back to the Notion task. Claude Code writes the PR URL to the Notion task and changes the status to "In Review."

Step 4 — Developer optionally runs /doc-task

Claude Code generates a documentation page in Notion covering the authentication system: how JWT tokens work in this project, the API endpoints (POST /auth/register, POST /auth/login, POST /auth/refresh), required environment variables (JWT_SECRET, TOKEN_EXPIRY), and troubleshooting tips for common auth errors.

Step 5 — After PR review and merge, developer runs /complete-task

Claude Code verifies the PR is merged, updates the Notion status to "Done," sets the completion timestamp, deletes the feature branch (local and remote), and generates a changelog entry in Notion. The task has traveled from "To Do" to "Done" with minimal manual overhead.

Notion Database Templates

Setting up the right Notion databases from the start saves you headaches later. Here are the essential templates and their API payloads for programmatic creation.

Sprint Board Template

The core task board with columns optimized for the Claude Code pipeline:

To create this database programmatically via the Notion API:

# API payload to create the sprint board database
{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Sprint Board" } }],
  "properties": {
    "Title": { "title": {} },
    "Status": {
      "select": {
        "options": [
          { "name": "Backlog", "color": "default" },
          { "name": "To Do", "color": "blue" },
          { "name": "In Progress", "color": "yellow" },
          { "name": "In Review", "color": "orange" },
          { "name": "Done", "color": "green" }
        ]
      }
    },
    "Priority": {
      "select": {
        "options": [
          { "name": "Critical", "color": "red" },
          { "name": "High", "color": "orange" },
          { "name": "Medium", "color": "yellow" },
          { "name": "Low", "color": "gray" }
        ]
      }
    },
    "Type": {
      "select": {
        "options": [
          { "name": "Feature", "color": "green" },
          { "name": "Bug", "color": "red" },
          { "name": "Refactor", "color": "purple" },
          { "name": "Docs", "color": "blue" }
        ]
      }
    },
    "Branch Name": { "rich_text": {} },
    "PR URL": { "url": {} },
    "Completed At": { "date": {} },
    "Claude Code Log": { "rich_text": {} }
  }
}

Bug Tracker Template

A specialized database for bug reports with fields that feed directly into the /fix-bug command:

{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Bug Tracker" } }],
  "properties": {
    "Bug Title": { "title": {} },
    "Severity": {
      "select": {
        "options": [
          { "name": "P0 - Critical", "color": "red" },
          { "name": "P1 - High", "color": "orange" },
          { "name": "P2 - Medium", "color": "yellow" },
          { "name": "P3 - Low", "color": "gray" }
        ]
      }
    },
    "Status": {
      "select": {
        "options": [
          { "name": "Reported", "color": "red" },
          { "name": "Investigating", "color": "yellow" },
          { "name": "Fix In Progress", "color": "orange" },
          { "name": "Fixed", "color": "green" },
          { "name": "Won't Fix", "color": "gray" }
        ]
      }
    },
    "Steps to Reproduce": { "rich_text": {} },
    "Expected Behavior": { "rich_text": {} },
    "Actual Behavior": { "rich_text": {} },
    "Root Cause": { "rich_text": {} },
    "Fix PR": { "url": {} },
    "Reported By": { "people": {} },
    "Environment": { "rich_text": {} }
  }
}

Documentation Wiki Template

A database for auto-generated documentation, linked to your sprint board tasks:

{
  "parent": { "type": "page_id", "page_id": "YOUR_PARENT_PAGE_ID" },
  "title": [{ "type": "text", "text": { "content": "Documentation Wiki" } }],
  "properties": {
    "Doc Title": { "title": {} },
    "Category": {
      "select": {
        "options": [
          { "name": "API Reference", "color": "blue" },
          { "name": "Architecture", "color": "purple" },
          { "name": "Setup Guide", "color": "green" },
          { "name": "Runbook", "color": "orange" },
          { "name": "Changelog", "color": "gray" }
        ]
      }
    },
    "Related Task": {
      "relation": {
        "database_id": "YOUR_SPRINT_BOARD_DATABASE_ID"
      }
    },
    "Last Updated": { "date": {} },
    "Generated By": {
      "select": {
        "options": [
          { "name": "Claude Code", "color": "blue" },
          { "name": "Manual", "color": "gray" }
        ]
      }
    }
  }
}

Error Handling and Monitoring

Any automated system needs robust error handling. Here's how to make your pipeline resilient.

When Claude Code Fails

Claude Code can fail for several reasons: ambiguous requirements, missing dependencies, test environment issues, or API rate limits. The orchestrator handles this with a retry mechanism (up to 3 attempts), but you should also build fallback behavior:

# In your orchestrator, add a failure handler:

def _handle_failure(self, task, stage, error):
    """Handle pipeline failure with escalation."""
    self.notion.append_log(
        task.page_id,
        f"FAILED at {stage}: {error[:300]}"
    )

    # After max retries, reset status and flag for human attention
    self.notion.update_status(task.page_id, "To Do")
    self.notion.update_property(
        task.page_id, "Priority", "Critical",
        prop_type="select"
    )

    # Send notification (Slack webhook example)
    if os.environ.get("SLACK_WEBHOOK_URL"):
        httpx.post(
            os.environ["SLACK_WEBHOOK_URL"],
            json={
                "text": f":warning: Pipeline failed for: {task.title}\n"
                        f"Stage: {stage}\nError: {error[:200]}"
            },
        )

Logging All Interactions to Notion

Every Claude Code interaction should be logged to the task's page in Notion. This creates an audit trail that helps with debugging and gives visibility to the whole team. The append_log method in the orchestrator handles this — it adds timestamped entries as paragraph blocks on the task page. For richer logs, you can append code blocks with Claude Code's full output:

def append_code_log(self, page_id: str, title: str, content: str):
    """Append a code block log entry to the Notion page."""
    self.client.patch(
        f"/blocks/{page_id}/children",
        json={
            "children": [
                {
                    "object": "block",
                    "type": "heading_3",
                    "heading_3": {
                        "rich_text": [{"type": "text",
                                       "text": {"content": title}}]
                    },
                },
                {
                    "object": "block",
                    "type": "code",
                    "code": {
                        "rich_text": [{"type": "text",
                                       "text": {"content": content[:2000]}}],
                        "language": "plain text",
                    },
                },
            ]
        },
    ).raise_for_status()

Rate Limiting Notion API Calls

Notion's API has a rate limit of 3 requests per second for integrations. When processing multiple tasks or making many updates, you can hit this limit. Add simple rate limiting to your client:

import time
from threading import Lock

class RateLimiter:
    def __init__(self, max_per_second: float = 2.5):
        self.min_interval = 1.0 / max_per_second
        self.last_call = 0.0
        self.lock = Lock()

    def wait(self):
        with self.lock:
            now = time.monotonic()
            elapsed = now - self.last_call
            if elapsed < self.min_interval:
                time.sleep(self.min_interval - elapsed)
            self.last_call = time.monotonic()

Handling Concurrent Tasks

If multiple developers (or orchestrator instances) try to pick the same task simultaneously, you'll get conflicts. Use Notion's status field as an optimistic lock: before starting work on a task, check that its status is still "To Do." If it has changed, skip it and move to the next one. In the orchestrator, this looks like re-querying the task status before processing:

def process_task(self, task):
    # Re-check status to avoid race conditions
    current = self.notion.get_task(task.page_id)
    if current.status != "To Do":
        logger.info(f"Task '{task.title}' already claimed, skipping")
        return True  # Not a failure, just skip
    # ... proceed with processing

Security Considerations

Automating code generation introduces security considerations that you need to address before deploying this pipeline in a production environment.

Store API keys securely. Never hardcode the Notion API key, GitHub tokens, or any other credentials in your code or configuration files. Use environment variables loaded from a .env file that's excluded from version control via .gitignore. For production orchestrator deployments, use a secrets manager like AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's secret storage.

Apply least-privilege permissions. Your Notion integration should only have access to the specific databases it needs — not your entire workspace. When creating the integration at notion.so/my-integrations, select only the capabilities required (read, update, insert) and share only the relevant databases with the integration.

Never skip human code review. This is non-negotiable. No matter how good Claude Code is at generating code, every PR should be reviewed by a human before merging. The pipeline is designed to create PRs and set the status to "In Review" — there's a deliberate human checkpoint before code reaches production. The /complete-task command should only be run after a human has reviewed and merged the PR.

Audit the generated code. Set up automated security scanning in your CI/CD pipeline. Tools like Bandit (Python), ESLint security plugins (JavaScript), or Semgrep can catch common security issues in generated code before it reaches review. This adds a safety net that catches issues like SQL injection, hardcoded secrets, or insecure cryptographic practices.

Limit the orchestrator's blast radius. If running the orchestrator in automated mode, consider sandboxing it in a container or VM with limited network access. It should only be able to reach the Notion API, your git remote, and the local filesystem. This prevents any accidentally generated malicious code from accessing sensitive internal systems.

Comparison with Alternative Stacks

How does the Claude Code + Notion pipeline compare to other popular development automation stacks? This comparison is based on real-world experience and community feedback as of early 2026.

The fundamental differentiator for Claude Code is its agentic nature. While Copilot and Cursor are reactive — they respond when you're typing in an editor — Claude Code is proactive. You give it a task, and it executes autonomously across files, commands, and external services. This is what makes the pipeline architecture possible. You can't build a "task goes in, PR comes out" pipeline with a code autocompleter.

Tips for Success

After building and iterating on this pipeline, here are the lessons that will save you the most time and headaches.

Start small. Don't try to automate everything on day one. Begin with the /pick-task and /submit-task commands to prove the Notion integration works. Add /work-task once you're comfortable with the MCP connection. Graduate to the full orchestrator only after the individual commands are reliable. Each stage builds confidence in the next.

Always keep a human in the review loop. I cannot stress this enough. Claude Code generates excellent code, but it doesn't have the business context to know if a feature is solving the right problem. Use the pipeline to eliminate grunt work, not to eliminate human judgment. The "In Review" status exists for a reason.

Keep CLAUDE.md updated. Your CLAUDE.md file is the single most impactful lever for code quality. Every time your project's conventions, tech stack, or architecture changes, update CLAUDE.md. Think of it as the onboarding document you'd give a senior developer joining the project — because that's essentially what Claude Code is reading before every task.

Write detailed Notion task descriptions. The quality of Claude Code's output is directly proportional to the quality of the input. A task that says "add auth" will produce generic results. A task with acceptance criteria, edge cases, and links to relevant documentation will produce production-ready code. Invest the time upfront in clear task descriptions.

Use Notion's rollup and formula properties for metrics. Once your pipeline is running, you can track velocity using Notion's built-in analytics. Create a formula property that calculates the time between "In Progress" and "Done." Use rollups to aggregate tasks per sprint, per developer, or per type. These metrics help you understand how much the pipeline is accelerating your team.

Monitor your API usage. Both the Notion API and Claude Code have rate limits and usage quotas. If you're running the orchestrator in continuous watch mode, keep an eye on API call counts. The rate limiter in the orchestrator script helps, but unexpected spikes (like a database with 50 tasks in "To Do") can still cause issues.

Version control your command files. Your .claude/commands/ directory should be committed to git and treated as part of the project's infrastructure. This ensures every developer on the team has the same pipeline commands, and changes to workflows go through the same PR review process as code changes.

Conclusion

We've built something significant in this guide: a complete automated workflow pipeline that connects Notion's flexible project management to Claude Code's agentic coding capabilities. Let's recap what you now have at your disposal.

Five custom Claude Code commands — /pick-task, /work-task, /submit-task, /doc-task, and /complete-task — that manage the entire task lifecycle from selection to completion. Each command reads from and writes to Notion, creating a bidirectional integration where your project board isn't just a passive display but an active part of the development process.

An MCP-powered Notion connection that gives Claude Code native access to your project database without custom API plumbing. A Python orchestrator script that can run the pipeline autonomously, with retry logic, error handling, and Notion-based logging. Specialized workflows for bug fixes, documentation generation, sprint planning, and code review. And database templates that you can deploy to Notion with a single API call.

The bigger picture here is about the future of software development. We're moving from a world where AI assists with individual code completions to one where AI operates as a team member that can own entire tasks from start to finish. The pipeline we've built is an early example of this paradigm — and it's practical enough to use today.

But I want to leave you with a critical nuance: this pipeline augments human developers, it doesn't replace them. The human remains in the loop for task definition (what to build), code review (is it correct and safe?), and strategic decisions (should we build it at all?). The pipeline eliminates the mechanical overhead of branch creation, status updates, PR formatting, documentation generation, and task bookkeeping. That's the work nobody enjoys and everyone forgets. Automating it doesn't just save time — it saves mental energy for the decisions that actually move the product forward.

If you're ready to start, here's your action plan: install Claude Code, create a Notion integration, set up the MCP configuration, and implement /pick-task as your first command. Run it on a real task. See the Notion status update automatically. Once you experience that "it just works" moment, you'll want to build out the rest of the pipeline. And now you have everything you need to do it.

References

• Claude Code Documentation — Anthropic
• Model Context Protocol (MCP) — Official Specification
• Notion API Documentation — Notion Developers
• Notion MCP Server — GitHub Repository
• Notion API Reference — Databases, Pages, and Blocks
• Claude Code CLI Usage — Non-Interactive Mode
• GitHub CLI (gh) Manual — Pull Request Management
• Developer Time Management Research — Atlassian