meegle-cli 0.1.1 → 0.1.3

package/README-en.md

@@ -0,0 +1,222 @@
+# meegle-cli
+
+CLI for Feishu Project (Meegle).  
+Current mode is `plugin-only`: it supports `plugin_access_token / virtual_plugin_token`, but not `user_access_token`.
+
+## Risk Notes
+
+This CLI can directly create, update, and delete Meegle data.  
+In a B2B environment, the main risks are:
+
+- using the wrong `profile`
+- using the wrong `projectKey`
+- letting scripts or AI tools write to production by mistake
+- running bulk mutations without checking the target scope first
+
+Starting from `0.1.3`:
+
+- write commands print a risk summary first
+- interactive terminals require confirmation
+- non-interactive environments (scripts / AI / CI) must pass `--yes`
+
+## Install
+
+```bash
+npm install -g meegle-cli
+meegle --help
+```
+
+## What You Need
+
+- `pluginId`
+- `pluginSecret`
+- `userKey`
+- `projectKey`
+
+Optional:
+
+- `baseURL`
+  - default: `https://project.feishu.cn`
+
+## Quick Start
+
+### 1. Initialize a profile
+
+```bash
+meegle auth init \
+  --target-profile default \
+  --plugin-id <PLUGIN_ID> \
+  --plugin-secret <PLUGIN_SECRET> \
+  --default-user-key <USER_KEY>
+```
+
+Or use environment variables:
+
+```bash
+export MEEGLE_PLUGIN_ID=<PLUGIN_ID>
+export MEEGLE_PLUGIN_SECRET=<PLUGIN_SECRET>
+export MEEGLE_USER_KEY=<USER_KEY>
+
+meegle auth init --target-profile default
+```
+
+### 2. Verify credentials
+
+```bash
+meegle --profile default auth status --json
+```
+
+### 3. List spaces
+
+```bash
+meegle --profile default space list --json
+```
+
+### 4. Query yourself
+
+```bash
+meegle --profile default user query --self --json
+```
+
+## Common Tasks
+
+### Get a work item
+
+```bash
+meegle --profile default workitem get \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
+  --json
+```
+
+### Create a work item
+
+```bash
+meegle --profile default workitem create \
+  --yes \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --name "Login improvement" \
+  --desc "Improve error messages" \
+  --owner <USER_KEY> \
+  --priority P2 \
+  --json
+```
+
+### Add a comment
+
+```bash
+meegle --profile default comment add \
+  --yes \
+  --project-key <PROJECT_KEY> \
+  --type story \
+  --id 6300034462 \
+  --content "Received, starting now" \
+  --json
+```
+
+## View Usage
+
+Do not infer view type from the page URL.  
+Always call `view list` first, then choose the correct API.
+
+### Resolve a view
+
+```bash
+meegle --profile default view list \
+  --project-key 69zyer \
+  --body-file ./examples/view-list.json \
+  --json
+```
+
+Check:
+
+- `view_id`
+- `name`
+- `view_type`
+  - `1` = condition view
+  - `2` = fixed view
+
+### Fixed view items
+
+```bash
+meegle --profile default view fix-items \
+  --project-key 69zyer \
+  --view-id sypbi-z60 \
+  --query-file ./examples/view-fix-items.json \
+  --json
+```
+
+## Related Field Filtering
+
+For related fields such as `planning_version`, do not use:
+
+- `workitem search filter` with `field_value_pairs`
+
+Use this flow instead:
+
+1. find the related work item ID
+2. run `workitem search by-params`
+3. pass the related work item **ID list**, not the display name
+
+### Example: find stories by planning version
+
+Step 1: search the `version` work item:
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+Step 2: use the returned version `id` in `planning_version`:
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+Replace `1234567890` in the example file with the real version work item ID.
+
+## Write Safety
+
+In non-interactive environments, write commands must pass `--yes`.
+
+Example:
+
+```bash
+meegle --profile default --yes workitem update ...
+```
+
+## Agent Notes
+
+If you use this CLI from an AI agent or automation:
+
+1. run `meegle --help` or subcommand `--help` first
+2. do not guess request shapes from web URLs
+3. use `workitem search by-params` for custom fields and related fields
+4. `field_value_pairs` is for create/update, not for search
+5. in non-interactive environments, write commands must pass `--yes`
+
+## Examples
+
+- `examples/view-list.json`
+- `examples/view-fix-items.json`
+- `examples/version-search-filter.json`
+- `examples/story-by-planning-version.json`
+
+## Limits
+
+This CLI currently rejects user-token-only commands such as:
+
+- `user search`
+- `user group create`
+- `user group update-members`
+- `user group query-members`
+
+That is expected behavior in `plugin-only` mode.

