spovishun-skills 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -5,6 +5,156 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] — 2026-06-04
+
+Patch release with two breaking-but-necessary changes:
+
+1. Fixes a runtime-breaking confusion between Notion `database_id` and
+   `data_source_id` in five bundled skills (4xx from the Notion API).
+2. Closes a long-standing self-inconsistency: skills referenced
+   `scripts/notion/*.js` CLI helpers that **did not ship with the plugin**, so
+   every freshly-installed consumer hit `MODULE_NOT_FOUND` the moment a skill
+   tried to read the board. The scripts are now part of the plugin and the
+   Claude adapter installs them into `.claude/scripts/notion/`.
+
+### Fixed
+
+- **`lib/placeholder-map.js`** — removed two false aliases that mapped the configured
+  `database_id` / `epics_database_id` under `*_COLLECTION_ID` / `*_DATA_SOURCE_ID` names.
+  In Notion's data-sources model a database id and its data_source (collection) id are
+  different UUIDs. Skills that interpolated those aliases into MCP
+  `parent: { type: "data_source_id", data_source_id: "<value>" }` parents failed at
+  runtime with `404 object_not_found` — proven against the live Notion API during the
+  spovishun-93 dogfooding.
+- **`skills/newtask`**, **`skills/newepic`**, **`skills/notion-spovishun-task-manager`**,
+  **`skills/task-decomposer`** — the MCP create-page examples now use
+  `parent: { type: "database_id", database_id: "{{NOTION_DATABASE_ID}}" }` (or
+  `{{NOTION_EPICS_DATABASE_ID}}` for epics). Inline notes flag the single-data-source
+  prerequisite of the `database_id` parent and point to `notion-task-board-manager`
+  for the multi-source / live-fetched `data_source_id` pattern.
+- **`skills/task-decomposer`** — Step 0 board lookup no longer constructs a broken
+  `data_source_url: "collection://<database_id>"` URL; switched to
+  `node scripts/notion/get-board.js`, which uses the REST `/databases/{id}/query`
+  endpoint that is consistent with the rest of the consumer-side tooling.
+- **`skills/notion-navigator`** — prose now references `{{NOTION_DATABASE_ID}}` /
+  `{{NOTION_EPICS_DATABASE_ID}}` and clarifies they are database_ids, not collection
+  ids, with a pointer to live-fetching the data_source_id when MCP needs it.
+- **`hooks/notion-task-inject.js`** — renamed the misleading `NOTION_BOARD_COLLECTION_ID`
+  env-var reference to `NOTION_DATABASE_ID` (the value was always a `database_id`; the
+  hook calls `/v1/databases/{id}/query`). The old name is still accepted as a
+  deprecated alias so existing consumer `.env` files keep working.
+
+### Changed
+
+- **Board v2 (Scrum) Stage default flipped to explicit `Backlog`.** Pre-v1.2.2, the
+  `notion-spovishun-task-manager/references/board-v2-stages.md` doc told `newtask` to
+  leave `Stage` empty — that left new tasks invisible to the `Stage = Backlog` Backlog
+  view filter unless you also kept the `Stage is empty` clause around forever. New tasks
+  now set `Stage: "Backlog"` explicitly in the MCP create body (omit the property
+  entirely on Board v1 / when `notion.picker.stage_filter` is unset). Doc and skill
+  guidance updated together; the Backlog view filter clause is unchanged for
+  backward compatibility with pre-v1.2.2 tasks.
+
+### Removed
+
+- **Placeholders `NOTION_BOARD_COLLECTION_ID` and `NOTION_EPICS_DATA_SOURCE_ID`** —
+  no longer surfaced by the placeholder map; dropped from every manifest that declared
+  them (`newtask`, `newepic`, `notion-navigator`, `notion-spovishun-task-manager`,
+  `task-decomposer`). Any skill body still referencing one will fail install with a
+  clear `UNKNOWN_PLACEHOLDER` error — intended, surfaces the bug.
+
+### Added — Notion CLI scripts now ship with the plugin
+
+- **`scripts/notion/`** — 7 CLI helpers (`get-board.js`, `get-task.js`,
+  `get-claude-md.js`, `create-task.js`, `create-epic.js`, `list-epics.js`,
+  `update-status.js`) plus 12 shared `lib/` modules. Ported from the Spovishun
+  project and generalized: no hard-coded Notion UUIDs, no hard-coded
+  `spovishun-` task-id prefix. All values resolve at run time:
+  - `NOTION_DATABASE_ID` / `NOTION_EPICS_DATABASE_ID` / `NOTION_CLAUDE_MD_PAGE_ID`
+    env vars take precedence; otherwise read from `spovishun-skills.config.yaml`.
+  - `PROJECT_PREFIX` env var or a slugified `project.name` drives the task-id
+    regex (e.g. `myapp-42` for `project.name: "MyApp"`).
+- **`adapters/claude/index.js`** — new `installScripts()` step that mirrors
+  `scripts/notion/` into the consumer's `.claude/scripts/notion/` when
+  `stack.notion` is true. No-op otherwise. Codex / Windsurf targets do not
+  receive scripts (those adapters surface skills as inline text).
+- **`scripts/notion/create-task.js`** — supports a new `stage` field on stdin
+  for Board v2 (Scrum). Default `"Backlog"`; pass `null` to omit the Stage
+  column entirely on Board v1.
+- **`scripts/notion/lib/config-reader.js`** — strips a UTF-8 BOM before
+  scanning the consumer config so `Out-File -Encoding utf8` (PowerShell 5.1)
+  configs don't silently parse to empty.
+
+### Changed — skill bodies use installed script path
+
+- All eight skills that invoke a Notion CLI helper (`newtask`, `newepic`,
+  `task-decomposer`, `notion-spovishun-task-manager`, `notion-task-to-code`,
+  `notion-workflow-spovishun`, `notion-content-reader`) now reference
+  `node .claude/scripts/notion/<script>.js` instead of the un-prefixed
+  `node scripts/notion/<script>.js` that pointed nowhere on a fresh install.
+
+### Manifests bumped
+
+- `newtask` 1.0.0 → 1.0.1
+- `newepic` 1.0.0 → 1.0.1
+- `notion-navigator` 1.0.0 → 1.0.1
+- `notion-spovishun-task-manager` 1.0.0 → 1.0.1
+- `task-decomposer` 1.0.0 → 1.0.1
+- `notion-task-to-code` 1.0.0 → 1.0.1
+- `notion-workflow-spovishun` 1.0.0 → 1.0.1
+- `notion-content-reader` 1.0.0 → 1.0.1
+
+### Migration notes for consumers
+
+1. Re-run `npx spovishun-skills install --target=<target>` after upgrading.
+2. The `NOTION_BOARD_COLLECTION_ID` env var in `.env` keeps working but is deprecated;
+   rename it to `NOTION_DATABASE_ID` at your convenience.
+3. Board v2 users on Notion: new tasks created via these skills will explicitly land
+   in `Stage = "Backlog"` (was: empty). If you have a Backlog view filtering on
+   `Stage is empty` only, broaden it to `Stage = Backlog OR Stage is empty`.
+
+### Known follow-ups (not addressed in this patch)
+
+- First-install pruning over hand-authored `.claude/` (carried over from v1.2.1). A
+  deprecated `diagram-design/` skill folder and a legacy `.claude/skills/_templates/`
+  directory are not removed because the pre-existing install has no provenance.
+
+## [1.2.1] — 2026-06-03
+
+Patch release. Fixes a Claude-adapter bug surfaced by dogfooding the published plugin in the
+Spovishun project: the Claude install was writing 24 of 36 skills without any YAML frontmatter,
+which silently degraded Claude Code's skill triggering (it fell back to the body's first H1
+instead of the manifest's `description`).
+
+### Fixed
+
+- **`adapters/claude/index.js`** now synthesizes a `---\nname: <id>\ndescription: ...\n---`
+  frontmatter block at the top of every `.claude/skills/<id>/SKILL.md` when the canonical body
+  does not already start with one. Bodies that ship with their own inline frontmatter (e.g.
+  `code-reviewer`) are written verbatim — no double-wrap. Agents and templates are unchanged.
+- **`adapters/claude/update.js`** mirrors the install behavior so `update --target=claude` and
+  `sync` produce byte-identical output to a fresh install for the same upstream commit.
+- **`bin/update.js`** prepends the same synthesized frontmatter when building its upstream
+  checksum map, so the three-way classifier sees AUTO_APPLY (not "drifted") once a re-install
+  with the new adapter has run.
+
+### Added
+
+- **`lib/skill-frontmatter.js`** — small pure helper module. `composeSkillDescription(manifest)`
+  appends a `Triggers: <en+uk joined>.` suffix to the manifest's `description` so triggering
+  matches the convention used by hand-authored inline-frontmatter skills like `code-reviewer`.
+  `ensureSkillFrontmatter(body, manifest)` is the no-op-if-present write-side guard.
+- Tests: `test/skill-frontmatter.test.js` (unit) + new `manifest-only` / `inline-frontmatter`
+  / `agent-unchanged` cases in `test/install-claude.test.js`. New fixture
+  `test/fixtures/source/skills/inline-frontmatter-skill/` covers the no-double-wrap path.
+
+### Known follow-ups (not addressed in this patch)
+
+- Pruning hand-authored artifacts the lockfile never owned. A first install over a hand-authored
+  `.claude/` cannot remove pre-existing files (e.g. a deprecated `diagram-design/` skill folder,
+  or a legacy `.claude/skills/_templates/` directory) because they have no provenance. Likely
+  fix: teach `install` to prune known-removed skill ids and detect the legacy template location.
+
 ## [1.2.0] — 2026-06-02
 
 Folder-layout supporting files across all adapters, templates as a first-class artifact kind,

