ogt-docs-create-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OGT Docs - Create Task

OGT Docs - 创建任务

Complete guide for creating and managing tasks in the docs-first workflow.

文档优先工作流中任务创建与管理的完整指南。

Overview

概述

Tasks are the unit of work in the docs-first system. Each task is a folder that moves through workflow stages, accumulating documentation and signals as it progresses.

mermaid

flowchart LR
    subgraph stages ["Task Lifecycle"]
        P[pending] --> IP[in_progress]
        IP --> R[review]
        R --> D[done]

        IP --> B[blocked]
        B --> IP

        R --> REJ[rejected]
        REJ --> P

        D --> IMP[implemented]
    end

    style P fill:#fef3c7
    style IP fill:#dbeafe
    style R fill:#e0e7ff
    style B fill:#fee2e2
    style REJ fill:#fecaca
    style D fill:#d1fae5
    style IMP fill:#a7f3d0

任务是文档优先系统中的工作单元。每个任务是一个文件夹，会在不同工作流阶段间流转，在推进过程中积累文档和标记信息。

mermaid

flowchart LR
    subgraph stages ["Task Lifecycle"]
        P[pending] --> IP[in_progress]
        IP --> R[review]
        R --> D[done]

        IP --> B[blocked]
        B --> IP

        R --> REJ[rejected]
        REJ --> P

        D --> IMP[implemented]
    end

    style P fill:#fef3c7
    style IP fill:#dbeafe
    style R fill:#e0e7ff
    style B fill:#fee2e2
    style REJ fill:#fecaca
    style D fill:#d1fae5
    style IMP fill:#a7f3d0

Folder Structure

文件夹结构

docs/todo/
├── pending/                    # Tasks not yet started
│   └── {task_slug}/
│       ├── task.md             # Primary task definition
│       ├── context.md          # Background information (optional)
│       ├── .version            # Schema version
│       └── .priority           # Priority level (content: critical|high|medium|low)
│
├── in_progress/                # Tasks being actively worked on
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md         # Work log and updates
│       ├── .version
│       ├── .priority
│       ├── .assigned_to_{agent}  # Who's working on it
│       └── .started_at         # Timestamp when started
│
├── review/                     # Tasks awaiting review
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── implementation.md   # What was done
│       ├── .version
│       ├── .ready_for_review   # Empty signal
│       ├── .pr_link            # PR URL if applicable
│       └── .review_requested_at
│
├── blocked/                    # Tasks that cannot proceed
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── .version
│       ├── .blocked            # Empty signal
│       ├── .blocked_reason     # Why blocked (content)
│       ├── .blocked_at         # When blocked
│       └── .depends_on         # What it's waiting for
│
├── done/                       # Completed and verified tasks
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── implementation.md
│       ├── verification.md     # How it was verified
│       ├── .version
│       ├── .verified           # Empty signal - REQUIRED
│       ├── .completed_at       # Completion timestamp
│       └── .verified_by_{agent}  # Who verified
│
├── rejected/                   # Tasks that were declined
│   └── {task_slug}/
│       ├── task.md
│       ├── .version
│       ├── .rejected           # Empty signal
│       ├── .rejected_reason    # Why rejected (content)
│       └── .rejected_at        # When rejected
│
└── implemented/                # Done tasks that are deployed/released
    └── {task_slug}/
        ├── task.md
        ├── implementation.md
        ├── verification.md
        ├── .version
        ├── .verified
        ├── .completed_at
        ├── .implemented_at     # When deployed
        └── .release_version    # Which release included it

