@juancr11/sibu 0.10.0 → 0.11.1

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.1",
   "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": "91",
   "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": {
@@ -122,10 +122,10 @@
       ]
     },
     "skills/react/SKILL.md": {
-      "version": "1",
+      "version": "2",
       "description": "Selectable React skill for component design, props, state ownership, and presentational boundaries.",
       "changes": [
-        "Adds an optional React skill for projects that create or change React components, props, state ownership, or presentational and data-owning boundaries."
+        "Strengthens React component guidance around Single Responsibility Principle splits, stateless versus stateful boundaries, and one component per file by default."
       ]
     },
     "skills/scrum-master-planner/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/react/SKILL.md

@@ -21,15 +21,17 @@ This skill covers React componentization, component responsibility, state owners
 
 ### 1. Treat components like focused functions
 - A component should have one clear reason to exist.
-- If a component does too many unrelated things, split it.
-- Prefer small components with clear names and explicit responsibilities.
-- Do not split components just to create more files; split when it improves understanding.
-
-### 2. Separate presentational components from data-owning components
-- Presentational components should mostly render UI from props.
-- Data-owning components may fetch, subscribe, mutate, or coordinate data.
-- Keep it obvious which components interact with the server and which are purely presentational.
-- Avoid hiding server interactions deep inside components that look presentational.
+- Apply the Single Responsibility Principle aggressively: split components whenever rendering, state ownership, event handling, data access, layout, formatting, or low-level UI concerns start to blur together.
+- Create as many components as needed to keep each component easy to name, test, scan, and change independently.
+- Prefer small components with clear names and explicit responsibilities over broad components with internal sections.
+- Do not preserve a large component just to avoid adding files; a few extra focused components are better than one file that hides multiple responsibilities.
+
+### 2. Separate stateless, stateful, and data-owning components
+- Stateless presentational components should render UI from props and avoid owning state or side effects.
+- Stateful interaction components may own local UI state when that state belongs only to their focused responsibility.
+- Data-owning components may fetch, subscribe, mutate, or coordinate server data.
+- Keep stateless, stateful, and server-interacting responsibilities visibly separate; split components when those roles mix.
+- Avoid hiding state transitions, server interactions, or mutations deep inside components that look presentational.
 
 ### 3. Keep props narrow and explicit
 - Pass only what the child component needs.
@@ -63,13 +65,18 @@ This skill covers React componentization, component responsibility, state owners
 - Name components by what they represent in the UI or product.
 - Keep server-interacting, stateful, and presentational responsibilities easy to identify from the component shape.
 - Avoid mixing data fetching, mutation, layout, formatting, and low-level UI rendering in one component.
+- Each component should live in its own file by default; do not define multiple components in the same file just because they are currently small.
+- If a helper component is only temporary, promote it to its own file as soon as it represents a meaningful UI responsibility.
 
 ## Decision rule
 
 When unsure, prefer:
 1. one clear responsibility per component
-2. presentational components that render from props
-3. data/server interaction in obvious owner components
-4. local state unless coordination requires lifting it
-5. composition over flag-heavy component APIs
-6. no duplicated derived state
+2. more focused components instead of fewer overloaded components
+3. one component per file by default
+4. stateless presentational components that render from props
+5. stateful components only where local interaction state is genuinely owned
+6. data/server interaction in obvious owner components
+7. local state unless coordination requires lifting it
+8. composition over flag-heavy component APIs
+9. no duplicated derived state

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.