---
name: notion-spec-to-implementation
description: Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.
metadata:
  short-description: Turn Notion specs into implementation plans, tasks, and progress tracking
---

# Spec to Implementation

Ported from [`openai/plugins` commit `1dc195897af4161d039b80d8471ec0a10c9bbc89`](https://github.com/openai/plugins/tree/1dc195897af4161d039b80d8471ec0a10c9bbc89/plugins/notion/skills). Notion Labs' MIT notice is in `LICENSE.txt`. Tool names are the hosted Notion MCP names. This host does not use the OpenAI client aliases `search` and `fetch`. `agents/openai.yaml` was not copied. Write tools require an explicit user request and host approval.


Convert a Notion spec into linked implementation plans, tasks, and ongoing status updates.

## Quick start
1) Locate the spec with `notion-search`, then fetch it with `notion-fetch`.
2) Parse requirements and ambiguities using `reference/spec-parsing.md`.
3) Create a plan page with `notion-create-pages` (pick a template: quick vs. full).
4) Find the task database, confirm schema, then create tasks with `notion-create-pages`.
5) Link spec ↔ plan ↔ tasks; keep status current with `notion-update-page`.

## Tool-call guardrails
- Notion tool availability can vary by workspace. If a Notion MCP call returns `Tool <name> not found`, treat that tool as unavailable for the rest of the current task. Do not retry it with different arguments or call it again later; use `notion-search` and `notion-fetch` where sufficient.
- Use one literal search query per `notion-search` call and include `filters: {}` when no narrower filter is needed. Run separate searches for alternate phrasings instead of putting `or` in a single query string.
- Only send Notion page, database, or data-source URLs/IDs to `notion-fetch`; external connected-source search results are not fetch targets.
- Create plans and task pages with explicit `parent` and `pages` fields. For task databases, fetch first and use the returned `collection://...` data source ID.
- To append an implementation section to a spec, fetch the current section text first, then use `notion-update-page` with `command: "update_content"`, `properties: {}`, and exact `old_str` / `new_str` content. For property-only edits, use `command: "update_properties"` with `content_updates: []`; the current deployed schema expects both top-level fields even when one is unused.

## Workflow

### 0) If Notion tools are unavailable, pause and ask the user to connect Notion
1. Open the plugin details and connect Notion through the workspace Connector.
2. Complete Notion authorization if prompted. Never request tokens or passwords in chat.
3. Retry after the connection is ready. An installed plugin does not grant access to pages the connected user cannot see.

After Notion is connected, finish the current answer and tell the user to retry so they can continue with Step 1.

### 1) Locate and read the spec
- Search first (`notion-search`); if multiple hits, ask the user which to use.
- Fetch the page (`notion-fetch`) and scan for requirements, acceptance criteria, constraints, and priorities. See `reference/spec-parsing.md` for extraction patterns.
- Capture gaps/assumptions in a clarifications block before proceeding.

### 2) Choose plan depth
- Simple change → use `reference/quick-implementation-plan.md`.
- Multi-phase feature/migration → use `reference/standard-implementation-plan.md`.
- Create the plan via `notion-create-pages`, include: overview, linked spec, requirements summary, phases, dependencies/risks, and success criteria. Link back to the spec.

### 3) Create tasks
- Find the task database (`notion-search` → `notion-fetch` to confirm the data source and required properties). Patterns in `reference/task-creation.md`.
- Size tasks to 1–2 days. Use `reference/task-creation-template.md` for content (context, objective, acceptance criteria, dependencies, resources).
- Set properties: title/action verb, status, priority, relations to spec + plan, due date/story points/assignee if provided.
- Create pages with `notion-create-pages` using the database’s `data_source_id`.

### 4) Link artifacts
- Plan links to spec; tasks link to both plan and spec.
- Optionally update the spec with a short “Implementation” section pointing to the plan and tasks using `notion-update-page`.

### 5) Track progress
- Use the cadence in `reference/progress-tracking.md`.
- Post updates with `reference/progress-update-template.md`; close phases with `reference/milestone-summary-template.md`.
- Keep checklists and status fields in plan/tasks in sync; note blockers and decisions.

## References and examples
- `reference/` — parsing patterns, plan/task templates, progress cadence (e.g., `spec-parsing.md`, `standard-implementation-plan.md`, `task-creation.md`, `progress-tracking.md`).
- `examples/` — end-to-end walkthroughs (e.g., `ui-component.md`, `api-feature.md`, `database-migration.md`).