docs/todo/
├── pending/                    # 未启动的任务
│   └── {task_slug}/
│       ├── task.md             # 主要任务定义
│       ├── context.md          # 背景信息（可选）
│       ├── .version            # 版本 Schema
│       └── .priority           # 优先级（内容：critical|high|medium|low）
│
├── in_progress/                # 进行中的任务
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md         # 工作日志与更新
│       ├── .version
│       ├── .priority
│       ├── .assigned_to_{agent}  # 任务负责人
│       └── .started_at         # 启动时间戳
│
├── review/                     # 待审核任务
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── implementation.md   # 完成内容说明
│       ├── .version
│       ├── .ready_for_review   # 空文件标记
│       ├── .pr_link            # 对应PR链接（如有）
│       └── .review_requested_at
│
├── blocked/                    # 受阻任务
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── .version
│       ├── .blocked            # 空文件标记
│       ├── .blocked_reason     # 受阻原因（内容）
│       ├── .blocked_at         # 受阻时间戳
│       └── .depends_on         # 依赖项
│
├── done/                       # 已完成并验证的任务
│   └── {task_slug}/
│       ├── task.md
│       ├── progress.md
│       ├── implementation.md
│       ├── verification.md     # 验证说明
│       ├── .version
│       ├── .verified           # 空文件标记 - 必填
│       ├── .completed_at       # 完成时间戳
│       └── .verified_by_{agent}  # 验证人
│
├── rejected/                   # 已拒绝的任务
│   └── {task_slug}/
│       ├── task.md
│       ├── .version
│       ├── .rejected           # 空文件标记
│       ├── .rejected_reason    # 拒绝原因（内容）
│       └── .rejected_at        # 拒绝时间戳
│
└── implemented/                # 已部署/发布的完成任务
    └── {task_slug}/
        ├── task.md
        ├── implementation.md
        ├── verification.md
        ├── .version
        ├── .verified
        ├── .completed_at
        ├── .implemented_at     # 部署时间戳
        └── .release_version    # 对应版本号

Stage: pending/

阶段：pending/

Tasks that are defined but not yet started.

已定义但尚未启动的任务。

Example: pending/fuzzy_search/

示例：pending/fuzzy_search/

pending/
└── fuzzy_search/
    ├── task.md
    ├── context.md
    ├── .version
    └── .priority

pending/
└── fuzzy_search/
    ├── task.md
    ├── context.md
    ├── .version
    └── .priority

task.md

markdown

undefined

markdown

undefined

Task: Fuzzy Search Implementation

Task: 模糊搜索实现

Summary

概述

Replace substring search with fuzzy indexed search using MiniSearch.

使用MiniSearch将子字符串搜索替换为模糊索引搜索。

Objectives

目标

Install MiniSearch library
Create SearchIndexService
Refactor GlobalSearch component
Add debounce to search input

安装MiniSearch库
创建SearchIndexService
重构GlobalSearch组件
为搜索输入添加防抖功能

Acceptance Criteria

验收标准

Typing "fir" returns "Fireball", "Fire Elemental", etc.
Results ranked by relevance
Search responds within 16ms
TypeScript compiles clean

输入"fir"返回"Fireball"、"Fire Elemental"等结果
结果按相关性排序
搜索响应时间在16ms以内
TypeScript编译无错误

Dependencies

依赖项

None

Estimated Effort

预估工作量

Medium (2-4 hours)

中等（2-4小时）

References

参考资料

MiniSearch docs: https://lucaong.github.io/minisearch/
Current search: front/components/features/GlobalSearch.tsx

undefined

MiniSearch文档: https://lucaong.github.io/minisearch/
当前搜索实现: front/components/features/GlobalSearch.tsx

undefined

context.md

markdown

undefined

markdown

undefined

Context: Fuzzy Search

背景：模糊搜索

Current State

当前状态

GlobalSearch.tsx uses

String.toLowerCase().includes()

for matching. No ranking, no debounce, no fuzzy matching.

GlobalSearch.tsx使用

String.toLowerCase().includes()

进行匹配。无排序、无防抖、无模糊匹配。

User Request

用户需求

"Global search with ctrl+k, should be instant, indexed, fuzzy. If I search fire just by typing fir I should get instantly a list."

"使用ctrl+k唤起的全局搜索应具备即时性、索引化和模糊匹配能力。输入'fir'就能立刻显示相关结果。"

Technical Decision

技术决策

MiniSearch chosen over:

Fuse.js (heavier, slower on large datasets)
Lunr (no fuzzy matching)

MiniSearch is 6KB gzipped, used by VitePress.

undefined

选择MiniSearch而非：

Fuse.js（体积更大，大数据集下速度更慢）
Lunr（无模糊匹配功能）

MiniSearch压缩后仅6KB，已被VitePress采用。

undefined

.version

json

{ "schema": "1.0", "created": "2026-02-05T10:00:00Z" }

json

{ "schema": "1.0", "created": "2026-02-05T10:00:00Z" }

.priority

high

high

Stage: in_progress/

阶段：in_progress/

Tasks actively being worked on.

正在进行中的任务。

Example: in_progress/card_variants/

示例：in_progress/card_variants/

in_progress/
└── card_variants/
    ├── task.md
    ├── progress.md
    ├── .version
    ├── .priority
    ├── .assigned_to_claude
    └── .started_at

