opentasks-task-lifecycle

OpenTasks Task Lifecycle

Use this skill after using-opentasks routes task lifecycle work here. Markdown remains the source of truth.

Source Files

• info-for-agent/tasks.md: task ledger
• tasks/{task-name}/brief.md: 完整任务 brief 和迭代需求历史
• tasks/{task-name}/progress.md: plan、checkpoint ledger 和收尾证据
• tasks/{task-name}/...: task-local deliverables when needed

Use opentasks CLI for deterministic writes when available. If the CLI is unavailable, hand-edit Markdown using the exact table format.

Startup

1. Confirm info-for-agent/tasks.md exists; if not, run opentasks init when available.
2. Identify whether the user is starting a new task, continuing an active task, iterating an older task, or finishing work.
3. For cross-repository path lookup, use opentasks-repo-index before editing task state.

Use this skill only when the user explicitly asks to start, record, continue, iterate, track, or finish an OpenTasks task, or clearly wants a piece of work tracked over time. Small requests can be lightweight tasks; larger multi-step work uses the full lifecycle.

Aone work items and DingTalk documents are explicit tools. Create or update them only when the user asks for an Aone item or DingTalk document; lightweight/full lifecycle does not decide this automatically. DingTalk content belongs to the DingTalk tool/skill; OpenTasks records only necessary evidence links and results.

Lightweight vs Full Lifecycle

• Lightweight task: write tasks.md, brief.md, and progress.md; define a short plan and checkpoint only meaningful progress.
• Full lifecycle task: use for multi-step implementation, document delivery, release, or handoff work; use the same plan/checkpoint model, but keep stricter verification, delivery evidence, commits, and close-check gates when required.

New Task

调用 CLI 前，先把用户原始诉求整理成完整 Markdown 需求文档，不要压缩成一句摘要。保留重要背景、目标、约束、输出期望、参考资料、验收标准和明确决策。

Create an Aone work item only when the user explicitly asks for Aone. Default to stamp=Req; use stamp=Bug only when the user clearly says this is a bug/defect. Resolve project name and assignee from info-for-agent/memories.md; if either is missing, ask the user. If Aone is not requested or the user skips it, record -.

Use:

opentasks task start \
  --name "<short task name>" \
  --slug "<english-kebab-slug>" \
  --brief "<完整任务 brief，可包含 Markdown 小节>" \
  --repo "<repo-name>" \
  --project "<project-name>" \
  --step "<plan-step>" \
  --work-item "<Aone work item ID or ->" \
  --date "YYYY-MM-DD"

Repeat --repo, --project, and --step as needed. The CLI writes repo/project values into the generated ## 关联 table in brief.md. If no --step is supplied, the default plan is context-loaded, work, and verify.

This creates:

• a T{N} row in info-for-agent/tasks.md
• tasks/{slug}/
• tasks/{slug}/brief.md
• tasks/{slug}/progress.md

The generated brief includes a ## 关联 table. Use it to record task-local links:

| 类型 | 名称 | 说明 |
|------|------|------|
| project | plugin-platform | 本任务属于插件平台升级 |
| repo | opentasks | 任务管理和 hooks 实现 |

Long-lived relationships between repos belong in info-for-agent/repo-map.md, not in every task brief.

For plain text brief content, the CLI stores it under ### 核心需求. If you provide structured Markdown, prefer sections such as:

### 背景

...

### 核心需求

...

### 输出

...

### 约束

...

Continue Task

1. Match the user request to an active row in info-for-agent/tasks.md.
2. Continue using the existing tasks/{slug}/ directory.
3. Keep task-local deliverables under that directory when needed.
4. Update the row conclusion only when there is meaningful progress.

Progress Checkpoints

Use progress.md for the task plan, current step state, append-only ledger, and short external evidence. Do not duplicate task requirements from brief.md.

Record durable progress with:

opentasks task checkpoint \
  --task-id "<task-id>" \
  --step "<step>" \
  --status "done|skipped|blocked|pending" \
  --evidence "<short evidence>" \
  --date "YYYY-MM-DD"

