pm-skill 1.1.4 → 1.1.6

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,38 @@ 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.
 
+## Rules
+
+- If the user writes `/pm-skill <args>`, execute `npx pm-skill <args>` from the project root.
+- When the user mentions pm-skill, Linear issues, or Notion documents, prefer using pm-skill commands.
+- This tool requires shell execution and network access (Linear/Notion APIs).
+
+## 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 +53,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 +91,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 +98,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 +134,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

@@ -1,8 +1,24 @@
+---
+name: pm-skill
+description: Structured project management CLI — Linear + Notion integration. Trigger on: pm-skill, Linear issue, Notion doc, start-feature, report-bug, push-doc, backlog
+---
+
 # PM Skill — Structured Project Management
 
 Linear + Notion integration for structured project management.
 "Design freedom, usage discipline" — only labels/templates/severity defined in `config.yml` are allowed.
 
+## Rules
+
+- When the user mentions **pm-skill**, **Linear issue**, **Notion document**, **start-feature**, **report-bug**, **backlog**, or **push-doc**, use this skill.
+- If the user writes `/pm-skill <args>`, execute `npx pm-skill <args>` from the project root.
+- This skill requires **shell execution** and **network access** (Linear/Notion APIs).
+- If `.env` does not exist, run `npx pm-skill init` first.
+
+## Prerequisites
+
+Requires Node.js 18+. If `.env` does not exist in the project, run `init` first.
+
 ## Setup
 
 ```bash
@@ -14,6 +30,9 @@ npx pm-skill setup
 
 # Create missing labels in Linear
 npx pm-skill setup --sync
+
+# Install as Codex global skill (optional)
+npx pm-skill install-codex-skill
 ```
 
 ## Commands
@@ -24,8 +43,15 @@ Verify Linear/Notion connection + label matching. `--sync` creates missing label
 npx pm-skill setup
 ```
 
+### select-project / select-page
+Switch active Linear project or Notion root page.
+```bash
+npx pm-skill select-project "Project Name"
+npx pm-skill select-page "Page Name"
+```
+
 ### start-feature
-Start feature development. Creates Linear issue + Notion PRD + bidirectional links.
+Start feature development. Creates Linear issue with task checklist.
 ```bash
 npx pm-skill start-feature "Feature title"
 ```
@@ -43,20 +69,41 @@ Add sub-task to an issue.
 npx pm-skill add-task ENG-10 "Write unit tests"
 ```
 
-### relate
-Link two issues. (related, similar)
+### relate / block
+Link or set blocking relationship between issues.
 ```bash
 npx pm-skill relate ENG-10 ENG-11 --type related
+npx pm-skill block ENG-10 ENG-11
 ```
 
-### block
-Set blocking relationship. (ENG-10 must complete before ENG-11)
+### push-doc
+Upload markdown to Notion. Optionally link to a Linear issue.
 ```bash
-npx pm-skill block ENG-10 ENG-11
+# From file
+npx pm-skill push-doc ./design.md --title "Design Doc" --issue ENG-10
+
+# From content (AI agent use case)
+npx pm-skill push-doc --title "Report" --content "# Results..." --issue ENG-10
+
+# Under a specific parent page
+npx pm-skill push-doc ./schema.md --parent <page-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 Notion page as a category/folder.
+```bash
+npx pm-skill create-folder "Schema Docs" --parent <page-id>
 ```
 
 ### attach-doc
-Attach document URL to issue. Type is validated against config.
+Attach a document URL to an issue with type validation.
 ```bash
 npx pm-skill attach-doc ENG-10 \
   --url "https://notion.so/..." \
@@ -71,6 +118,13 @@ Show issue details including sub-issues, relations, and attachments.
 npx pm-skill get ENG-10
 ```
 
+### delete
+Delete issue(s) and linked Notion pages.
+```bash
+npx pm-skill delete ENG-10
+npx pm-skill delete ENG-10 --recursive   # also delete sub-issues
+```
+
 ## Workflow Examples
 
 ### Feature Development
@@ -78,9 +132,8 @@ npx pm-skill get ENG-10
 npx pm-skill start-feature "Booking cancellation"
 npx pm-skill add-task ENG-10 "API endpoint"
 npx pm-skill add-task ENG-10 "Frontend UI"
-npx pm-skill add-task ENG-10 "Tests"
+npx pm-skill push-doc ./design.md --issue ENG-10
 npx pm-skill relate ENG-10 ENG-8 --type related
-npx pm-skill block ENG-10 ENG-15
 ```
 
 ### Bug Fix