in_progress/
└── card_variants/
    ├── task.md
    ├── progress.md
    ├── .version
    ├── .priority
    ├── .assigned_to_claude
    └── .started_at

task.md

markdown

undefined

markdown

undefined

Task: Card Variant System Expansion

Task: 卡片变体系统扩展

Summary

概述

Add Condensed, ListItemCondensed, and stub Quaternary/Penta card variants.

添加Condensed、ListItemCondensed卡片变体，并创建Quaternary/Penta卡片的占位实现。

Objectives

目标

Update UICardFrameType enum
Create *Condensed.tsx components
Create *ListItemCondensed.tsx components
Stub Quaternary and Penta variants
Update all *CardMain.tsx orchestrators

更新UICardFrameType枚举
创建*Condensed.tsx组件
创建*ListItemCondensed.tsx组件
编写Quaternary和Penta变体的占位代码
更新所有*CardMain.tsx编排器

Acceptance Criteria

验收标准

Dependencies

依赖项

None

Estimated Effort

预估工作量

Large (4-8 hours)

undefined

大型（4-8小时）

undefined

progress.md

markdown

undefined

markdown

undefined

Progress: Card Variants

进度：卡片变体

2026-02-05 10:30 - Started

2026-02-05 10:30 - 启动

Read existing card components
Identified 8 entity types needing variants
Created implementation plan

阅读现有卡片组件代码
确定需要变体的8种实体类型
制定实现计划

2026-02-05 11:00 - UICardFrameType Updated

2026-02-05 11:00 - UICardFrameType已更新

Added Condensed, Penta, ListItem, ListItemCondensed to type
File: front/data/app-generics.ts:82

为类型添加Condensed、Penta、ListItem、ListItemCondensed选项
文件路径: front/data/app-generics.ts:82

2026-02-05 11:30 - CreatureCardCondensed Created

2026-02-05 11:30 - CreatureCardCondensed已创建

Created front/components/compendium/CreatureCardCondensed.tsx
64x64 portrait, rarity border, type icon badge
Tooltip on hover shows name

创建front/components/compendium/CreatureCardCondensed.tsx
64x64头像、稀有度边框、类型图标徽章
悬停时显示名称提示框

Current Status

当前状态

类型定义已更新
CreatureCardCondensed已完成
ItemCardCondensed待完成
AbilityCardCondensed待完成
剩余实体类型待处理
ListItemCondensed变体待完成
Quaternary/Penta占位代码待编写
编排器待更新

undefined

.assigned_to_claude

(empty file - presence indicates assignment)

(空文件 - 存在即表示已分配)

.started_at

2026-02-05T10:30:00Z

2026-02-05T10:30:00Z

Stage: review/

阶段：review/

Tasks completed and awaiting review.

已完成并等待审核的任务。

Example: review/spell_routes/

示例：review/spell_routes/

review/
└── spell_routes/
    ├── task.md
    ├── progress.md
    ├── implementation.md
    ├── .version
    ├── .ready_for_review
    ├── .pr_link
    └── .review_requested_at

review/
└── spell_routes/
    ├── task.md
    ├── progress.md
    ├── implementation.md
    ├── .version
    ├── .ready_for_review
    ├── .pr_link
    └── .review_requested_at

task.md

markdown

undefined

markdown

undefined

Task: Wire SpellDetailView into Router

Task: 将SpellDetailView接入路由

Summary

概述

SpellDetailView.tsx exists but is not routed. Wire it into the app router.

SpellDetailView.tsx已存在但未接入路由。需将其接入应用路由系统。

Objectives

目标

Add route to APP_ROUTES
Add Route element in App.tsx
Verify component loads correctly

在APP_ROUTES中添加路由
在App.tsx中添加Route元素
验证组件可正常加载

Acceptance Criteria

验收标准

/spells/:slug route works
SpellDetailView renders with spell data
Navigation from spell cards works
TypeScript compiles clean

undefined

/spells/:slug路由可正常访问
SpellDetailView可渲染法术数据
可从法术卡片导航至详情页
TypeScript编译无错误

undefined

progress.md

markdown

undefined

markdown

undefined

Progress: Spell Routes

进度：法术路由

2026-02-05 09:00 - Started

2026-02-05 09:00 - 启动

Located SpellDetailView at front/app/(main)/compendium/SpellDetailView.tsx
Reviewed existing route patterns

