pm-skill 1.0.0

package/.env.example

@@ -0,0 +1,17 @@
+# === Linear ===
+# Settings > API > Personal API Keys 에서 발급
+LINEAR_API_KEY=lin_api_xxxxxxxx
+
+# setup 커맨드로 확인 가능
+LINEAR_DEFAULT_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+LINEAR_DEFAULT_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+# === Notion ===
+# https://www.notion.so/my-integrations 에서 발급
+NOTION_API_KEY=secret_xxxxxxxx
+
+# Notion에서 문서를 생성할 상위 페이지 ID
+NOTION_ROOT_PAGE_ID=xxxxxxxx
+
+# (선택) 버그 추적 DB ID — 설정 시 report-bug가 DB 엔트리로 생성
+NOTION_BUG_DB_ID=xxxxxxxx

package/AGENTS.md

@@ -0,0 +1,87 @@
+# PM Skill — Agent Instructions
+
+This file provides instructions for AI coding assistants (Codex, Claude Code, etc.) to use the pm-skill CLI.
+
+## What is pm-skill?
+
+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.
+
+## How to Run Commands
+
+```bash
+# If installed globally via npm:
+pm-skill <command> [args] [flags]
+
+# If running from source:
+npx tsx src/workflows.ts <command> [args] [flags]
+```
+
+## Available Commands
+
+### setup
+Verify Linear/Notion connection and show team/label configuration.
+```bash
+pm-skill setup
+```
+
+### start-feature
+Create a Linear issue + Notion PRD page with bidirectional links.
+```bash
+pm-skill start-feature "<title>"
+```
+
+### report-bug
+File a bug report with severity-based priority mapping.
+```bash
+pm-skill report-bug "<title>" --severity <urgent|high|medium|low>
+```
+Default severity: medium.
+
+### add-task
+Add a sub-issue to a parent issue.
+```bash
+pm-skill add-task <parent-issue-id> "<title>"
+```
+
+### relate
+Set a relationship between two issues.
+```bash
+pm-skill relate <issue1> <issue2> --type <related|similar>
+```
+Default type: related.
+
+### block
+Set a blocking dependency (issue1 blocks issue2).
+```bash
+pm-skill block <blocker-issue> <blocked-issue>
+```
+
+### attach-doc
+Attach a document URL to an issue with type validation.
+```bash
+pm-skill attach-doc <issue> --url "<url>" --title "<title>" --type <source-of-truth|issue-tracking|domain-knowledge>
+```
+
+### get
+Show issue details including children, relations, and attachments.
+```bash
+pm-skill get <issue-id>
+```
+
+## Configuration
+
+- **`.env`** — API keys and IDs. Looked up in: CWD → `~/.pm-skill/` → package root.
+- **`config.yml`** — Labels, templates, priorities, severity mappings. Same lookup order.
+
+## Workflow Patterns
+
+### Feature Development
+1. `start-feature "Feature Name"` — creates Linear issue + Notion PRD
+2. `add-task ENG-XX "Sub-task 1"` — break down into sub-tasks
+3. `relate ENG-XX ENG-YY` — link related issues
+4. `attach-doc ENG-XX --url "..." --title "..." --type source-of-truth`
+
+### Bug Fix
+1. `report-bug "Bug Description" --severity high`
+2. `add-task ENG-XX "Root cause analysis"`
+3. `add-task ENG-XX "Fix and test"`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lsm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# pm-skill
+
+Structured project management CLI that integrates **Linear** and **Notion**. Designed to work with AI coding assistants — Claude Code, Codex, and any tool that can run shell commands.
+
+> "Design freedom, usage discipline" — only labels, templates, and severity levels defined in `config.yml` are allowed.
+
+## Features
+
+- **start-feature** — Create Linear issue + Notion PRD page, auto-linked
+- **report-bug** — File bug with severity-based priority mapping
+- **add-task** — Add sub-issues to a parent
+- **relate / block** — Set issue relationships and dependencies
+- **attach-doc** — Attach documents with type validation
+- **get** — View issue details with children, relations, and attachments
+- **setup** — Verify connections and discover team/label IDs
+
+## Installation
+
+### Option A: npm (recommended)
+
+```bash
+npm install -g pm-skill
+pm-skill help
+```
+
+### Option B: npx (no install)
+
+```bash
+npx pm-skill help
+```
+
+### Option C: Clone as Claude Code skill
+
+```bash
+git clone https://github.com/Leonamin/pm-skill.git ~/.claude/skills/pm-skill
+cd ~/.claude/skills/pm-skill && npm install
+```
+
+### Option D: Clone for Codex
+
+```bash
+git clone https://github.com/Leonamin/pm-skill.git ~/pm-skill
+cd ~/pm-skill && npm install
+# Codex will read AGENTS.md for instructions
+```
+
+## Setup
+
+### 1. Create `.env`
+
+Place `.env` in any of these locations (checked in order):
+1. Current working directory
+2. `~/.pm-skill/`
+3. Package root
+
+```bash
+# Copy the template
+cp .env.example ~/.pm-skill/.env
+# Edit with your API keys
+```
+
+```env
+LINEAR_API_KEY=lin_api_xxxxxxxx
+LINEAR_DEFAULT_TEAM_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+NOTION_API_KEY=secret_xxxxxxxx
+NOTION_ROOT_PAGE_ID=xxxxxxxx
+```
+
+### 2. Run setup
+
+```bash
+pm-skill setup
+```
+
+This shows your Linear teams, workflow states, and labels — and verifies that `config.yml` labels match your Linear workspace.
+
+### 3. Customize `config.yml`
+
+Copy `config.yml` to `~/.pm-skill/config.yml` and edit labels, templates, priorities, and severity mappings to match your project.
+
+**Rule: every label and template must have a `description` field.**
+
+## Usage
+
+```bash
+# Start a feature
+pm-skill start-feature "Booking cancellation"
+
+# Report a bug
+pm-skill report-bug "Payment amount error" --severity high
+
+# Add sub-tasks
+pm-skill add-task ENG-10 "Write unit tests"
+pm-skill add-task ENG-10 "Frontend UI"
+
+# Link issues
+pm-skill relate ENG-10 ENG-8 --type related
+pm-skill block ENG-10 ENG-15
+
+# Attach documents
+pm-skill attach-doc ENG-10 --url "https://notion.so/..." --title "Design Doc" --type source-of-truth
+
+# View issue details
+pm-skill get ENG-10
+```
+
+## Using with AI Assistants
+
+### Claude Code
+
+If installed as a skill in `~/.claude/skills/pm-skill/`, Claude Code auto-discovers it via `SKILL.md`. You can invoke commands through natural language:
+
+> "Create a feature issue for booking cancellation"
+
+### Codex
+
+Clone the repo and Codex reads `AGENTS.md` for command instructions. Run commands via:
+
+```bash
+npx tsx src/workflows.ts start-feature "Booking cancellation"
+```
+
+### Any AI Assistant
+
+Any assistant that can execute shell commands can use pm-skill:
+
+```bash
+pm-skill start-feature "My Feature"
+```
+
+## Config Structure
+
+| Section | Description |
+|---------|-------------|
+| `labels` | Available labels (description required) |
+| `templates` | Command-to-label/priority/Notion-template mappings |
+| `priorities` | Priority key (p0-p3) to Linear priority number mapping |
+| `severity_mapping` | Severity name to priority key mapping |
+| `doc_types` | Document types for attach-doc validation |
+| `epics` | Epic definitions (project-specific) |
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,134 @@
+# PM Skill — 정형화된 프로젝트 관리 도구
+
+Linear와 Notion을 정형화된 틀 안에서 조작하는 프로젝트 관리 스킬.
+"설계의 자유, 사용의 부자유" — config.yml에 정의된 라벨/템플릿/severity만 사용 가능.
+
+## 설정
+
+### 1. API 키 발급
+
+**Linear**: Settings > API > Personal API Keys
+**Notion**: https://www.notion.so/my-integrations > New integration
+
+### 2. .env 생성
+
+```bash
+cp .env.example .env
+# LINEAR_API_KEY, NOTION_API_KEY 입력
+```
+
+### 3. Setup 실행
+
+```bash
+npx tsx src/workflows.ts setup
+```
+
+팀/상태/라벨 ID를 확인하고 `.env`에 `LINEAR_DEFAULT_TEAM_ID` 등을 설정.
+
+### 4. Config 커스터마이징
+
+`config.yml`에서 라벨, 템플릿, severity 매핑을 프로젝트에 맞게 수정.
+**규칙: 모든 라벨/템플릿에 `description` 필수.** 없으면 로딩 시 에러.
+
+```yaml
+labels:
+  - id: my-label
+    name: My Label
+    description: "이 라벨의 용도 설명"  # ← 필수!
+```
+
+## 커맨드 레퍼런스
+
+### setup
+Linear/Notion 연결 상태 확인 + .env 안내.
+```bash
+npx tsx src/workflows.ts setup
+```
+
+### start-feature
+기능 개발 시작. Linear 이슈 + Notion PRD + 상호 URL 연결.
+```bash
+npx tsx src/workflows.ts start-feature "예약 취소 기능"
+```
+
+### report-bug
+버그 리포트. severity로 우선순위 자동 매핑.
+```bash
+npx tsx src/workflows.ts report-bug "결제 금액 오류" --severity high
+# severity: urgent, high, medium(기본), low
+```
+
+### add-task
+이슈에 하위 태스크 추가.
+```bash
+npx tsx src/workflows.ts add-task ENG-10 "단위 테스트 작성"
+```
+
+### relate
+이슈 간 관계 설정. (related, similar)
+```bash
+npx tsx src/workflows.ts relate ENG-10 ENG-11 --type related
+```
+
+### block
+선행 관계 설정. (ENG-10 완료 후 ENG-11 진행)
+```bash
+npx tsx src/workflows.ts block ENG-10 ENG-11
+```
+
+### attach-doc
+이슈에 문서 URL 첨부. doc_type은 config 검증.
+```bash
+npx tsx src/workflows.ts attach-doc ENG-10 \
+  --url "https://notion.so/..." \
+  --title "결제 설계서" \
+  --type source-of-truth
+# type: source-of-truth, issue-tracking, domain-knowledge
+```
+
+### get
+이슈 상세 조회. 하위이슈, 관계, 첨부문서 포함.
+```bash
+npx tsx src/workflows.ts get ENG-10
+```
+
+## 워크플로우 예시
+
+### 기능 개발
+```bash
+# 1. 기능 시작
+npx tsx src/workflows.ts start-feature "예약 취소 기능"
+# → Linear ENG-10 + Notion PRD 생성
+
+# 2. 하위 태스크 추가
+npx tsx src/workflows.ts add-task ENG-10 "API 엔드포인트 구현"
+npx tsx src/workflows.ts add-task ENG-10 "프론트엔드 UI"
+npx tsx src/workflows.ts add-task ENG-10 "테스트 작성"
+
+# 3. 관련 이슈 연결
+npx tsx src/workflows.ts relate ENG-10 ENG-8 --type related
+
+# 4. 선행 관계 설정
+npx tsx src/workflows.ts block ENG-10 ENG-15
+```
+
+### 버그 수정
+```bash
+# 1. 버그 리포트
+npx tsx src/workflows.ts report-bug "결제 금액 오류" --severity high
+
+# 2. 하위 태스크
+npx tsx src/workflows.ts add-task ENG-20 "원인 분석"
+npx tsx src/workflows.ts add-task ENG-20 "수정 및 테스트"
+```
+
+## Config 구조
+
+| 섹션 | 설명 |
+|------|------|
+| `labels` | 사용 가능한 라벨 목록 (description 필수) |
+| `templates` | 커맨드별 기본 라벨/우선순위/Notion 템플릿 매핑 |
+| `priorities` | Plank 우선순위 → Linear 우선순위 매핑 (p0-p3) |
+| `severity_mapping` | severity 이름 → priority 키 매핑 |
+| `doc_types` | 문서 유형 (attach-doc의 --type 값) |
+| `epics` | 에픽 목록 (프로젝트별 정의) |