package/README.md

@@ -3,6 +3,33 @@
 面向飞书项目（Meegle）的命令行工具。  
 当前版本运行在 `plugin-only` 模式：只支持 `plugin_access_token / virtual_plugin_token`，不支持 `user_access_token`。
 
+## 风险提示
+
+这是一个可直接对空间数据执行增删改的 CLI。  
+在 toB 场景里，误操作成本很高，尤其是：
+
+- 打错 `profile`
+- 打错 `projectKey`
+- 把脚本或 AI 的写操作直接打到线上
+- 批量更新 / 删除目标超出预期
+
+从 `0.1.3` 起：
+
+- 写操作会先输出风险摘要
+- 交互终端里默认要求确认
+- 非交互环境（脚本 / AI / CI）必须显式传 `--yes`
+
+交互终端的目标体验是：
+
+- 人类用户只需要回复简短确认词，例如 `确认删除`
+- Agent / 脚本才需要显式 `--yes`
+
+建议：
+
+1. 先在测试空间验证命令
+2. 再切生产 profile
+3. 对写操作显式确认 `profile / projectKey / id`
+
 ## 适用对象
 
 - 想在终端里查询空间、工作项、视图、评论、子任务
@@ -159,6 +186,7 @@ meegle --profile default workitem get \
 
 ```bash
 meegle --profile default workitem create \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --name "登录优化" \
@@ -172,6 +200,7 @@ meegle --profile default workitem create \
 
 ```bash
 meegle --profile default workitem update \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -183,6 +212,7 @@ meegle --profile default workitem update \
 
 ```bash
 meegle --profile default comment add \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -194,6 +224,7 @@ meegle --profile default comment add \
 
 ```bash
 meegle --profile default comment add \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -205,6 +236,7 @@ meegle --profile default comment add \
 
 ```bash
 meegle --profile default subtask create \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -222,6 +254,7 @@ meegle --profile default subtask create \
 
 ```bash
 meegle --profile default workflow state-change \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -234,6 +267,7 @@ meegle --profile default workflow state-change \
 
 ```bash
 meegle --profile default workflow node-operate \
+  --yes \
   --project-key <PROJECT_KEY> \
   --type story \
   --id 6300034462 \
@@ -331,10 +365,96 @@ meegle --profile default view panoramic-items \
 
 不要直接拿整个空间总池代替“这个视图”的口径。
 
+## 关联字段筛选
+
+### 结论先说
+
+像 `planning_version` 这类字段，不要用：
+
+- `workitem search filter` + `field_value_pairs`
+
+正确做法是：
+
+1. 先找到被关联工作项的实例 ID
+2. 再用 `workitem search by-params`
+3. 对关联字段传 **ID 列表**，不要传名称
+
+### 为什么
+
+`planning_version` 的字段类型是：
+
+- `work_item_related_multi_select`
+
+这类字段的筛选值格式是：
+
+- `list<int64>`，也就是关联工作项 ID 列表
+
+不是：
+
+- 版本名称字符串
+- `field_value_pairs`
+
+### 典型例子：按“规划版本”筛需求
+
+目标：找出 `planning_version` 关联到某个版本实例的全部 story。
+
+#### 第一步：先找版本实例
+
+先在 `version` 类型里按名称查候选：
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+示例文件：
+
+- [examples/version-search-filter.json](./examples/version-search-filter.json)
+
+你要从返回结果里拿到真正的版本实例 `id`。
+
+#### 第二步：再按 `planning_version` 查 story
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+示例文件：
+
+- [examples/story-by-planning-version.json](./examples/story-by-planning-version.json)
+
+重点：
+
+- 把 `1234567890` 替换成真实版本实例 ID
+- 不要直接写版本名称
+
+### 常见误用
+
+错误方向：
+
+1. 用 `workitem search filter` 查自定义关联字段
+2. 在筛选请求体里传 `field_value_pairs`
+3. 直接把版本名称塞给 `planning_version`
+
+这些场景下，接口常见表现是：
+
+- 条件被忽略
+- 返回全部需求
+- 让人误以为 CLI 不支持
+
+根因通常不是 CLI 丢参，而是请求体结构不符合接口契约。
+
 ## 参数约定
 
 - 常用查询优先走直接参数，不强制写 JSON 文件
 - 常用写操作优先走直接参数，例如 `--name`、`--desc`、`--content`
+- 非交互环境下，写操作必须显式传 `--yes`
 - 复杂请求体可使用 `--body <json>` 或 `--body-file <path>`
 - 复杂查询参数可使用 `--query-file <path>`
 - 自定义字段统一使用 `--field field_key=value`
@@ -400,6 +520,33 @@ meegle auth init \
 先回到 `view list` 看 `view_type`。  
 不要只凭页面 URL 去猜视图类型。
 
+### 5. 明明传了条件，结果返回全部数据
+
+优先检查三件事：
+
+1. 用的命令是不是对
+   - 内置字段简单筛选：`workitem search filter`
+   - 自定义字段 / 关联字段：`workitem search by-params`
+2. 值格式是不是对
+   - 关联工作项字段通常要传实例 ID，不是名称
+3. 请求体键是不是对
+   - `field_value_pairs` 用于创建 / 更新，不是搜索条件
+
+### 6. 写操作在脚本 / Agent 里被拒绝
+
+如果报错类似：
+
+- `非交互环境下，写操作需要显式传 --yes`
+
+说明当前进程不是交互终端。  
+这是预期行为，用来拦截脚本和 AI 的误操作。
+
+处理方式：
+
+```bash
+meegle --profile default --yes workitem update ...
+```
+
 ## 命令总览
 
 - `auth`: `init`, `status`
@@ -428,3 +575,23 @@ npm test
 ```
 
 发布说明见 [RELEASE.md](./RELEASE.md)。