找到SpellDetailView文件路径：front/app/(main)/compendium/SpellDetailView.tsx
查看现有路由模式

2026-02-05 09:15 - Implementation Complete

2026-02-05 09:15 - 实现完成

Added spell_detail to APP_ROUTES in app-configs.ts
Added Route element in App.tsx
Tested with /spells/fireball - works
TypeScript compiles clean

undefined

在app-configs.ts的APP_ROUTES中添加spell_detail配置
在App.tsx中添加Route元素
测试/spells/fireball路由 - 可正常访问
TypeScript编译无错误

undefined

implementation.md

markdown

undefined

markdown

undefined

Implementation: Spell Routes

实现说明：法术路由

Files Changed

修改的文件

front/data/app-configs.ts

Added route configuration:

typescript

spell_detail: {
  path: '/spells/:slug',
  label: 'Spell Detail',
}

undefined

添加路由配置：

typescript

spell_detail: {
  path: '/spells/:slug',
  label: 'Spell Detail',
}

undefined

front/app/App.tsx

Added import and route:

typescript

import SpellDetailView from './(main)/compendium/SpellDetailView';
// ...
<Route path="/spells/:slug" element={<SpellDetailView />} />

添加导入语句和路由：

typescript

import SpellDetailView from './(main)/compendium/SpellDetailView';
// ...
<Route path="/spells/:slug" element={<SpellDetailView />} />

Testing

测试情况

Manual test: /spells/fireball loads correctly
Manual test: /spells/magic-missile loads correctly
TypeScript: No errors

undefined

手动测试：/spells/fireball可正常加载
手动测试：/spells/magic-missile可正常加载
TypeScript：无错误

undefined

.ready_for_review


(empty file)


(空文件)

.pr_link


https://github.com/org/repo/pull/123


https://github.com/org/repo/pull/123

.review_requested_at


2026-02-05T09:30:00Z


2026-02-05T09:30:00Z

Stage: blocked/

阶段：blocked/

Tasks that cannot proceed due to dependencies or blockers.

因依赖项或阻碍因素无法推进的任务。

Example: blocked/auth_refactor/

示例：blocked/auth_refactor/


blocked/
└── auth_refactor/
├── task.md
├── progress.md
├── .version
├── .blocked
├── .blocked_reason
├── .blocked_at
└── .depends_on


blocked/
└── auth_refactor/
├── task.md
├── progress.md
├── .version
├── .blocked
├── .blocked_reason
├── .blocked_at
└── .depends_on

task.md

markdown

undefined

markdown

undefined

Task: Auth Service Refactor

Task: 认证服务重构

Summary

概述

Refactor AuthService to support multiple OAuth providers.

重构AuthService以支持多OAuth提供商。

Objectives

目标

Abstract provider-specific logic
Add Steam OAuth support
Implement token refresh flow
Update all auth consumers

抽象提供商特定逻辑
添加Steam OAuth支持
实现令牌刷新流程
更新所有认证消费者

Acceptance Criteria

验收标准

Google OAuth仍可正常使用
Discord OAuth仍可正常使用
Steam OAuth可正常使用
令牌可自动刷新
对API无破坏性变更

undefined

progress.md

markdown

undefined

markdown

undefined

Progress: Auth Refactor

进度：认证服务重构

2026-02-03 14:00 - Started

2026-02-03 14:00 - 启动

Analyzed current AuthService implementation
Identified 3 provider-specific code paths

分析当前AuthService实现
识别出3个提供商特定代码路径

2026-02-03 15:00 - BLOCKED

2026-02-03 15:00 - 任务受阻

Steam OAuth requires server-side changes
Backend team needs to add Steam provider to Strapi
Cannot proceed until backend work is complete

Steam OAuth需要服务端变更
后端团队需为Strapi添加Steam提供商
后端工作完成前无法推进

Waiting For

等待项

Backend task: "Add Steam OAuth Provider to Strapi"
ETA: Unknown

undefined

后端任务："为Strapi添加Steam OAuth提供商"
预计完成时间：未知

undefined

.blocked

(empty file)

(空文件)

.blocked_reason

Requires backend changes: Steam OAuth provider must be added to Strapi before frontend can implement Steam login flow. Backend task not yet created.

需要后端变更：前端实现Steam登录流程前，需先为Strapi添加Steam OAuth提供商。该后端任务尚未创建。

.blocked_at

2026-02-03T15:00:00Z

