Spec to Implementation
Ported from openai/plugins commit 1dc195897af4161d039b80d8471ec0a10c9bbc89. 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
- Locate the spec with
notion-search, then fetch it with notion-fetch.
- Parse requirements and ambiguities using
reference/spec-parsing.md.
- Create a plan page with
notion-create-pages (pick a template: quick vs. full).
- Find the task database, confirm schema, then create tasks with
notion-create-pages.
- 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
- Open the plugin details and connect Notion through the workspace Connector.
- Complete Notion authorization if prompted. Never request tokens or passwords in chat.
- 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).
1---2name: notion-spec-to-implementation3description: Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.4metadata:5 source: https://skillmd.com/skills/xpert-ai/notion-spec-to-implementation6 short-description: Turn Notion specs into implementation plans, tasks, and progress tracking7---89# Spec to Implementation1011Ported 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.121314Convert a Notion spec into linked implementation plans, tasks, and ongoing status updates.1516## Quick start171) Locate the spec with `notion-search`, then fetch it with `notion-fetch`.182) Parse requirements and ambiguities using `reference/spec-parsing.md`.193) Create a plan page with `notion-create-pages` (pick a template: quick vs. full).204) Find the task database, confirm schema, then create tasks with `notion-create-pages`.215) Link spec ↔ plan ↔ tasks; keep status current with `notion-update-page`.2223## Tool-call guardrails24- 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.25- 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.26- Only send Notion page, database, or data-source URLs/IDs to `notion-fetch`; external connected-source search results are not fetch targets.27- Create plans and task pages with explicit `parent` and `pages` fields. For task databases, fetch first and use the returned `collection://...` data source ID.28- 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.2930## Workflow3132### 0) If Notion tools are unavailable, pause and ask the user to connect Notion331. Open the plugin details and connect Notion through the workspace Connector.342. Complete Notion authorization if prompted. Never request tokens or passwords in chat.353. Retry after the connection is ready. An installed plugin does not grant access to pages the connected user cannot see.3637After Notion is connected, finish the current answer and tell the user to retry so they can continue with Step 1.3839### 1) Locate and read the spec40- Search first (`notion-search`); if multiple hits, ask the user which to use.41- Fetch the page (`notion-fetch`) and scan for requirements, acceptance criteria, constraints, and priorities. See `reference/spec-parsing.md` for extraction patterns.42- Capture gaps/assumptions in a clarifications block before proceeding.4344### 2) Choose plan depth45- Simple change → use `reference/quick-implementation-plan.md`.46- Multi-phase feature/migration → use `reference/standard-implementation-plan.md`.47- Create the plan via `notion-create-pages`, include: overview, linked spec, requirements summary, phases, dependencies/risks, and success criteria. Link back to the spec.4849### 3) Create tasks50- Find the task database (`notion-search` → `notion-fetch` to confirm the data source and required properties). Patterns in `reference/task-creation.md`.51- Size tasks to 1–2 days. Use `reference/task-creation-template.md` for content (context, objective, acceptance criteria, dependencies, resources).52- Set properties: title/action verb, status, priority, relations to spec + plan, due date/story points/assignee if provided.53- Create pages with `notion-create-pages` using the database’s `data_source_id`.5455### 4) Link artifacts56- Plan links to spec; tasks link to both plan and spec.57- Optionally update the spec with a short “Implementation” section pointing to the plan and tasks using `notion-update-page`.5859### 5) Track progress60- Use the cadence in `reference/progress-tracking.md`.61- Post updates with `reference/progress-update-template.md`; close phases with `reference/milestone-summary-template.md`.62- Keep checklists and status fields in plan/tasks in sync; note blockers and decisions.6364## References and examples65- `reference/` — parsing patterns, plan/task templates, progress cadence (e.g., `spec-parsing.md`, `standard-implementation-plan.md`, `task-creation.md`, `progress-tracking.md`).66- `examples/` — end-to-end walkthroughs (e.g., `ui-component.md`, `api-feature.md`, `database-migration.md`).