+
+## Examples
+
+可直接复制修改的模板在：
+
+- [examples/view-list.json](./examples/view-list.json)
+- [examples/view-fix-items.json](./examples/view-fix-items.json)
+- [examples/version-search-filter.json](./examples/version-search-filter.json)
+- [examples/story-by-planning-version.json](./examples/story-by-planning-version.json)
+
+## AI / Agent 提示
+
+如果你在 Agent、Openclaw、脚本平台里调用 `meegle-cli`，建议遵守这几条：
+
+1. 先跑 `meegle --help` 或子命令 `--help`，不要凭印象猜参数名
+2. 不要从页面 URL 直接猜视图类型；先调用 `view list`
+3. 自定义字段和关联字段优先走 `workitem search by-params`
+4. `planning_version` 这类关联字段，先查出被关联工作项的 `id`，再筛主工作项
+5. `field_value_pairs` 是写操作格式，不是搜索格式
+6. 非交互环境里，写操作必须显式传 `--yes`

package/dist/cli.js

@@ -708,6 +708,32 @@ async function buildWorkflowNodeOperateRequest(options) {
         fields: fields.length > 0 ? fields : undefined,
     };
 }
+/**
+ * 删除前先读出目标摘要，能明显降低误删概率。
+ *
+ * @param ctx 守卫上下文
+ * @param args 工作项定位参数
+ */
+async function buildWorkItemRemovePreview(ctx, args) {
+    const workItemId = parseInteger(args.id, 'id');
+    const items = await ctx.client.workItem.query(args.projectKey, args.type, {
+        work_item_ids: [workItemId],
+        fields: ['name'],
+    }, { auth: ctx.auth });
+    const target = items[0];
+    if (!target) {
+        throw new CliError('删除前未找到目标工作项，请先确认 projectKey、type 和 id 是否正确。', 2);
+    }
+    return {
+        lines: [
+            `projectKey: ${args.projectKey}`,
+            `workItemType: ${args.type}`,
+            `workItemId: ${workItemId}`,
+            `workItemName: ${target.name}`,
+        ],
+        confirmPhrase: '确认删除',
+    };
+}
 function resolveGlobal(program) {
     return program.opts();
 }