2026-02-03T15:00:00Z

.depends_on

- backend/steam_oauth_provider (not yet created)
- Strapi plugin configuration

- backend/steam_oauth_provider（尚未创建）
- Strapi插件配置

Stage: done/

阶段：done/

Completed tasks that have been verified.

已完成且经过验证的任务。

Example: done/ogt_cli_commands/

示例：done/ogt_cli_commands/

done/
└── ogt_cli_commands/
    ├── task.md
    ├── progress.md
    ├── implementation.md
    ├── verification.md
    ├── .version
    ├── .verified
    ├── .completed_at
    └── .verified_by_claude

done/
└── ogt_cli_commands/
    ├── task.md
    ├── progress.md
    ├── implementation.md
    ├── verification.md
    ├── .version
    ├── .verified
    ├── .completed_at
    └── .verified_by_claude

task.md

markdown

undefined

markdown

undefined

Task: OGT CLI Check Commands

Task: OGT CLI检查命令

Summary

概述

Create generic file/data validation CLI tools under

ogt check

在

ogt check

下创建通用的文件/数据验证CLI工具。

Objectives

目标

ogt check assets - Check for missing files
ogt check slugs - Verify slug conventions
ogt check indexed - Verify index.ts exports
ogt check data - Validate against schema

ogt check assets - 检查缺失文件
ogt check slugs - 验证slug命名规范
ogt check indexed - 验证index.ts导出内容
ogt check data - 按Schema验证数据

Acceptance Criteria

验收标准

All commands have --help
Commands return proper exit codes
JSON output option available
TypeScript compiles clean

undefined

所有命令支持--help
命令返回正确的退出码
支持JSON输出选项
TypeScript编译无错误

undefined

verification.md

markdown

undefined

markdown

undefined

Verification: OGT CLI Commands

验证说明：OGT CLI命令

Verification Date

验证日期

2026-01-30

Tests Performed

执行的测试

Command Existence

命令存在性

bash

$ ogt check --help

bash

$ ogt check --help

✅ Shows subcommands: assets, slugs, indexed, data, from-list

✅ 显示子命令：assets, slugs, indexed, data, from-list

$ ogt check assets --help

✅ Shows usage and flags

✅ 显示使用方法和参数

$ ogt check slugs --help

✅ Shows usage and flags

✅ 显示使用方法和参数

$ ogt check indexed --help

✅ Shows usage and flags

✅ 显示使用方法和参数

$ ogt check data --help

✅ Shows usage and flags

✅ 显示使用方法和参数

undefined

undefined

Functional Tests

功能测试

bash

$ ogt check indexed creatures

bash

$ ogt check indexed creatures

✅ Returns JSON with 197 total, 197 passed

✅ 返回JSON，包含197个条目，全部通过验证

$ ogt check slugs front/data/app-creatures -r

✅ Returns JSON with slug validation results

✅ 返回slug验证结果的JSON

$ ogt check assets static/public/creatures portrait.png -r

✅ Returns JSON listing missing portraits

✅ 返回缺失头像列表的JSON

undefined

undefined

Exit Codes

退出码测试

bash

$ ogt check indexed creatures && echo "pass"

bash

$ ogt check indexed creatures && echo "pass"

✅ Exits 0, prints "pass"

✅ 退出码0，输出"pass"

$ ogt check indexed nonexistent || echo "fail"

✅ Exits 1, prints "fail"

✅ 退出码1，输出"fail"

undefined

undefined

Verification Result

验证结果

PASS - All acceptance criteria met

undefined

通过 - 所有验收标准均已满足

undefined

.verified


(empty file - REQUIRED for done/ status)


(空文件 - done/状态必填)

.completed_at


2026-01-30T14:00:00Z


2026-01-30T14:00:00Z

.verified_by_claude


(empty file)


(空文件)

Stage: rejected/

阶段：rejected/

Tasks that were declined and will not be implemented.

已被拒绝且不会实现的任务。

Example: rejected/legacy_api_compat/

示例：rejected/legacy_api_compat/


rejected/
└── legacy_api_compat/
├── task.md
├── .version
├── .rejected
├── .rejected_reason
└── .rejected_at


rejected/
└── legacy_api_compat/
├── task.md
├── .version
├── .rejected
├── .rejected_reason
└── .rejected_at

task.md

markdown

undefined

markdown

undefined

Task: Legacy API Compatibility Layer

Task: 旧版API兼容层

