@juancr11/sibu 0.10.0 → 0.11.0

package/README.md

@@ -44,7 +44,7 @@ Use `sibu skills stop <file>` to stop managing an Sibu-tracked workflow file. Th
 
 ## MCP server setup
 
-Sibu can generate MCP server configuration for supported agents. The first supported server is GitHub's official MCP server.
+Sibu can generate MCP server configuration for supported agents. Supported MCP servers include GitHub and Notion.
 
 Sibu only writes and tracks MCP config files. Runtime prerequisites, credentials, and provider authentication remain user-owned.
 
@@ -121,15 +121,36 @@ export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
 
 Do not commit tokens or write them into Sibu-managed config files. The generated configs read `GITHUB_PERSONAL_ACCESS_TOKEN` from the environment so credentials can stay outside the repository.
 
-### 4. Stop managing the GitHub MCP server
+### 4. Configure the Notion MCP server
 
-To remove GitHub from Sibu's selected MCP server state, run:
+You can select Notion during `sibu init`, or add it later:
+
+```sh
+sibu mcp use notion
+```
+
+When Notion is selected, Sibu asks for a Notion docs destination parent page URL or page ID. Sibu stores that parent page reference in `.sibu/state.json` so feature-doc export guidance knows where Notion pages should go.
+
+Sibu configures supported agent MCP files for Notion, but it does not manage Notion OAuth login, workspace selection, integration installation, page permissions, credentials, or live connectivity. Your Notion MCP connection must be authenticated separately and must have access to the configured parent page. For provider setup details, use Notion's MCP documentation: <https://developers.notion.com/guides/mcp/get-started-with-mcp>.
+
+Feature briefs, technical designs, and UX docs are still written to local Markdown first. Notion is an optional export destination, not Sibu's source of truth.
+
+For Codex with the hosted Notion MCP server, you may need to run the agent-specific MCP login flow after Sibu writes config, such as:
+
+```sh
+codex mcp login notion
+```
+
+### 5. Stop managing an MCP server
+
+To remove a selected MCP server from Sibu's state, run:
 
 ```sh
 sibu mcp stop github
+sibu mcp stop notion
 ```
 
-Sibu updates generated agent config where possible and asks whether to keep or delete MCP-only config files.
+Sibu updates generated agent config where possible and asks whether to keep or delete MCP-only config files. Stopping Notion only updates local Sibu state and managed MCP config files; it does not delete Notion pages or change Notion permissions.
 
 ## Release notes and changelog
 

package/bin/modules/interactive-guidance/index.js

@@ -1 +1 @@
-export { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, MCP_SERVER_SELECTION_MESSAGE, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';
+export { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForNotionDocsParentPage, askForMissingFrameworkSkills, askForNewArchitectureSkill, askForNewLanguageSkills, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, MCP_SERVER_SELECTION_MESSAGE, renderIntro, shouldAskForNewLanguageSkills, } from './prompts.js';

package/bin/modules/interactive-guidance/prompts.js

@@ -89,6 +89,22 @@ export async function askForMcpServers() {
     }
     return SELECTABLE_MCP_SERVERS.filter((server) => selectedMcpServerIds.includes(server.id));
 }
