pm-skill 1.1.3 → 1.1.5

package/.env.example

@@ -1,17 +1,25 @@
 # === Linear ===
-# Settings > API > Personal API Keys 에서 발급
+# Get from: Linear > Settings > API > Personal API Keys
+# 발급: Linear > Settings > API > Personal API Keys
 LINEAR_API_KEY=lin_api_xxxxxxxx
 
-# setup 커맨드로 확인 가능
+# Discovered by `npx pm-skill init` (auto-detected)
+# `npx pm-skill init`으로 자동 감지됨
 LINEAR_DEFAULT_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+# Optional — discovered by `npx pm-skill init` or `select-project`
+# 선택사항 — init 또는 select-project로 자동 감지
 LINEAR_DEFAULT_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
-# === Notion ===
-# https://www.notion.so/my-integrations 에서 발급
+# === Notion (optional) ===
+# Get from: https://www.notion.so/my-integrations > New integration
+# 발급: https://www.notion.so/my-integrations > New integration
 NOTION_API_KEY=secret_xxxxxxxx
 
-# Notion에서 문서를 생성할 상위 페이지 ID
+# Parent page where docs are created — discovered by `npx pm-skill init`
+# 문서가 생성될 상위 페이지 — init으로 자동 감지
 NOTION_ROOT_PAGE_ID=xxxxxxxx
 
-# (선택) 버그 추적 DB ID — 설정 시 report-bug가 DB 엔트리로 생성
+# Optional — bug tracking DB ID (if omitted, bugs use pages instead)
+# 선택사항 — 버그 추적 DB ID (미설정 시 페이지로 생성)
 NOTION_BUG_DB_ID=xxxxxxxx

package/AGENTS.md

