Notion Spec To Implementation

---
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

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

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

## Workflow

### 0) If any MCP call fails because Notion MCP is not connected, pause and set it up:
1. Add the Notion MCP:
   - `codex mcp add notion --url https://mcp.notion.com/mcp`
2. Enable remote MCP client:
   - Set `[features].rmcp_client = true` in `config.toml` **or** run `codex --enable rmcp_client`
3. Log in with OAuth:
   - `codex mcp login notion`

After successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.

### 1) Locate and read the spec
- Search first (`Notion:notion-search`); if multiple hits, ask the user which to use.
- Fetch the page (`Notion: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: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:notion-search` → `Notion:notion-fetch` to confirm the data source and required properties). Patterns in `reference/task-creation.md` ([source](https://raw.githubusercontent.com/openai/skills/main/skills/.curated/notion-spec-to-implementation/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: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:notion-update-page`.

### 5) Track progress
- Use the cadence in `reference/progress-tracking.md` ([source](https://raw.githubusercontent.com/openai/skills/main/skills/.curated/notion-spec-to-implementation/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`).


---

## Companion Files

The following reference files are included for convenience:

### reference/quick-implementation-plan.md

# Quick Implementation Plan Template

For simpler features or small changes.

```markdown
# Implementation: [Feature Name]

## Spec
<mention-page url="...">Specification</mention-page>

## Summary
[Quick description]

## Tasks
- [ ] <mention-page url="...">Task 1</mention-page>
- [ ] <mention-page url="...">Task 2</mention-page>
- [ ] <mention-page url="...">Task 3</mention-page>

## Timeline
Start: [Date]
Target completion: [Date]

## Status
[Update as work progresses]
```

### reference/standard-implementation-plan.md

# Standard Implementation Plan Template

Use this template for most feature implementations.

```markdown
# Implementation Plan: [Feature Name]

## Overview
[1-2 sentence feature description and business value]

## Linked Specification
<mention-page url="...">Original Specification</mention-page>

## Requirements Summary

### Functional Requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

### Non-Functional Requirements
- **Performance**: [Targets]
- **Security**: [Requirements]
- **Scalability**: [Needs]

### Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Technical Approach

### Architecture
[High-level architectural decisions]

### Technology Stack
- Backend: [Technologies]
- Frontend: [Technologies]
- Infrastructure: [Technologies]

### Key Design Decisions
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Implementation Phases

### Phase 1: Foundation (Week 1)
**Goal**: Set up core infrastructure

**Tasks**:
- [ ] <mention-page url="...">Database schema design</mention-page>
- [ ] <mention-page url="...">API scaffolding</mention-page>
- [ ] <mention-page url="...">Authentication setup</mention-page>

**Deliverables**: Working API skeleton
**Estimated effort**: 3 days

### Phase 2: Core Features (Week 2-3)
**Goal**: Implement main functionality

**Tasks**:
- [ ] <mention-page url="...">Feature A implementation</mention-page>
- [ ] <mention-page url="...">Feature B implementation</mention-page>

**Deliverables**: Core features working
**Estimated effort**: 1 week

### Phase 3: Integration & Polish (Week 4)
**Goal**: Complete integration and refinement

**Tasks**:
- [ ] <mention-page url="...">Frontend integration</mention-page>
- [ ] <mention-page url="...">Testing & QA</mention-page>

**Deliverables**: Production-ready feature
**Estimated effort**: 1 week

## Dependencies

### External Dependencies
- [Dependency 1]: [Status]
- [Dependency 2]: [Status]

### Internal Dependencies
- [Team/component dependency]

### Blockers
- [Known blocker] or None currently

## Risks & Mitigation

### Risk 1: [Description]
- **Probability**: High/Medium/Low
- **Impact**: High/Medium/Low
- **Mitigation**: [Strategy]

### Risk 2: [Description]
- **Probability**: High/Medium/Low
- **Impact**: High/Medium/Low
- **Mitigation**: [Strategy]

## Timeline

| Milestone | Target Date | Status |
|-----------|-------------|--------|
| Phase 1 Complete | [Date] | ⏳ Planned |
| Phase 2 Complete | [Date] | ⏳ Planned |
| Phase 3 Complete | [Date] | ⏳ Planned |
| Launch | [Date] | ⏳ Planned |

## Success Criteria

### Technical Success
- [ ] All acceptance criteria met
- [ ] Performance targets achieved
- [ ] Security requirements satisfied
- [ ] Test coverage > 80%

### Business Success
- [ ] [Business metric 1]
- [ ] [Business metric 2]

## Resources

### Documentation
- <mention-page url="...">Design Doc</mention-page>
- <mention-page url="...">API Spec</mention-page>

### Related Work
- <mention-page url="...">Related Feature</mention-page>

## Progress Tracking

[This section updated regularly]

### Phase Status
- Phase 1: ⏳ Not Started
- Phase 2: ⏳ Not Started
- Phase 3: ⏳ Not Started

**Overall Progress**: 0% complete

### Latest Update: [Date]
[Brief status update]
```

### reference/task-creation-template.md

# Task Creation Template

When creating tasks from spec.

```markdown
# [Task Name]

## Context
Part of implementation for <mention-page url="...">Feature Spec</mention-page>

Implementation plan: <mention-page url="...">Implementation Plan</mention-page>

## Description
[What needs to be done]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Technical Details
[Technical approach or notes]

## Dependencies
- Blocked by: [Task] or None
- Blocks: [Task] or None

## Resources
- [Link to design]
- [Link to related code]

## Progress
[To be updated during implementation]
```

### reference/progress-update-template.md

# Progress Update Template

Use this to update progress on implementation plans and tasks.

```markdown
## Progress: [Date]

### Completed Today
- [Specific item completed]
- [Specific item completed]

### In Progress
- [Current work item and status]

### Next Steps
1. [Next action]
2. [Next action]

### Blockers
- [Blocker description] or None

### Notes
[Additional context, decisions made, issues encountered]
```

### reference/milestone-summary-template.md

# Milestone Summary Template

Use this when completing major phases or milestones.

```markdown
## Phase [N] Complete: [Date]

### Accomplishments
- [Major item delivered]
- [Major item delivered]

### Deliverables
- <mention-page url="...">Deliverable 1</mention-page>
- [Link to PR/deployment]

### Metrics
- [Relevant metric]
- [Relevant metric]

### Learnings
- [What went well]
- [What to improve]

### Next Phase
Starting [Phase name] on [Date]
```