package/config.yml

@@ -0,0 +1,82 @@
+labels:
+  - id: dev
+    name: Development
+    description: "코드 개발 작업 (새 기능, 기존 기능 변경)"
+    color: "#0088ff"
+  - id: design
+    name: Design
+    description: "UI/UX 디자인 관련 작업"
+    color: "#ff00ff"
+  - id: plan
+    name: Planning
+    description: "기획, 설계, 의사결정 문서 작업"
+    color: "#00cc88"
+  - id: bug
+    name: Bug
+    description: "버그 수정"
+    color: "#ff0000"
+  - id: refactor
+    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
+    linear_labels: [dev]
+    linear_priority: p2
+  - id: bugfix
+    name: Bug Report
+    description: "버그 리포트 템플릿"
+    notion_template: bug-report
+    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
+    description: "설계 문서 템플릿"
+    notion_template: design-doc
+    linear_labels: [design, plan]
+    linear_priority: p2
+
+priorities:
+  p0: { linear: 1, name: "Urgent" }
+  p1: { linear: 2, name: "High" }
+  p2: { linear: 3, name: "Medium" }
+  p3: { linear: 4, name: "Low" }
+
+severity_mapping:
+  urgent: p0
+  high: p1
+  medium: p2
+  low: p3
+
+doc_types:
+  - id: source-of-truth
+    description: "진실의 원천 문서 — 프로젝트의 공식 기준이 되는 문서"
+  - id: issue-tracking
+    description: "장기 이슈 추적 문서 — 해결까지 시간이 걸리는 문제 기록"
+  - id: domain-knowledge
+    description: "도메인 지식 문서 — 프로젝트 도메인 관련 학습/참고 자료"
+
+epics: []

