@bicorne/task-flow 0.1.0 → 0.2.0

package/README.md

@@ -1,119 +1,201 @@
 # @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. 验证并合并
+pnpm build && pnpm test && pnpm lint
+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. 验证并合并
+pnpm build && pnpm test && pnpm lint
+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 +205,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 +402,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 命令。
 

package/assets/.harnessrc

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

package/dist/commands/init.js

@@ -109,7 +109,6 @@ function initHarness(options = {}) {
             snapshotsDir: 'snapshots',
             archiveDir: 'archive',
             reportsDir: 'reports',
-            plansDir: 'plans',
             specRoot: 'spec',
         };
         try {

package/dist/lib/config.d.ts

@@ -21,7 +21,6 @@ export interface Config {
     snapshotsDir?: string;
     archiveDir?: string;
     reportsDir?: string;
-    plansDir?: string;
     specRoot?: string;
     configFile?: string;
     harnessRootAbs?: string;
@@ -30,7 +29,6 @@ export interface Config {
     snapshotsDirAbs?: string;
     archiveDirAbs?: string;
     reportsDirAbs?: string;
-    plansDirAbs?: string;
     specRootAbs?: string;
     projectRoot?: string;
     configPath?: string;

package/dist/lib/config.js

@@ -62,7 +62,6 @@ exports.DEFAULTS = {
     snapshotsDir: 'snapshots',
     archiveDir: 'archive',
     reportsDir: 'reports',
-    plansDir: 'plans',
     specRoot: 'spec',
 };
 /**
@@ -75,7 +74,6 @@ const ENV_MAPPING = {
     HARNESS_SNAPSHOTS_DIR: 'snapshotsDir',
     HARNESS_ARCHIVE_DIR: 'archiveDir',
     HARNESS_REPORTS_DIR: 'reportsDir',
-    HARNESS_PLANS_DIR: 'plansDir',
     HARNESS_SPEC_ROOT: 'specRoot',
     HARNESS_CONFIG_FILE: 'configFile',
 };
@@ -190,7 +188,7 @@ function loadConfig(options = {}) {
         ...envConfig,
     };
     // Resolve all paths to absolute
-    const pathKeys = ['harnessRoot', 'worktreesDir', 'tasksDir', 'snapshotsDir', 'archiveDir', 'reportsDir', 'plansDir', 'specRoot'];
+    const pathKeys = ['harnessRoot', 'worktreesDir', 'tasksDir', 'snapshotsDir', 'archiveDir', 'reportsDir', 'specRoot'];
     for (const key of pathKeys) {
         const value = config[key];
         if (typeof value === 'string') {
@@ -204,7 +202,6 @@ function loadConfig(options = {}) {
     config.snapshotsDirAbs = resolvePath(config.snapshotsDir, config.harnessRootAbs);
     config.archiveDirAbs = resolvePath(config.archiveDir, config.harnessRootAbs);
     config.reportsDirAbs = resolvePath(config.reportsDir, config.harnessRootAbs);
-    config.plansDirAbs = resolvePath(config.plansDir, config.harnessRootAbs);
     config.worktreesDirAbs = resolvePath(config.worktreesDir, projectRoot);
     config.specRootAbs = resolvePath(config.specRoot, projectRoot);
     // Add metadata
@@ -240,7 +237,6 @@ function ensureDirectories(config) {
         config.snapshotsDirAbs,
         config.archiveDirAbs,
         config.reportsDirAbs,
-        config.plansDirAbs,
         config.worktreesDirAbs,
     ];
     for (const dir of dirs) {

package/dist/slash/executor.js

@@ -4,8 +4,43 @@
  * Execute slash commands by dispatching to the appropriate command modules.
  * Supports both single commands and composite (multi-step) commands.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeSlashCommand = executeSlashCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const registry_1 = require("./registry");
 const extract_1 = require("../commands/extract");
 const design_1 = require("../commands/design");
@@ -16,6 +51,8 @@ const status_1 = require("../commands/status");
 const archive_1 = require("../lib/archive");
 const merge_1 = require("../commands/merge");
 const sync_task_to_openspec_1 = require("../spec/sync-task-to-openspec");
+const analyze_1 = require("../commands/analyze");
+const config_1 = require("../lib/config");
 function extractChangeName(parsed) {
     const firstArg = parsed.args[0];
     if (firstArg && !firstArg.startsWith('--')) {
@@ -50,7 +87,8 @@ function extractFlagValue(parsed, flag) {
 function hasFlag(parsed, flag) {
     return parsed.args.includes(`--${flag}`) || parsed.args.includes(`-${flag}`);
 }
-async function executeSingleCommand(commandName, changeName, taskId, parsed) {
+async function executeSingleCommand(commandName, changeName, taskId, parsed, extraContextFile) {
+    const contextFile = extractFlagValue(parsed, 'context-file') || extraContextFile;
     switch (commandName) {
         case 'extract': {
             if (!changeName) {
@@ -59,7 +97,7 @@ async function executeSingleCommand(commandName, changeName, taskId, parsed) {
             const result = await (0, extract_1.extract)({
                 change: changeName,
                 force: hasFlag(parsed, 'force'),
-                contextFile: extractFlagValue(parsed, 'context-file'),
+                contextFile,
             });
             return {
                 step: 'extract',
@@ -76,7 +114,7 @@ async function executeSingleCommand(commandName, changeName, taskId, parsed) {
                 change: changeName,
                 force: hasFlag(parsed, 'force'),
                 skipPrompt: true,
-                contextFile: extractFlagValue(parsed, 'context-file'),
+                contextFile,
             });
             return {
                 step: 'design',
@@ -179,15 +217,84 @@ async function executeSingleCommand(commandName, changeName, taskId, parsed) {
             return { step: commandName, success: false, message: `Unknown command: ${commandName}` };
     }
 }
+function findExistingContextFile(projectRoot) {
+    const candidatePaths = [
+        path.resolve(projectRoot, 'context.json'),
+        path.resolve(projectRoot, '.harness', 'context.json'),
+        path.resolve(projectRoot, '.tmp', 'context.json'),
+    ];
+    for (const p of candidatePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
+function generateTempContextFile(projectRoot) {
+    const tmpDir = path.resolve(projectRoot, '.tmp');
+    if (!fs.existsSync(tmpDir)) {
+        fs.mkdirSync(tmpDir, { recursive: true });
+    }
+    const contextPath = path.resolve(tmpDir, 'context.json');
+    const result = (0, analyze_1.analyzeProject)({ cwd: projectRoot, output: contextPath });
+    if (!result.success || !result.outputPath) {
+        throw new Error(`Failed to generate context: ${result.message}`);
+    }
+    return result.outputPath;
+}
 async function executeCompositeCommand(cmdDef, changeName, taskId, parsed) {
     const steps = cmdDef.steps || [];
     const stepResults = [];
+    let contextFile;
     console.log(`[SLASH] Executing composite command: /tf:${cmdDef.name}`);
     console.log(`[SLASH] Steps: ${steps.join(' → ')}`);
     console.log('');
+    if (cmdDef.name === 'propose') {
+        const explicitContextFile = extractFlagValue(parsed, 'context-file');
+        if (explicitContextFile) {
+            console.log(`[SLASH] ✓ Using explicit context: ${explicitContextFile}`);
+            contextFile = explicitContextFile;
+        }
+        else {
+            const config = (0, config_1.loadConfig)({});
+            const projectRoot = config.projectRoot || process.cwd();
+            const existingContext = findExistingContextFile(projectRoot);
+            if (existingContext) {
+                console.log(`[SLASH] ✓ Using existing context: ${existingContext}`);
+                contextFile = existingContext;
+            }
+            else {
+                console.log('[SLASH] → Step: analyze (auto)');
+                try {
+                    contextFile = generateTempContextFile(projectRoot);
+                    console.log(`[SLASH] ✓ analyze: Context generated at ${contextFile}`);
+                    stepResults.push({
+                        step: 'analyze',
+                        success: true,
+                        message: `Context generated: ${contextFile}`,
+                        detail: { contextPath: contextFile },
+                    });
+                }
+                catch (error) {
+                    const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+                    console.log(`[SLASH] ✗ analyze: ${errorMsg}`);
+                    return {
+                        success: false,
+                        command: cmdDef.name,
+                        changeName,
+                        taskId,
+                        steps: stepResults,
+                        message: `Failed to generate context: ${errorMsg}`,
+                        error: errorMsg,
+                    };
+                }
+                console.log('');
+            }
+        }
+    }
     for (const step of steps) {
         console.log(`[SLASH] → Step: ${step}`);
-        const result = await executeSingleCommand(step, changeName, taskId, parsed);
+        const result = await executeSingleCommand(step, changeName, taskId, parsed, contextFile);
         stepResults.push(result);
         if (result.success) {
             console.log(`[SLASH] ✓ ${step}: ${result.message || 'OK'}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bicorne/task-flow",
-  "version": "0.1.0",
-  "description": "Git worktree-based parallel task execution system for zero-conflict multi-task development",
+  "version": "0.2.0",
+  "description": "Harness Engineering tool for requirements analysis and task decomposition. AI-driven PRD generation, technical specs, and multi-phase task planning with zero-conflict parallel development via Git worktree.",
   "license": "MIT",
   "type": "commonjs",
   "main": "./dist/index.js",