@bicorne/task-flow 0.1.0 → 0.2.1

package/README.md

@@ -1,119 +1,199 @@
 # @bicorne/task-flow
 
-A git worktree-based parallel task execution system for zero-conflict multi-task development.
+需求分析与任务拆分的 Harness Engineering 工具。帮助 AI 梳理用户需求生成 PRD 文档、编写技术规格、拆分多阶段任务文件，并通过 Git worktree 实现零冲突并行开发。适用于新功能开发、Bug 修复、代码重构等场景。
 
-## Installation
+## 核心特性
+
+- **🤖 AI-First 设计**：支持 Slash Commands，在 AI 对话中直接执行任务
+- **🌳 零冲突开发**：基于 Git worktree 实现多任务并行开发
+- **📋 标准化流程**：从需求分析到代码合并的完整工作流
+- **🔄 Hooks 机制**：支持生命周期钩子，实现自动化检查和验证
+- **📦 标准任务格式**：PHASE-*.json 格式，支持依赖管理和进度跟踪
+
+## 安装
 
 ```bash
-# Install from npm (recommended)
+# 全局安装（推荐）
 npm install -g @bicorne/task-flow
 
-# Or use via npx
+# 或使用 pnpm
+pnpm add -g @bicorne/task-flow
+
+# 或使用 npx（无需安装）
 npx @bicorne/task-flow init
 ```
 
-**Requirements:**
+**系统要求：**
 
-| Dependency | Version | Description |
-|------------|---------|-------------|
-| **Node.js** | >= 22.11.0 | Required for CLI execution |
-| **Git** | >= 2.17 | Required for worktree functionality |
-| **Bash** | >= 4.0 | Required for bootstrap scripts |
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| **Node.js** | >= 24.14.0 | CLI 运行环境 |
+| **Git** | >= 2.17 | worktree 功能依赖 |
+| **Bash** | >= 4.0 | 引导脚本依赖 |
 
-**Git Configuration (for worktree tests):**
+**Git 配置（worktree 测试需要）：**
 ```bash
 git config --global user.name "Your Name"
 git config --global user.email "your@email.com"
 ```
 
-## Quick Start
+## 快速开始
 
-### Step 1: Initialize Task Flow
+### 方式一：Slash Commands（推荐）
+
+在 AI 对话中直接输入命令，AI 会自动识别并执行：
 
 ```bash
-task-flow init
-```
+# 1. 初始化项目
+/tf:init
 
-This creates:
-- `.harness/` - Root directory for harness state
-- `.harness/state.json` - Current state file
-- `.harnessrc.example` - Configuration template
+# 2. 一键创建变更提案（extract + design + tasks）
+/tf:propose my-feature
 
-### Step 2: Create PRD Document
+# 3. AI 审查并编辑生成的 PRD 和设计文档
 
-```bash
-task-flow extract --change my-feature
-```
+# 4. 应用并创建工作区
+/tf:apply my-feature
 
-This creates:
-- `spec/changes/my-feature/product-requirement.md` - PRD document
+# 5. 在工作区中编码实现
+cd .worktrees/harness-feat-my-feature
 
-### Step 3: Edit PRD Document Manually
+# 6. 完成后合并
+cd ../..
+/tf:merge my-feature
 
-Edit `spec/changes/my-feature/product-requirement.md` to describe your change:
-- Project background and goals
-- Users and scenarios
-- Global design and architecture
-- Detailed functional requirements
-- Non-functional requirements
-- Launch and operations plan
+# 7. 归档
+/tf:archive --task-id my-feature
+```
 
-### Step 4: Generate Design
+### 方式二：传统 CLI 命令
 
 ```bash
