Scopecraft Command

Scopecraft 命令

一款功能强大的命令行工具和 MCP 服务，用于管理 Markdown 驱动的任务管理（MDTM）文件。Scopecraft 通过结构化方式帮助你组织任务、功能和开发工作流。

版本 2.0：现已支持双状态工作流（当前／归档）和基于阶段的组织方式、用于复杂功能的父任务，以及高级子任务排序功能！

主要功能：

• 通过灵活的项目根目录配置，适用于任何 AI IDE（Cursor、Claude Desktop 等）
• 支持基于阶段的任务组织的双状态工作流（当前／归档 + 阶段元数据）
• 支持父任务、子任务排序和并行执行
• 支持带 TOML/YAML frontmatter 的 MDTM 格式
• 同时提供 CLI 和 MCP 服务接口
• 包含用于功能开发的 Claude 专用命令
• 自动检测项目类型
• 支持多项目并轻松切换

安装

从 NPM 安装

全局安装（推荐）

# Install globally with npm
npm install -g @scopecraft/cmd

# Or with yarn
yarn global add @scopecraft/cmd

# Or with bun
bun install -g @scopecraft/cmd

安装后，即可使用以下命令：

• scopecraft / sc - 用于任务管理的 CLI
• scopecraft-mcp / sc-mcp - MCP 服务（HTTP/SSE）
• scopecraft-stdio / sc-stdio - MCP 服务（STDIO 传输）

使用 npx（无需安装）

# Run CLI commands directly
npx @scopecraft/cmd sc task list
npx @scopecraft/cmd sc feature create "New Feature"

# Run MCP STDIO server
npx --package=@scopecraft/cmd scopecraft-stdio --root-dir /path/to/your/project

从源代码安装

# Clone repository
git clone https://github.com/scopecraft-ai/scopecraft-command.git
cd scopecraft-command

# Install dependencies
bun install

# Build project
bun run build

# Install globally
bun run install:global

项目根目录配置

Scopecraft 现已适用于任何 AI IDE！通过以下任一方法配置项目根目录：

AI IDE 快速设置

Cursor / Claude Desktop

# Start MCP server with your project
scopecraft-mcp --root-dir /path/to/your/project

也可以将以下内容添加到 IDE 的 MCP 配置中：

{
  "scopecraft": {
    "command": "scopecraft-mcp",
    "args": ["--root-dir", "/path/to/your/project"]
  }
}

多个项目

创建 ~/.scopecraft/config.json：

{
  "projects": {
    "frontend": { "path": "/projects/myapp/frontend" },
    "backend": { "path": "/projects/myapp/backend" }
  }
}

然后在运行时切换项目：

init_root /projects/myapp/backend

配置方法

1. CLI 参数：--root-dir /path/to/project
2. MCP 命令：init_root /path/to/project
3. 配置文件：~/.scopecraft/config.json
4. 环境变量：SCOPECRAFT_ROOT=/path/to/project

详细设置说明请参阅项目根目录配置指南。

入门

# Initialize Scopecraft in your project
sc init

# Create your first task
sc task create --title "My first feature" --type feature

# List your tasks
sc task list

快速开始

基本任务管理

# List all tasks
sc task list
sc task list --current    # Show only active tasks  
sc task list --phase backlog  # Show backlog items by phase

# Create a new task (goes to current with phase=backlog by default)
sc task create --title "Implement user authentication" --type feature

# Update task status
sc task update TASK-123 --status "In Progress"
sc task start TASK-123    # Shortcut for marking as "In Progress"
sc task complete TASK-123 # Shortcut for marking as "Done"

# View task details
sc task get TASK-123

父任务（复杂功能）

# Create a parent task with subtasks
sc parent create --title "User Authentication" --type feature

# Add subtasks to a parent
sc parent add-subtask auth-05K --title "Design login UI"
sc parent add-subtask auth-05K --title "Implement API" --after 01-design

# View parent task with tree visualization
sc parent show auth-05K --tree

# Work with subtasks (use full path or --parent option)
sc task update current/auth-05K/02-impl-api --status "In Progress"
sc task complete 02-impl-api --parent auth-05K

任务排序

# Make subtasks run in parallel
sc task parallelize 02-api 03-ui --parent auth-05K

# Reorder subtasks
sc task resequence auth-05K --from 1,2,3 --to 3,1,2

# Convert simple task to parent with subtasks
sc task promote simple-auth-05M --subtasks "Design,Build,Test"

工作流管理

# Two-state workflow: current (with phases) → archive
sc task create --title "New feature"          # Creates in current/ with phase=backlog
sc task update new-feature-05A --status "In Progress"  # Status changes, stays in current/
sc task update new-feature-05A --phase active          # Change phase to active
sc task complete new-feature-05A              # Moves to archive/ when done

