ClawPM Skill
Multi-project task management. All commands emit JSON by default; use -f text for human-readable output.
First-Time Setup
CODEBLOCK0
Creating Projects
Projects are directories with a .project/ folder. They don't need to be git repos.
Initialize in any directory
CODEBLOCK1
From a git clone (auto-init)
Git repos under ~/clawpm/projects/ auto-initialize on first use:
CODEBLOCK2
Discover untracked repos
CODEBLOCK3
Quick Start
CODEBLOCK4
Top-Level Commands (Shortcuts)
| Command | Equivalent | Description |
|---|
| INLINECODE3 | INLINECODE4 | Quick add a task |
| INLINECODE5 |
clawpm tasks add -t "Title" -b "desc" | Add with body |
|
clawpm add "Title" --parent 25 | - | Add subtask |
|
clawpm done 42 |
clawpm tasks state 42 done | Mark task done |
|
clawpm start 42 |
clawpm tasks state 42 progress | Start working |
|
clawpm block 42 |
clawpm tasks state 42 blocked | Mark blocked |
|
clawpm next |
clawpm projects next | Get next task |
|
clawpm status | - | Project overview |
|
clawpm context | - | Full agent context |
|
clawpm use <id> | - | Set project context |
Project Auto-Detection
ClawPM automatically detects your project from (in priority order):
- 1. Subcommand flag: INLINECODE19
- Global flag: INLINECODE20
- Current directory: Walks up looking for INLINECODE21
- Auto-init: If in untracked git repo under project_roots, auto-initializes
- Context: Previously set with INLINECODE22
Short Task IDs
You can use just the numeric part of a task ID:
- -
42 → CLAWP-042 (prefix derived from project ID) - INLINECODE25 →
CLAWP-042 (full ID works too)
Subtasks
CODEBLOCK5
Subtasks move with parent on state change (done/blocked moves entire directory).
Agent Context (Resuming Work)
Get everything needed to resume work in one command:
CODEBLOCK6
Returns JSON with: project info + spec, in-progress/next task, blockers, recent work log, git status, open issues.
Workflow Example
CODEBLOCK7
Hit a blocker:
CODEBLOCK8
Full Command Reference
Projects
CODEBLOCK9
Tasks
CODEBLOCK10
Work Log
CODEBLOCK11
Note: State changes (start/done/block) auto-log to worklog with git fileschanged.
Research
CODEBLOCK12
Issues
CODEBLOCK13
Admin
CODEBLOCK14
Work Log Actions
- -
start - Started working (auto-logged on clawpm start) - INLINECODE29 - Made progress
- INLINECODE30 - Completed (auto-logged on
clawpm done) - INLINECODE32 - Hit a blocker (auto-logged on
clawpm block) - INLINECODE34 - Git commit (logged via
clawpm log commit) - INLINECODE36 - Switching tasks
- INLINECODE37 - Research note
- INLINECODE38 - General observation
Task States & File Locations
| State | File Pattern | Meaning |
|---|
| open | INLINECODE39 | Ready to work |
| progress |
tasks/CLAWP-042.progress.md | In progress |
| done |
tasks/done/CLAWP-042.md | Completed |
| blocked |
tasks/blocked/CLAWP-042.md | Waiting |
Tips
- - Flag order:
clawpm [global flags] <command> [command flags] — e.g. INLINECODE44 - JSON output: All commands emit JSON by default; use
-f text for human-readable - One command per call: Don't chain clawpm commands with
&& — run each separately - Portfolio root: Default INLINECODE47
- Work log: Append-only at INLINECODE48
Troubleshooting
CODEBLOCK15
ClawPM 技能
多项目管理任务。所有命令默认输出 JSON；使用 -f text 可获取人类可读的输出。
首次设置
bash
clawpm setup # 创建 ~/clawpm/ 目录，包含 portfolio.toml、projects/、work_log.jsonl
clawpm setup --check # 验证安装
创建项目
项目是包含 .project/ 文件夹的目录。它们不需要是 git 仓库。
在任何目录中初始化
bash
cd /path/to/my-project
clawpm project init # 从目录自动检测 ID/名称
clawpm project init --id myproj # 自定义 ID
从 git 克隆（自动初始化）
~/clawpm/projects/ 下的 Git 仓库在首次使用时自动初始化：
bash
git clone git@github.com:user/repo.git ~/clawpm/projects/repo
cd ~/clawpm/projects/repo
clawpm add 第一个任务 # 自动初始化 .project/，然后添加任务
发现未追踪的仓库
bash
clawpm projects list --all # 显示已追踪 + 未追踪的 git 仓库
快速开始
bash
从项目目录（自动检测）：
clawpm status # 查看项目状态
clawpm next # 获取下一个任务
clawpm start 42 # 开始任务（短 ID 可用）
clawpm done 42 # 标记完成
或设置项目上下文：
clawpm use my-project
clawpm status # 现在使用 my-project
顶层命令（快捷方式）
| 命令 | 等价于 | 描述 |
|---|
| clawpm add 标题 | clawpm tasks add -t 标题 | 快速添加任务 |
| clawpm add 标题 -b 描述 |
clawpm tasks add -t 标题 -b 描述 | 添加带描述的任务 |
| clawpm add 标题 --parent 25 | - | 添加子任务 |
| clawpm done 42 | clawpm tasks state 42 done | 标记任务完成 |
| clawpm start 42 | clawpm tasks state 42 progress | 开始工作 |
| clawpm block 42 | clawpm tasks state 42 blocked | 标记阻塞 |
| clawpm next | clawpm projects next | 获取下一个任务 |
| clawpm status | - | 项目概览 |
| clawpm context | - | 完整代理上下文 |
| clawpm use
| - | 设置项目上下文 |
项目自动检测
ClawPM 按以下优先级自动检测您的项目：
- 1. 子命令标志：clawpm tasks list --project clawpm
- 全局标志：clawpm --project clawpm status
- 当前目录：向上查找 .project/settings.toml
- 自动初始化：如果在 project_roots 下的未追踪 git 仓库中，自动初始化
- 上下文：之前通过 clawpm use 设置
短任务 ID
您可以使用任务 ID 的数字部分：
- - 42 → CLAWP-042（前缀从项目 ID 派生）
- CLAWP-042 → CLAWP-042（完整 ID 也可用）
子任务
bash
clawpm add 子任务 --parent 25 # 创建子任务（如有必要自动拆分父任务）
clawpm tasks split 25 # 手动将任务转换为父目录
clawpm done 25 # 如果子任务未完成则失败
clawpm done 25 --force # 覆盖并强制完成
子任务在状态变更时随父任务移动（完成/阻塞移动整个目录）。
代理上下文（恢复工作）
通过一个命令获取恢复工作所需的所有内容：
bash
clawpm context # 当前项目的完整上下文
clawpm context -p myproj # 特定项目
返回 JSON，包含：项目信息 + 规格、进行中/下一个任务、阻塞项、最近工作日志、git 状态、未解决问题。
工作流程示例
bash
clawpm context # 获取完整上下文
clawpm start 42 # 标记进行中（自动记录日志）
... 执行工作 ...
git add . && git commit -m feat: ...
clawpm done 42 --note 已完成 # 自动记录日志，包含 files_changed
clawpm log commit # 也记录 git 提交本身
遇到阻塞：
bash
clawpm block 42 --note 需要 API 凭据
完整命令参考
项目
bash
clawpm projects list [--all] # 列出项目（--all 包含未追踪仓库）
clawpm projects next # 所有项目中的下一个任务
clawpm project context [project] # 完整项目上下文
clawpm project init # 在当前目录初始化项目
任务
bash
clawpm tasks # 列出任务（默认：开放+进行中+阻塞）
clawpm tasks list [-s open|done|blocked|progress|all] [--flat]
clawpm tasks show # 任务详情
clawpm tasks add -t 标题 [--priority 3] [--complexity m] [--parent ] [-b 描述]
clawpm tasks edit [--title ...] [--priority N] [--complexity s|m|l|xl] [--body ...]
clawpm tasks state open|progress|done|blocked [--note ...] [--force]
clawpm tasks split # 转换为子任务的父目录
工作日志
bash
clawpm log add --task --action progress --summary 我做了什么
clawpm log tail [--limit 10] # 最近条目（自动过滤到当前项目）
clawpm log tail --all # 所有项目中的最近条目
clawpm log tail --follow # 实时追踪（类似 tail -f）
clawpm log last # 最近条目（自动过滤到当前项目）
clawpm log last --all # 所有项目中的最近条目
clawpm log commit [-n 10] # 将最近的 git 提交记录到工作日志
clawpm log commit --dry-run # 预览而不记录
clawpm log commit --task # 将提交与任务关联
注意：状态变更（开始/完成/阻塞）会自动记录到工作日志，包含 git files_changed。
研究
bash
clawpm research list
clawpm research add --type investigation --title 问题
clawpm research link --id --session-key
问题
bash
clawpm issues add --type bug --severity high --actual 发生了什么
clawpm issues list [--open] # 仅未解决的问题
管理
bash
clawpm setup # 创建投资组合（首次）
clawpm setup --check # 验证安装
clawpm status # 项目概览
clawpm context # 完整代理上下文
clawpm doctor # 健康检查
clawpm use [project] # 设置/显示项目上下文
clawpm use --clear # 清除上下文
工作日志操作
- - start - 开始工作（在 clawpm start 时自动记录）
- progress - 取得进展
- done - 完成（在 clawpm done 时自动记录）
- blocked - 遇到阻塞（在 clawpm block 时自动记录）
- commit - Git 提交（通过 clawpm log commit 记录）
- pause - 切换任务
- research - 研究笔记
- note - 一般观察
任务状态与文件位置
| 状态 | 文件模式 | 含义 |
|---|
| open | tasks/CLAWP-042.md | 准备就绪 |
| progress |
tasks/CLAWP-042.progress.md | 进行中 |
| done | tasks/done/CLAWP-042.md | 已完成 |
| blocked | tasks/blocked/CLAWP-042.md | 等待中 |
提示
- - 标志顺序：clawpm [全局标志] <命令> [命令标志] — 例如 clawpm -f text tasks list -s open
-