-task-flow design --change my-feature
-```
+# 1. 初始化项目
+task-flow init
 
-This generates:
-- `spec/changes/my-feature/design.md` - Technical specification
+# 2. 扫描项目（可选）
+task-flow analyze --output context.json
 
-### Step 5: Generate Tasks
+# 3. 生成 PRD 文档
+task-flow extract --change my-feature --context-file context.json
 
-```bash
-task-flow tasks --change my-feature
-```
+# 4. 编辑 PRD 文档
+# 文件位置: spec/changes/my-feature/product-requirement.md
 
-This generates:
-- `spec/changes/my-feature/tasks.md` - Task list
-- `spec/changes/my-feature/tasks/PHASE-*.json` - Individual task files
-- `spec/changes/my-feature/manifest.json` - Execution config
+# 5. 生成技术设计（可选）
+task-flow design --change my-feature --context-file context.json
 
-### Step 6: Create Worktree
+# 6. 生成任务文件
+task-flow tasks --change my-feature --yes
 
-```bash
-task-flow worktree --change my-feature
+# 7. 创建隔离工作区
+task-flow worktree --change my-feature --yes
+
+# 8. 在工作区中开发
+cd .worktrees/harness-feat-my-feature
+
+# 9. 完成后合并
+cd ../..
+task-flow merge my-feature
 ```
 
-This creates:
-- `.worktrees/harness-feat-my-feature/` - Isolated worktree
-- `.harness/` symlink in worktree
+## 命令参考
+
+### Slash Commands
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `/tf:init` | 初始化项目 | `/tf:init` |
+| `/tf:propose <name>` | 一键创建变更提案（extract + design + tasks） | `/tf:propose add-oauth` |
+| `/tf:apply <name>` | 应用并创建工作区 | `/tf:apply add-oauth` |
+| `/tf:extract <name>` | 生成 PRD 文档 | `/tf:extract add-oauth` |
+| `/tf:design <name>` | 生成技术设计 | `/tf:design add-oauth` |
+| `/tf:tasks <name>` | 生成任务文件 | `/tf:tasks add-oauth` |
+| `/tf:worktree <name>` | 创建隔离工作区 | `/tf:worktree add-oauth` |
+| `/tf:merge <id>` | 合并代码 | `/tf:merge add-oauth` |
+| `/tf:archive --task-id <id>` | 归档已完成任务 | `/tf:archive --task-id add-oauth` |
+| `/tf:status` | 显示当前状态 | `/tf:status` |
+| `/tf:sync --task-id <id>` | 同步状态到 spec | `/tf:sync --task-id add-oauth` |
+
+### CLI 命令
+
+| 命令 | 说明 | 关键参数 |
+|------|------|----------|
+| `init` | 初始化项目 | `--force` 强制覆盖 |
+| `analyze` | 扫描项目生成 context | `--output <path>` |
+| `extract` | 生成 PRD 文档 | `--change <name> --context-file <path>` |
+| `design` | 生成技术设计 | `--change <name> --context-file <path> --skip-prompt` |
+| `tasks` | 生成任务文件 | `--change <name> --yes --input <json>` |
+| `worktree` | 创建隔离工作区 | `--change <name> --yes` |
+| `status` | 显示当前状态 | - |
+| `merge` | 合并代码 | `<task-id> --dry-run` |
+| `archive` | 归档任务 | `--task-id <id> --event <event>` |
+| `sync` | 同步状态到 spec | `--task-id <id>` |
+
+详细用法请参考 [CLI 使用教程](references/CLI-TUTORIAL.md)。
+
+## 核心概念
+
+### AI 调用模型
+
+```
+AI 分析项目 → 生成 context.json → 调用 CLI 生成文档 → AI 审查并填充 → 执行任务
+```
+
+- **AI 是"大脑"**：理解项目、做决策、填充内容
+- **CLI 是"手"**：文件操作、格式转换、状态管理
+
+### Context 协议
+
+AI 在调用命令前生成 context JSON，传递项目理解：
+
+```typescript
+interface AiContext {
+  version: '1.0';
+  project: {
+    name: string;
+    type?: 'library' | 'application' | 'service' | 'cli' | 'monorepo';
+    techStack?: { language?: string; framework?: string; runtime?: string; };
+  };
+  analysis?: {
+    architectureSummary?: string;
+    coreModules?: Array<{ name: string; path: string; description: string }>;
+    risks?: string[];
+  };
+  task?: {
+    type?: 'feat' | 'fix' | 'refactor' | 'test' | 'docs' | 'chore';
+    priority?: 'high' | 'medium' | 'low';
+    affectedFiles?: string[];
+    constraints?: string[];
+  };
+}
+```
 
-## Commands
+### 工作流程
 
-| Command | Description |
-|---------|-------------|
-| `init` | Initialize task flow in current project |
-| `extract` | Extract project requirements and generate PRD document |
-| `design` | Generate design.md from product-requirement.md |
-| `tasks` | Generate tasks.md and PHASE-*.json files |
-| `worktree` | Create isolated git worktree |
-| `status` | Show current task and phase status |
-| `archive` | Archive current task state |
-| `merge` | Merge completed worktree back to main |
-| `sync` | Sync task execution status to spec |
+```
+analyze → extract → design → tasks → worktree → implement → review → merge
+   │        │         │         │         │
+   │        │         │         │         └── 创建隔离 git worktree
+   │        │         │         └── 生成 PHASE-*.json 任务文件
+   │        │         └── 分析 PRD 生成技术规格（可选）
+   │        └── 提取需求生成 PRD 文档
+   └── 自动扫描项目结构，生成 context.json 骨架
+```
 
-## Configuration
+## 配置
 
-### Environment Variables
+### 环境变量
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `HARNESS_ROOT` | `.harness` | Root directory for harness state |
-| `HARNESS_WORKTREES_DIR` | `.worktrees` | Directory for worktree checkouts |
-| `HARNESS_CONFIG_FILE` | `.harnessrc` | Path to config file |
-| `HARNESS_SPEC_ROOT` | `spec` | Root directory for spec files |
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `HARNESS_ROOT` | `.harness` | Harness 状态根目录 |
+| `HARNESS_WORKTREES_DIR` | `.worktrees` | worktree 检出目录 |
+| `HARNESS_CONFIG_FILE` | `.harnessrc` | 配置文件路径 |
+| `HARNESS_SPEC_ROOT` | `spec` | spec 文件根目录 |
 
-### Config File (`.harnessrc`)
+### 配置文件 (`.harnessrc`)
 
 ```json
 {
@@ -123,30 +203,169 @@ This creates:
   "snapshotsDir": "snapshots",
   "archiveDir": "archive",
   "reportsDir": "reports",
-  "plansDir": "plans",
   "specRoot": "spec"
 }
 ```
 
-## Directory Structure
+### Hooks 配置
 
+在 `.harness/hooks.json` 中配置生命周期钩子：
+
+```json
+{
+  "version": "1.0",
+  "hooks": {
+    "pre-design": [
+      { "name": "check-prd-exists", "script": "src/hooks/check-prd-exists.js", "enabled": true }
+    ],
+    "pre-worktree": [
+      { "name": "check-worktree-conflict", "script": "src/hooks/check-worktree-conflict.js", "enabled": true }
+    ],
+    "post-task-complete": [
+      { "name": "phase-gate-validator", "script": "src/hooks/phase-gate-validator.js", "enabled": true }
+    ]
+  }
+}
 ```
-spec/
-├── changes/
-│   └── <change-name>/
-│       ├── product-requirement.md  # 产品需求文档（AI 生成）
-│       ├── design.md               # 技术规格（可选，AI 生成）
-│       ├── tasks.md                # 任务清单（AI 生成）
-│       ├── tasks/                  # 多阶段任务 JSON
-│       │   ├── PHASE-1-1-1.json
-│       │   ├── PHASE-1-1-2.json
-│       │   └── ...
-│       └── manifest.json           # 执行配置
-├── skills.json                     # 技能工具注册（可选）
-└── mcp.json                        # MCP 工具注册（可选）
+
+## 目录结构
+
+### 项目目录
+
+```
+harness-task-flow/
+├── src/
+│   ├── index.ts                    # CLI 入口
+│   ├── commands/                   # 命令实现
+│   │   ├── init.ts
+│   │   ├── extract.ts
+│   │   ├── design.ts
+│   │   ├── tasks.ts
+│   │   ├── worktree.ts
+│   │   ├── status.ts
+│   │   ├── archive.ts
+│   │   ├── merge.ts
+│   │   ├── sync.ts
+│   │   ├── analyze.ts
+│   │   ├── merge/                  # 合并命令子模块
+│   │   └── tasks-gen/              # 任务生成子模块
+│   ├── lib/                        # 核心工具库
+│   │   ├── config.ts               # 配置管理
+│   │   ├── state.ts                # 状态管理
+│   │   ├── archive.ts              # 归档管理
+│   │   ├── constants.ts            # 常量定义
+│   │   ├── interactive.ts          # 交互式 CLI
+│   │   └── mcp-client.ts           # MCP 客户端
+│   ├── hooks/                      # 事件钩子
+│   │   ├── hook-runner/            # Hook 执行引擎
+│   │   ├── check-prd-exists.ts
+│   │   ├── check-worktree-conflict.ts
+│   │   ├── phase-gate-validator.ts
+│   │   ├── phase-complete-detector.ts
+│   │   ├── save-checkpoint.ts
+│   │   ├── start-mcp-servers.ts
+│   │   └── stop-mcp-servers.ts
+│   ├── slash/                      # Slash Commands
+│   │   ├── parser.ts
+│   │   ├── registry.ts
+│   │   └── executor.ts
+│   ├── spec/                       # Spec 集成
+│   │   ├── openspec-to-task/       # OpenSpec 转换
+│   │   ├── sync-openspec-to-task.ts
+│   │   └── sync-task-to-openspec.ts
+│   └── types/                      # 类型定义
+│       └── ai-context.ts
+├── assets/                         # 文件模板
+│   ├── schema.json                 # 任务 JSON Schema
+│   ├── product-requirement.md      # PRD 模板
+│   ├── design.md                   # 技术规格模板
+│   ├── tasks.md                    # 任务清单模板
+│   ├── PHASE-task.json.example     # 任务 JSON 示例
+│   ├── hooks.json                  # Hooks 配置示例
+│   └── .harnessrc                  # 配置文件示例
+├── tests/                          # 测试文件
+├── references/                     # 参考文档
+│   ├── CLI-TUTORIAL.md
+│   ├── AI-CONVERSATION-TUTORIAL.md
+│   └── GIT-WORKTREE-SOP.md
+├── SKILL.md                        # Skill 文档
+└── package.json
+```
+
+### 运行时目录
+
+```
+project/
+├── .harness/                       # Harness 运行时目录
+│   ├── state.json                  # 当前运行状态
+│   ├── hooks.json                  # Hooks 配置
+│   ├── skills.json                 # 技能工具注册（可选）
+│   ├── mcp.json                    # MCP 服务器注册（可选）
+│   └── archive/                    # 归档目录
+├── spec/                           # 规格文档目录
+│   └── changes/                    # 变更提案目录
+│       └── <change-name>/          # 具体变更
+│           ├── product-requirement.md  # 产品需求文档
+│           ├── design.md               # 技术规格（可选）
+│           ├── tasks.md                # 任务清单
+│           ├── tasks/                  # 多阶段任务 JSON
+│           │   ├── PHASE-1-1-1.json
+│           │   ├── PHASE-1-1-2.json
+│           │   └── ...
+│           └── manifest.json           # 执行配置清单
+└── .worktrees/                     # Git worktree 目录
+    └── harness-feat-<name>/        # 隔离工作区
 ```
 
-## Tool Registration
+## 任务文件格式
+
+PHASE-*.json 任务文件遵循标准 Schema：
+
+```json
+{
+  "id": "PHASE-1-1-1",
+  "type": "feat",
+  "title": "实现用户认证",
+  "priority": "high",
+  "phase": 1,
+  "dependencies": [],
+  "docs_to_read": ["spec/changes/my-feature/design.md"],
+  "spec": {
+    "description": "实现基于 JWT 的用户认证系统",
+    "files": ["src/auth/jwt.ts", "src/auth/middleware.ts"],
+    "context": ["spec/changes/my-feature/product-requirement.md"]
+  },
+  "acceptance_criteria": [
+    "用户可以登录并获取 JWT token",
+    "受保护的路由需要验证 token",
+    "token 过期后自动刷新"
+  ],
+  "implementation": {
+    "steps": [
+      { "step": "安装依赖", "details": "npm install jsonwebtoken" },
+      { "step": "实现 JWT 工具函数", "details": "创建 sign 和 verify 函数" },
+      { "step": "实现认证中间件", "details": "验证 token 并注入用户信息" }
+    ],
+    "notes": "使用 RS256 算法"
+  },
+  "validation": {
+    "commands": [
+      "pnpm build",
+      "pnpm test",
+      "pnpm lint"
+    ],
+    "manual_checks": [
+      "验证登录流程正常",
+      "检查 token 刷新机制"
+    ]
+  },
+  "status": "pending"
+}
+```
+
+完整 Schema 定义见 [assets/schema.json](assets/schema.json)。
+
+## 工具注册
 
 ### skills.json
 
@@ -181,72 +400,45 @@ spec/
 }
 ```
 
