{"skill":{"slug":"clawpm","displayName":"Clawpm","summary":"Multi-project task and research management (JSON-first CLI)","description":"---\nname: clawpm\ndescription: Multi-project task and research management (JSON-first CLI)\nuser-invocable: true\nmetadata: { \"openclaw\": { \"homepage\": \"https://github.com/malphas-gh/clawpm\", \"requires\": { \"bins\": [\"clawpm\"] }, \"emoji\": \"📋\", \"install\": [{ \"id\": \"uv\", \"kind\": \"uv\", \"package\": \"git+https://github.com/malphas-gh/clawpm\", \"bins\": [\"clawpm\"], \"label\": \"Install clawpm (uv)\" }] } }\n---\n\n# ClawPM Skill\n\nMulti-project task management. All commands emit JSON by default; use `-f text` for human-readable output.\n\n## First-Time Setup\n\n```bash\nclawpm setup               # Creates ~/clawpm/ with portfolio.toml, projects/, work_log.jsonl\nclawpm setup --check       # Verify installation\n```\n\n## Creating Projects\n\nProjects are directories with a `.project/` folder. They don't need to be git repos.\n\n### Initialize in any directory\n\n```bash\ncd /path/to/my-project\nclawpm project init                    # Auto-detects ID/name from directory\nclawpm project init --id myproj        # Custom ID\n```\n\n### From a git clone (auto-init)\n\nGit repos under `~/clawpm/projects/` auto-initialize on first use:\n\n```bash\ngit clone git@github.com:user/repo.git ~/clawpm/projects/repo\ncd ~/clawpm/projects/repo\nclawpm add \"First task\"    # Auto-initializes .project/, then adds task\n```\n\n### Discover untracked repos\n\n```bash\nclawpm projects list --all   # Shows tracked + untracked git repos\n```\n\n## Quick Start\n\n```bash\n# From a project directory (auto-detected):\nclawpm status              # See project status\nclawpm next                # Get next task\nclawpm start 42            # Start task (short ID works)\nclawpm done 42             # Mark done\n\n# Or set a project context:\nclawpm use my-project\nclawpm status              # Now uses my-project\n```\n\n## Top-Level Commands (Shortcuts)\n\n| Command | Equivalent | Description |\n|---------|------------|-------------|\n| `clawpm add \"Title\"` | `clawpm tasks add -t \"Title\"` | Quick add a task |\n| `clawpm add \"Title\" -b \"desc\"` | `clawpm tasks add -t \"Title\" -b \"desc\"` | Add with body |\n| `clawpm add \"Title\" --parent 25` | - | Add subtask |\n| `clawpm done 42` | `clawpm tasks state 42 done` | Mark task done |\n| `clawpm start 42` | `clawpm tasks state 42 progress` | Start working |\n| `clawpm block 42` | `clawpm tasks state 42 blocked` | Mark blocked |\n| `clawpm next` | `clawpm projects next` | Get next task |\n| `clawpm status` | - | Project overview |\n| `clawpm context` | - | Full agent context |\n| `clawpm use <id>` | - | Set project context |\n\n## Project Auto-Detection\n\nClawPM automatically detects your project from (in priority order):\n1. **Subcommand flag**: `clawpm tasks list --project clawpm`\n2. **Global flag**: `clawpm --project clawpm status`\n3. **Current directory**: Walks up looking for `.project/settings.toml`\n4. **Auto-init**: If in untracked git repo under project_roots, auto-initializes\n5. **Context**: Previously set with `clawpm use <project>`\n\n## Short Task IDs\n\nYou can use just the numeric part of a task ID:\n- `42` → `CLAWP-042` (prefix derived from project ID)\n- `CLAWP-042` → `CLAWP-042` (full ID works too)\n\n## Subtasks\n\n```bash\nclawpm add \"Subtask\" --parent 25   # Creates subtask (auto-splits parent if needed)\nclawpm tasks split 25              # Manually convert task to parent directory\n\nclawpm done 25             # Fails if subtasks not done\nclawpm done 25 --force     # Override and complete anyway\n```\n\nSubtasks move with parent on state change (done/blocked moves entire directory).\n\n## Agent Context (Resuming Work)\n\nGet everything needed to resume work in one command:\n\n```bash\nclawpm context             # Full context for current project\nclawpm context -p myproj   # Specific project\n```\n\nReturns JSON with: project info + spec, in-progress/next task, blockers, recent work log, git status, open issues.\n\n## Workflow Example\n\n```bash\nclawpm context             # Get full context\nclawpm start 42            # Mark in progress (auto-logs)\n# ... do work ...\ngit add . && git commit -m \"feat: ...\"\nclawpm done 42 --note \"Completed\"       # Auto-logs with files_changed\nclawpm log commit                        # Also log the git commits themselves\n```\n\nHit a blocker:\n```bash\nclawpm block 42 --note \"Need API credentials\"\n```\n\n## Full Command Reference\n\n### Projects\n```bash\nclawpm projects list [--all]            # List projects (--all includes untracked repos)\nclawpm projects next                    # Next task across all projects\nclawpm project context [project]        # Full project context\nclawpm project init                     # Initialize project in current dir\n```\n\n### Tasks\n```bash\nclawpm tasks                            # List tasks (default: open+progress+blocked)\nclawpm tasks list [-s open|done|blocked|progress|all] [--flat]\nclawpm tasks show <id>                  # Task details\nclawpm tasks add -t \"Title\" [--priority 3] [--complexity m] [--parent <id>] [-b \"body\"]\nclawpm tasks edit <id> [--title \"...\"] [--priority N] [--complexity s|m|l|xl] [--body \"...\"]\nclawpm tasks state <id> open|progress|done|blocked [--note \"...\"] [--force]\nclawpm tasks split <id>                 # Convert to parent directory for subtasks\n```\n\n### Work Log\n```bash\nclawpm log add --task <id> --action progress --summary \"What I did\"\nclawpm log tail [--limit 10]            # Recent entries (auto-filtered to current project)\nclawpm log tail --all                   # Recent entries across all projects\nclawpm log tail --follow                # Live tail (like tail -f)\nclawpm log last                         # Most recent entry (auto-filtered to current project)\nclawpm log last --all                   # Most recent entry across all projects\nclawpm log commit [-n 10]               # Log recent git commits to work log\nclawpm log commit --dry-run             # Preview without logging\nclawpm log commit --task <id>           # Associate commits with a task\n```\n\nNote: State changes (start/done/block) auto-log to work_log with git files_changed.\n\n### Research\n```bash\nclawpm research list\nclawpm research add --type investigation --title \"Question\"\nclawpm research link --id <research_id> --session-key <key>\n```\n\n### Issues\n```bash\nclawpm issues add --type bug --severity high --actual \"What happened\"\nclawpm issues list [--open]             # Open issues only\n```\n\n### Admin\n```bash\nclawpm setup               # Create portfolio (first-time)\nclawpm setup --check       # Verify installation\nclawpm status              # Project overview\nclawpm context             # Full agent context\nclawpm doctor              # Health check\nclawpm use [project]       # Set/show project context\nclawpm use --clear         # Clear context\n```\n\n## Work Log Actions\n\n- `start` - Started working (auto-logged on `clawpm start`)\n- `progress` - Made progress\n- `done` - Completed (auto-logged on `clawpm done`)\n- `blocked` - Hit a blocker (auto-logged on `clawpm block`)\n- `commit` - Git commit (logged via `clawpm log commit`)\n- `pause` - Switching tasks\n- `research` - Research note\n- `note` - General observation\n\n## Task States & File Locations\n\n| State | File Pattern | Meaning |\n|-------|--------------|---------|\n| open | `tasks/CLAWP-042.md` | Ready to work |\n| progress | `tasks/CLAWP-042.progress.md` | In progress |\n| done | `tasks/done/CLAWP-042.md` | Completed |\n| blocked | `tasks/blocked/CLAWP-042.md` | Waiting |\n\n## Tips\n\n- **Flag order**: `clawpm [global flags] <command> [command flags]` — e.g. `clawpm -f text tasks list -s open`\n- **JSON output**: All commands emit JSON by default; use `-f text` for human-readable\n- **One command per call**: Don't chain clawpm commands with `&&` — run each separately\n- **Portfolio root**: Default `~/clawpm`\n- **Work log**: Append-only at `<portfolio>/work_log.jsonl`\n\n## Troubleshooting\n\n```bash\nclawpm doctor              # Check for issues\nclawpm setup --check       # Verify installation\nclawpm log tail            # See recent activity\n```\n","tags":{"latest":"0.1.3"},"stats":{"comments":0,"downloads":1215,"installsAllTime":2,"installsCurrent":2,"stars":0,"versions":4},"createdAt":1771065906621,"updatedAt":1778990473910},"latestVersion":{"version":"0.1.3","createdAt":1771575586296,"changelog":"- Added a homepage URL to the skill metadata.\n- Removed `CLAWPM_PORTFOLIO` and `CLAWPM_PROJECT_ROOTS` environment variable documentation.\n- Removed guidance on overriding portfolio/project roots and on modifying `portfolio.toml`.\n- Improved troubleshooting advice (now suggests `clawpm log tail` for recent activity).\n- No changes to core commands or skill logic.","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"malphas-gh","userId":"s17dtb8gnsk6htaw29vvhbveh1885afv","displayName":"malphas-gh","image":"https://avatars.githubusercontent.com/u/259541107?v=4"},"moderation":null}