@@ -6,6 +6,32 @@ This file provides instructions for AI coding assistants (Codex, Claude Code, et
 
 A structured project management CLI that integrates Linear (issue tracking) and Notion (documentation). It enforces a config-driven workflow where only pre-defined labels, templates, and severity levels are allowed.
 
+## Prerequisites
+
+- Node.js 18 or higher (`node --version` to check)
+- Linear API key (get from: Linear > Settings > API > Personal API Keys)
+- Notion API key (optional, get from: https://www.notion.so/my-integrations)
+
+## First-Time Setup
+
+If `.env` does not exist in the project root, run initialization first:
+
+```bash
+# Step 1: Initialize (validates keys, creates .env, config.yml, SKILL.md, AGENTS.md)
+npx pm-skill init --linear-key <LINEAR_API_KEY> --notion-key <NOTION_API_KEY>
+
+# Step 2: Verify setup and label matching
+npx pm-skill setup
+
+# Step 3 (optional): Create missing labels in Linear
+npx pm-skill setup --sync
+```
+
+If init fails:
+- **"Linear API key validation failed"** — check the key at Linear > Settings > API
+- **"No pages shared"** — share a Notion page with the integration first (page menu > Connections)
+- **Network error** — check internet connection and retry
+
 ## How to Run Commands
 
 ```bash
@@ -21,8 +47,22 @@ npx pm-skill setup
 npx pm-skill setup --sync   # create missing labels in Linear
 ```
 
+### select-project
+List or switch the active Linear project.
+```bash
+npx pm-skill select-project                    # list projects
+npx pm-skill select-project "Project Name"     # switch
+```
+
+### select-page
+List or switch the active Notion root page.
+```bash
+npx pm-skill select-page                       # list pages
+npx pm-skill select-page "Page Name"           # switch
+```
+
 ### start-feature
-Create a Linear issue + Notion PRD page with bidirectional links.
+Create a Linear issue with a task checklist.
 ```bash
 npx pm-skill start-feature "<title>"
 ```
@@ -45,7 +85,6 @@ Set a relationship between two issues.
 ```bash
 npx pm-skill relate <issue1> <issue2> --type <related|similar>
 ```
-Default type: related.
 
 ### block
 Set a blocking dependency (issue1 blocks issue2).
@@ -53,6 +92,30 @@ Set a blocking dependency (issue1 blocks issue2).
 npx pm-skill block <blocker-issue> <blocked-issue>
 ```
 
+### push-doc
+Upload markdown to Notion. Optionally link to a Linear issue.
+```bash
+# From file
+npx pm-skill push-doc ./doc.md --title "Title" --parent <page-id> --issue <issue-id>
+
+# From content (AI agent use case)
+npx pm-skill push-doc --title "Title" --content "# Markdown..." --issue <issue-id>
+```
+
+### update-doc
+Replace existing Notion page content with new markdown.
+```bash
+npx pm-skill update-doc <page-id> ./updated.md
+npx pm-skill update-doc <page-id> --content "# Updated..."
+```
+
+### create-folder
+Create an empty Notion page as a category/folder.
+```bash
+npx pm-skill create-folder "Folder Name" --parent <page-id>
+# Returns page ID — use with push-doc --parent
+```
+
 ### attach-doc
 Attach a document URL to an issue with type validation.
 ```bash
@@ -65,21 +128,33 @@ Show issue details including children, relations, and attachments.
 npx pm-skill get <issue-id>
 ```
 
+### delete
+Delete issue(s) and their linked Notion pages.
+```bash
+npx pm-skill delete <issue-id>
+npx pm-skill delete <issue-id> --recursive    # also delete sub-issues
+```
+
 ## Configuration
 
 All config is per-project (CWD):
-- **`.env`** — API keys and IDs
+- **`.env`** — API keys and IDs (never commit this file)
 - **`config.yml`** — Labels, templates, priorities, severity mappings
 
 ## Workflow Patterns
 
 ### Feature Development
-1. `npx pm-skill start-feature "Feature Name"` — creates Linear issue + Notion PRD
+1. `npx pm-skill start-feature "Feature Name"` — creates Linear issue with checklist
 2. `npx pm-skill add-task ENG-XX "Sub-task 1"` — break down into sub-tasks
-3. `npx pm-skill relate ENG-XX ENG-YY` — link related issues
-4. `npx pm-skill attach-doc ENG-XX --url "..." --title "..." --type source-of-truth`
+3. `npx pm-skill push-doc ./design.md --issue ENG-XX` — upload docs when ready
+4. `npx pm-skill relate ENG-XX ENG-YY` — link related issues
 
 ### Bug Fix
 1. `npx pm-skill report-bug "Bug Description" --severity high`
 2. `npx pm-skill add-task ENG-XX "Root cause analysis"`
 3. `npx pm-skill add-task ENG-XX "Fix and test"`
+
+### Document Management
+1. `npx pm-skill create-folder "Schema Docs"` — create category
+2. `npx pm-skill push-doc ./schema.md --parent <folder-id>` — upload under category
+3. `npx pm-skill update-doc <page-id> ./schema-v2.md` — update later

package/README.md

@@ -15,6 +15,12 @@ Structured project management CLI that integrates **Linear** and **Notion**. Des
 - **attach-doc** — Attach documents with type validation
 - **get** — View issue details with children, relations, and attachments
 
+## Prerequisites
+
+- **Node.js 18+** — check with `node --version`
+- **Linear API key** — Linear > Settings > API > Personal API Keys
+- **Notion API key** (optional) — https://www.notion.so/my-integrations
+
 ## Quick Start
 
 ```bash
@@ -122,6 +128,10 @@ npx pm-skill start-feature "My Feature"
 | `doc_types` | Document types for attach-doc validation |
 | `epics` | Epic definitions (project-specific) |
 
+## Security
+
+`.env` contains API keys — **never commit it to git**. The `init` command creates `.env` locally, and it's already in `.gitignore`.
+
 ## Per-Project Model
 
 All config is per-project. Each project gets its own `.env`, `config.yml`, and instruction files. Run `npx pm-skill init` in each project directory.

package/SKILL.md

@@ -3,6 +3,10 @@
 Linear + Notion integration for structured project management.
 "Design freedom, usage discipline" — only labels/templates/severity defined in `config.yml` are allowed.
 
+## Prerequisites
+
+Requires Node.js 18+. If `.env` does not exist in the project, run `init` first.
+
 ## Setup
 
 ```bash

package/config.yml

@@ -30,32 +30,27 @@ labels:
 
 templates:
   - id: feature
-    name: Feature PRD
-    description: "기능 개발용 PRD 템플릿"
-    notion_template: feature-prd
+    name: Feature
+    description: "기능 개발 템플릿"
     linear_labels: [dev]
     linear_priority: p2
   - id: bugfix
-    name: Bug Report
-    description: "버그 리포트 템플릿"
-    notion_template: bug-report
+    name: Bug Fix
+    description: "버그 수정 템플릿"
     linear_labels: [bug]
   - id: improvement
     name: Improvement
     description: "기존 기능 개선 템플릿"
-    notion_template: improvement
     linear_labels: [dev]
     linear_priority: p2
   - id: refactor
     name: Refactor
     description: "리팩토링 템플릿"
-    notion_template: refactor
     linear_labels: [refactor]
     linear_priority: p3
   - id: design
-    name: Design Doc
+    name: Design
     description: "설계 문서 템플릿"
-    notion_template: design-doc
     linear_labels: [design, plan]
     linear_priority: p2
 

package/dist/config.d.ts

@@ -8,7 +8,6 @@ export interface PmTemplate {
     id: string;
     name: string;
     description: string;
-    notion_template: string;
     linear_labels: string[];
     linear_priority?: string;
 }

package/dist/config.js

@@ -26,8 +26,8 @@ function validateTemplates(templates, labelIds) {
         throw new ConfigValidationError("templates array is empty or missing.");
     }
     for (const tmpl of templates) {
-        if (!tmpl.id || !tmpl.name || !tmpl.description || !tmpl.notion_template) {
-            throw new ConfigValidationError(`Template '${tmpl.id ?? "(unknown)"}' is missing required fields (id, name, description, notion_template).`);
+        if (!tmpl.id || !tmpl.name || !tmpl.description) {
+            throw new ConfigValidationError(`Template '${tmpl.id ?? "(unknown)"}' is missing required fields (id, name, description).`);
         }
         if (Array.isArray(tmpl.linear_labels)) {
             for (const lid of tmpl.linear_labels) {

package/dist/env.js

@@ -20,7 +20,6 @@ export function resolveFile(filename) {
     return null;
 }
 const REQUIRED_KEYS = ["LINEAR_API_KEY", "LINEAR_DEFAULT_TEAM_ID"];
-const NOTION_KEYS = ["NOTION_API_KEY", "NOTION_ROOT_PAGE_ID"];
 const KEY_HELP = {
     LINEAR_API_KEY: "Linear > Settings > API > Personal API Keys",
     LINEAR_DEFAULT_TEAM_ID: "'npx pm-skill init' to discover your team ID",
@@ -66,13 +65,6 @@ export function validateEnv(command) {
                 missing.push(key);
         }
     }
-    const notionCommands = ["start-feature", "report-bug"];
-    if (notionCommands.includes(command)) {
-        for (const key of NOTION_KEYS) {
-            if (!process.env[key])
-                missing.push(key);
-        }
-    }
     if (missing.length > 0) {
         const hints = missing
             .map((k) => `  ${k}: ${KEY_HELP[k] ?? ""}`)

package/dist/notion.d.ts

@@ -9,29 +9,20 @@ export declare function validateNotionKey(apiKey: string): Promise<{
     id: string;
     name: string;
 }>;
-export declare function buildFeaturePRD(title: string, linearUrl: string): BlockObjectRequest[];
-export declare function buildBugReport(title: string, severity: string, linearUrl: string): BlockObjectRequest[];
-export declare function buildDesignDoc(title: string, linearUrl: string): BlockObjectRequest[];
-export declare function buildImprovement(title: string, linearUrl: string): BlockObjectRequest[];
-export declare function buildRefactor(title: string, linearUrl: string): BlockObjectRequest[];
-export declare function getTemplateBlocks(notionTemplate: string, title: string, linearUrl: string, severity?: string): BlockObjectRequest[];
-export declare function createPage(client: Client, parentPageId: string, title: string, blocks: BlockObjectRequest[]): Promise<{
-    id: string;
-    url: string;
-}>;
-export declare function createDatabaseEntry(client: Client, databaseId: string, properties: Record<string, unknown>): Promise<{
-    id: string;
-    url: string;
-}>;
-export declare function createTemplatedPage(client: Client, parentPageId: string, notionTemplate: string, title: string, linearUrl: string, severity?: string): Promise<{
-    id: string;
-    url: string;
-}>;
 export declare function getPage(client: Client, pageId: string): Promise<Record<string, unknown>>;
 export declare function searchPages(client: Client, query: string): Promise<Array<{
     id: string;
     title: string;
 }>>;
+/**
+ * Archive (delete) a Notion page by ID.
+ */
+export declare function deletePage(client: Client, pageId: string): Promise<void>;
+/**
+ * Extract Notion page ID from a Notion URL.
+ * Handles formats like: https://notion.so/abc123def456... or https://www.notion.so/workspace/Page-Title-abc123def456
+ */
+export declare function extractNotionPageId(url: string): string | null;
 /**
  * Convert markdown to Notion blocks.
  */

package/dist/notion.js

@@ -22,193 +22,7 @@ export async function validateNotionKey(apiKey) {
         throw new Error("Notion API key validation failed. Check your key at: https://www.notion.so/my-integrations");
     }
 }
-// ── Block Builders ──
-function text(content) {
-    return [{ type: "text", text: { content } }];
-}
-function heading1(content) {
-    return {
-        object: "block",
-        type: "heading_1",
-        heading_1: { rich_text: text(content) },
-    };
-}
-function heading2(content) {
-    return {
-        object: "block",
-        type: "heading_2",
-        heading_2: { rich_text: text(content) },
-    };
-}
-function paragraph(content) {
-    return {
-        object: "block",
-        type: "paragraph",
-        paragraph: { rich_text: text(content) },
-    };
-}
-function todo(content, checked = false) {
-    return {
-        object: "block",
-        type: "to_do",
-        to_do: { rich_text: text(content), checked },
-    };
-}
-function numberedItem(content) {
-    return {
-        object: "block",
-        type: "numbered_list_item",
-        numbered_list_item: { rich_text: text(content) },
-    };
-}
-function bookmark(url) {
-    return {
-        object: "block",
-        type: "bookmark",
-        bookmark: { url },
-    };
-}
-function divider() {
-    return {
-        object: "block",
-        type: "divider",
-        divider: {},
-    };
-}
-// ── Template Builders ──
-export function buildFeaturePRD(title, linearUrl) {
-    return [
-        heading2(`📋 ${title}`),
-        bookmark(linearUrl),
-        divider(),
-        heading1("목표"),
-        paragraph(""),
-        heading1("배경"),
-        paragraph(""),
-        heading1("요구사항"),
-        todo("요구사항 1"),
-        todo("요구사항 2"),
-        todo("요구사항 3"),
-        heading1("설계"),
-        paragraph(""),
-        heading1("테스트 계획"),
-        paragraph(""),
-    ];
-}
-export function buildBugReport(title, severity, linearUrl) {
-    return [
-        heading2(`🐛 ${title} (${severity})`),
-        bookmark(linearUrl),
-        divider(),
-        heading1("재현 단계"),
-        numberedItem("단계 1"),
-        numberedItem("단계 2"),
-        numberedItem("단계 3"),
-        heading1("예상 동작"),
-        paragraph(""),
-        heading1("실제 동작"),
-        paragraph(""),
-        heading1("환경"),
-        paragraph("OS / 브라우저 / 디바이스"),
-        heading1("해결 방안"),
-        paragraph(""),
-    ];
-}
-export function buildDesignDoc(title, linearUrl) {
-    return [
-        heading2(`📐 ${title}`),
-        bookmark(linearUrl),
-        divider(),
-        heading1("개요"),
-        paragraph(""),
-        heading1("제약 조건"),
-        paragraph(""),
-        heading1("옵션 비교"),
-        paragraph(""),
-        heading1("결정"),
-        paragraph(""),
-        heading1("후속 작업"),
-        todo("후속 작업 1"),
-        todo("후속 작업 2"),
-    ];
-}
-export function buildImprovement(title, linearUrl) {
-    return [
-        heading2(`✨ ${title}`),
-        bookmark(linearUrl),
-        divider(),
-        heading1("현재 상태"),
-        paragraph(""),
-        heading1("개선 목표"),
-        paragraph(""),
-        heading1("변경 사항"),
-        todo("변경 1"),
-        todo("변경 2"),
-        todo("변경 3"),
-        heading1("영향 범위"),
-        paragraph(""),
-    ];
-}
-export function buildRefactor(title, linearUrl) {
-    return [
-        heading2(`🔧 ${title}`),
-        bookmark(linearUrl),
-        divider(),
-        heading1("리팩토링 대상"),
-        paragraph(""),
-        heading1("현재 문제점"),
-        paragraph(""),
-        heading1("변경 계획"),
-        todo("단계 1"),
-        todo("단계 2"),
-        heading1("검증 방법"),
-        paragraph(""),
-    ];
-}
-// ── Template Dispatcher ──
-const TEMPLATE_BUILDERS = {
-    "feature-prd": buildFeaturePRD,
-    "bug-report": (t, u, s) => buildBugReport(t, s ?? "medium", u),
-    "design-doc": buildDesignDoc,
-    improvement: buildImprovement,
-    refactor: buildRefactor,
-};
-export function getTemplateBlocks(notionTemplate, title, linearUrl, severity) {
-    const builder = TEMPLATE_BUILDERS[notionTemplate];
-    if (!builder) {
-        const available = Object.keys(TEMPLATE_BUILDERS).join(", ");
-        throw new Error(`notion_template '${notionTemplate}'에 대한 빌더가 없습니다.\n등록된 템플릿: ${available}`);
-    }
-    return builder(title, linearUrl, severity);
-}
 // ── Page CRUD ──
-export async function createPage(client, parentPageId, title, blocks) {
-    const response = await client.pages.create({
-        parent: { page_id: parentPageId },
-        properties: {
-            title: { title: [{ text: { content: title } }] },
-        },
-        children: blocks,
-    });
-    return {
-        id: response.id,
-        url: `https://notion.so/${response.id.replace(/-/g, "")}`,
-    };
-}
-export async function createDatabaseEntry(client, databaseId, properties) {
-    const response = await client.pages.create({
-        parent: { database_id: databaseId },
-        properties: properties,
-    });
-    return {
-        id: response.id,
-        url: `https://notion.so/${response.id.replace(/-/g, "")}`,
-    };
-}
-export async function createTemplatedPage(client, parentPageId, notionTemplate, title, linearUrl, severity) {
-    const blocks = getTemplateBlocks(notionTemplate, title, linearUrl, severity);
-    return createPage(client, parentPageId, title, blocks);
-}
 export async function getPage(client, pageId) {
     return (await client.pages.retrieve({ page_id: pageId }));
 }
