Notion Workspace Manager

Notion Workspace Manager

Role

You are responsible for the shape and discoverability of a solution's Notion workspace. You do not author the content of architecture, specs, or sprint plans — those come from the architect, spec-author, and sprint-planner skills. You guarantee that:

• Every solution has a predictable top-level layout so collaborators know where things live.
• New workspaces start with the right scaffolding (and a link to the Linear/JIRA project so tracker integration is discoverable).
• Mature workspaces don't drift indefinitely — they are periodically audited against the canon and re-aligned with explicit user approval.

This is the Notion-tracker-neutral parallel of confluence-space-manager. The canonical structure is identical and is the authoritative source in skills/confluence-space-manager/references/canonical-space-structure.md — read it before any mode runs. This skill only differs in realisation (Notion pages + databases instead of Confluence pages) and in one design choice below.

The page-tree + database hybrid (the Notion-specific decision)

Confluence is page-only; Notion has databases. The default realisation:

Page-tree-only mode (Confluence-faithful, no databases) is available on request, but the hybrid is the default because the queryable surfaces (Specs, Releases, Impl Logs) are where Notion beats a flat tree.

Operating Modes

Default to Audit if ambiguous — auditing is read-only and never destructive.

Inputs

• Root page id — the Notion page the structure is created under. Notion has no

"space key"; the unit is a page id. For Create, may be omitted → a workspace-level home page is created first (proven: notion-create-pages with no parent).

• Repo root — to discover steering docs, releases, and specs that should seed the structure.
• Tracker project URL — Linear project (or JIRA) to link from the Overview page.
• Solution scope (optional: solution, pipeline, agent, ui, bie, research-bid) — toggles optional sections.

Outputs

Canonical Structure (Notion realisation)

{Root home page}                          ← repo overview, tracker link, cross-links
├── 01 Overview          (page)
├── 02 Steering          (page)           ← mirror of documentation/steering/
├── 03 Releases          (database)       ← one row per release
├── 04 Architecture      (page)
├── 05 Specs             (database)       ← one row per feature spec; links to Linear epic
├── 06 Sprints           (page)
├── 07 Reviews           (page)
├── 08 Ontology          (page)
├── 09 References         (page)          ← external docs, glossary, audit reports
├── 99 WIP               (page)
└── Impl Logs            (database)       ← linear-impl-logger mirror target (optional)

Numeric prefixes keep sidebar order stable and are part of the canonical title.

Workflow — Create Mode

Step 1 — Detect existing state

• If a root page id is given, notion-fetch it and read its children. If it already

has content, only add missing canonical sections — never overwrite user content.

• If no root page id, notion-search for an existing home by name. If none, create a

workspace-level home page (notion-create-pages with no parent — proven to land at workspace root). Note: the MCP cannot create teamspaces; if the user wants the home inside a specific teamspace, ask them to provide its page id.

• Read repo documentation/steering/, documentation/releases/, documentation/specs/ to seed sections.

Step 2 — Confirm plan with user

Show a preview tree (sections + which are pages vs databases, seeded from repo metadata). Ask for approval. The user may opt out of any section or switch to page-tree-only. Gate: create nothing until approved.

Step 3 — Create sections (proven sequence)

In order (01 → 99). Use the live-proven sequence: 1. Create/confirm the root home page (notion-create-pages, properties.title, icon, body with tracker + repo links). 2. Batch-create the page sections as children: one notion-create-pages call with parent: {type:"page_id", page_id: <root>} and the page list (01 Overview, 02 Steering, 04 Architecture, 06 Sprints, 07 Reviews, 08 Ontology, 09 References, 99 WIP), each with a short purpose body. 3. Create the databases (notion-create-database, parent: {page_id}) for 03 Releases, 05 Specs, and (optional) Impl Logs, using the schemas in references/notion-mapping.md. Capture each data_source_id. 4. Body content is Notion-flavored Markdown. For anything beyond headings/lists/links, read the MCP resource notion://docs/enhanced-markdown-spec first — do not guess block syntax.

Step 4 — Wire tracker integration

Notion has no MCP equivalent of Confluence's project-linker macro, and Notion↔Linear sync is configured in-app. So instead: put the tracker project URL on the Overview page, and (for the Specs/Releases databases) include a "Linear Epic" URL column so each row links to its tracker item. Note in the return that native two-way sync must be enabled in the Notion UI if wanted.

Step 5 — Persist mapping

Write/update documentation/workflow-config.md with: notion.rootPageId, notion.sections.{...} page ids, and notion.dataSources.{specs, releases, implLogs}. This is what product-vision-steering, release-planner, feature-spec-author, and linear-impl-logger use as the parent/target for their publications.

Step 6 — Return

Report: home page URL, created sections (with ids), databases (with data-source ids), warnings about pre-existing content not modified, and the workflow-config path.

Workflow — Audit Mode

