notion-workspace-manager

portability	ol-coupled
reuse	ol-platform-only
requires	["notion-mcp"]
name	notion-workspace-manager
description	Bootstrap, audit, and align solution-specific Notion workspaces against the canonical Ontoledgy structure. The Notion parallel of confluence-space-manager, selected when the docs backend is Notion. Operates in three modes: (1) Create — scaffold a solution's page tree (Overview, Steering, Releases, Architecture, Specs, Sprints, Reviews, Ontology, References, WIP) under a root page, using a page-tree + database hybrid; (2) Audit — compare an existing workspace against the canonical structure and produce a gap report; (3) Align — apply approved improvements (rename, move, create, archive). Use when: the docs backend is Notion (not Confluence — use confluence-space-manager for Confluence) and a new solution repo needs a Notion home, an existing workspace has drifted, or a team wants to align workspaces before a release. Reads the repo's documentation/steering/, documentation/releases/, and documentation/specs/ to seed the structure. Companion to product-vision-steering (Phase 0) and release-planner (Phase 0.5) — provides the Notion-side container they publish into.

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:

Section	Notion form	Why
01 Overview, 02 Steering, 04 Architecture, 06 Sprints, 07 Reviews, 08 Ontology, 09 References, 99 WIP	Pages	narrative prose; a page tree reads best
03 Releases	Database (one row per release)	filterable by status/date, links to epics
05 Specs	Database (one row per feature spec)	queryable index; cross-links to the Linear epic
Impl Logs	Database (one row per logged task)	the searchable knowledge base impl-logger mirrors into

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

Mode	Inputs	Output	When
Create	Repo path (with optional documentation/steering/), root page id (or none → workspace-level home), tracker project URL	Canonical pages + databases created under the root + documentation/workflow-config.md updated	New solution repo, new project, demo/POC kickoff
Audit	Root page id	Gap report (Markdown table + a Notion page) listing missing/misplaced/misnamed sections, severity, recommended action	Periodic review, before a release, onboarding
Align	Audit report + user approval per item	Pages/databases renamed, moved, created, or archived; audit report updated	After Audit, when actions are approved

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

Output	Where
Created/updated Notion pages + databases	Under the root page
Gap report (Audit)	documentation/notion/{root}-audit-{YYYY-MM-DD}.md + a Notion page under "09 References"
Alignment changelog (Align)	Appended to the same audit file
Workflow config update	documentation/workflow-config.md — notion root page id, section page ids, data-source ids

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)       ← 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 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), 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.