@scopecraft/cmd

Scopecraft Command

A powerful command-line tool and MCP server for managing Markdown-Driven Task Management (MDTM) files. Scopecraft helps you organize tasks, features, and development workflows with a structured approach.

Version 2.0: Now with workflow-based task organization (backlog → current → archive), parent tasks for complex features, and advanced subtask sequencing capabilities!

Key Features:

• Works with any AI IDE (Cursor, Claude Desktop, etc.) via flexible project root configuration
• Workflow-based task management with automatic state transitions
• Parent tasks with subtask sequencing and parallel execution
• Supports MDTM format with TOML/YAML frontmatter
• Provides both CLI and MCP server interfaces
• Includes specialized Claude commands for feature development
• Automated project type detection
• Multi-project support with easy switching

Installation

Install from NPM

Global Installation (Recommended)

# 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

After installation, these commands will be available:

• scopecraft / sc - CLI for task management
• scopecraft-mcp / sc-mcp - MCP server (HTTP/SSE)
• scopecraft-stdio / sc-stdio - MCP server (STDIO transport)

Using with npx (No Installation)

# 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

Install from Source

# 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

Project Root Configuration

Scopecraft now works with any AI IDE! Configure your project root using one of these methods:

Quick Setup for AI IDEs

Cursor / Claude Desktop

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

Or add to your IDE's MCP configuration:

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

Multiple Projects

Create ~/.scopecraft/config.json:

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

Then switch projects at runtime:

init_root /projects/myapp/backend

Configuration Methods

• CLI Parameter: --root-dir /path/to/project
• MCP Command: init_root /path/to/project
• Config File: ~/.scopecraft/config.json
• Environment: SCOPECRAFT_ROOT=/path/to/project

See Project Root Configuration Guide for detailed setup instructions.

Quick Start

Basic Task Management

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

# Create a new task (goes to 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

Parent Tasks (Complex Features)

# 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

Task Sequencing

# 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"

Workflow Management

# Tasks move through workflows: backlog → current → archive
sc task create --title "New feature"          # Creates in backlog
sc task update new-feature-05A --status "In Progress"  # Moves to current
sc task complete new-feature-05A              # Marks as done

# Move parent tasks between workflows
sc parent move auth-05K current

Worktree Management

# 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 Pattern

Commands follow an intuitive pattern:

<entity> <command> [options]

Entities:

• task - Task management (simple and subtasks)
• parent - Parent task management (folders with subtasks)
• area - Area directories (organizational units)
• workflow - Task sequences and status
• template - Task templates

Example:

# New format
sc task list

# Legacy format (still supported)
sc list

Claude Commands

Scopecraft includes specialized Claude commands for structured development:

Available Commands

• /project:01_brainstorm-feature - Interactive ideation (Step 1)
• /project:02_feature-proposal - Create formal proposals (Step 2)
• /project:03_feature-to-prd - Expand to detailed PRDs (Step 3)
• /project:04_feature-planning - Break down into tasks (Step 4)
• /project:05_implement {mode} {task-id} - Execute with guidance
  • Modes: typescript, ui, mcp, cli, devops
• /project:review - Review project state

Example Workflow

# 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 Server Usage

Starting the Server

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

# With custom port
MCP_PORT=8080 scopecraft-mcp

# STDIO transport
scopecraft-stdio

Integration with Roo Commander

Configure in your Roo Commander settings to enable LLM agents to manage tasks directly through the MCP protocol.

Example Request

{
  "method": "task.list",
  "params": {
    "status": "🔵 In Progress",
    "format": "json"
  }
}

Documentation

• Feature Development Workflow
• Claude Commands Guide
• Organizational Structure Guide
• MDTM Directory Structure
• Development Guide

Integration Options

Standalone Usage

Use Scopecraft directly to manage MDTM files in any project. Supports standard MDTM format with TOML or YAML frontmatter.

With Roo Commander

Complements Roo Commander's LLM-based management by providing direct CRUD operations. The MCP server allows efficient task manipulation without parsing markdown.

Project Type Detection

Automatically detects project type and adapts behavior accordingly. No special configuration needed.

Credits

Scopecraft implements the Markdown-Driven Task Management (MDTM) format created by Roo Commander. We are grateful for this standardized format for task management in markdown files.

License

MIT