@@ -960,7 +986,9 @@ function registerWorkItem(program) {
             id: 'workitem.remove',
             authPolicy: 'PLUGIN_WITH_USER_KEY',
             endpoint: { method: 'DELETE', path: '/open_api/:project_key/work_item/:work_item_type_key/:work_item_id' },
-        }, global, async (ctx) => ctx.client.workItem.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), { auth: ctx.auth }));
+        }, global, async (ctx) => ctx.client.workItem.remove(options.projectKey, options.type, parseInteger(options.id, 'id'), { auth: ctx.auth }), {
+            riskPreview: async (ctx) => buildWorkItemRemovePreview(ctx, options),
+        });
         printOk(Boolean(global.json));
     });
     workItem
@@ -2028,6 +2056,7 @@ export function buildCli() {
         .option('--user-key <userKey>', '本次命令覆盖 userKey')
         .option('--compat-auth', '读接口使用兼容模式 (x-auth-mode=0)，默认严格模式')
         .option('--json', '输出 JSON')
+        .option('--yes', '跳过写操作确认，脚本 / AI / CI 使用')
         .addHelpText('after', `
 常用示例：
   meegle auth init --target-profile demo --plugin-id <id> --plugin-secret <secret> --default-user-key <userKey>

package/dist/core/auth-policy.d.ts

@@ -1,5 +1,6 @@
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export type AuthPolicy = 'NONE' | 'PLUGIN_WITH_USER_KEY' | 'PLUGIN_OPTIONAL_USER_KEY' | 'USER_TOKEN_REQUIRED';
+export type RiskLevel = 'READ_ONLY' | 'WRITE' | 'DANGEROUS';
 export interface EndpointRef {
     method: HttpMethod;
     path: string;
@@ -12,3 +13,7 @@ export interface CommandMeta {
 export declare function isUserTokenOnlyEndpoint(path: string): boolean;
 export declare function assertCommandSupported(meta: CommandMeta): void;
 export declare function assertEndpointAllowed(endpoint?: EndpointRef): void;
+/**
+ * 风险级别由命令语义决定，比按 HTTP 方法推断更稳定。
+ */
+export declare function getCommandRiskLevel(meta: CommandMeta): RiskLevel;

package/dist/core/auth-policy.js

@@ -1,4 +1,20 @@
 import { CliError } from './cli-error.js';
+const DANGEROUS_COMMAND_PATTERNS = [
+    /^workitem\.(remove|freeze|unfreeze|abort|restore|update-compound)$/,
+    /^view\.delete$/,
+    /^attachment\.delete$/,
+    /^workhour\.delete$/,
+];
+const WRITE_COMMAND_PATTERNS = [
+    /^workitem\.create$/,
+    /^workitem\.update$/,
+    /^workflow\.(state-change|node-operate|node-update)$/,
+    /^comment\.(add|update|remove)$/,
+    /^subtask\.(create|update|remove|operate)$/,
+    /^attachment\.(upload-file|upload)$/,
+    /^workhour\.(create|update)$/,
+    /^view\.(create-fix|update-fix|create-condition|update-condition)$/,
+];
 const USER_TOKEN_ONLY_TEMPLATES = new Set([
     '/open_api/user/search',
     '/open_api/:project_key/user_group',
@@ -35,3 +51,15 @@ export function assertEndpointAllowed(endpoint) {
         throw new CliError(`接口 ${endpoint.method} ${endpoint.path} 在文档中标注为仅支持 user_access_token，plugin-only 模式已拒绝。`, 2);
     }
 }
+/**
+ * 风险级别由命令语义决定，比按 HTTP 方法推断更稳定。
+ */
+export function getCommandRiskLevel(meta) {
+    if (DANGEROUS_COMMAND_PATTERNS.some((pattern) => pattern.test(meta.id))) {
+        return 'DANGEROUS';
+    }
+    if (WRITE_COMMAND_PATTERNS.some((pattern) => pattern.test(meta.id))) {
+        return 'WRITE';
+    }
+    return 'READ_ONLY';
+}

package/dist/core/command-guard.d.ts

@@ -5,6 +5,7 @@ export interface RuntimeOptions {
     profile?: string;
     userKey?: string;
     compatAuth?: boolean;
+    yes?: boolean;
 }
 export interface GuardContext {
     profileName: string;
@@ -13,4 +14,11 @@ export interface GuardContext {
     auth: AuthContext;
     userKey?: string;
 }
-export declare function runGuarded<T>(meta: CommandMeta, runtime: RuntimeOptions, action: (ctx: GuardContext) => Promise<T>): Promise<T>;
+export interface RiskPreview {
+    lines?: string[];
+    confirmPhrase?: string;
+}
+export interface GuardHooks {
+    riskPreview?: (ctx: GuardContext) => Promise<RiskPreview | undefined>;
+}
+export declare function runGuarded<T>(meta: CommandMeta, runtime: RuntimeOptions, action: (ctx: GuardContext) => Promise<T>, hooks?: GuardHooks): Promise<T>;

package/dist/core/command-guard.js

@@ -1,5 +1,6 @@
+import { createInterface } from 'node:readline/promises';
 import { CliError } from './cli-error.js';
-import { assertCommandSupported, assertEndpointAllowed } from './auth-policy.js';
+import { assertCommandSupported, assertEndpointAllowed, getCommandRiskLevel, } from './auth-policy.js';
 import { getProfile } from './config-store.js';
 import { createClient } from './client-factory.js';
 function resolveUserKey(runtimeUserKey, defaultUserKey) {
@@ -24,7 +25,78 @@ function buildPluginAuth(userKey, compatAuth) {
         authMode: compatAuth ? 0 : 1,
     };
 }
-export async function runGuarded(meta, runtime, action) {
+function isInteractiveShell() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function isHighRiskProfile(profileName) {
+    return /(^|[-_])(prod|production|live)([-_]|$)/i.test(profileName);
+}
+function escalateRiskLevel(riskLevel, profileName) {
+    if (!isHighRiskProfile(profileName)) {
+        return riskLevel;
+    }
+    if (riskLevel === 'WRITE') {
+        return 'DANGEROUS';
+    }
+    return riskLevel;
+}
+function buildRiskSummary(meta, profileName, riskLevel) {
+    const args = process.argv.slice(2).join(' ');
+    return [
+        `命令: meegle ${args}`,
+        `profile: ${profileName}`,
+        `风险级别: ${riskLevel}`,
+        meta.endpoint ? `接口: ${meta.endpoint.method} ${meta.endpoint.path}` : '接口: N/A',
+    ];
+}
+/**
+ * 在统一守卫里注入风险预览，避免每个高风险命令各自实现一套确认流程。
+ *
+ * @param meta 命令元数据
+ * @param runtime 运行时选项
+ * @param profileName 当前 profile 名称
+ * @param preview 命令特定的风险预览
+ */
+async function confirmWriteRisk(meta, runtime, profileName, preview) {
+    const originalRisk = getCommandRiskLevel(meta);
+    const riskLevel = escalateRiskLevel(originalRisk, profileName);
+    if (riskLevel === 'READ_ONLY') {
+        return;
+    }
+    const summary = [...buildRiskSummary(meta, profileName, riskLevel), ...(preview?.lines ?? [])];
+    process.stderr.write('即将执行写操作：\n');
+    for (const line of summary) {
+        process.stderr.write(`- ${line}\n`);
+    }
+    if (runtime.yes) {
+        return;
+    }
+    if (!isInteractiveShell()) {
+        throw new CliError('非交互环境下，写操作需要显式传 --yes。', 2);
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        if (riskLevel === 'DANGEROUS') {
+            const confirmPhrase = preview?.confirmPhrase ?? '确认执行';
+            const answer = (await rl.question(`危险操作。请输入“${confirmPhrase}”确认继续执行: `)).trim();
+            if (answer !== confirmPhrase) {
+                throw new CliError('已取消执行。', 2);
+            }
+            return;
+        }
+        const answer = (await rl.question('确认继续执行写操作？[y/N] ')).trim().toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            throw new CliError('已取消执行。', 2);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runGuarded(meta, runtime, action, hooks) {
     assertCommandSupported(meta);
     assertEndpointAllowed(meta.endpoint);
     const { name: profileName, profile } = await getProfile(runtime.profile);
@@ -34,5 +106,8 @@ export async function runGuarded(meta, runtime, action) {
     }
     const client = createClient(profile);
     const auth = buildPluginAuth(userKey, runtime.compatAuth);
-    return action({ profileName, profile, client, auth, userKey });
+    const ctx = { profileName, profile, client, auth, userKey };
+    const preview = hooks?.riskPreview ? await hooks.riskPreview(ctx) : undefined;
+    await confirmWriteRisk(meta, runtime, profileName, preview);
+    return action(ctx);
 }

package/examples/story-by-planning-version.json

@@ -0,0 +1,23 @@
+{
+  "search_group": {
+    "conjunction": "AND",
+    "search_params": [
+      {
+        "param_key": "planning_version",
+        "operator": "CONTAINS",
+        "value": [
+          1234567890
+        ]
+      }
+    ]
+  },
+  "page_size": 200,
+  "page_num": 1,
+  "fields": [
+    "name",
+    "owner",
+    "priority",
+    "planning_version",
+    "work_item_status"
+  ]
+}

package/examples/version-search-filter.json

@@ -0,0 +1,8 @@
+{
+  "work_item_type_keys": [
+    "version"
+  ],
+  "work_item_name": "260312",
+  "page_size": 50,
+  "page_num": 1
+}

package/examples/view-fix-items.json

@@ -0,0 +1,4 @@
+{
+  "page_size": 50,
+  "page_num": 1
+}

package/examples/view-list.json

@@ -0,0 +1,9 @@
+{
+  "work_item_type_key": "story",
+  "view_ids": [
+    "sypbi-z60"
+  ],
+  "is_query_quick_filter": true,
+  "page_size": 10,
+  "page_num": 1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meegle-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Plugin-only CLI for Feishu Project (Meegle) based on meeglesdk",
   "type": "module",
   "bin": {
@@ -9,7 +9,10 @@
   "files": [
     "dist",
     "README.md",
-    "RELEASE.md"
+    "README-en.md",
+    "RELEASE.md",
+    "examples",
+    "skills"
   ],
   "scripts": {
     "clean": "rm -rf dist",

package/skills/meegle-cli-usage/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: meegle-cli-usage
+description: Use the meegle CLI shipped in this package instead of raw SDK or guessed API calls when an agent needs to query spaces, work items, views, PMO baselines, or related-field searches such as planning_version. Use for CLI-based Meegle automation, debugging, and analysis. Includes safety rules for write operations (`--yes` in non-interactive environments), view-type resolution, and relation-ID based filtering.
+---
+
+# Meegle CLI Usage
+
+Use `meegle` as the default entrypoint for Meegle operations in this package. Prefer invoking the CLI over reconstructing request payloads from memory.
+
+## Quick Start
+
+1. Resolve the command path.
+   - Try `meegle --help` first.
+   - If `meegle` is not in PATH, use `which meegle` or `npm bin -g`.
+   - If working inside this package without a global install, use `node_modules/.bin/meegle`.
+2. Resolve the command shape before guessing.
+   - Run `meegle --help` or `<subcommand> --help`.
+3. Separate read and write intent.
+   - Treat read commands as default-safe.
+   - Treat write commands as opt-in only.
+   - In non-interactive environments, only add `--yes` when the user explicitly approved the write.
+
+## Safety Rules
+
+1. Refuse to add `--yes` implicitly.
+2. Prefer read-only discovery before any write.
+3. Echo the target scope in reasoning before running a write:
+   - `profile`
+   - `projectKey`
+   - `workItemType`
+   - target `id` or `ids`
+4. If the task can be solved with `get`, `list`, `search`, or `query`, do that first.
+
+## Choose the Right Command
+
+### Query a view
+
+Do not infer the view type from a page URL.
+
+Always:
+
+1. Run `view list` with the candidate `view_id`
+2. Inspect `view_type`
+3. Use:
+   - `view fix-items` for fixed view (`view_type = 2`)
+   - `view panoramic-items` only when the view is not fixed
+
+### Filter by a related field
+
+For fields such as `planning_version` or `planning_sprint`:
+
+1. Do not use `workitem search filter` with `field_value_pairs`
+2. Resolve the related work item instance ID first
+3. Use `workitem search by-params`
+4. Pass the related work item **ID list**, not the display name
+
+This is the most common agent mistake. `field_value_pairs` belongs to create/update flows, not search flows.
+
+### Build a PMO baseline
+
+For PMO-style analysis:
+
+1. Resolve the target view
+2. Fetch the item IDs from the view
+3. Fetch work item details with selected fields
+4. Summarize:
+   - state distribution
+   - owner distribution
+   - priority coverage
+   - due-date coverage
+   - age / stale updates
+
+Do not replace a view-scoped baseline with the whole space backlog unless the user explicitly asks for that.
+
+## Write Operations
+
+Use write commands only after explicit user approval.
+
+Typical write commands:
+
+- `workitem create`
+- `workitem update`
+- `comment add/update/remove`
+- `subtask create/update/remove/operate`
+- `workflow state-change`
+- `workflow node-operate`
+
+In scripts, CI, or agent runners:
+
+- pass `--yes` only when approved
+- expect non-interactive write rejection if `--yes` is missing
+
+## Use the Bundled Examples
+
+Read [references/command-recipes.md](./references/command-recipes.md) when you need:
+
+- view lookup examples
+- fixed view item queries
+- version lookup by name
+- story lookup by `planning_version`
+- PMO baseline query order
+
+Use the package examples directly when possible:
+
+- `../../examples/view-list.json`
+- `../../examples/view-fix-items.json`
+- `../../examples/version-search-filter.json`
+- `../../examples/story-by-planning-version.json`

package/skills/meegle-cli-usage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Meegle CLI Usage"
+  short_description: "Agent guide for safe meegle-cli usage."
+  default_prompt: "Use $meegle-cli-usage to operate Meegle safely through the CLI."

package/skills/meegle-cli-usage/references/command-recipes.md

@@ -0,0 +1,99 @@
+# Command Recipes
+
+## Resolve a View
+
+Use this first whenever the user gives a page URL or a `view_id`.
+
+```bash
+meegle --profile default view list \
+  --project-key 69zyer \
+  --body-file ./examples/view-list.json \
+  --json
+```
+
+Interpretation:
+
+- `view_type = 2` -> fixed view -> use `view fix-items`
+- otherwise -> inspect whether `view panoramic-items` is the intended path
+
+## Fetch Fixed View Items
+
+```bash
+meegle --profile default view fix-items \
+  --project-key 69zyer \
+  --view-id sypbi-z60 \
+  --query-file ./examples/view-fix-items.json \
+  --json
+```
+
+Use the returned `work_item_id_list` as input to `workitem get`.
+
+## Find a Version Work Item by Name
+
+Use this when the user speaks in business names such as “260312 version” or “gray release”.
+
+```bash
+meegle --profile default workitem search filter \
+  --project-key 69zyer \
+  --body-file ./examples/version-search-filter.json \
+  --json
+```
+
+If multiple version items match:
+
+1. surface the candidates
+2. ask the user to confirm the intended version or pick the exact `id`
+
+## Find Stories by `planning_version`
+
+Never pass the version display name directly into `planning_version`.
+
+Correct flow:
+
+1. resolve the target version work item `id`
+2. place that numeric `id` into `examples/story-by-planning-version.json`
+3. run:
+
+```bash
+meegle --profile default workitem search by-params \
+  --project-key 69zyer \
+  --type story \
+  --body-file ./examples/story-by-planning-version.json \
+  --json
+```
+
+## PMO Baseline Workflow
+
+Use this order:
+
+1. `view list`
+2. `view fix-items` / `view panoramic-items`
+3. `workitem get --fields ...`
+4. summarize the returned dataset
+
+Recommended PMO fields:
+
+- `name`
+- `owner`
+- `priority`
+- `description`
+- `work_item_status`
+- `start_time`
+- `exp_time`
+
+Recommended output dimensions:
+
+- total count
+- state distribution
+- current node distribution
+- owner concentration
+- missing priority
+- missing due date
+- creation/update time range
+
+## Write Command Reminder
+
+In non-interactive environments:
+
+- add `--yes` only when the user explicitly approved a mutation
+- do not silently convert a read request into a write request