command

# 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) ```bash # 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) ```bash # 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 ```bash # 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 ```bash # Start MCP server with your project scopecraft-mcp --root-dir /path/to/your/project ``` Or add to your IDE's MCP configuration: ```json { "scopecraft": { "command": "scopecraft-mcp", "args": ["--root-dir", "/path/to/your/project"] } } ``` #### Multiple Projects Create `~/.scopecraft/config.json`: ```json { "projects": { "frontend": { "path": "/projects/myapp/frontend" }, "backend": { "path": "/projects/myapp/backend" } } } ``` Then switch projects at runtime: ``` init_root /projects/myapp/backend ``` ### Configuration Methods 1. **CLI Parameter**: `--root-dir /path/to/project` 2. **MCP Command**: `init_root /path/to/project` 3. **Config File**: `~/.scopecraft/config.json` 4. **Environment**: `SCOPECRAFT_ROOT=/path/to/project` See [Project Root Configuration Guide](docs/project-root-configuration-guide.md) for detailed setup instructions. ## Getting Started ```bash # 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 ```bash # 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) ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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) ```bash # 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) ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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 ```bash # 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 ```bash # 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 ```json { "method": "task.list", "params": { "status": "in_progress", "phase": "active", "format": "json" } } ``` ## Documentation ### CLI Reference and Guides - [CLI Reference](docs/04-reference/cli.md) - Complete command reference - [CLI Workflows Guide](docs/03-guides/cli-workflows.md) - Workflow patterns and best practices ### Development and Integration - [Feature Development Workflow](docs/feature-development-workflow.md) - [Claude Commands Guide](docs/claude-commands-guide.md) - [Organizational Structure Guide](docs/organizational-structure-guide.md) - [Development Guide](docs/DEVELOPMENT.md) ## 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](https://github.com/jezweb/roo-commander). We are grateful for this standardized format for task management in markdown files. ## License MIT