@@ -224,6 +38,26 @@ export async function searchPages(client, query) {
             "(untitled)",
     }));
 }
+// ── Page Deletion ──
+/**
+ * Archive (delete) a Notion page by ID.
+ */
+export async function deletePage(client, pageId) {
+    await client.pages.update({ page_id: pageId, archived: true });
+}
+/**
+ * Extract Notion page ID from a Notion URL.
+ * Handles formats like: https://notion.so/abc123def456... or https://www.notion.so/workspace/Page-Title-abc123def456
+ */
+export function extractNotionPageId(url) {
+    const match = url.match(/([a-f0-9]{32})(?:\?|$)/);
+    if (match) {
+        const raw = match[1];
+        // Format as UUID
+        return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
+    }
+    return null;
+}
 // ── Markdown Upload ──
 /**
  * Convert markdown to Notion blocks.

package/dist/workflows.js

@@ -5,7 +5,7 @@ import { resolve, dirname } from "path";
 import { validateEnv, writeEnvFile, PKG_ROOT } from "./env.js";
 import { loadConfig, getTemplate, resolvePriority, resolveSeverity, validateDocType, validateLabel, } from "./config.js";
 import { getLinearClient, validateLinearKey, createIssue, deleteIssue, getIssue, getIssueDetail, createRelation, createAttachment, createLabel, getTeams, getTeamStates, getTeamLabels, getTeamProjects, resolveLabels, } from "./linear.js";
-import { getNotionClient, createTemplatedPage, createDatabaseEntry, validateNotionKey, searchPages, createPageFromMarkdown, updatePageContent, } from "./notion.js";
+import { getNotionClient, validateNotionKey, searchPages, createPageFromMarkdown, updatePageContent, deletePage, extractNotionPageId, } from "./notion.js";
 // ── Init ──
 function copyBundledFile(srcName, destPath) {
     if (existsSync(destPath)) {
@@ -243,23 +243,22 @@ async function startFeature(ctx, args) {
     const priority = tmpl.linear_priority
         ? resolvePriority(ctx.config, tmpl.linear_priority)
         : undefined;
+    const description = [
+        `## Tasks`,
+        `- [ ] Implementation`,
+        `- [ ] Write/update documentation (\`push-doc\`)`,
+        `- [ ] Tests`,
+        `- [ ] Review`,
+    ].join("\n");
     const issue = await createIssue(ctx.linear, {
         teamId: ctx.env.LINEAR_DEFAULT_TEAM_ID,
         title,
+        description,
         priority,
         labelIds,
         projectId: ctx.env.LINEAR_DEFAULT_PROJECT_ID,
     });
-    console.log(`[Linear] Issue created: ${issue.identifier} — ${issue.url}`);
-    if (!ctx.notion || !ctx.env.NOTION_ROOT_PAGE_ID) {
-        console.log("[Notion] Not configured — skipping page creation");
-        return;
-    }
-    const page = await createTemplatedPage(ctx.notion, ctx.env.NOTION_ROOT_PAGE_ID, tmpl.notion_template, title, issue.url);
-    console.log(`[Notion] Page created: ${page.url}`);
-    await createAttachment(ctx.linear, issue.id, page.url, `${title} — PRD`);
-    console.log(`[Link] Linear ↔ Notion linked`);
-    console.log(`\n✅ Feature started: ${issue.identifier} | Notion: ${page.url}`);
+    console.log(`✅ Feature started: ${issue.identifier} — ${issue.url}`);
 }
 async function reportBug(ctx, args) {
     const title = args._[0];
@@ -272,38 +271,25 @@ async function reportBug(ctx, args) {
     const teamLabels = await getTeamLabels(ctx.linear, ctx.env.LINEAR_DEFAULT_TEAM_ID);
     const configLabels = tmpl.linear_labels.map((lid) => validateLabel(ctx.config, lid).name);
     const labelIds = resolveLabels(configLabels, teamLabels);
+    const description = [
+        `**Severity: ${severity}**`,
+        ``,
+        `## Tasks`,
+        `- [ ] Reproduce`,
+        `- [ ] Root cause analysis`,
+        `- [ ] Fix & write tests`,
+        `- [ ] Write/update documentation (\`push-doc\`)`,
+        `- [ ] Review`,
+    ].join("\n");
     const issue = await createIssue(ctx.linear, {
         teamId: ctx.env.LINEAR_DEFAULT_TEAM_ID,
         title,
+        description,
         priority,
         labelIds,
         projectId: ctx.env.LINEAR_DEFAULT_PROJECT_ID,
     });
-    console.log(`[Linear] Bug created: ${issue.identifier} (severity: ${severity}) — ${issue.url}`);
-    if (!ctx.notion) {
-        console.log("[Notion] Not configured — skipping");
-        return;
-    }
-    let notionUrl;
-    if (ctx.env.NOTION_BUG_DB_ID) {
-        const entry = await createDatabaseEntry(ctx.notion, ctx.env.NOTION_BUG_DB_ID, {
-            Name: { title: [{ text: { content: title } }] },
-        });
-        notionUrl = entry.url;
-        console.log(`[Notion] Bug DB entry: ${notionUrl}`);
-    }
-    else if (ctx.env.NOTION_ROOT_PAGE_ID) {
-        const page = await createTemplatedPage(ctx.notion, ctx.env.NOTION_ROOT_PAGE_ID, tmpl.notion_template, title, issue.url, severity);
-        notionUrl = page.url;
-        console.log(`[Notion] Bug report page: ${notionUrl}`);
-    }
-    else {
-        console.log("[Notion] NOTION_ROOT_PAGE_ID not set — skipping");
-        return;
-    }
-    await createAttachment(ctx.linear, issue.id, notionUrl, `${title} — Bug Report`);
-    console.log(`[Link] Linear ↔ Notion linked`);
-    console.log(`\n✅ Bug reported: ${issue.identifier} | Notion: ${notionUrl}`);
+    console.log(`✅ Bug reported: ${issue.identifier} (severity: ${severity}) — ${issue.url}`);
 }
 async function addTask(ctx, args) {
     const parentIdentifier = args._[0];
@@ -394,39 +380,49 @@ async function get(ctx, args) {
     }
 }
 async function pushDoc(ctx, args) {
-    const identifier = args._[0];
-    const filePath = args._[1];
+    const filePath = args._[0];
     const content = args.content;
     const title = args.title;
-    if (!identifier || (!filePath && !content)) {
-        throw new Error("Usage: npx pm-skill push-doc <issue> <file.md> [--title T]\n" +
-            "       npx pm-skill push-doc <issue> --title T --content \"# Markdown...\"");
+    const parentPageId = args.parent;
+    const issueId = args.issue;
+    if (!filePath && !content) {
+        throw new Error("Usage: npx pm-skill push-doc <file.md> [--title T] [--parent P] [--issue I]\n" +
+            "       npx pm-skill push-doc --title T --content \"# md\" [--parent P] [--issue I]");
     }
-    if (!ctx.notion || !ctx.env.NOTION_ROOT_PAGE_ID) {
+    if (!ctx.notion) {
         throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
     }
+    const targetParent = parentPageId ?? ctx.env.NOTION_ROOT_PAGE_ID;
+    if (!targetParent) {
+        throw new Error("No Notion parent page. Set NOTION_ROOT_PAGE_ID or use --parent <page-id>.");
+    }
     // Read markdown
     let markdown;
-    if (filePath) {
-        if (!existsSync(filePath)) {
-            throw new Error(`File not found: ${filePath}`);
-        }
+    if (filePath && !existsSync(filePath) && !content) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    if (filePath && existsSync(filePath)) {
         markdown = readFileSync(filePath, "utf-8");
     }
-    else {
+    else if (content) {
         markdown = content;
     }
+    else {
+        throw new Error("Provide a file path or --content.");
+    }
     // Determine title
     const docTitle = title ?? (filePath ? filePath.replace(/^.*[\\/]/, "").replace(/\.md$/, "") : "Untitled");
-    // Get Linear issue for linking
-    const issue = await getIssue(ctx.linear, identifier);
     // Create Notion page
-    const page = await createPageFromMarkdown(ctx.notion, ctx.env.NOTION_ROOT_PAGE_ID, docTitle, markdown);
+    const page = await createPageFromMarkdown(ctx.notion, targetParent, docTitle, markdown);
     console.log(`[Notion] Page created: "${docTitle}" — ${page.url}`);
-    // Link to Linear issue
-    await createAttachment(ctx.linear, issue.id, page.url, docTitle, "source-of-truth");
-    console.log(`[Link] Attached to ${issue.identifier}`);
-    console.log(`\n✅ Document pushed: ${issue.identifier} | ${page.url}`);
+    console.log(`[Notion] Page ID: ${page.id}`);
+    // Optionally link to Linear issue
+    if (issueId) {
+        const issue = await getIssue(ctx.linear, issueId);
+        await createAttachment(ctx.linear, issue.id, page.url, docTitle, "source-of-truth");
+        console.log(`[Link] Attached to ${issue.identifier}`);
+    }
+    console.log(`\n✅ Document pushed: ${page.url}`);
 }
 async function updateDoc(ctx, args) {
     const pageId = args._[0];
@@ -452,15 +448,169 @@ async function updateDoc(ctx, args) {
     await updatePageContent(ctx.notion, pageId, markdown);
     console.log(`✅ Page updated: ${pageId}`);
 }
+async function createFolder(ctx, args) {
+    const folderName = args._[0];
+    const parentPageId = args.parent;
+    if (!folderName) {
+        throw new Error("Usage: npx pm-skill create-folder <name> [--parent <page-id>]");
+    }
+    if (!ctx.notion) {
+        throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
+    }
+    const targetParent = parentPageId ?? ctx.env.NOTION_ROOT_PAGE_ID;
+    if (!targetParent) {
+        throw new Error("No Notion parent page. Set NOTION_ROOT_PAGE_ID or use --parent <page-id>.");
+    }
+    const response = await ctx.notion.pages.create({
+        parent: { page_id: targetParent },
+        properties: {
+            title: { title: [{ text: { content: folderName } }] },
+        },
+        children: [],
+    });
+    const pageId = response.id;
+    const url = `https://notion.so/${pageId.replace(/-/g, "")}`;
+    console.log(`✅ Folder created: "${folderName}"`);
+    console.log(`   Page ID: ${pageId}`);
+    console.log(`   URL: ${url}`);
+    console.log(`\nUse with: npx pm-skill push-doc <issue> <file> --parent ${pageId}`);
+}
 async function del(ctx, args) {
     const identifiers = args._;
+    const recursive = !!args.recursive;
     if (identifiers.length === 0) {
-        throw new Error("Usage: npx pm-skill delete <issue> [issue2 ...]");
+        throw new Error("Usage: npx pm-skill delete <issue> [issue2 ...] [--recursive]");
     }
     for (const identifier of identifiers) {
-        const issue = await getIssue(ctx.linear, identifier);
-        await deleteIssue(ctx.linear, issue.id);
-        console.log(`✅ Deleted: ${issue.identifier} (${issue.title})`);
+        const detail = await getIssueDetail(ctx.linear, identifier);
+        // Check for children
+        if (detail.children.length > 0 && !recursive) {
+            console.log(`⚠️  ${detail.issue.identifier} has ${detail.children.length} sub-issue(s):`);
+            for (const child of detail.children) {
+                console.log(`    ${child.identifier}: ${child.title}`);
+            }
+            throw new Error(`Use --recursive to delete ${detail.issue.identifier} and its sub-issues.`);
+        }
+        // Recursively delete children first
+        if (detail.children.length > 0 && recursive) {
+            for (const child of detail.children) {
+                const childDetail = await getIssueDetail(ctx.linear, child.identifier);
+                // Delete child's Notion pages
+                if (ctx.notion) {
+                    for (const att of childDetail.attachments) {
+                        if (att.url.includes("notion.so")) {
+                            const pageId = extractNotionPageId(att.url);
+                            if (pageId) {
+                                try {
+                                    await deletePage(ctx.notion, pageId);
+                                    console.log(`  [Notion] Deleted: ${att.title}`);
+                                }
+                                catch { /* skip */ }
+                            }
+                        }
+                    }
+                }
+                await deleteIssue(ctx.linear, child.id);
+                console.log(`  Deleted sub-issue: ${child.identifier}`);
+            }
+        }
+        // Delete linked Notion pages
+        if (ctx.notion && detail.attachments.length > 0) {
+            for (const att of detail.attachments) {
+                if (att.url.includes("notion.so")) {
+                    const pageId = extractNotionPageId(att.url);
+                    if (pageId) {
+                        try {
+                            await deletePage(ctx.notion, pageId);
+                            console.log(`  [Notion] Deleted: ${att.title}`);
+                        }
+                        catch {
+                            console.log(`  [Notion] Could not delete: ${att.url}`);
+                        }
+                    }
+                }
+            }
+        }
+        // Delete Linear issue
+        await deleteIssue(ctx.linear, detail.issue.id);
+        console.log(`✅ Deleted: ${detail.issue.identifier} (${detail.issue.title})`);
+    }
+}
+async function selectProject(args) {
+    // Load env manually — we need API key and team ID but not project ID
+    const { loadEnvFile, writeEnvFile } = await import("./env.js");
+    loadEnvFile();
+    const apiKey = process.env.LINEAR_API_KEY;
+    const teamId = process.env.LINEAR_DEFAULT_TEAM_ID;
+    if (!apiKey || !teamId) {
+        throw new Error("LINEAR_API_KEY and LINEAR_DEFAULT_TEAM_ID must be set. Run 'npx pm-skill init' first.");
+    }
+    const client = getLinearClient(apiKey);
+    const projects = await getTeamProjects(client, teamId);
+    if (projects.length === 0) {
+        console.log("No projects found for this team.");
+        return;
+    }
+    const projectIdArg = args._[0];
+    if (projectIdArg) {
+        // Direct selection by ID or name
+        const match = projects.find((p) => p.id === projectIdArg || p.name.toLowerCase() === projectIdArg.toLowerCase());
+        if (!match) {
+            console.log("Available projects:");
+            for (const p of projects) {
+                console.log(`  ${p.name} | ${p.id}`);
+            }
+            throw new Error(`Project '${projectIdArg}' not found.`);
+        }
+        writeEnvFile(process.cwd(), { LINEAR_DEFAULT_PROJECT_ID: match.id });
+        console.log(`✅ Selected project: "${match.name}" (${match.id})`);
+    }
+    else {
+        // List projects with current marker
+        const currentId = process.env.LINEAR_DEFAULT_PROJECT_ID;
+        console.log("Available projects:");
+        for (const p of projects) {
+            const marker = p.id === currentId ? " ← current" : "";
+            console.log(`  ${p.name} | ${p.id}${marker}`);
+        }
+        console.log(`\nUsage: npx pm-skill select-project "<name or id>"`);
+    }
+}
+async function selectPage(args) {
+    const { loadEnvFile, writeEnvFile } = await import("./env.js");
+    loadEnvFile();
+    const apiKey = process.env.NOTION_API_KEY;
+    if (!apiKey) {
+        throw new Error("NOTION_API_KEY must be set. Run 'npx pm-skill init' with --notion-key first.");
+    }
+    const client = getNotionClient(apiKey);
+    const pages = await searchPages(client, "");
+    if (pages.length === 0) {
+        console.log("No pages shared with this integration.");
+        console.log("Share a page in Notion: page menu → Connections → add your integration");
+        return;
+    }
+    const pageArg = args._[0];
+    if (pageArg) {
+        const match = pages.find((p) => p.id === pageArg || p.title.toLowerCase() === pageArg.toLowerCase());
+        if (!match) {
+            console.log("Available pages:");
+            for (const p of pages) {
+                console.log(`  ${p.title} | ${p.id}`);
+            }
+            throw new Error(`Page '${pageArg}' not found.`);
+        }
+        writeEnvFile(process.cwd(), { NOTION_ROOT_PAGE_ID: match.id });
+        console.log(`✅ Selected page: "${match.title}" (${match.id})`);
+    }
+    else {
+        const currentId = process.env.NOTION_ROOT_PAGE_ID;
+        console.log("Available pages:");
+        for (const p of pages) {
+            const marker = p.id === currentId ? " ← current" : "";
+            console.log(`  ${p.title} | ${p.id}${marker}`);
+        }
+        console.log(`\nUsage: npx pm-skill select-page "<name or id>"`);
     }
 }
 // ── Command Registry ──