Common steps:

• context-loaded
• work
• verify

For larger tasks, define explicit steps at task start, such as read-doc, update-code, verify, record-aone, and git-commit.

context-loaded is normally written by the OpenTasks SessionStart hook after context injection. Do not duplicate it unless the hook did not run.

Stage Commit Policy

After meaningful code or documentation changes during task lifecycle work, make a stage git commit in the touched repo when it is safe to do so, then record it with opentasks task checkpoint --step git-commit --status done --evidence "<commit sha/message>". For full lifecycle tasks, include git-commit in the initial --step plan; if the decision is made later, checkpoint it with --allow-new-step. If there are no changes, the user asked not to commit, or the repo is not in a committable state, mark git-commit as skipped with the reason. Do not force commits for atomic repo management commands, and do not push unless the user explicitly asks.

Use done when completed, skipped when intentionally not needed, and blocked when work cannot proceed. Always include evidence.

Inspect progress with:

opentasks task status --task-id "<task-id>"

Aone work item links, DingTalk document links, GitHub PRs/commits, test reports, and release links go into checkpoint evidence. Keep tasks.md concise; its 工作项 field stores the work item ID or -.

Iteration

迭代时，先把本轮新增诉求整理成完整迭代需求小节。保留相对上一轮的变化、新增约束和预期输出。

Use:

opentasks task iterate \
  --task-id "<task-id>" \
  --brief "<本轮迭代 brief，可包含 Markdown 小节>" \
  --repo "<new-or-relevant-repo>" \
  --project "<new-or-relevant-project>" \
  --step "<this-iteration-plan-step>" \
  --work-item "<Aone work item ID; omit to reuse the previous task work item>" \
  --date "YYYY-MM-DD"

This marks the previous row as 迭代, adds T{N}-v{M}, reuses the same task directory, appends any missing repo/project rows to ## 关联, appends a ## YYYY-MM-DD 迭代 vN section to brief.md, and appends Plan vN to progress.md. It does not erase old plans or ledger entries.

Finish

Before finishing, run:

opentasks task close-check --task-id "<task-id>"

Use --require-commit or --require-push only when the task policy or user request requires those gates.

Use:

opentasks task finish \
  --task-id "<task-id>" \
  --date "YYYY-MM-DD" \
  --conclusion "<one-sentence final result>"

After finishing, route reusable learnings to opentasks-memory.

Remove Task Row

If the user gives a task ID and asks to delete or remove it, run the CLI directly. Do not load full context just to remove a task row.

opentasks task remove --task-id "<task-id>"

This removes the task row from tasks.md and moves the whole tasks/{slug} directory into trash, including brief.md and progress.md. Use opentasks-trash only for restore, purge, empty, or ambiguous delete targets.

State Values

Use only these states:

状态值	含义	何时设置
未开始	已创建记录，尚未执行	创建记录但暂不执行时
进行中	正在执行	开始执行任务时
迭代	本轮已完成，进入下一轮	老任务被迭代时，标记原记录
结束	任务完成	任务交付完成时

tasks.md Format

# 任务追踪表

## 任务记录

| ID | 任务名称 | 状态 | 迭代 | 关联任务 | 工作项 | 开始时间 | 结束时间 | 目录 | 核心结论 |
|----|---------|------|------|---------|-------|---------|---------|------|---------|

Rules

• IDs are T{N} for new tasks and T{N}-v{M} for iterations.
• Slugs are lowercase English kebab-case.
• brief.md records the task brief, not execution logs. Use it for user requests, background, goals, constraints, outputs, decisions, related repos/projects, and iteration deltas.
• progress.md records execution state and evidence only.
• New tasks get a new directory; iterations reuse the existing directory.
• Do not create duplicate task rows for clear continuations.
• Do not modify memories.md; route durable lessons to opentasks-memory.
• Do not maintain repository paths here; route repository lookup and updates to opentasks-repo-index.
• Do not permanently delete task-local deliverables unless the user explicitly asks.