1. notion-fetch the root page and walk its children (and notion-search within it). 2. Compare against the canon (the same checklist as confluence-space-manager/references/audit-checklist.md). Classify each section: ✅ present / ⚠ misnamed / ⚠ misplaced / ❌ missing / ➕ extra, plus a recommended action (rename/move/create/archive/accept). For database sections, also check the schema has the expected columns. 3. Compute the coverage score present / (present + missing + misnamed + misplaced) (informative only). 4. Write the report to documentation/notion/{root}-audit-{YYYY-MM-DD}.md and a Notion page under "09 References". Present recommendations as a checklist for the user to approve. Audit never modifies the workspace.

Workflow — Align Mode

Load approved actions, then apply in safe order to minimise broken links: 1. Create missing sections/databases (so children have a move target). 2. Rename misnamed pages (notion-update-page title) / databases. 3. Move misplaced pages (notion-move-pages). 4. Archive approved removals (Notion: move to trash / set archived — do not hard-delete; audit trail matters).

After each op, append to the audit report's Changelog with the page/db id and a timestamp. Re-audit silently and confirm the coverage score improved; surface any failed action with its error. Report changes applied (count by type), new score, and report URL.

Boundaries — What This Skill Does NOT Do

• Does not author content for steering / specs / architecture — those skills publish under the sections this skill provisions.
• Does not create tracker items — that's release-planner / linear-backlog-manager / backlog-manager.
• Does not create teamspaces — the MCP cannot; this skill scaffolds within a page the user controls.
• Does not delete content — archive is the strongest action, only when explicitly approved.
• Does not enforce prose quality inside pages — it enforces structure, not content.

References

• skills/confluence-space-manager/SKILL.md — the Confluence original; identical role, modes, and canonical structure.
• skills/confluence-space-manager/references/canonical-space-structure.md · audit-checklist.md · naming-conventions.md — the platform-neutral canon (authoritative; reused, not duplicated).
• references/notion-mapping.md — Confluence→Notion concept + MCP call mapping, the database schemas, the proven scaffold sequence, and Notion constraints.
• Notion MCP: notion-create-pages, notion-create-database, notion-update-page, notion-move-pages, notion-fetch, notion-search, notion-get-teams.
• Companion skills: product-vision-steering (Phase 0), release-planner (Phase 0.5), feature-spec-author (Phase 1), linear-impl-logger (Impl Logs mirror).

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the `skill-feedback` skill to report it?" If the user declines, continue without feedback capture.

Confluence → Notion mapping

How notion-workspace-manager realises the canonical (platform-neutral) space structure on Notion. The canonical structure itself lives in ../../confluence-space-manager/references/canonical-space-structure.md.

Concept & call mapping

Proven constraints (from the live trial, 2026-06-13)

• notion-create-pages with no parent → pages land at workspace root. Use this to create the home page when no root is supplied.
• A database's parent must be a `page_id` (not a data source).
• Creating a page under a database uses parent.data_source_id (the collection://… id), not the database id, when the database has multiple data sources.
• The workspace may be empty (no teamspaces) — that's fine; create the home at root.
• Basic Markdown (headings, lists, links, tables) works directly; for callouts/toggles/columns read the enhanced-markdown spec first.

Database schemas (SQL DDL for notion-create-database)

05 Specs

CREATE TABLE ("Spec" TITLE,
  "Status" SELECT('Draft':yellow, 'Approved':green, 'In Backlog':blue, 'Done':gray),
  "Linear Epic" URL, "Repo Path" URL, "Estimate (pts)" NUMBER, "Owner" RICH_TEXT)

03 Releases

CREATE TABLE ("Release" TITLE,
  "Status" SELECT('Planned':blue, 'In Progress':yellow, 'Shipped':green),
  "Target Date" DATE, "Roadmap" URL, "Theme" RICH_TEXT)

Impl Logs (optional — linear-impl-logger mirror target)

CREATE TABLE ("Task" TITLE, "Linear Issue" URL, "Commit" RICH_TEXT,
  "Files +/-" NUMBER, "Keywords" RICH_TEXT, "Date" DATE)

Proven scaffold sequence (Create mode)

1. Home page (no parent → workspace root, or under a supplied root page id): notion-create-pages([{ properties:{title}, icon, content }]) → capture page id. 2. Page sections (one batch call, same parent = home id): notion-create-pages({ parent:{type:"page_id", page_id:<home>}, pages:[01 Overview, 02 Steering, 04 Architecture, 06 Sprints, 07 Reviews, 08 Ontology, 09 References, 99 WIP] }). 3. Databases under the home (or under their section page): notion-create-database({ parent:{page_id}, title, schema }) for 05 Specs, 03 Releases, Impl Logs → capture each data_source_id. 4. Seed rows (optional): notion-create-pages({ parent:{type:"data_source_id", data_source_id:<ds>}, pages:[{properties:{...}}] }). 5. Persist all ids to documentation/workflow-config.md under notion.*.

Reference instance from the trial: home OL AI Context Library (37e28f42-f4f2-81a8-b090-f7acc417a595), section 05 Specs (37e28f42-f4f2-813d-8be7-e9b1af1f1d3f), Specs database data source collection://35161659-7cce-486b-a01c-7ded3b52c22d.