package/adapters/claude/index.js

@@ -7,6 +7,7 @@ import { buildPlaceholderMap } from '../../lib/placeholder-map.js';
 import { sha256 } from '../../lib/checksum.js';
 import { mergeSettings } from '../../lib/settings-merger.js';
 import { readLockfile, LOCKFILE_NAME } from '../../lib/lockfile.js';
+import { ensureSkillFrontmatter } from '../../lib/skill-frontmatter.js';
 
 const KIND_LAYOUT = {
   skill: { subdir: 'skills', bodyFilename: 'SKILL.md' },
@@ -47,11 +48,14 @@ export async function installClaude({ consumerCwd, pkgRoot, config, artifacts, w
 
     const manifestPlaceholders = (artifact.manifest?.placeholders ?? []).map((p) => p.key);
     const renderedBody = renderTemplate(artifact.bodyText, { configMap, manifestPlaceholders });
-    const checksum = sha256(renderedBody);
+    const bodyToWrite = artifact.kind === 'skill'
+      ? ensureSkillFrontmatter(renderedBody, artifact.manifest)
+      : renderedBody;
+    const checksum = sha256(bodyToWrite);
 
     const artifactDir = join(claudeDir, layout.subdir, artifact.id);
     mkdirSync(artifactDir, { recursive: true });
-    writeFileSync(join(artifactDir, layout.bodyFilename), renderedBody, 'utf8');
+    writeFileSync(join(artifactDir, layout.bodyFilename), bodyToWrite, 'utf8');
 
     for (const file of artifact.files ?? []) {
       const destPath = join(artifactDir, file.relPath);
@@ -71,6 +75,7 @@ export async function installClaude({ consumerCwd, pkgRoot, config, artifacts, w
   patchSettings(claudeDir, {});
   installHooks(pkgRoot, claudeDir);
   installRules(pkgRoot, claudeDir, configMap);
+  installScripts(pkgRoot, claudeDir, config, warn);
 
   return lockEntries;
 }
@@ -180,6 +185,43 @@ function copyRulesRecursive(baseDir, currentDir, claudeDir, configMap) {
   }
 }
 
+/**
+ * Copies CLI scripts that skill bodies invoke (e.g. `node .claude/scripts/notion/get-board.js`)
+ * into the consumer's `.claude/scripts/` tree. The whole `scripts/` subtree is
+ * mirrored recursively, preserving subdirectories. Each `notion/` script is
+ * gated on `stack.notion` — if the consumer is not running Notion, no scripts
+ * are copied at all.
+ *
+ * Codex / Windsurf adapters do not call this — those targets surface skills
+ * as inline text where shell-script delivery makes no sense.
+ */
+function installScripts(pkgRoot, claudeDir, config, warn) {
+  const scriptsRoot = join(pkgRoot, 'scripts');
+  if (!existsSync(scriptsRoot)) return;
+
+  const notionDir = join(scriptsRoot, 'notion');
+  if (existsSync(notionDir)) {
+    if (!config.stack?.notion) return;
+    const dest = join(claudeDir, 'scripts', 'notion');
+    mkdirSync(dest, { recursive: true });
+    copyDirRecursive(notionDir, dest);
+  }
+}
+
+function copyDirRecursive(srcDir, destDir) {
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      mkdirSync(destPath, { recursive: true });
+      copyDirRecursive(srcPath, destPath);
+    } else if (entry.isFile()) {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 function patchSettings(claudeDir, pluginHooks) {
   const settingsPath = join(claudeDir, 'settings.json');
   let existing = {};

package/adapters/claude/update.js

@@ -1,6 +1,7 @@
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { threeWayMerge } from '../../lib/three-way-merge.js';
+import { ensureSkillFrontmatter } from '../../lib/skill-frontmatter.js';
 
 const KIND_LAYOUT = {
   skill: { subdir: 'skills', bodyFilename: 'SKILL.md' },
@@ -39,12 +40,20 @@ export async function updateClaude({
   mkdirSync(outDir, { recursive: true });
   const outPath = join(outDir, layout.bodyFilename);
 
+  // Defensive: callers in bin/update.js already prepend the synthesized
+  // skill frontmatter, but ensureSkillFrontmatter is a no-op when the
+  // block is already there. Keeping it here means a direct adapter call
+  // with a raw rendered body still produces a Claude-loadable file.
+  const upstream = artifact.kind === 'skill'
+    ? ensureSkillFrontmatter(rendered, artifact.manifest)
+    : rendered;
+
   if (!conflict) {
-    writeFileSync(outPath, rendered, 'utf8');
+    writeFileSync(outPath, upstream, 'utf8');
     return;
   }
 
-  const ours = installedEntry ? installedEntry.content : rendered;
-  const { content } = threeWayMerge({ ours, theirs: rendered, oursLabel, theirsLabel });
+  const ours = installedEntry ? installedEntry.content : upstream;
+  const { content } = threeWayMerge({ ours, theirs: upstream, oursLabel, theirsLabel });
   writeFileSync(outPath, content, 'utf8');
 }

package/bin/update.js

@@ -15,6 +15,7 @@ import { sha256 } from '../lib/checksum.js';
 import { classifyArtifact, ACTIONS } from '../lib/update-classifier.js';
 import { updateClaude } from '../adapters/claude/update.js';
 import { updateWindsurf } from '../adapters/windsurf/update.js';
+import { ensureSkillFrontmatter } from '../lib/skill-frontmatter.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -97,7 +98,13 @@ export async function runUpdate({
   const upstreamMap = new Map();
   for (const artifact of upstreamArtifacts) {
     const manifestPlaceholders = (artifact.manifest?.placeholders ?? []).map((p) => p.key);
-    const rendered = renderTemplate(artifact.bodyText, { configMap, manifestPlaceholders });
+    const renderedBody = renderTemplate(artifact.bodyText, { configMap, manifestPlaceholders });
+    // Claude installs prepend a synthesized YAML frontmatter to every skill
+    // body (see adapters/claude/index.js). Mirror that here so the
+    // upstream checksum matches what is actually on disk after install/sync.
+    const rendered = target === 'claude' && artifact.kind === 'skill'
+      ? ensureSkillFrontmatter(renderedBody, artifact.manifest)
+      : renderedBody;
     const checksum = sha256(rendered);
     upstreamMap.set(`${artifact.kind}:${artifact.id}`, { artifact, rendered, checksum });
   }

package/hooks/notion-task-inject.js

@@ -21,7 +21,10 @@
  * Configuration. Env vars take precedence; otherwise resolved from the consumer's
  * spovishun-skills.config.yaml (so a plain `install` works without extra env setup):
  *   NOTION_TOKEN or NOTION_SKILLS_TOKEN  — Notion API token (required; from env/.env)
- *   NOTION_BOARD_COLLECTION_ID  ⟵ notion.database_id   — task board database ID (required)
+ *   NOTION_DATABASE_ID          ⟵ notion.database_id   — task board database ID (required)
+ *                                  (NOTION_BOARD_COLLECTION_ID is accepted as a
+ *                                  deprecated alias; it was a misnamed pre-1.2.2
+ *                                  env var that actually held the database id.)
  *   PROJECT_PREFIX              ⟵ slug(project.name)    — branch prefix → feature/<prefix>-N
  *   GIT_DEVELOP_BRANCH          ⟵ git.dev_branch        — base branch name, default "develop"
  *
@@ -125,7 +128,12 @@ function slug(name) {
 }
 
 const NOTION_TOKEN = process.env.NOTION_SKILLS_TOKEN || process.env.NOTION_TOKEN;
-const DATABASE_ID = process.env.NOTION_BOARD_COLLECTION_ID || readConfigValue('notion', 'database_id');
+// NOTION_BOARD_COLLECTION_ID is the deprecated 1.2.0/1.2.1 alias — it was always
+// a misnomer (the hook queries /v1/databases/{id}/query, not a data source).
+// Keep accepting it so existing consumer .env files keep working.
+const DATABASE_ID = process.env.NOTION_DATABASE_ID
+  || process.env.NOTION_BOARD_COLLECTION_ID
+  || readConfigValue('notion', 'database_id');
 const PROJECT_PREFIX = process.env.PROJECT_PREFIX || slug(readConfigValue('project', 'name')) || 'project';
 const DEVELOP_BRANCH = process.env.GIT_DEVELOP_BRANCH || readConfigValue('git', 'dev_branch') || 'develop';
 // Board v2 (Scrum) optional Stage select filter. Empty string = unset = no filter (Board v1).
@@ -627,7 +635,7 @@ async function main() {
   if (!hasTrigger) process.exit(0);
 
   if (!DATABASE_ID) {
-    process.stderr.write('[notion-task-inject] NOTION_BOARD_COLLECTION_ID not set, skipping\n');
+    process.stderr.write('[notion-task-inject] NOTION_DATABASE_ID not set, skipping\n');
     process.exit(0);
   }
 

package/lib/placeholder-map.js

@@ -35,13 +35,14 @@ export function buildPlaceholderMap(config) {
 
   if (config.stack?.notion) {
     set('NOTION_TOKEN_ENV', config.notion?.token_env);
+    // database_id and data_source_id (a.k.a. "collection id") are DIFFERENT
+    // identifiers in Notion's data-sources model. We only expose database_id
+    // here. Skills that need a data_source_id must fetch it live from the DB
+    // (`<data-source url="collection://...">`) — never interpolate one from
+    // config, and never alias database_id under a `*_COLLECTION_ID` /
+    // `*_DATA_SOURCE_ID` name (a 1.2.0/1.2.1 bug; tracked in CHANGELOG 1.2.2).
     set('NOTION_DATABASE_ID', config.notion?.database_id);
-    // NOTION_BOARD_COLLECTION_ID = data_source_id alias for the board database.
-    // Notion exposes the same identifier under both names depending on API path.
-    set('NOTION_BOARD_COLLECTION_ID', config.notion?.database_id);
     set('NOTION_EPICS_DATABASE_ID', config.notion?.epics_database_id);
-    // NOTION_EPICS_DATA_SOURCE_ID alias for the epics database (see comment above).
-    set('NOTION_EPICS_DATA_SOURCE_ID', config.notion?.epics_database_id);
     set('NOTION_ROOT_PAGE_ID', config.notion?.root_page_id);
     set('NOTION_DOCS_ROOT_ID', config.notion?.docs_root_id);
     set('NOTION_CLAUDE_MD_PAGE_ID', config.notion?.claude_md_page_id);

package/lib/skill-frontmatter.js

@@ -0,0 +1,87 @@
+/**
+ * Helpers for synthesizing the YAML frontmatter block that Claude Code expects
+ * at the top of every `.claude/skills/<id>/SKILL.md` file.
+ *
+ * Claude Code parses `name` and `description` from the frontmatter to drive
+ * skill triggering. A SKILL.md without it falls back to the body's first H1,
+ * which silently degrades trigger quality. Most manifests carry their
+ * metadata only in `manifest.yaml`, so the Claude adapter must synthesize the
+ * block from the manifest at install time.
+ */
+
+const FRONTMATTER_FENCE = '---';
+
+/**
+ * Detects a leading YAML frontmatter block. Accepts both `\n` and `\r\n`
+ * line endings on the opening fence.
+ */
+export function hasFrontmatter(text) {
+  if (typeof text !== 'string' || text.length < 4) return false;
+  return text.startsWith(`${FRONTMATTER_FENCE}\n`) || text.startsWith(`${FRONTMATTER_FENCE}\r\n`);
+}
+
+/**
+ * Builds a minimal but trigger-rich `description:` value for the synthesized
+ * frontmatter. Starts from `manifest.description` and appends a
+ * `Triggers: <terms>.` sentence built from `manifest.triggers.en` and
+ * `manifest.triggers.uk` so triggering matches the convention used by
+ * skills with hand-authored inline frontmatter (e.g. code-reviewer).
+ *
+ * Returns an empty string if neither piece is available — the caller decides
+ * whether that is an error worth surfacing.
+ */
+export function composeSkillDescription(manifest) {
+  const base = typeof manifest?.description === 'string' ? manifest.description.trim() : '';
+  const triggers = collectTriggers(manifest);
+  if (triggers.length === 0) return base;
+  const suffix = `Triggers: ${triggers.join(', ')}.`;
+  if (!base) return suffix;
+  const needsPeriod = !/[.!?]$/.test(base);
+  return needsPeriod ? `${base}. ${suffix}` : `${base} ${suffix}`;
+}
+
+function collectTriggers(manifest) {
+  const en = Array.isArray(manifest?.triggers?.en) ? manifest.triggers.en : [];
+  const uk = Array.isArray(manifest?.triggers?.uk) ? manifest.triggers.uk : [];
+  const seen = new Set();
+  const out = [];
+  for (const t of [...en, ...uk]) {
+    if (typeof t !== 'string') continue;
+    const trimmed = t.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * Builds the `---\nname: ...\ndescription: ...\n---\n` block for the given
+ * manifest. `description` values are emitted as JSON-encoded strings to
+ * survive embedded quotes, colons, and trailing punctuation without
+ * hand-rolled escaping.
+ */
+export function buildSkillFrontmatter(manifest) {
+  const name = manifest?.id ?? '';
+  const description = composeSkillDescription(manifest);
+  const lines = [FRONTMATTER_FENCE, `name: ${name}`];
+  if (description) {
+    lines.push(`description: ${JSON.stringify(description)}`);
+  }
+  lines.push(FRONTMATTER_FENCE, '');
+  return lines.join('\n');
+}
+
+/**
+ * Returns `renderedBody` unchanged if it already starts with a frontmatter
+ * fence (hand-authored inline frontmatter wins — we never double-wrap).
+ * Otherwise prepends a synthesized block built from `manifest`.
+ *
+ * Only call for `kind === 'skill'`. Agents intentionally ship richer
+ * Claude-specific frontmatter (tools, model, maxTurns) and templates carry
+ * no metadata Claude consumes.
+ */
+export function ensureSkillFrontmatter(renderedBody, manifest) {
+  if (hasFrontmatter(renderedBody)) return renderedBody;
+  return buildSkillFrontmatter(manifest) + renderedBody;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spovishun-skills",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Portable Claude Code skills, agents, hooks and rules — bootstrapped from the Spovishun project. Installs into Claude Code, Codex, Windsurf and Cursor via per-assistant adapters.",
   "type": "module",
   "publishConfig": {

package/scripts/notion/create-epic.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+const http = require('./lib/notion-http');
+const { loadToken } = require('./lib/load-token');
+const constants = require('./lib/constants');
+
+const VALID_STATUSES = ['Planned', 'Active', 'Completed'];
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function main() {
+  const token = loadToken();
+  if (!token) {
+    process.stderr.write('Error: NOTION_TOKEN or NOTION_SKILLS_TOKEN is required\n');
+    process.exit(2);
+  }
+
+  if (!constants.EPICS_DATABASE_ID) {
+    process.stderr.write('Error: NOTION_EPICS_DATABASE_ID is not configured (set env var or notion.epics_database_id in spovishun-skills.config.yaml)\n');
+    process.exit(2);
+  }
+
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.stderr.write('Error: invalid JSON on stdin\n');
+    process.exit(1);
+  }
+
+  const { name, goal, status, relatedNotionTask, icon, content } = input;
+
+  if (!name || typeof name !== 'string' || !name.trim()) {
+    process.stderr.write('Error: "name" is required and must be a non-empty string\n');
+    process.exit(1);
+  }
+  if (goal !== undefined && typeof goal !== 'string') {
+    process.stderr.write('Error: "goal" must be a string\n');
+    process.exit(1);
+  }
+  const epicStatus = status ?? 'Planned';
+  if (!VALID_STATUSES.includes(epicStatus)) {
+    process.stderr.write(`Error: "status" must be one of: ${VALID_STATUSES.join(', ')}\n`);
+    process.exit(1);
+  }
+  if (relatedNotionTask !== undefined && relatedNotionTask !== null && typeof relatedNotionTask !== 'string') {
+    process.stderr.write('Error: "relatedNotionTask" must be a string URL\n');
+    process.exit(1);
+  }
+  if (content !== undefined && typeof content !== 'string') {
+    process.stderr.write('Error: "content" must be a string\n');
+    process.exit(1);
+  }
+
+  const properties = {
+    Name: { title: [{ type: 'text', text: { content: name.trim() } }] },
+    Status: { select: { name: epicStatus } },
+  };
+  if (goal && goal.trim()) {
+    properties.Goal = { rich_text: [{ type: 'text', text: { content: goal.trim() } }] };
+  }
+  if (relatedNotionTask && relatedNotionTask.trim()) {
+    properties['Related Notion task'] = { url: relatedNotionTask.trim() };
+  }
+
+  const body = {
+    parent: { database_id: constants.EPICS_DATABASE_ID },
+    properties,
+    children: content
+      ? [{ object: 'block', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content } }] } }]
+      : [],
+  };
+
+  if (icon && typeof icon === 'string') {
+    body.icon = { type: 'emoji', emoji: icon };
+  }
+
+  const result = await http.post(token, '/v1/pages', body);
+
+  if (result?.object === 'error') {
+    process.stderr.write(`Notion API error: ${result.message || result.code}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify({ id: result.id, url: result.url }) + '\n');
+}
+
+main().catch(err => {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+});

package/scripts/notion/create-task.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const http = require('./lib/notion-http');
+const { loadToken } = require('./lib/load-token');
+const constants = require('./lib/constants');
+const { toDashed } = require('./lib/page-id');
+
+const VALID_PRIORITIES = ['High', 'Medium', 'Low'];
+// Board v2 (Scrum) Stage. New tasks default to Backlog so they appear in the
+// Backlog view (`Stage = Backlog`) and can be promoted into a Sprint. Pass
+// `stage` on stdin to override. Boards without a Stage property (Board v1)
+// should set `stage: null` to omit the Stage field entirely.
+const VALID_STAGES = ['Backlog', 'Sprint', 'Archive'];
+const DEFAULT_STAGE = 'Backlog';
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function normalizeRelationIds(value, fieldName) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    process.stderr.write(`Error: "${fieldName}" must be an array of page IDs\n`);
+    process.exit(1);
+  }
+  return value.map(id => {
+    if (typeof id !== 'string' || !id.trim()) {
+      process.stderr.write(`Error: "${fieldName}" entries must be non-empty strings\n`);
+      process.exit(1);
+    }
+    return toDashed(id.trim());
+  });
+}
+
+async function main() {
+  const token = loadToken();
+  if (!token) {
+    process.stderr.write('Error: NOTION_TOKEN or NOTION_SKILLS_TOKEN is required\n');
+    process.exit(2);
+  }
+
+  if (!constants.DATABASE_ID) {
+    process.stderr.write('Error: NOTION_DATABASE_ID is not configured (set env var or notion.database_id in spovishun-skills.config.yaml)\n');
+    process.exit(2);
+  }
+
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.stderr.write('Error: invalid JSON on stdin\n');
+    process.exit(1);
+  }
+
+  const { title, priority, content, icon, epicId, blockedBy, stage } = input;
+
+  if (!title || typeof title !== 'string' || !title.trim()) {
+    process.stderr.write('Error: "title" is required and must be a non-empty string\n');
+    process.exit(1);
+  }
+  if (!VALID_PRIORITIES.includes(priority)) {
+    process.stderr.write(`Error: "priority" must be one of: ${VALID_PRIORITIES.join(', ')}\n`);
+    process.exit(1);
+  }
+  if (stage !== undefined && stage !== null && !VALID_STAGES.includes(stage)) {
+    process.stderr.write(`Error: "stage" must be one of: ${VALID_STAGES.join(', ')} (or null to omit)\n`);
+    process.exit(1);
+  }
+  if (content !== undefined && typeof content !== 'string') {
+    process.stderr.write('Error: "content" must be a string\n');
+    process.exit(1);
+  }
+  if (epicId !== undefined && epicId !== null && (typeof epicId !== 'string' || !epicId.trim())) {
+    process.stderr.write('Error: "epicId" must be a non-empty string when provided\n');
+    process.exit(1);
+  }
+
+  const blockedByIds = normalizeRelationIds(blockedBy, 'blockedBy');
+
+  const properties = {
+    Name: { title: [{ type: 'text', text: { content: title.trim() } }] },
+    Priority: { select: { name: priority } },
+    Status: { status: { name: 'To do' } },
+  };
+  // stage === null means "Board v1, no Stage column"; omit. Default = Backlog.
+  if (stage !== null) {
+    properties.Stage = { select: { name: stage ?? DEFAULT_STAGE } };
+  }
+  if (epicId) {
+    properties.Epic = { relation: [{ id: toDashed(epicId.trim()) }] };
+  }
+  if (blockedByIds.length > 0) {
+    properties['Blocked by'] = { relation: blockedByIds.map(id => ({ id })) };
+  }
+
+  const body = {
+    parent: { database_id: constants.DATABASE_ID },
+    properties,
+    children: content
+      ? [{ object: 'block', type: 'paragraph', paragraph: { rich_text: [{ type: 'text', text: { content } }] } }]
+      : [],
+  };
+
+  if (icon && typeof icon === 'string') {
+    body.icon = { type: 'emoji', emoji: icon };
+  }
+
+  const result = await http.post(token, '/v1/pages', body);
+
+  if (result?.object === 'error') {
+    process.stderr.write(`Notion API error: ${result.message || result.code}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(JSON.stringify({ id: result.id, url: result.url }) + '\n');
+}
+
+main().catch(err => {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+});