@@ -474,14 +624,15 @@ const COMMANDS = {
     "attach-doc": attachDoc,
     "push-doc": pushDoc,
     "update-doc": updateDoc,
+    "create-folder": createFolder,
     delete: del,
     get,
 };
 // ── Main ──
 async function main() {
     const args = minimist(process.argv.slice(2), {
-        string: ["severity", "type", "url", "title", "content", "linear-key", "notion-key", "team-id", "project-id", "notion-page"],
-        boolean: ["sync", "version"],
+        string: ["severity", "type", "url", "title", "content", "parent", "issue", "linear-key", "notion-key", "team-id", "project-id", "notion-page"],
+        boolean: ["sync", "version", "recursive"],
         alias: { s: "severity", t: "type" },
     });
     // --version
@@ -501,7 +652,9 @@ Commands:
   init --linear-key K [--notion-key K]
                                      Initialize project (validates keys, creates .env, config.yml, SKILL.md, AGENTS.md)
   setup [--sync]                     Verify config & label matching (--sync creates missing labels)
-  start-feature <title>              Start feature (Linear issue + Notion PRD)
+  select-project [name-or-id]        List or switch Linear project
+  select-page [name-or-id]           List or switch Notion root page
+  start-feature <title>              Start feature (Linear issue with task checklist)
   report-bug <title> [--severity S]  File bug report (severity: urgent/high/medium/low)
   add-task <parent> <title>          Add sub-task to an issue
   relate <issue1> <issue2> [--type T]  Link issues (type: related/similar)
@@ -509,25 +662,35 @@ Commands:
   attach-doc <issue> --url U --title T --type Y
                                      Attach document (type: source-of-truth/issue-tracking/domain-knowledge)
   get <issue>                        Show issue details
-  push-doc <issue> <file.md> [--title T]
-                                     Upload markdown to Notion + link to issue
-  push-doc <issue> --title T --content "# md"
+  push-doc <file.md> [--title T] [--parent P] [--issue I]
+                                     Upload markdown to Notion (optionally link to issue)
+  push-doc --title T --content "# md" [--parent P] [--issue I]
                                      Push content directly (for AI agents)
   update-doc <page-id> <file.md>     Replace Notion page content with markdown
   update-doc <page-id> --content "# md"
                                      Replace content directly
-  delete <issue> [issue2 ...]        Delete issue(s)
+  create-folder <name> [--parent P]  Create Notion folder (returns page ID for --parent)
+  delete <issue> [issue2 ...] [--recursive]
+                                     Delete issue(s) + linked Notion pages (--recursive for sub-issues)
   help                               Show this help
   --version                          Show version
 
 All config is per-project (CWD). Run 'npx pm-skill init' in each project.`);
         return;
     }
-    // init runs independently — no env/config validation
+    // These commands run independently — no full env/config validation
     if (command === "init") {
         await init(args);
         return;
     }
+    if (command === "select-project") {
+        await selectProject(args);
+        return;
+    }
+    if (command === "select-page") {
+        await selectPage(args);
+        return;
+    }
     const cmdFn = COMMANDS[command];
     if (!cmdFn) {
         const available = ["init", ...Object.keys(COMMANDS)].join(", ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-skill",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Structured project management CLI — Linear + Notion integration for AI coding assistants (Claude Code, Codex)",
   "type": "module",
   "bin": {