-## Workflow
-
-### New Slash Command Workflow (v2)
-
-```
-extract → design → tasks → worktree → implement → review → merge
-```
-
-## Architecture
-
-```
-harness-task-flow/
-├── src/
-│   ├── index.ts              # CLI entry point
-│   ├── commands/             # Command implementations
-│   │   ├── init.ts
-│   │   ├── extract.ts        # Extract requirements → PRD
-│   │   ├── design.ts         # Analyze PRD → tech spec (optional)
-│   │   ├── tasks.ts          # Generate PHASE-*.json task files
-│   │   ├── worktree.ts       # Create isolated worktree
-│   │   ├── status.ts
-│   │   ├── archive.ts
-│   │   ├── merge.ts
-│   │   └── sync.ts
-│   ├── lib/                  # Core utilities
-│   │   ├── config.ts
-│   │   ├── state.ts
-│   │   ├── archive.ts
-│   │   └── tool-registry.ts
-│   ├── hooks/                # Event hooks
-│   │   ├── hook-runner.ts
-│   │   ├── check-prd-exists.ts
-│   │   ├── phase-gate-validator.ts
-│   │   ├── phase-complete-detector.ts
-│   │   ├── save-checkpoint.ts
-│   │   └── check-worktree-conflict.ts
-│   └── spec/                 # Spec integration
-│       ├── sync-openspec-to-task.ts
-│       └── sync-task-to-openspec.ts
-├── assets/                 # File templates
-│   ├── schema.json           # Task JSON schema
-│   ├── product-requirement.md # PRD template
-│   ├── design.md             # Tech spec template
-│   └── tasks.md              # Tasks template
-├── SKILL.md
-└── package.json
-```
-
-## Development
+## 开发
 
 ```bash
-# Install dependencies
+# 安装依赖
 pnpm install
 
-# Run tests
+# 运行测试
 pnpm test
 
-# Lint
+# 代码检查
 pnpm lint
+
+# 类型检查
+pnpm typecheck
+
+# 构建
+pnpm build
+
+# 监听模式构建
+pnpm build:watch
+
+# 发布（使用 changesets）
+pnpm changeset
+pnpm version
+pnpm release
 ```
 
