| 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:
- Create/confirm the root home page (
notion-create-pages, properties.title, icon, body with tracker + repo links).
- 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.
- 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.
- 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
notion-fetch the root page and walk its children (and notion-search within it).- 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.
- Compute the coverage score
present / (present + missing + misnamed + misplaced) (informative only).
- 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:
- Create missing sections/databases (so children have a move target).
- Rename misnamed pages (
notion-update-page title) / databases.
- Move misplaced pages (
notion-move-pages).
- 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.