package/dist/config.d.ts

@@ -0,0 +1,40 @@
+export interface PmLabel {
+    id: string;
+    name: string;
+    description: string;
+    color?: string;
+}
+export interface PmTemplate {
+    id: string;
+    name: string;
+    description: string;
+    notion_template: string;
+    linear_labels: string[];
+    linear_priority?: string;
+}
+export interface PmPriority {
+    linear: number;
+    name: string;
+}
+export interface PmDocType {
+    id: string;
+    description: string;
+}
+export interface PmEpic {
+    id: string;
+    name: string;
+}
+export interface PmConfig {
+    labels: PmLabel[];
+    templates: PmTemplate[];
+    priorities: Record<string, PmPriority>;
+    severity_mapping: Record<string, string>;
+    doc_types: PmDocType[];
+    epics: PmEpic[];
+}
+export declare function loadConfig(configPath?: string): PmConfig;
+export declare function validateLabel(config: PmConfig, labelId: string): PmLabel;
+export declare function validateDocType(config: PmConfig, typeId: string): PmDocType;
+export declare function getTemplate(config: PmConfig, templateId: string): PmTemplate;
+export declare function resolvePriority(config: PmConfig, priorityKey: string): number;
+export declare function resolveSeverity(config: PmConfig, severity: string): number;

