Skip to content
Back to search

command

Scopecraft Command - A CLI and MCP server for Markdown-Driven Task Management (MDTM)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/scopecraft--command/badge.svg)](/listings/scopecraft--command)

HTML

<a href="/listings/scopecraft--command"><img src="/api/listings/scopecraft--command/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 413 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Scopecraft Command
  2. 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.
  3. > **Version 2.0**: Now with two-state workflow (current/archive) and phase-based organization, parent tasks for complex features, and advanced subtask sequencing capabilities!
  4. **Key Features:**
  5. * Works with any AI IDE (Cursor, Claude Desktop, etc.) via flexible project root configuration
  6. * Two-state workflow with phase-based task organization (current/archive + phase metadata)
  7. * Parent tasks with subtask sequencing and parallel execution
  8. * Supports MDTM format with TOML/YAML frontmatter
  9. * Provides both CLI and MCP server interfaces
  10. * Includes specialized Claude commands for feature development
  11. * Automated project type detection
  12. * Multi-project support with easy switching
  13. ## Installation
  14. ### Install from NPM
  15. #### Global Installation (Recommended)
  16. ```bash
  17. # Install globally with npm
  18. npm install -g @scopecraft/cmd
  19. # Or with yarn
  20. yarn global add @scopecraft/cmd
  21. # Or with bun
  22. bun install -g @scopecraft/cmd
  23. ```
  24. After installation, these commands will be available:
  25. - `scopecraft` / `sc` - CLI for task management
  26. - `scopecraft-mcp` / `sc-mcp` - MCP server (HTTP/SSE)
  27. - `scopecraft-stdio` / `sc-stdio` - MCP server (STDIO transport)
  28. #### Using with npx (No Installation)
  29. ```bash
  30. # Run CLI commands directly
  31. npx @scopecraft/cmd sc task list
  32. npx @scopecraft/cmd sc feature create "New Feature"
  33. # Run MCP STDIO server
  34. npx --package=@scopecraft/cmd scopecraft-stdio --root-dir /path/to/your/project
  35. ```
  36. ### Install from Source
  37. ```bash
  38. # Clone repository
  39. git clone https://github.com/scopecraft-ai/scopecraft-command.git
  40. cd scopecraft-command
  41. # Install dependencies
  42. bun install
  43. # Build project
  44. bun run build
  45. # Install globally
  46. bun run install:global
  47. ```
  48. ## Project Root Configuration
  49. Scopecraft now works with any AI IDE! Configure your project root using one of these methods:
  50. ### Quick Setup for AI IDEs
  51. #### Cursor / Claude Desktop
  52. ```bash
  53. # Start MCP server with your project
  54. scopecraft-mcp --root-dir /path/to/your/project
  55. ```
  56. Or add to your IDE's MCP configuration:
  57. ```json
  58. {
  59. "scopecraft": {
  60. "command": "scopecraft-mcp",
  61. "args": ["--root-dir", "/path/to/your/project"]
  62. }
  63. }
  64. ```
  65. #### Multiple Projects
  66. Create `~/.scopecraft/config.json`:
  67. ```json
  68. {
  69. "projects": {
  70. "frontend": { "path": "/projects/myapp/frontend" },
  71. "backend": { "path": "/projects/myapp/backend" }
  72. }
  73. }
  74. ```
  75. Then switch projects at runtime:
  76. ```
  77. init_root /projects/myapp/backend
  78. ```
  79. ### Configuration Methods
  80. 1. **CLI Parameter**: `--root-dir /path/to/project`
  81. 2. **MCP Command**: `init_root /path/to/project`
  82. 3. **Config File**: `~/.scopecraft/config.json`
  83. 4. **Environment**: `SCOPECRAFT_ROOT=/path/to/project`
  84. See [Project Root Configuration Guide](docs/project-root-configuration-guide.md) for detailed setup instructions.
  85. ## Getting Started
  86. ```bash
  87. # Initialize Scopecraft in your project
  88. sc init
  89. # Create your first task
  90. sc task create --title "My first feature" --type feature
  91. # List your tasks
  92. sc task list
  93. ```
  94. ## Quick Start
  95. ### Basic Task Management
  96. ```bash
  97. # List all tasks
  98. sc task list
  99. sc task list --current # Show only active tasks
  100. sc task list --phase backlog # Show backlog items by phase
  101. # Create a new task (goes to current with phase=backlog by default)
  102. sc task create --title "Implement user authentication" --type feature
  103. # Update task status
  104. sc task update TASK-123 --status "In Progress"
  105. sc task start TASK-123 # Shortcut for marking as "In Progress"
  106. sc task complete TASK-123 # Shortcut for marking as "Done"
  107. # View task details
  108. sc task get TASK-123
  109. ```
  110. ### Parent Tasks (Complex Features)
  111. ```bash
  112. # Create a parent task with subtasks
  113. sc parent create --title "User Authentication" --type feature
  114. # Add subtasks to a parent
  115. sc parent add-subtask auth-05K --title "Design login UI"
  116. sc parent add-subtask auth-05K --title "Implement API" --after 01-design
  117. # View parent task with tree visualization
  118. sc parent show auth-05K --tree
  119. # Work with subtasks (use full path or --parent option)
  120. sc task update current/auth-05K/02-impl-api --status "In Progress"
  121. sc task complete 02-impl-api --parent auth-05K
  122. ```
  123. ### Task Sequencing
  124. ```bash
  125. # Make subtasks run in parallel
  126. sc task parallelize 02-api 03-ui --parent auth-05K
  127. # Reorder subtasks
  128. sc task resequence auth-05K --from 1,2,3 --to 3,1,2
  129. # Convert simple task to parent with subtasks
  130. sc task promote simple-auth-05M --subtasks "Design,Build,Test"
  131. ```
  132. ### Workflow Management
  133. ```bash
  134. # Two-state workflow: current (with phases) → archive
  135. sc task create --title "New feature" # Creates in current/ with phase=backlog
  136. sc task update new-feature-05A --status "In Progress" # Status changes, stays in current/
  137. sc task update new-feature-05A --phase active # Change phase to active
  138. sc task complete new-feature-05A # Moves to archive/ when done
  139. # Move parent tasks to archive when complete
  140. sc parent move auth-05K archive
  141. ```
  142. ### Environment and Session Management
  143. Scopecraft provides integrated development environments and Claude session management.
  144. #### Environment Commands
  145. ```bash
  146. # Create or switch to task environment
  147. sc env auth-feature-05A
  148. # List active environments
  149. sc env list
  150. # Get environment path for shell integration
  151. cd "$(sc env path auth-feature-05A)"
  152. # Close environment when done
  153. sc env close auth-feature-05A --force
  154. ```
  155. #### Interactive Development (Work Command)
  156. ```bash
  157. # Interactive task selection
  158. sc work
  159. # Work on specific task
  160. sc work auth-feature-05A
  161. # Work with additional context
  162. sc work auth-feature-05A "Focus on security requirements"
  163. # Resume previous session
  164. sc work --session session-abc123
  165. ```
  166. #### Autonomous Development (Dispatch Command)
  167. ```bash
  168. # Autonomous execution in Docker
  169. sc dispatch auth-feature-05A
  170. # Execute in tmux session
  171. sc dispatch auth-feature-05A --exec tmux
  172. # Execute in specific mode
  173. sc dispatch auth-feature-05A --mode implementation
  174. # Resume autonomous session
  175. sc dispatch --session session-xyz789
  176. ```
  177. #### Composable Workflows
  178. ```bash
  179. # Complete development workflow
  180. sc task create --title "New feature" --type feature --phase backlog
  181. sc env new-feature-05A
  182. sc work new-feature-05A
  183. # Or autonomous processing
  184. sc dispatch new-feature-05A --exec tmux
  185. ```
  186. ### Legacy Worktree Management
  187. For compatibility with existing workflows:
  188. ```bash
  189. # Start a task worktree
  190. tw-start TASK-123
  191. # Start a feature worktree
  192. tw-feat-start FEATURE_auth
  193. # List active worktrees
  194. tw-list
  195. # Finish and merge work
  196. tw-finish TASK-123
  197. ```
  198. ## Entity-Command Pattern
  199. Commands follow an intuitive pattern:
  200. ```
  201. <entity> <command> [options]
  202. ```
  203. Entities:
  204. - `task` - Task management (simple and subtasks)
  205. - `parent` - Parent task management (folders with subtasks)
  206. - `env` - Development environment management (worktrees)
  207. - `work` - Interactive Claude development sessions
  208. - `dispatch` - Autonomous Claude execution
  209. - `area` - Area directories (organizational units)
  210. - `workflow` - Task sequences and status
  211. - `template` - Task templates
  212. Examples:
  213. ```bash
  214. # Task management
  215. sc task list
  216. sc task create --title "Feature X" --type feature
  217. # Environment management
  218. sc env feature-x-05A
  219. sc env list
  220. # Interactive development
  221. sc work feature-x-05A
  222. # Autonomous execution
  223. sc dispatch feature-x-05A --exec tmux
  224. # Legacy format (still supported)
  225. sc list
  226. ```
  227. ## Claude Commands
  228. Scopecraft includes specialized Claude commands for structured development:
  229. ### Available Commands
  230. - `/project:01_brainstorm-feature` - Interactive ideation (Step 1)
  231. - `/project:02_feature-proposal` - Create formal proposals (Step 2)
  232. - `/project:03_feature-to-prd` - Expand to detailed PRDs (Step 3)
  233. - `/project:04_feature-planning` - Break down into tasks (Step 4)
  234. - `/project:05_implement {mode} {task-id}` - Execute with guidance
  235. - Modes: `typescript`, `ui`, `mcp`, `cli`, `devops`
  236. - `/project:review` - Review project state
  237. ### Example Workflow
  238. ```bash
  239. # Step 1: Start with an idea
  240. /project:01_brainstorm-feature "better task filtering"
  241. # Step 2: Create proposal
  242. /project:02_feature-proposal
  243. # Step 3: Expand to PRD
  244. /project:03_feature-to-prd TASK-20250517-123456
  245. # Step 4: Plan implementation
  246. /project:04_feature-planning FEATURE-20250517-123456
  247. # Execute tasks
  248. /project:05_implement ui TASK-20250517-234567
  249. # Automatically find and implement next task in feature
  250. /project:implement-next FEATURE_auth
  251. /project:implement-next # Auto-detect from current worktree
  252. ```
  253. ## MCP Server Usage
  254. ### Starting the Server
  255. ```bash
  256. # HTTP/SSE Server (default port 3000)
  257. scopecraft-mcp
  258. # With custom port
  259. MCP_PORT=8080 scopecraft-mcp
  260. # STDIO transport
  261. scopecraft-stdio
  262. ```
  263. ### Integration with Roo Commander
  264. Configure in your Roo Commander settings to enable LLM agents to manage tasks directly through the MCP protocol.
  265. ### Example Request
  266. ```json
  267. {
  268. "method": "task.list",
  269. "params": {
  270. "status": "in_progress",
  271. "phase": "active",
  272. "format": "json"
  273. }
  274. }
  275. ```
  276. ## Documentation
  277. ### CLI Reference and Guides
  278. - [CLI Reference](docs/04-reference/cli.md) - Complete command reference
  279. - [CLI Workflows Guide](docs/03-guides/cli-workflows.md) - Workflow patterns and best practices
  280. ### Development and Integration
  281. - [Feature Development Workflow](docs/feature-development-workflow.md)
  282. - [Claude Commands Guide](docs/claude-commands-guide.md)
  283. - [Organizational Structure Guide](docs/organizational-structure-guide.md)
  284. - [Development Guide](docs/DEVELOPMENT.md)
  285. ## Integration Options
  286. ### Standalone Usage
  287. Use Scopecraft directly to manage MDTM files in any project. Supports standard MDTM format with TOML or YAML frontmatter.
  288. ### With Roo Commander
  289. Complements Roo Commander's LLM-based management by providing direct CRUD operations. The MCP server allows efficient task manipulation without parsing markdown.
  290. ### Project Type Detection
  291. Automatically detects project type and adapts behavior accordingly. No special configuration needed.
  292. ## Credits
  293. 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.
  294. ## License
  295. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.