@@ -90,13 +143,9 @@ npx pm-skill add-task ENG-20 "Root cause analysis"
 npx pm-skill add-task ENG-20 "Fix and test"
 ```
 
-## Config
-
-| Section | Description |
-|---------|-------------|
-| `labels` | Available labels (description required) |
-| `templates` | Command → label/priority/Notion template mappings |
-| `priorities` | p0-p3 → Linear priority mapping |
-| `severity_mapping` | severity name → priority key |
-| `doc_types` | Document types for attach-doc |
-| `epics` | Epic definitions |
+### Document Management
+```bash
+npx pm-skill create-folder "Schema Docs"
+npx pm-skill push-doc ./schema.md --parent <folder-id>
+npx pm-skill update-doc <page-id> ./schema-v2.md
+```

package/config.yml

@@ -19,43 +19,29 @@ labels:
     name: Refactor
     description: "기존 코드 리팩토링 (기능 변경 없음)"
     color: "#888888"
-  - id: admin
-    name: Admin
-    description: "인프라, 배포, 환경 설정 등 관리 작업"
-    color: "#ffaa00"
-  - id: guest
-    name: Guest
-    description: "외부 의존성, 서드파티 연동 관련"
-    color: "#aa88ff"
-
 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,24 +9,6 @@ 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;

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 }));
 }

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, deletePage, extractNotionPageId, } from "./notion.js";
+import { getNotionClient, validateNotionKey, searchPages, createPageFromMarkdown, updatePageContent, deletePage, extractNotionPageId, } from "./notion.js";
 // ── Init ──
 function copyBundledFile(srcName, destPath) {
     if (existsSync(destPath)) {
@@ -243,24 +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(`   Notion Page ID: ${page.id} (use with --parent for sub-docs)`);
+    console.log(`✅ Feature started: ${issue.identifier} — ${issue.url}`);
 }
 async function reportBug(ctx, args) {
     const title = args._[0];
@@ -273,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];
@@ -395,14 +380,14 @@ 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;
     const parentPageId = args.parent;
-    if (!identifier || (!filePath && !content)) {
-        throw new Error("Usage: npx pm-skill push-doc <issue> <file.md> [--title T] [--parent P]\n" +
-            "       npx pm-skill push-doc <issue> --title T --content \"# md\" [--parent P]");
+    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) {
         throw new Error("Notion is not configured. Run 'npx pm-skill init' with --notion-key.");
@@ -413,27 +398,31 @@ async function pushDoc(ctx, args) {
     }
     // 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 under specified parent
+    // Create Notion page
     const page = await createPageFromMarkdown(ctx.notion, targetParent, docTitle, markdown);
     console.log(`[Notion] Page created: "${docTitle}" — ${page.url}`);
     console.log(`[Notion] Page ID: ${page.id}`);
-    // 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}`);
+    // 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];
@@ -488,11 +477,43 @@ async function createFolder(ctx, args) {
 }
 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 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) {
@@ -504,7 +525,7 @@ async function del(ctx, args) {
                             console.log(`  [Notion] Deleted: ${att.title}`);
                         }
                         catch {
-                            console.log(`  [Notion] Could not delete: ${att.url} (may already be deleted or no access)`);
+                            console.log(`  [Notion] Could not delete: ${att.url}`);
                         }
                     }
                 }
@@ -555,6 +576,51 @@ async function selectProject(args) {
         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>"`);
+    }
+}
+async function installCodexSkill() {
+    const { homedir } = await import("os");
+    const targetDir = resolve(homedir(), ".codex", "skills", "pm-skill");
+    const targetPath = resolve(targetDir, "SKILL.md");
+    copyBundledFile("SKILL.md", targetPath);
+    console.log(`\n✅ Codex skill installed: ${targetPath}`);
+    console.log(`   Restart Codex to pick up the new skill.`);
+}
 // ── Command Registry ──
 const COMMANDS = {
     setup: (ctx, args) => setup(ctx, args),
@@ -573,8 +639,8 @@ const COMMANDS = {
 // ── Main ──
 async function main() {
     const args = minimist(process.argv.slice(2), {
-        string: ["severity", "type", "url", "title", "content", "parent", "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
@@ -595,7 +661,9 @@ Commands:
                                      Initialize project (validates keys, creates .env, config.yml, SKILL.md, AGENTS.md)
   setup [--sync]                     Verify config & label matching (--sync creates missing labels)
   select-project [name-or-id]        List or switch Linear project
-  start-feature <title>              Start feature (Linear issue + Notion PRD)
+  select-page [name-or-id]           List or switch Notion root page
+  install-codex-skill                Install skill to ~/.codex/skills/ for Codex
+  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)
@@ -603,15 +671,16 @@ 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] [--parent P]
-                                     Upload markdown to Notion + link to issue
-  push-doc <issue> --title T --content "# md" [--parent P]
+  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
   create-folder <name> [--parent P]  Create Notion folder (returns page ID for --parent)
-  delete <issue> [issue2 ...]        Delete issue(s) + linked Notion pages
+  delete <issue> [issue2 ...] [--recursive]
+                                     Delete issue(s) + linked Notion pages (--recursive for sub-issues)
   help                               Show this help
   --version                          Show version
 
@@ -627,6 +696,14 @@ All config is per-project (CWD). Run 'npx pm-skill init' in each project.`);
         await selectProject(args);
         return;
     }
+    if (command === "select-page") {
+        await selectPage(args);
+        return;
+    }
+    if (command === "install-codex-skill") {
+        await installCodexSkill();
+        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.4",
+  "version": "1.1.6",
   "description": "Structured project management CLI — Linear + Notion integration for AI coding assistants (Claude Code, Codex)",
   "type": "module",
   "bin": {