-## License
+## 文档
+
+- [CLI 使用教程](references/CLI-TUTORIAL.md) - 人类开发者如何使用 CLI 命令
+- [AI 对话教程](references/AI-CONVERSATION-TUTORIAL.md) - 如何通过 AI 对话完成任务
+- [Git Worktree SOP](references/GIT-WORKTREE-SOP.md) - Git worktree 使用规范
+
+## 许可证
 
-MIT License - See LICENSE file for details.
+MIT License - 详见 [LICENSE](LICENSE) 文件
 
-## Links
+## 链接
 
 - [Agent Skills Specification](https://agentskills.io/specification)
-- [Task Flow](https://github.com/didengren/harness-task-flow)
+- [GitHub Repository](https://github.com/didengren/harness-task-flow)
+- [Issue Tracker](https://github.com/didengren/harness-task-flow/issues)

package/SKILL.md

@@ -75,7 +75,7 @@ analyze → extract → design → tasks → worktree → implement → review
 
 | Slash Command | 说明 | AI 执行的操作 |
 |---------------|------|---------------|
-| `/tf:propose <name>` | 一键创建变更提案 | extract → design → tasks |
+| `/tf:propose <name>` | 一键创建变更提案 | analyze → extract → design → tasks |
 | `/tf:apply <name>` | 应用并创建工作区 | worktree |
 | `/tf:archive --task-id <id>` | 归档已完成任务 | archive → sync |
 | `/tf:init` | 初始化项目 | init |
@@ -87,6 +87,12 @@ analyze → extract → design → tasks → worktree → implement → review
 | `/tf:merge <id>` | 合并代码 | merge |
 | `/tf:sync --task-id <id>` | 同步状态到 spec | sync |
 
+> **`/tf:propose` 自动处理 context**：
+> - 优先查找现有 context 文件（`context.json`、`.harness/context.json`、`.tmp/context.json`）
+> - 若不存在则自动执行 `analyze` 生成临时 context 文件到 `.tmp/context.json`
+> - 生成的 context 会传递给后续的 `extract` 和 `design` 步骤
+> - AI 可在执行后审查并补充 context 内容，再次运行 `/tf:propose` 时会复用已有 context
+
 > **使用方式**：直接在 AI 对话中输入 `/tf:init` 即可，无需加 `task-flow` 前缀。
 > AI 读取本 Skill 文档后，会自动识别并执行对应的 CLI 命令。
 
@@ -127,8 +133,7 @@ analyze → extract → design → tasks → worktree → implement → review
 # 5. 在工作区中编码实现
 cd .worktrees/harness-feat-add-oauth
 
-# 6. 验证并合并
-pnpm build && pnpm test && pnpm lint
+# 6. 完成后合并
 cd ../..
 /tf:merge add-oauth
 
@@ -160,8 +165,7 @@ task-flow worktree --change add-oauth --yes
 # 7. 在工作区中编码实现
 cd .worktrees/harness-feat-add-oauth
 
-# 8. 验证并合并
-pnpm build && pnpm test && pnpm lint
+# 8. 完成后合并
 cd ../..
 task-flow merge add-oauth
 ```

package/assets/.harnessrc

@@ -5,6 +5,5 @@
   "snapshotsDir": "snapshots",
   "archiveDir": "archive",
   "reportsDir": "reports",
-  "plansDir": "plans",
   "specRoot": "spec"
 }