Summary

概述

Create compatibility layer for v0 API endpoints.

为v0 API端点创建兼容层。

Objectives

目标

Map v0 endpoints to v1 services
Maintain backward compatibility for 6 months
Log deprecation warnings

将v0端点映射到v1服务
保持向后兼容6个月
记录弃用警告

Acceptance Criteria

验收标准

.rejected

(empty file)

(空文件)

.rejected_reason

Decision: Clean break over compatibility layer.

Rationale:
1. No external consumers of v0 API
2. Maintenance burden outweighs benefits
3. v0 endpoints have security issues
4. Better to document migration path

Alternative: Create migration guide instead.
See: docs/guides/v0_to_v1_migration/

决策：选择彻底切换而非兼容层。

理由：
1. 无外部消费者使用v0 API
2. 维护成本超过收益
3. v0端点存在安全问题
4. 更好的方式是提供迁移指南

替代方案：创建迁移指南。
参考：docs/guides/v0_to_v1_migration/

.rejected_at

2026-02-01T09:00:00Z

2026-02-01T09:00:00Z

Stage: implemented/

阶段：implemented/

Tasks that are done AND deployed/released to production.

已完成且已部署/发布到生产环境的任务。

Example: implemented/creatures_index/

示例：implemented/creatures_index/

implemented/
└── creatures_index/
    ├── task.md
    ├── implementation.md
    ├── verification.md
    ├── .version
    ├── .verified
    ├── .completed_at
    ├── .implemented_at
    └── .release_version

implemented/
└── creatures_index/
    ├── task.md
    ├── implementation.md
    ├── verification.md
    ├── .version
    ├── .verified
    ├── .completed_at
    ├── .implemented_at
    └── .release_version

.implemented_at

2026-02-02T10:00:00Z

2026-02-02T10:00:00Z

.release_version

v1.2.0

v1.2.0

Task Lifecycle Operations

任务生命周期操作

Creating a New Task

创建新任务

mermaid

flowchart TD
    A[User Request] --> B{Task Defined?}
    B -->|No| C[Create task.md]
    C --> D[Add context.md if needed]
    D --> E[Set .priority]
    E --> F[Add .version]
    F --> G[Place in pending/]
    B -->|Yes| H[Update existing task]

Steps:

Create folder:
```
docs/todo/pending/{task_slug}/
```
Create
```
task.md
```
with Summary, Objectives, Acceptance Criteria
Optionally add
```
context.md
```
for background
Create
```
.priority
```
with level (critical/high/medium/low)
Create
```
.version
```
with schema version

mermaid

flowchart TD
    A[用户需求] --> B{任务已定义？}
    B -->|否| C[创建task.md]
    C --> D[按需添加context.md]
    D --> E[设置.priority]
    E --> F[添加.version]
    F --> G[放入pending/]
    B -->|是| H[更新现有任务]

步骤：

创建文件夹：
```
docs/todo/pending/{task_slug}/
```
创建
```
task.md
```
，包含概述、目标、验收标准
按需添加
```
context.md
```
补充背景信息
创建
```
.priority
```
文件，设置优先级（critical/high/medium/low）
创建
```
.version
```
文件，设置Schema版本

Starting a Task

启动任务

bash

undefined

bash

undefined

Move from pending to in_progress

从pending移动到in_progress

mv docs/todo/pending/{task_slug} docs/todo/in_progress/

Add assignment signal

添加负责人标记

touch docs/todo/in_progress/{task_slug}/.assigned_to_{agent}

Add start timestamp

添加启动时间戳

echo "$(date -Iseconds)" > docs/todo/in_progress/{task_slug}/.started_at

Create progress log

创建进度日志

touch docs/todo/in_progress/{task_slug}/progress.md

undefined

touch docs/todo/in_progress/{task_slug}/progress.md

undefined

Blocking a Task

标记任务受阻

bash

undefined

bash

undefined

Move to blocked

移动到blocked

mv docs/todo/in_progress/{task_slug} docs/todo/blocked/

Add blocked signals

添加受阻标记

touch docs/todo/blocked/{task_slug}/.blocked echo "Reason here" > docs/todo/blocked/{task_slug}/.blocked_reason echo "$(date -Iseconds)" > docs/todo/blocked/{task_slug}/.blocked_at

undefined

touch docs/todo/blocked/{task_slug}/.blocked echo "受阻原因" > docs/todo/blocked/{task_slug}/.blocked_reason echo "$(date -Iseconds)" > docs/todo/blocked/{task_slug}/.blocked_at