package/dist/config.js

@@ -0,0 +1,144 @@
+import { readFileSync } from "fs";
+import yaml from "js-yaml";
+import { resolveFile } from "./env.js";
+// ── Validation ──
+class ConfigValidationError extends Error {
+    constructor(message) {
+        super(`[Config validation failed] ${message}`);
+        this.name = "ConfigValidationError";
+    }
+}
+function validateLabels(labels) {
+    if (!Array.isArray(labels) || labels.length === 0) {
+        throw new ConfigValidationError("labels array is empty or missing.");
+    }
+    for (const label of labels) {
+        if (!label.id || !label.name) {
+            throw new ConfigValidationError(`Label missing id or name: ${JSON.stringify(label)}`);
+        }
+        if (!label.description) {
+            throw new ConfigValidationError(`Label '${label.id}' is missing description. All labels require a description.`);
+        }
+    }
+}
+function validateTemplates(templates, labelIds) {
+    if (!Array.isArray(templates) || templates.length === 0) {
+        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 (Array.isArray(tmpl.linear_labels)) {
+            for (const lid of tmpl.linear_labels) {
+                if (!labelIds.has(lid)) {
+                    throw new ConfigValidationError(`Template '${tmpl.id}' references unregistered label '${lid}' in linear_labels.`);
+                }
+            }
+        }
+    }
+}
+function validatePriorities(priorities) {
+    if (!priorities || typeof priorities !== "object") {
+        throw new ConfigValidationError("priorities is missing.");
+    }
+    for (const key of ["p0", "p1", "p2", "p3"]) {
+        const p = priorities[key];
+        if (!p ||
+            typeof p.linear !== "number" ||
+            typeof p.name !== "string") {
+            throw new ConfigValidationError(`priorities.${key} requires linear (number) and name (string).`);
+        }
+    }
+}
+function validateSeverityMapping(mapping, priorityKeys) {
+    if (!mapping || typeof mapping !== "object") {
+        throw new ConfigValidationError("severity_mapping is missing.");
+    }
+    for (const [severity, pKey] of Object.entries(mapping)) {
+        if (!priorityKeys.has(pKey)) {
+            throw new ConfigValidationError(`severity_mapping '${severity}: ${pKey}' — '${pKey}' is not defined in priorities.`);
+        }
+    }
+}
+function validateDocTypes(docTypes) {
+    if (!Array.isArray(docTypes) || docTypes.length === 0) {
+        throw new ConfigValidationError("doc_types array is empty or missing.");
+    }
+    for (const dt of docTypes) {
+        if (!dt.id || !dt.description) {
+            throw new ConfigValidationError(`doc_type '${dt.id ?? "(unknown)"}' is missing id or description.`);
+        }
+    }
+}
+// ── Loader ──
+export function loadConfig(configPath) {
+    const path = configPath ?? resolveFile("config.yml");
+    if (!path) {
+        throw new ConfigValidationError("config.yml not found. Looked in: CWD, ~/.pm-skill/, package root.\n" +
+            "Copy the bundled config.yml to one of these locations and customize it.");
+    }
+    let raw;
+    try {
+        const content = readFileSync(path, "utf-8");
+        raw = yaml.load(content);
+    }
+    catch (e) {
+        throw new ConfigValidationError(`Cannot read config.yml: ${path}\n${e.message}`);
+    }
+    validateLabels(raw.labels);
+    const labelIds = new Set(raw.labels.map((l) => l.id));
+    validateTemplates(raw.templates, labelIds);
+    validatePriorities(raw.priorities);
+    const priorityKeys = new Set(Object.keys(raw.priorities));
+    validateSeverityMapping(raw.severity_mapping, priorityKeys);
+    validateDocTypes(raw.doc_types);
+    return {
+        labels: raw.labels,
+        templates: raw.templates,
+        priorities: raw.priorities,
+        severity_mapping: raw.severity_mapping,
+        doc_types: raw.doc_types,
+        epics: Array.isArray(raw.epics) ? raw.epics : [],
+    };
+}
+// ── Query helpers ──
+export function validateLabel(config, labelId) {
+    const label = config.labels.find((l) => l.id === labelId);
+    if (!label) {
+        const available = config.labels.map((l) => l.id).join(", ");
+        throw new Error(`Label '${labelId}' is not defined in config.\nAvailable: ${available}`);
+    }
+    return label;
+}
+export function validateDocType(config, typeId) {
+    const dt = config.doc_types.find((d) => d.id === typeId);
+    if (!dt) {
+        const available = config.doc_types.map((d) => d.id).join(", ");
+        throw new Error(`Doc type '${typeId}' is not defined in config.\nAvailable: ${available}`);
+    }
+    return dt;
+}
+export function getTemplate(config, templateId) {
+    const tmpl = config.templates.find((t) => t.id === templateId);
+    if (!tmpl) {
+        const available = config.templates.map((t) => t.id).join(", ");
+        throw new Error(`Template '${templateId}' is not defined in config.\nAvailable: ${available}`);
+    }
+    return tmpl;
+}
+export function resolvePriority(config, priorityKey) {
+    const p = config.priorities[priorityKey];
+    if (!p) {
+        throw new Error(`Priority '${priorityKey}' is not defined in config.`);
+    }
+    return p.linear;
+}
+export function resolveSeverity(config, severity) {
+    const pKey = config.severity_mapping[severity];
+    if (!pKey) {
+        const available = Object.keys(config.severity_mapping).join(", ");
+        throw new Error(`Severity '${severity}' is not defined in config severity_mapping.\nAvailable: ${available}`);
+    }
+    return resolvePriority(config, pKey);
+}