+export async function askForNotionDocsParentPage() {
+    const parentPage = await text({
+        message: 'Enter the Notion docs destination parent page URL or page ID.',
+        placeholder: 'https://www.notion.so/workspace/Sibu-Docs-...',
+        validate(value) {
+            if (!value?.trim()) {
+                return 'Enter a Notion parent page that your Notion MCP connection can access.';
+            }
+        },
+    });
+    if (isCancel(parentPage)) {
+        cancel('Initialization cancelled.');
+        process.exit(0);
+    }
+    return parentPage.trim();
+}
 async function askForFrameworkSkillSelection({ message, cancelMessage, }) {
     const selectedFrameworkSkillIds = await multiselect({
         message,

package/bin/modules/mcp-server-selection-management/stop-mcp-server/handler.js

@@ -79,6 +79,10 @@ export function stopSelectedMcpServer({ rootPath, state, serverId }) {
     const stoppedPaths = [];
     const stoppedFiles = [];
     nextState.selectedMcpServers = selectionResult.remainingMcpServers.map((server) => server.id);
+    if (serverId === 'notion' && nextState.mcpServerConfigs?.notion) {
+        const { notion: _notion, ...remainingMcpServerConfigs } = nextState.mcpServerConfigs;
+        nextState.mcpServerConfigs = Object.keys(remainingMcpServerConfigs).length > 0 ? remainingMcpServerConfigs : undefined;
+    }
     nextState.templateVersion = manifest.templateVersion;
     nextState.updatedAt = new Date().toISOString();
     for (const previousTarget of previousTargets.filter((target) => target.mcpConfigAgentId)) {

package/bin/modules/mcp-server-selection-management/use-mcp-server/handler.js

@@ -3,9 +3,13 @@ import path from 'node:path';
 import { log } from '@clack/prompts';
 import { STATE_RELATIVE_PATH } from '../../../shared/catalog.js';
 import { getProjectContext } from '../../../shared/paths.js';
+import { askForNotionDocsParentPage } from '../../interactive-guidance/index.js';
 import { getWorkflowMutationReadiness } from '../../workflow-mutation-readiness/index.js';
 import { getSelectedAgentsFromState, getSelectedArchitectureSkillFromState, getSelectedDatabaseSkillsFromState, getSelectedFrameworkSkillsFromState, getSelectedLanguageSkillsFromState, getSelectedMcpServersFromState, getSelectedWorkflowSkillsFromState, getWorkflowTargets, renderMissingWorkflowFiles, resolveSelectableMcpServerById, writeSibuState, } from '../../workflow-target-planning/index.js';
-export async function handleUseMcpServer(command) {
+const defaultDependencies = {
+    askForNotionDocsParentPage,
+};
+export async function handleUseMcpServer(command, dependencies = defaultDependencies) {
     const { rootPath, statePath } = getProjectContext();
     const readiness = getWorkflowMutationReadiness({ rootPath, statePath });
     if (!readiness.ok) {
@@ -30,9 +34,11 @@ export async function handleUseMcpServer(command) {
             }
             process.exitCode = 1;
             return;
-        case 'selected':
-            applySelectedMcpServer({ rootPath, statePath, state: readiness.state, selectionResult });
+        case 'selected': {
+            const mcpServerConfigs = await getNextMcpServerConfigs({ state: readiness.state, selectionResult, dependencies });
+            applySelectedMcpServer({ rootPath, statePath, state: readiness.state, selectionResult, mcpServerConfigs });
             return;
+        }
     }
 }
 export function getNextMcpSelection(state, serverId) {
@@ -50,7 +56,17 @@ export function getNextMcpSelection(state, serverId) {
         selectedMcpServers: [...selectedMcpServerIds, resolution.resolved.server.id].map(getMcpServerById),
     };
 }
-function applySelectedMcpServer({ rootPath, statePath, state, selectionResult, }) {
+async function getNextMcpServerConfigs({ state, selectionResult, dependencies, }) {
+    if (!selectionResult.selectedMcpServers.some((server) => server.id === 'notion') || state.selectedMcpServers?.includes('notion')) {
+        return state.mcpServerConfigs;
+    }
+    const docsParentPage = await dependencies.askForNotionDocsParentPage();
+    return {
+        ...state.mcpServerConfigs,
+        notion: { docsParentPage },
+    };
+}
+function applySelectedMcpServer({ rootPath, statePath, state, selectionResult, mcpServerConfigs, }) {
     const selectedAgents = getSelectedAgentsFromState(state);
     const selectedLanguageSkills = getSelectedLanguageSkillsFromState(state);
     const selectedFrameworkSkills = getSelectedFrameworkSkillsFromState(state);
@@ -92,6 +108,7 @@ function applySelectedMcpServer({ rootPath, statePath, state, selectionResult, }
         selectedWorkflowSkills,
         selectedDatabaseSkills,
         selectedMcpServers: selectionResult.selectedMcpServers,
+        mcpServerConfigs,
         targets,
     });
     log.success(`Updated ${STATE_RELATIVE_PATH}`);

package/bin/modules/project-adoption/handler.js

@@ -4,13 +4,14 @@ import { intro, log, outro } from '@clack/prompts';
 import chalk from 'chalk';
 import { STATE_RELATIVE_PATH } from '../../shared/catalog.js';
 import { getProjectContext } from '../../shared/paths.js';
-import { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, renderIntro, } from '../interactive-guidance/index.js';
+import { askForArchitectureSkill, askForDatabaseSkills, askForFrameworkSkills, askForLanguageSkills, askForMcpServers, askForNotionDocsParentPage, askForProjectOverview, askForSupportedAgents, askForWorkflowSkills, renderIntro, } from '../interactive-guidance/index.js';
 import { readStateForDoctor } from '../workflow-state-registry/index.js';
 import { getWorkflowTargets, renderMissingWorkflowFiles, writeSibuState } from '../workflow-target-planning/index.js';
 const defaultDependencies = {
     renderIntro,
     askForSupportedAgents,
     askForMcpServers,
+    askForNotionDocsParentPage,
     askForLanguageSkills,
     askForFrameworkSkills,
     askForDatabaseSkills,
@@ -40,6 +41,7 @@ export async function handleInitProject(_command, dependencies = defaultDependen
     }
     const selectedAgents = await dependencies.askForSupportedAgents();
     const selectedMcpServers = await dependencies.askForMcpServers();
+    const notionDocsParentPage = selectedMcpServers.some((server) => server.id === 'notion') ? await dependencies.askForNotionDocsParentPage() : undefined;
     const selectedLanguageSkills = await dependencies.askForLanguageSkills();
     const selectedFrameworkSkills = await dependencies.askForFrameworkSkills();
     const selectedDatabaseSkills = await dependencies.askForDatabaseSkills();
@@ -84,6 +86,7 @@ export async function handleInitProject(_command, dependencies = defaultDependen
         selectedWorkflowSkills,
         selectedDatabaseSkills,
         selectedMcpServers,
+        mcpServerConfigs: notionDocsParentPage ? { notion: { docsParentPage: notionDocsParentPage } } : undefined,
         targets,
     });
     log.success(`Created ${STATE_RELATIVE_PATH}`);

package/bin/modules/template-catalog-rendering/templates.js

@@ -39,16 +39,13 @@ export function renderSkillRouting(contents, selectedLanguageSkills, selectedFra
     return contents.replace('{{OPTIONAL_SKILL_ROUTING}}', optionalRouting);
 }
 export function renderMcpConfig({ agentId, baseContents, selectedMcpServers, }) {
-    const githubServer = selectedMcpServers.find((server) => server.id === 'github');
-    if (!githubServer) {
+    if (selectedMcpServers.length === 0) {
         return baseContents ?? renderJsonMcpConfig({});
     }
     if (agentId === 'codex') {
-        return renderCodexGithubMcpConfig(baseContents ?? '');
+        return renderCodexMcpConfig(baseContents ?? '', selectedMcpServers);
     }
-    return renderJsonMcpConfig({
-        github: buildGithubMcpServerConfig(agentId),
-    });
+    return renderJsonMcpConfig(buildJsonMcpServerConfigs(agentId, selectedMcpServers));
 }
 export function extractProjectOverview(filePath) {
     if (!fs.existsSync(filePath)) {
@@ -59,13 +56,26 @@ export function extractProjectOverview(filePath) {
     const overview = match?.[1]?.trim();
     return overview || undefined;
 }
-function renderCodexGithubMcpConfig(baseContents) {
+function renderCodexMcpConfig(baseContents, selectedMcpServers) {
     const trimmedBaseContents = baseContents.trimEnd();
+    const serverConfigs = selectedMcpServers.map((server) => buildCodexMcpServerConfig(server)).filter((config) => config.length > 0);
+    if (serverConfigs.length === 0) {
+        return baseContents;
+    }
     const separator = trimmedBaseContents ? '\n\n' : '';
-    return `${trimmedBaseContents}${separator}[mcp_servers.github]
+    return `${trimmedBaseContents}${separator}${serverConfigs.join('\n\n')}\n`;
+}
+function buildCodexMcpServerConfig(server) {
+    if (server.id === 'github') {
+        return `[mcp_servers.github]
 url = "https://api.githubcopilot.com/mcp/"
-bearer_token_env_var = "GITHUB_PERSONAL_ACCESS_TOKEN"
-`;
+bearer_token_env_var = "GITHUB_PERSONAL_ACCESS_TOKEN"`;
+    }
+    if (server.id === 'notion') {
+        return `[mcp_servers.notion]
+url = "https://mcp.notion.com/mcp"`;
+    }
+    return '';
 }
 function getMcpConfigAgentId(templateRelativePath) {
     if (templateRelativePath === '.codex/config.toml') {
@@ -79,6 +89,18 @@ function getMcpConfigAgentId(templateRelativePath) {
     }
     return undefined;
 }
+function buildJsonMcpServerConfigs(agentId, selectedMcpServers) {
+    const mcpServers = {};
+    for (const server of selectedMcpServers) {
+        if (server.id === 'github') {
+            mcpServers.github = buildGithubMcpServerConfig(agentId);
+        }
+        if (server.id === 'notion') {
+            mcpServers.notion = buildNotionMcpServerConfig();
+        }
+    }
+    return mcpServers;
+}
 function buildGithubMcpServerConfig(agentId) {
     const headers = {
         Authorization: 'Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}',
@@ -95,6 +117,11 @@ function buildGithubMcpServerConfig(agentId) {
         headers,
     };
 }
+function buildNotionMcpServerConfig() {
+    return {
+        url: 'https://mcp.notion.com/mcp',
+    };
+}
 function renderJsonMcpConfig(mcpServers) {
     return `${JSON.stringify({ mcpServers }, null, 2)}\n`;
 }

package/bin/modules/workflow-state-registry/state.js

@@ -61,12 +61,29 @@ function isSibuState(value) {
             (Array.isArray(state.selectedDatabaseSkills) && state.selectedDatabaseSkills.every((skill) => typeof skill === 'string'))) &&
         (state.selectedMcpServers === undefined ||
             (Array.isArray(state.selectedMcpServers) && state.selectedMcpServers.every((server) => typeof server === 'string'))) &&
+        (state.mcpServerConfigs === undefined || isMcpServerConfigs(state.mcpServerConfigs)) &&
         (state.reviewedArchitectureSkills === undefined ||
             (Array.isArray(state.reviewedArchitectureSkills) && state.reviewedArchitectureSkills.every((skill) => typeof skill === 'string'))) &&
         !!state.managedFiles &&
         typeof state.managedFiles === 'object' &&
         Object.values(state.managedFiles).every(isManagedFileState));
 }
+function isMcpServerConfigs(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const configs = value;
+    if (configs.notion !== undefined) {
+        if (!configs.notion || typeof configs.notion !== 'object') {
+            return false;
+        }
+        const notionConfig = configs.notion;
+        if (typeof notionConfig.docsParentPage !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
 function isManagedFileState(value) {
     if (!value || typeof value !== 'object') {
         return false;

package/bin/modules/workflow-target-planning/catalog.js

@@ -206,6 +206,12 @@ export const SELECTABLE_MCP_SERVERS = [
         description: "Configure GitHub's official MCP server; Sibu writes config only, while prerequisites, runtime availability, credentials, and authentication remain user-owned",
         source: 'github/github-mcp-server',
     },
+    {
+        id: 'notion',
+        name: 'Notion MCP Server',
+        description: 'Configure Notion MCP server access; Sibu writes config only, while OAuth authentication, workspace access, page permissions, and credentials remain user-owned',
+        source: 'developers.notion.com/guides/mcp',
+    },
 ];
 export const SUPPORTED_AGENTS = [
     {

package/bin/modules/workflow-target-planning/workflow-targets.js

@@ -49,7 +49,7 @@ export function getSelectedSkillTargetsForAgents(selectedAgents, selectedLanguag
     return [...skillTargets.values()];
 }
 export function getSelectedMcpTargetsForAgents(selectedAgents, selectedMcpServers) {
-    if (!selectedMcpServers.some((server) => server.id === 'github')) {
+    if (selectedMcpServers.length === 0) {
         return [];
     }
     return selectedAgents.flatMap((agent) => {
@@ -158,7 +158,7 @@ export function renderMissingWorkflowFiles({ missingTargets, overview, selectedL
         };
     });
 }
-export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers, targets, }) {
+export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLanguageSkills, selectedFrameworkSkills, selectedArchitectureSkill, selectedWorkflowSkills = [], selectedDatabaseSkills = [], selectedMcpServers, mcpServerConfigs, targets, }) {
     const previousState = readExistingState(statePath);
     const now = new Date().toISOString();
     const manifest = readTemplateManifest();
@@ -174,6 +174,7 @@ export function writeSibuState({ rootPath, statePath, selectedAgents, selectedLa
         selectedWorkflowSkills: selectedWorkflowSkills.map((skill) => skill.id),
         selectedDatabaseSkills: selectedDatabaseSkills.map((skill) => skill.id),
         ...(selectedMcpServers !== undefined ? { selectedMcpServers: selectedMcpServers.map((server) => server.id) } : {}),
+        ...(mcpServerConfigs ?? previousState?.mcpServerConfigs ? { mcpServerConfigs: mcpServerConfigs ?? previousState?.mcpServerConfigs } : {}),
         managedFiles: Object.fromEntries(targets
             .filter((target) => fs.existsSync(target.targetPath))
             .map((target) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "89",
+  "templateVersion": "90",
   "templates": {
     "AGENTS.md": {
       "version": "28",
@@ -66,17 +66,17 @@
       ]
     },
     "skills/feature-brief-writer/SKILL.md": {
-      "version": "9",
+      "version": "10",
       "description": "Mandatory feature brief writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Removes Open Questions from the feature brief template and requires the interview to resolve material feature questions before drafting."
+        "Adds optional Notion export guidance after local feature briefs are written while keeping Markdown as the canonical artifact."
       ]
     },
     "skills/technical-design-writer/SKILL.md": {
-      "version": "16",
+      "version": "17",
       "description": "Mandatory technical design writer skill installed once at the shared .agents/skills workspace path.",
       "changes": [
-        "Requires technical designs crossing framework boundaries to name the allowed application/orchestration entrypoint and forbidden lower-level dependencies."
+        "Adds optional Notion export guidance after local technical designs are written while keeping Markdown as the canonical artifact."
       ]
     },
     "skills/typescript/SKILL.md": {
@@ -157,10 +157,10 @@
       ]
     },
     "skills/ux-expert/SKILL.md": {
-      "version": "6",
+      "version": "7",
       "description": "Selectable UX expert skill for UI-changing features, responsive design, flows, states, accessibility, and binding mockups.",
       "changes": [
-        "Updates boundary wording to use Deep Module Maps."
+        "Adds optional Notion export guidance after local UX specs are written while keeping Markdown as the canonical artifact."
       ]
     }
   }

package/templates/skills/feature-brief-writer/SKILL.md

@@ -283,6 +283,31 @@ When shaping a feature brief, prefer:
 7. measurable success signals
 8. non-technical acceptance criteria
 
+## Optional Notion export after local write
+
+After the local Markdown file is written successfully, optionally offer Notion export. Local Markdown remains the canonical pipeline artifact and Notion is only a convenience export destination.
+
+1. Do not check Notion export before the local file exists.
+2. After writing the local file, read `.sibu/state.json` if available.
+3. Offer export only when all are true:
+   - `selectedMcpServers` includes `notion`
+   - `mcpServerConfigs.notion.docsParentPage` is present
+   - Notion MCP tools are available in the current agent session
+4. If export is unavailable, do nothing else and finish with the normal local path response.
+5. If export is available, ask for explicit opt-in before creating or modifying any Notion page.
+6. If the user declines, do nothing else.
+7. If the user accepts, create or reuse Notion organization pages under the configured parent page:
+
+```txt
+<docsParentPage>
+└── <repo name>
+    └── Features
+        └── <feature name>
+            └── Feature Brief
+```
+
+Create a new document page for the just-written artifact content. Do not write Notion URLs back into local Markdown. Report Notion export success or a clear Notion export failure, while preserving the local file as the completed artifact either way.
+
 ## Final response behavior
 
 After writing the file, final-answer with only the path created or updated. Do not paste the feature brief body, excerpt, outline, or section summaries.

package/templates/skills/technical-design-writer/SKILL.md

@@ -158,6 +158,31 @@ Use this structure as a starting point. Delete sections that do not add value.
 
 A good technical design is short, specific, and useful. It should not try to be the product brief, architecture skill, clean-code skill, implementation plan, or ticket backlog.
 
+## Optional Notion export after local write
+
+After the local Markdown file is written successfully, optionally offer Notion export. Local Markdown remains the canonical pipeline artifact and Notion is only a convenience export destination.
+
+1. Do not check Notion export before the local file exists.
+2. After writing the local file, read `.sibu/state.json` if available.
+3. Offer export only when all are true:
+   - `selectedMcpServers` includes `notion`
+   - `mcpServerConfigs.notion.docsParentPage` is present
+   - Notion MCP tools are available in the current agent session
+4. If export is unavailable, do nothing else and finish with the normal local path response.
+5. If export is available, ask for explicit opt-in before creating or modifying any Notion page.
+6. If the user declines, do nothing else.
+7. If the user accepts, create or reuse Notion organization pages under the configured parent page:
+
+```txt
+<docsParentPage>
+└── <repo name>
+    └── Features
+        └── <feature name>
+            └── Technical Design
+```
+
+Create a new document page for the just-written artifact content. Do not write Notion URLs back into local Markdown. Report Notion export success or a clear Notion export failure, while preserving the local file as the completed artifact either way.
+
 ## Final response behavior
 
 After writing the file, final-answer with only the path created or updated. Do not paste the technical design body, excerpt, outline, or section summaries.

package/templates/skills/ux-expert/SKILL.md

@@ -118,6 +118,31 @@ Use only helpful sections from this shape:
 
 The Binding Mockups section is authoritative for downstream work unless this UX spec is revised.
 
+## Optional Notion export after local write
+
+After the local Markdown file is written successfully, optionally offer Notion export. Local Markdown remains the canonical pipeline artifact and Notion is only a convenience export destination.
+
+1. Do not check Notion export before the local file exists.
+2. After writing the local file, read `.sibu/state.json` if available.
+3. Offer export only when all are true:
+   - `selectedMcpServers` includes `notion`
+   - `mcpServerConfigs.notion.docsParentPage` is present
+   - Notion MCP tools are available in the current agent session
+4. If export is unavailable, do nothing else and finish with the normal local path response.
+5. If export is available, ask for explicit opt-in before creating or modifying any Notion page.
+6. If the user declines, do nothing else.
+7. If the user accepts, create or reuse Notion organization pages under the configured parent page:
+
+```txt
+<docsParentPage>
+└── <repo name>
+    └── Features
+        └── <feature name>
+            └── UX Design
+```
+
+Create a new document page for the just-written artifact content. Do not write Notion URLs back into local Markdown. Report Notion export success or a clear Notion export failure, while preserving the local file as the completed artifact either way.
+
 ## Final response behavior
 
 After writing the file, final-answer with only the path created or updated. Do not paste the UX spec body, excerpt, outline, mockups, or section summaries.