# Move parent tasks to archive when complete
sc parent move auth-05K archive

环境和会话管理

Scopecraft 提供集成开发环境和 Claude 会话管理功能。

环境命令

# Create or switch to task environment
sc env auth-feature-05A

# List active environments
sc env list

# Get environment path for shell integration
cd "$(sc env path auth-feature-05A)"

# Close environment when done
sc env close auth-feature-05A --force

交互式开发（Work 命令）

# Interactive task selection
sc work

# Work on specific task
sc work auth-feature-05A

# Work with additional context
sc work auth-feature-05A "Focus on security requirements"

# Resume previous session
sc work --session session-abc123

自主开发（Dispatch 命令）

# Autonomous execution in Docker
sc dispatch auth-feature-05A

# Execute in tmux session
sc dispatch auth-feature-05A --exec tmux

# Execute in specific mode
sc dispatch auth-feature-05A --mode implementation

# Resume autonomous session
sc dispatch --session session-xyz789

可组合工作流

# Complete development workflow
sc task create --title "New feature" --type feature --phase backlog
sc env new-feature-05A
sc work new-feature-05A

# Or autonomous processing
sc dispatch new-feature-05A --exec tmux

旧版 Worktree 管理

为了兼容现有工作流：

# Start a task worktree
tw-start TASK-123

# Start a feature worktree
tw-feat-start FEATURE_auth

# List active worktrees
tw-list

# Finish and merge work
tw-finish TASK-123

实体－命令模式

命令遵循直观的模式：

<entity> <command> [options]

实体：

• task - 任务管理（简单任务和子任务）
• parent - 父任务管理（包含子任务的文件夹）
• env - 开发环境管理（worktree）
• work - 交互式 Claude 开发会话
• dispatch - 自主 Claude 执行
• area - 区域目录（组织单元）
• workflow - 任务序列和状态
• template - 任务模板

示例：

# Task management
sc task list
sc task create --title "Feature X" --type feature

# Environment management
sc env feature-x-05A
sc env list

# Interactive development
sc work feature-x-05A

# Autonomous execution
sc dispatch feature-x-05A --exec tmux

# Legacy format (still supported)
sc list

Claude 命令

Scopecraft 包含用于结构化开发的 Claude 专用命令：

可用命令

• /project:01_brainstorm-feature - 交互式构思（第 1 步）
• /project:02_feature-proposal - 创建正式提案（第 2 步）
• /project:03_feature-to-prd - 扩展为详细的 PRD（第 3 步）
• /project:04_feature-planning - 拆分为任务（第 4 步）
• /project:05_implement {mode} {task-id} - 在指导下执行
  • 模式：typescript、ui、mcp、cli、devops
• /project:review - 查看项目状态

工作流示例

# Step 1: Start with an idea
/project:01_brainstorm-feature "better task filtering"

# Step 2: Create proposal
/project:02_feature-proposal

# Step 3: Expand to PRD
/project:03_feature-to-prd TASK-20250517-123456

# Step 4: Plan implementation
/project:04_feature-planning FEATURE-20250517-123456

# Execute tasks
/project:05_implement ui TASK-20250517-234567

# Automatically find and implement next task in feature
/project:implement-next FEATURE_auth
/project:implement-next  # Auto-detect from current worktree

MCP 服务使用方法

启动服务

# HTTP/SSE Server (default port 3000)
scopecraft-mcp

# With custom port
MCP_PORT=8080 scopecraft-mcp

# STDIO transport
scopecraft-stdio

与 Roo Commander 集成

在 Roo Commander 设置中进行配置，即可让 LLM Agent 通过 MCP 协议直接管理任务。

请求示例

{
  "method": "task.list", 
  "params": {
    "status": "in_progress",
    "phase": "active",
    "format": "json"
  }
}

文档

CLI 参考与指南

• CLI 参考 - 完整的命令参考
• CLI 工作流指南 - 工作流模式与最佳实践

开发与集成

• 功能开发工作流
• Claude 命令指南
• 组织结构指南
• 开发指南

集成选项

独立使用

在任何项目中直接使用 Scopecraft 管理 MDTM 文件。支持带有 TOML 或 YAML 前置元数据的标准 MDTM 格式。

与 Roo Commander 配合使用

通过提供直接的 CRUD 操作，补充 Roo Commander 基于大模型的管理方式。MCP 服务无需解析 Markdown，即可高效处理任务。

项目类型检测

自动检测项目类型并据此调整行为。无需特殊配置。

致谢

Scopecraft 实现了由 Roo Commander 创建的 Markdown 驱动任务管理（MDTM）格式。我们感谢这一用于管理 Markdown 文件中任务的标准化格式。

许可证

MIT