package/dist/env.d.ts

@@ -0,0 +1,31 @@
+export declare const GLOBAL_DIR: string;
+/**
+ * Resolve a file by checking multiple directories in order:
+ * 1. CWD (project-local override)
+ * 2. ~/.pm-skill/ (user-global config)
+ * 3. Package root (bundled defaults)
+ */
+export declare function resolveFile(filename: string): string | null;
+export interface ValidatedEnv {
+    LINEAR_API_KEY: string;
+    LINEAR_DEFAULT_TEAM_ID: string;
+    LINEAR_DEFAULT_PROJECT_ID?: string;
+    NOTION_API_KEY?: string;
+    NOTION_ROOT_PAGE_ID?: string;
+    NOTION_BUG_DB_ID?: string;
+}
+/**
+ * Hierarchical .env loading:
+ * 1. CWD/.env (project-specific, highest priority)
+ * 2. ~/.pm-skill/.env (global defaults, fills in missing keys)
+ *
+ * Both files are loaded. CWD values take precedence over global.
+ */
+export declare function loadEnvFiles(): void;
+export declare function validateEnv(command: string): ValidatedEnv;
+/**
+ * Write key=value pairs to a .env file.
+ * If the file exists, updates existing keys and appends new ones.
+ * If not, creates it fresh.
+ */
+export declare function writeEnvFile(targetDir: string, entries: Record<string, string>): string;