taskwarrior

由 Taskwarrior 提供支持的工作区本地任务管理。添加、组织、 并按项目、标签、截止日期和所有数据的优先级跟踪任务 存储在活动工作空间内。

# Taskwarrior (Workspace-Local Tasks) — AgentSkill

## Skill name
taskwarrior

## Purpose
Manage tasks using Taskwarrior as the backend with data stored inside the current workspace. This skill provides a safe, workspace-scoped wrapper for common Taskwarrior operations (add/list/modify/done/projects/tags/due/priority/annotations).

## Runtime requirements (ClawHub)
This skill **requires Taskwarrior to already be available** in the runtime environment (e.g., included in the base image).
- Validation: run `task --version`
- If missing: report the dependency and instruct the environment owner to install system package **taskwarrior** (some distros package it as **task**).

This skill **does not perform system-level installs** (no `apt`, `brew`, `dnf`, etc.).

## Workspace root resolution (portable)
The skill resolves the workspace root at runtime:
1) If set, use the first available of:
   - OPENCLAW_WORKSPACE
   - WORKSPACE
   - PROJECT_DIR
   - REPO_ROOT
2) Otherwise, fallback to the current working directory.

All Taskwarrior data is stored under:
`<workspace>/.openclaw/taskwarrior/`

## Workspace-local Taskwarrior home
- taskrc: `<workspace>/.openclaw/taskwarrior/taskrc`
- data dir: `<workspace>/.openclaw/taskwarrior/.task/`

Every Taskwarrior command MUST run with:
- `TASKRC=<workspace>/.openclaw/taskwarrior/taskrc`
- (optional) `TASKDATA=<workspace>/.openclaw/taskwarrior/.task`

Never write to global `~/.task` or `~/.taskrc` unless the user explicitly asks to use global storage.

## Core workflow
1) **Check dependency**
   - Run: `task --version`
   - If missing: stop and return dependency instructions (see references/clawhub_notes.md).

2) **Initialize workspace storage**
   - Ensure directories exist:
     - `<workspace>/.openclaw/taskwarrior/`
     - `<workspace>/.openclaw/taskwarrior/.task/`
   - Ensure `<workspace>/.openclaw/taskwarrior/taskrc` contains at least:
     - `data.location=<workspace>/.openclaw/taskwarrior/.task`
     - `confirmation=off`
     - `verbose=off`

3) **Execute requested operations**
   - Prefer stable/common commands (see references/taskwarrior_cheatsheet.md).

4) **Verify results**
   - After any mutation, show a focused `task <id> info` or filtered `task <filter> list`.

## Supported operations (useful subset)
- Add tasks: `task add ...`
- List tasks: `task list`, `task <filter> list`
- Modify tasks: `task <id> modify ...`
- Complete tasks: `task <id> done`
- Start/stop: `task <id> start|stop` (if desired)
- Projects/tags: `task projects`, `task tags`, `project:<name>`, `+tag`, `-tag`
- Due/priorities: `due:<date>`, `priority:H|M|L`
- Notes: `task <id> annotate "..."`

## Safety
Follow `references/safe_command_policy.md`.
Highlights:
- No delete/purge unless explicitly requested.
- Avoid broad bulk changes without previewing the matching set.
- No global config writes by default.

## References
- references/workspace_data_layout.md
- references/taskwarrior_cheatsheet.md
- references/safe_command_policy.md
- references/examples.md
- references/clawhub_notes.md

---

## 中文说明

# Taskwarrior（工作区本地任务）— AgentSkill

## 技能名称
taskwarrior

## 用途
以 Taskwarrior 作为后端管理任务，数据存储在当前工作区内。本技能为常见的 Taskwarrior 操作（add/list/modify/done/projects/tags/due/priority/annotations）提供安全的、限定于工作区范围的封装。

## 运行时要求（ClawHub）
本技能**要求运行时环境中已经提供 Taskwarrior**（例如包含在基础镜像中）。
- 验证：运行 `task --version`
- 如果缺失：报告该依赖，并指示环境所有者安装系统软件包 **taskwarrior**（某些发行版将其打包为 **task**）。

本技能**不执行系统级安装**（不使用 `apt`、`brew`、`dnf` 等）。

## 工作区根目录解析（可移植）
本技能在运行时解析工作区根目录：
1) 如果已设置，使用以下首个可用项：
   - OPENCLAW_WORKSPACE
   - WORKSPACE
   - PROJECT_DIR
   - REPO_ROOT
2) 否则，回退到当前工作目录。

所有 Taskwarrior 数据存储于：
`<workspace>/.openclaw/taskwarrior/`

## 工作区本地的 Taskwarrior 主目录
- taskrc：`<workspace>/.openclaw/taskwarrior/taskrc`
- 数据目录：`<workspace>/.openclaw/taskwarrior/.task/`

每个 Taskwarrior 命令都必须使用以下变量运行：
- `TASKRC=<workspace>/.openclaw/taskwarrior/taskrc`
- （可选）`TASKDATA=<workspace>/.openclaw/taskwarrior/.task`

除非用户明确要求使用全局存储，否则切勿写入全局的 `~/.task` 或 `~/.taskrc`。

## 核心工作流程
1) **检查依赖**
   - 运行：`task --version`
   - 如果缺失：停止并返回依赖说明（参见 references/clawhub_notes.md）。

2) **初始化工作区存储**
   - 确保目录存在：
     - `<workspace>/.openclaw/taskwarrior/`
     - `<workspace>/.openclaw/taskwarrior/.task/`
   - 确保 `<workspace>/.openclaw/taskwarrior/taskrc` 至少包含：
     - `data.location=<workspace>/.openclaw/taskwarrior/.task`
     - `confirmation=off`
     - `verbose=off`

3) **执行请求的操作**
   - 优先使用稳定/常见的命令（参见 references/taskwarrior_cheatsheet.md）。

4) **验证结果**
   - 任何修改之后，显示有针对性的 `task <id> info` 或经过过滤的 `task <filter> list`。

## 支持的操作（实用子集）
- 添加任务：`task add ...`
- 列出任务：`task list`、`task <filter> list`
- 修改任务：`task <id> modify ...`
- 完成任务：`task <id> done`
- 开始/停止：`task <id> start|stop`（如有需要）
- 项目/标签：`task projects`、`task tags`、`project:<name>`、`+tag`、`-tag`
- 截止日期/优先级：`due:<date>`、`priority:H|M|L`
- 备注：`task <id> annotate "..."`

## 安全
遵循 `references/safe_command_policy.md`。
要点：
- 除非明确请求，否则不执行 delete/purge。
- 在预览匹配集之前，避免进行大范围的批量更改。
- 默认不写入全局配置。

## 参考资料
- references/workspace_data_layout.md
- references/taskwarrior_cheatsheet.md
- references/safe_command_policy.md
- references/examples.md
- references/clawhub_notes.md