README - command by scopecraft

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 two-state workflow (current/archive) and phase-based organization, 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
Two-state workflow with phase-based task organization (current/archive + phase metadata)
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 for detailed setup instructions.

Getting Started

# 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

Quick Start

Basic Task Management

# 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

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

# 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

Environment and Session Management

Scopecraft provides integrated development environments and Claude session management.

Environment Commands

# 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

Interactive Development (Work Command)

# 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

Autonomous Development (Dispatch Command)

# 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

Composable Workflows

# 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

Legacy Worktree Management

For compatibility with existing workflows:

# 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)
env - Development environment management (worktrees)
work - Interactive Claude development sessions
dispatch - Autonomous Claude execution
area - Area directories (organizational units)
workflow - Task sequences and status
template - Task templates

Examples:

# 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 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",
    "phase": "active",
    "format": "json"
  }
}

Documentation

CLI Reference and Guides

- Complete command reference
- Workflow patterns and best practices

Development and Integration

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