undefined

Submitting for Review

提交审核

bash

undefined

bash

undefined

Move to review

移动到review

mv docs/todo/in_progress/{task_slug} docs/todo/review/

Add review signals

添加审核标记

touch docs/todo/review/{task_slug}/.ready_for_review echo "$(date -Iseconds)" > docs/todo/review/{task_slug}/.review_requested_at

Add implementation docs

添加实现文档

Create implementation.md documenting what was done

创建implementation.md记录完成的工作

undefined

undefined

Completing a Task

完成任务

CRITICAL: Must verify before marking done!

bash

undefined

重要：标记完成前必须先验证！

bash

undefined

1. Run ALL acceptance criteria checks

1. 检查所有验收标准

2. Document in verification.md

2. 在verification.md中记录验证过程

3. ONLY if all pass:

3. 仅当所有标准通过后执行：

Move to done

移动到done

mv docs/todo/review/{task_slug} docs/todo/done/

Add completion signals

添加完成标记

touch docs/todo/done/{task_slug}/.verified # REQUIRED echo "$(date -Iseconds)" > docs/todo/done/{task_slug}/.completed_at touch docs/todo/done/{task_slug}/.verified_by_{agent}

undefined

touch docs/todo/done/{task_slug}/.verified # 必填 echo "$(date -Iseconds)" > docs/todo/done/{task_slug}/.completed_at touch docs/todo/done/{task_slug}/.verified_by_{agent}

undefined

Rejecting a Task

拒绝任务

bash

undefined

bash

undefined

Move to rejected

移动到rejected

mv docs/todo/review/{task_slug} docs/todo/rejected/

Add rejection signals

添加拒绝标记

touch docs/todo/rejected/{task_slug}/.rejected echo "Reason here" > docs/todo/rejected/{task_slug}/.rejected_reason echo "$(date -Iseconds)" > docs/todo/rejected/{task_slug}/.rejected_at

---

touch docs/todo/rejected/{task_slug}/.rejected echo "拒绝原因" > docs/todo/rejected/{task_slug}/.rejected_reason echo "$(date -Iseconds)" > docs/todo/rejected/{task_slug}/.rejected_at

---

Signal Files Reference

标记文件参考

Status Signals (empty files)

状态标记（空文件）

Signal	Stage	Meaning
`.blocked`	blocked/	Task cannot proceed
`.ready_for_review`	review/	Ready for review
`.verified`	done/, implemented/	REQUIRED - Implementation verified
`.rejected`	rejected/	Task declined

标记文件	所属阶段	含义
`.blocked`	blocked/	任务无法推进
`.ready_for_review`	review/	等待审核
`.verified`	done/, implemented/	必填 - 实现已验证
`.rejected`	rejected/	任务已被拒绝

Assignment Signals (empty files)

分配标记（空文件）

Signal	Stage	Meaning
`.assigned_to_{agent}`	in_progress/	Who's working on it
`.verified_by_{agent}`	done/	Who verified it
`.approved_by_{name}`	any	Who approved

标记文件	所属阶段	含义
`.assigned_to_{agent}`	in_progress/	任务负责人
`.verified_by_{agent}`	done/	验证人
`.approved_by_{name}`	任意阶段	审批人

Content Signals (contain text)

内容标记（包含文本）

Signal	Content	Example
`.version`	JSON schema version	`{"schema": "1.0", "created": "..."}`
`.priority`	Priority level	`high`
`.blocked_reason`	Why blocked	Free text explanation
`.rejected_reason`	Why rejected	Free text explanation
`.depends_on`	Dependencies	List of dependencies
`.pr_link`	PR URL	`https://github.com/...`
`.started_at`	ISO timestamp	`2026-02-05T10:00:00Z`
`.completed_at`	ISO timestamp	`2026-02-05T14:00:00Z`
`.blocked_at`	ISO timestamp	`2026-02-05T12:00:00Z`
`.rejected_at`	ISO timestamp	`2026-02-05T09:00:00Z`
`.implemented_at`	ISO timestamp	`2026-02-05T16:00:00Z`
`.release_version`	Version string	`v1.2.0`

