@bicorne/task-flow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# @bicorne/task-flow
+
+A git worktree-based parallel task execution system for zero-conflict multi-task development.
+
+## Installation
+
+```bash
+# Install from npm (recommended)
+npm install -g @bicorne/task-flow
+
+# Or use via 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 |
+
+**Git Configuration (for worktree tests):**
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your@email.com"
+```
+
+## Quick Start
+
+### Step 1: Initialize Task Flow
+
+```bash
+task-flow init
+```
+
+This creates:
+- `.harness/` - Root directory for harness state
+- `.harness/state.json` - Current state file
+- `.harnessrc.example` - Configuration template
+
+### Step 2: Create PRD Document
+
+```bash
+task-flow extract --change my-feature
+```
+
+This creates:
+- `spec/changes/my-feature/product-requirement.md` - PRD document
+
+### Step 3: Edit PRD Document Manually
+
+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
+
+### Step 4: Generate Design
+
+```bash
+task-flow design --change my-feature
+```
+
+This generates:
+- `spec/changes/my-feature/design.md` - Technical specification
+
+### Step 5: Generate Tasks
+
+```bash
+task-flow tasks --change my-feature
+```
+
+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
+
+### Step 6: Create Worktree
+
+```bash
+task-flow worktree --change my-feature
+```
+
+This creates:
+- `.worktrees/harness-feat-my-feature/` - Isolated worktree
+- `.harness/` symlink in worktree
+
+## 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 |
+
+## 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 |
+
+### Config File (`.harnessrc`)
+
+```json
+{
+  "harnessRoot": ".harness",
+  "worktreesDir": ".worktrees",
+  "tasksDir": "tasks",
+  "snapshotsDir": "snapshots",
+  "archiveDir": "archive",
+  "reportsDir": "reports",
+  "plansDir": "plans",
+  "specRoot": "spec"
+}
+```
+
+## Directory Structure
+
+```
+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 工具注册（可选）
+```
+
+## Tool Registration
+
+### skills.json
+
+```json
+{
+  "version": "1.0",
+  "skills": [
+    {
+      "name": "project-scaffold",
+      "description": "项目工程脚手架 skill",
+      "path": ".trae/skills/scaffold",
+      "enabled": true
+    }
+  ]
+}
+```
+
+### mcp.json
+
+```json
+{
+  "version": "1.0",
+  "mcpServers": [
+    {
+      "name": "component-library",
+      "description": "组件库知识库 MCP",
+      "command": "node",
+      "args": ["mcp-server.js"],
+      "enabled": true
+    }
+  ]
+}
+```
+
+## 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
+```
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Links
+
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [Task Flow](https://github.com/didengren/harness-task-flow)

package/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: harness-task-flow
+description: |
+  需求分析与任务拆分工具。帮助 AI 梳理用户需求生成 PRD 文档、编写技术规格、
+  拆分多阶段任务文件，并通过 Git worktree 实现零冲突并行开发。适用于新功能开发、
+  Bug 修复、代码重构等场景。
+license: MIT
+compatibility: Node.js >= 24.14.0, Git >= 2.17
+---
+
+# Task Flow — AI Skill
+
+基于 Git worktree 的并行任务执行系统，让 AI 能够零冲突地多任务开发。
+
+---
+
+## 核心概念
+
+### 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[];
+  };
+}
+```
+
+---
+
+## 工作流
+
+```
+analyze → extract → design → tasks → worktree → implement → review → merge
+   │        │         │         │         │
+   │        │         │         │         └── 创建隔离 git worktree
+   │        │         │         └── 生成 PHASE-*.json 任务文件
+   │        │         └── 分析 PRD 生成技术规格（可选）
+   │        └── 提取需求生成 PRD 文档
+   └── 自动扫描项目结构，生成 context.json 骨架
+```
+
+---
+
+## 命令速查
+
+### Slash Commands（推荐）
+
+类似 OpenSpec 的 `/opsx:propose` 模式，用户在 AI 对话中直接输入 `/tf:<command>`，AI 识别后自动执行对应操作：
+
+| Slash Command | 说明 | AI 执行的操作 |
+|---------------|------|---------------|
+| `/tf:propose <name>` | 一键创建变更提案 | extract → design → tasks |
+| `/tf:apply <name>` | 应用并创建工作区 | worktree |
+| `/tf:archive --task-id <id>` | 归档已完成任务 | archive → sync |
+| `/tf:init` | 初始化项目 | init |
+| `/tf:status` | 显示当前状态 | status |
+| `/tf:extract <name>` | 生成 PRD 文档 | extract |
+| `/tf:design <name>` | 生成技术设计 | design |
+| `/tf:tasks <name>` | 生成任务文件 | tasks |
+| `/tf:worktree <name>` | 创建隔离工作区 | worktree |
+| `/tf:merge <id>` | 合并代码 | merge |
+| `/tf:sync --task-id <id>` | 同步状态到 spec | sync |
+
+> **使用方式**：直接在 AI 对话中输入 `/tf:init` 即可，无需加 `task-flow` 前缀。
+> AI 读取本 Skill 文档后，会自动识别并执行对应的 CLI 命令。
+
+### 传统 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` |
+| `worktree` | 创建隔离工作区 | `--change <name> --yes` |
+| `status` | 显示当前状态 | - |
+| `merge` | 合并代码 | `<task-id> --dry-run` |
+| `archive` | 归档任务 | `--task-id <id> --event <event>` |
+
+详细用法见 [CLI 使用教程](references/CLI-TUTORIAL.md)。
+
+---
+
+## AI 调用示例
+
+### 使用 Slash Commands（推荐）
+
+```bash
+# 1. 初始化
+/tf:init
+
+# 2. 一键创建变更提案（extract + design + tasks）
+/tf:propose add-oauth
+
+# 3. AI 审查并编辑生成的 PRD 和设计文档
+
+# 4. 应用并创建工作区
+/tf:apply add-oauth
+
+# 5. 在工作区中编码实现
+cd .worktrees/harness-feat-add-oauth
+
+# 6. 验证并合并
+pnpm build && pnpm test && pnpm lint
+cd ../..
+/tf:merge add-oauth
+
+# 7. 归档
+/tf:archive --task-id add-oauth
+```
+
+### 使用传统 CLI 命令
+
+```bash
+# 1. 初始化
+task-flow init
+
+# 2. 扫描项目
+task-flow analyze --output /tmp/context.json
+
+# 3. AI 补充 context.json（analysis、task 字段）
+
+# 4. 生成文档
+task-flow extract --change add-oauth --context-file /tmp/context.json
+task-flow design --change add-oauth --context-file /tmp/context.json
+
+# 5. AI 编辑生成的 PRD 和设计文档
+
+# 6. 生成任务并创建工作区
+task-flow tasks --change add-oauth --yes
+task-flow worktree --change add-oauth --yes
+
+# 7. 在工作区中编码实现
+cd .worktrees/harness-feat-add-oauth
+
+# 8. 验证并合并
+pnpm build && pnpm test && pnpm lint
+cd ../..
+task-flow merge add-oauth
+```
+
+完整对话示例见 [AI 对话教程](references/AI-CONVERSATION-TUTORIAL.md)。
+
+---
+
+## 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 }
+    ]
+  }
+}
+```
+
+---
+
+## 最佳实践
+
+### 推荐模式
+
+```bash
+task-flow analyze --output context.json
+# AI 补充 context.json
+task-flow extract --change <name> --context-file context.json
+task-flow design --change <name> --context-file context.json
+# AI 编辑生成的文档
+task-flow tasks --change <name> --yes
+task-flow worktree --change <name> --yes
+```
+
+### 避免
+
+| 反模式 | 正确做法 |
+|--------|----------|
+| 用 `--input` 传超长文本 | 用 `--context-file` 传结构化 JSON |
+| 跳过 PRD 审查直接 tasks | AI 先审查并编辑 PRD |
+| 单 worktree 多 Agent | 每任务独立 worktree |
+| 跳过验证阶段 | 始终通过 build/test/lint |
+
+---
+
+## 参考文档
+
+- [AI 对话教程](references/AI-CONVERSATION-TUTORIAL.md) - 人类与 AI 对话完成开发任务
+- [CLI 使用教程](references/CLI-TUTORIAL.md) - 人类直接使用 CLI
+- [Git Worktree SOP](references/GIT-WORKTREE-SOP.md) - Git worktree 操作流程
+
+---
+
+## 目录结构
+
+```
+project/
+├── .harness/
+│   ├── state.json              # 当前状态
+│   ├── hooks.json              # Hooks 配置
+│   └── archive/                # 归档任务
+├── .worktrees/                 # worktree 目录
+├── spec/changes/<change-name>/
+│   ├── product-requirement.md  # PRD
+│   ├── design.md               # 技术设计
+│   ├── tasks/                  # PHASE-*.json
+│   └── manifest.json           # 执行配置
+└── .harnessrc                  # 配置文件
+```
+
+---
+
+## 许可证
+
+MIT License

package/assets/.harnessrc

@@ -0,0 +1,10 @@
+{
+  "harnessRoot": ".harness",
+  "worktreesDir": ".worktrees",
+  "tasksDir": "tasks",
+  "snapshotsDir": "snapshots",
+  "archiveDir": "archive",
+  "reportsDir": "reports",
+  "plansDir": "plans",
+  "specRoot": "spec"
+}

package/assets/PHASE-task.json.example

@@ -0,0 +1,50 @@
+{
+  "id": "PHASE-1-1-1",
+  "type": "feat",
+  "title": "Example task title",
+  "priority": "medium",
+  "phase": 1,
+  "dependencies": [],
+  "docs_to_read": [
+    "spec/changes/change-name/proposal.md",
+    "spec/changes/change-name/design.md"
+  ],
+  "spec": {
+    "description": "Detailed description of what this task should accomplish",
+    "files": [
+      "src/path/to/file1.ts",
+      "src/path/to/file2.ts"
+    ],
+    "context": []
+  },
+  "acceptance_criteria": [
+    "Feature works as expected",
+    "Tests pass",
+    "Code follows project conventions"
+  ],
+  "implementation": {
+    "steps": [
+      {
+        "step": "Step 1 description",
+        "details": "Optional details for this step"
+      },
+      {
+        "step": "Step 2 description",
+        "details": "Optional details for this step"
+      }
+    ],
+    "notes": "Any additional notes for implementation"
+  },
+  "validation": {
+    "commands": [
+      "pnpm build",
+      "pnpm test",
+      "pnpm lint"
+    ],
+    "manual_checks": [
+      "Verify UI renders correctly",
+      "Check error handling"
+    ]
+  },
+  "status": "pending"
+}

package/assets/design.md

@@ -0,0 +1,69 @@
+# 技术规格文档
+
+## 文档基础信息
+
+- **需求名称**: [待填写]
+- **文档状态**: 草稿
+- **技术负责人**: [待填写]
+- **修订历史**: 
+  - [日期] - v1.0 - 初始版本
+
+## 技术选型
+
+### 核心技术栈
+<!-- 列出本次需求涉及的核心技术及选型理由 -->
+
+### 新增依赖
+<!-- 列出需要引入的新依赖库及其用途 -->
+
+### 技术决策
+<!-- 记录关键技术决策及其权衡 -->
+
+## 架构设计
+
+### 系统架构图
+<!-- 提供系统架构图，展示各组件关系 -->
+
+### 模块划分
+<!-- 描述模块划分及职责边界 -->
+
+### 数据流向
+<!-- 描述核心数据流转路径 -->
+
+## 接口设计
+
+### API 接口
+<!-- 列出需要新增或修改的 API 接口 -->
+
+### 数据格式
+<!-- 定义请求和响应的数据格式 -->
+
+### 错误处理
+<!-- 定义错误码和错误处理策略 -->
+
+## 数据模型
+
+### 数据库设计
+<!-- 描述数据库表结构设计 -->
+
+### 数据关系
+<!-- 描述实体间的关系 -->
+
+### 数据迁移
+<!-- 描述数据迁移策略 -->
+
+## 技术风险与缓解
+
+### 已识别风险
+<!-- 列出技术实现中的潜在风险 -->
+
+### 缓解措施
+<!-- 针对每个风险的缓解方案 -->
+
+## 性能与扩展
+
+### 性能要求
+<!-- 描述性能指标和优化策略 -->
+
+### 扩展性设计
+<!-- 描述如何支持未来的扩展需求 -->

package/assets/hooks.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0",
+  "hooks": {
+    "pre-design": [],
+    "post-design": [],
+    "pre-planning": [],
+    "post-planning": [],
+    "pre-implementation": [],
+    "post-implementation": [],
+    "pre-review": [],
+    "post-review": [],
+    "pre-merge": [],
+    "post-merge": []
+  }
+}