标记文件	内容格式	示例
`.version`	JSON Schema版本	`{"schema": "1.0", "created": "..."}`
`.priority`	优先级级别	`high`
`.blocked_reason`	受阻原因	自由文本说明
`.rejected_reason`	拒绝原因	自由文本说明
`.depends_on`	依赖项列表	依赖项列表
`.pr_link`	PR链接	`https://github.com/...`
`.started_at`	ISO时间戳	`2026-02-05T10:00:00Z`
`.completed_at`	ISO时间戳	`2026-02-05T14:00:00Z`
`.blocked_at`	ISO时间戳	`2026-02-05T12:00:00Z`
`.rejected_at`	ISO时间戳	`2026-02-05T09:00:00Z`
`.implemented_at`	ISO时间戳	`2026-02-05T16:00:00Z`
`.release_version`	版本字符串	`v1.2.0`

Task.md Template

Task.md模板

markdown

undefined

markdown

undefined

Task: {Title}

Task: {任务标题}

Summary

概述

One paragraph describing what needs to be done and why.

用一段话描述需要完成的工作及原因。

Objectives

目标

Specific objective 1
Specific objective 2
Specific objective 3

具体目标1
具体目标2
具体目标3

Acceptance Criteria

验收标准

Dependencies

依赖项

{dependency} or "None"

{依赖项} 或 "无"

Estimated Effort

预估工作量

{Tiny|Small|Medium|Large|XLarge} ({time estimate})

{极小|小|中等|大|极大}（{时间预估}）

References

参考资料

Relevant link 1
Relevant file path
Related task

---

相关链接1
相关文件路径
关联任务

---

Verification Rules

验证规则

NEVER mark a task as done without verification.

未经过验证绝不能标记任务为完成。

Verification Checklist

验证检查清单

markdown

undefined

markdown

undefined

For each acceptance criterion:

针对每个验收标准：

IDENTIFY: What command/action proves this criterion?
RUN: Execute the verification
CAPTURE: Record the output
ASSESS: Does it pass?

确定：用什么命令/操作可验证该标准？
执行：运行验证操作
记录：保存输出结果
评估：是否通过？

Required Verifications by Type:

按类型分类的必填验证：

File Creation

文件创建

File exists:
```
test -f {path} && echo "EXISTS"
```
File is exported (if module):
```
grep "export" {index_file}
```

文件存在：
```
test -f {路径} && echo "EXISTS"
```
文件已导出（如为模块）：
```
grep "export" {索引文件}
```

Dependency Installation

依赖安装

In package.json:
```
grep "{package}" package.json
```
Can import: Create test file with import

已在package.json中：
```
grep "{包名}" package.json
```
可正常导入：创建测试文件验证导入

Route Addition

路由添加

In router:
```
grep "{route}" {router_file}
```
Navigable: Test in browser

已在路由配置中：
```
grep "{路由}" {路由文件}
```
可正常访问：在浏览器中测试

Pattern Removal

模式移除

Zero matches:
```
grep -r "{pattern}" {path} | wc -l
```
= 0

无匹配结果：
```
grep -r "{模式}" {路径} | wc -l
```
= 0

Type Addition

类型添加

Type exists:
```
grep "type {Name}" {types_file}
```
Compiles:
```
tsc --noEmit
```
or equivalent

类型已存在：
```
grep "type {类型名}" {类型文件}
```
可正常编译：
```
tsc --noEmit
```
或等价命令

General

通用验证

TypeScript compiles: Run type checker
Tests pass: Run test suite
No console errors: Check browser/runtime

---

TypeScript编译：运行类型检查器
测试通过：运行测试套件
无控制台错误：检查浏览器/运行时

---

Common Mistakes

常见错误

Mistake	Why It's Wrong	Correct Approach
Moving to done/ without .verified	No proof of completion	Verify first, then move
Trusting task.md checkboxes	Checkboxes can be wrong	Run actual verification
Skipping implementation.md	No record of what changed	Document all changes
Empty verification.md	No proof of verification	Record actual test output
Multiple tasks in progress	Context switching waste	Finish one, then start next
Editing task.md in done/	History should be immutable	Create follow-up task instead

错误内容	错误原因	正确做法
未添加.verified就移动到done/	无完成证明	先验证，再移动
仅依赖task.md中的复选框	复选框可能标记错误	执行实际验证操作
跳过implementation.md	无变更记录	记录所有变更内容
verification.md为空	无验证证明	记录实际测试输出
同时进行多个任务	上下文切换会浪费时间	完成一个再开始下一个
编辑done/中的task.md	历史记录应不可变	创建后续任务替代