SCUD

Sprint Cycle Unified Development - Fast, AI-powered task management for building software

Version 1.17.0 - Stable release. Fast Rust CLI with SCG format, DAG-driven execution, and Claude Code hook integration.

A lightweight DAG-driven task management system with automatic completion enforcement via Claude Code hooks.

---

Quick Start

Install

Using pnpm (recommended):

pnpm add -g scud-task
cd your-project
scud init
scud hooks install  # Enable automatic task completion

Using npm:

npm install -g scud-task
cd your-project
scud init
scud hooks install

Using Bun:

# Bun blocks postinstall scripts by default, so use npm or pnpm
# Or manually run the postinstall after bun install:
bun install -g scud-task
cd ~/.bun/install/global/node_modules/scud-task
node bin/postinstall.js

Basic Usage

# Create tasks manually or parse from a PRD
scud parse-prd docs/feature.md --tag my-feature

# Find and work on next ready task
scud next --tag my-feature
scud set-status 1 in-progress

# When done, mark complete (or let hooks do it automatically)
scud set-status 1 done

Full guide: docs/guides/COMPLETE_GUIDE.md Orchestrator pattern: docs/orchestrator.md

---

Usage Modes

SCUD offers two ways to work with AI assistants, each with different trade-offs:

Mode 1: Direct CLI (Recommended)

How it works:

• Use SCUD CLI directly via bash for manual task management
• Hooks enforce automatic task completion when Claude Code sessions end
• DAG execution ensures tasks become ready when dependencies complete

Setup:

pnpm add -g scud-task   # or: npm install -g scud-task
cd your-project
scud init
scud hooks install      # Critical: enables automatic completion

Pros:

• ✅ Full file system access (can edit tasks.scg directly if needed)
• ✅ Automatic task completion via hooks (prevents forgotten updates)
• ✅ More flexible - can use any tool/command
• ✅ Better error messages (sees full CLI output)
• ✅ Can combine SCUD with other tools seamlessly
• ✅ DAG-driven execution (tasks ready when deps complete)

Cons:

• ❌ Requires bash/shell access
• ❌ Must learn CLI commands

Best for: Individual developers, orchestrator patterns, automated workflows

---

Mode 2: MCP Server (Universal Protocol)

How it works:

• Lightweight TypeScript server wraps SCUD CLI
• Exposes 20 MCP tools + 3 resources via standardized protocol
• Works with any MCP-compatible client (Claude Desktop, Cursor, Claude Code, etc.)

Setup:

pnpm add -g scud-task scud-mcp   # or: npm install -g scud-task scud-mcp

# Configure your MCP client (example for Claude Desktop):
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "scud": {
      "command": "scud-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

# For Cursor/other clients, see scud-mcp/README.md for config
# Then use naturally: "Initialize SCUD and parse my PRD"

Pros:

• ✅ Structured protocol (well-defined tool schemas)
• ✅ Works across multiple AI clients (Claude Desktop, Cursor, etc.)
• ✅ Cleaner interface (named tools vs bash commands)
• ✅ Type-safe tool calls with validation
• ✅ Can add file access via MCP resources (extensible)

Cons:

• ❌ Requires MCP server installation (extra dependency)
• ❌ Less ad-hoc than direct bash (predefined tools only)
• ❌ Client must support MCP protocol

Best for: Multi-client usage, structured workflows, type-safe operations

---

Which Mode Should You Use?

Use Direct CLI if:

• You want maximum flexibility (any bash command)
• You need DAG-driven execution with hooks
• You're building orchestrator patterns (parallel execution)
• You want zero external dependencies (just the CLI)
• You want automatic task completion enforcement

Use MCP Server if:

• You use multiple AI clients (Claude Desktop, Cursor, etc.)
• You want structured, type-safe tool calls
• You prefer protocol-based integration
• You want extensible architecture (can add custom tools/resources)

Can you use both? Yes! The MCP server wraps the CLI, so they're fully compatible. Both modes work in Claude Code, Cursor, and Claude Desktop.

---

Core Concepts

SCG Format

Tasks are stored in SCG (SCUD Graph) format—a token-efficient, human-readable text format that achieves ~75% token reduction compared to JSON. SCG explicitly represents the task dependency graph with sections for nodes, edges, and metadata. Inspired in part by Nikolai Mushegian's JAMS spec (GitHub).

@nodes
auth:1 | Design auth system | X | 13 | H
auth:1.1 | Implement JWT | D | 5 | H

@edges
auth:1.1 -> auth:1

Full spec: docs/reference/SCG_FORMAT_SPEC.md

DAG-Driven Execution

Tasks become ready when their dependencies complete. No manual phase management required.

Task 1 ──┐
         ├──> Task 3 ──> Task 5
Task 2 ──┘      │
                └──> Task 4

Tags

Group related tasks together (e.g., auth-system, payment-flow). Each tag has its own task graph.

Automatic Completion

Claude Code hooks enforce task completion when sessions end. Set SCUD_TASK_ID env var and the hook marks it done automatically.

Parallel Execution

Use orchestrator patterns to spawn multiple Claude Code agents in parallel, each working on a ready task.

---

Key Features

Fast Rust CLI

• ⚡ 50x faster than JavaScript alternatives
• 🎯 42x fewer tokens (500 vs 21k)
• 📦 Single binary - no dependencies

Hook-Enforced Completion

• 🔒 Automatic task completion via Claude Code hooks
• ✅ Prevents forgotten updates (solves 15% failure case)
• 🎯 Session-based - marks done when Claude session ends

DAG-Driven Execution

• 📊 Dependency graphs - tasks ready when deps complete
• 🔀 Parallel waves - visualize concurrent work
• 🎯 Smart scheduling - next command finds ready tasks

Orchestrator Support

• 👥 Parallel agents - spawn multiple Claude instances
• 🔒 Task locking - prevent conflicts
• 📊 Session monitoring - track active work

---

Documentation

Getting Started:

• Complete Guide - Comprehensive reference (25,000 words)
• Orchestrator Pattern - Parallel execution guide
• Migration Guide - Upgrading from BMAD-TM Lite

Integration:

• MCP Server Guide - Model Context Protocol integration
• Quick Reference - Command cheat sheet

Advanced:

• Parallel Features - Task locking & orchestration

Development:

• Development Logs - Implementation details & history

---

Commands

Setup

scud init                          # Initialize SCUD
scud hooks install                 # Enable automatic completion
scud hooks status                  # Check hook status

Core Commands (Instant)

scud tags                          # List all tags
scud list [--tag <tag>]           # List tasks
scud next [--tag <tag>]           # Find next ready task
scud set-status <id> <status>      # Update task
scud stats [--tag <tag>]          # Show statistics
scud waves [--tag <tag>]          # Show parallel waves

AI Commands (Requires XAI_API_KEY)

scud parse-prd <file> --tag <tag>  # Parse PRD into tasks
scud analyze-complexity             # Analyze all tasks
scud expand --all                   # Break down complex tasks

Default: grok-code-fast-1 via xAI. Configure with scud config --provider <provider> --model <model>.

Orchestrator Commands

scud claim <id> --name <name>      # Claim task (lock)
scud release <id>                  # Release task lock
scud whois [--tag <tag>]          # See who's working on what
scud doctor [--tag <tag>]         # Check for stale locks

---

Example Workflow

# 1. Initialize
scud init
scud hooks install

# 2. Create tasks from PRD
scud parse-prd docs/feature.md --tag auth-system
# Creates tasks with dependencies

# 3. View execution plan
scud waves --tag auth-system
# Shows which tasks can run in parallel

# 4. Work on next ready task
scud next --tag auth-system
# Returns: Task 1 is ready

# 5. Implement (manual or via orchestrator)
# Manual: Work on task, then mark done
scud set-status 1 done

# Or with orchestrator: Start Claude session with task ID
SCUD_TASK_ID=1 claude "Implement task 1"
# Hook auto-marks complete when session ends

# 6. Repeat until done
scud stats --tag auth-system
# Shows progress: 8/10 complete

See docs/orchestrator.md for parallel execution patterns.

---

Why SCUD?

DAG-Driven:

• Tasks become ready when dependencies complete
• No manual phase management
• Visualize parallel execution waves
• Smart scheduling finds ready work

Hook-Enforced:

• Automatic task completion
• Prevents forgotten status updates
• Session-based tracking
• Solves 15% agent failure case

Fast & Simple:

• Rust CLI is instant
• SCG format is human-readable and git-friendly
• Works offline (core commands)
• No vendor lock-in

Orchestrator-Ready:

• Spawn parallel Claude agents
• Task locking prevents conflicts
• Monitor active sessions
• Doctor command finds stale work

---

Requirements

• Node.js 16+ (for pnpm/npm package wrapper)
• xAI API key (for AI features only; core commands work offline)

export XAI_API_KEY=xai-...

Alternative providers: Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), OpenRouter (OPENROUTER_API_KEY). Configure with scud config.

---

File Structure

.scud/
├── tasks/tasks.scg           # All tasks in SCG format (see spec)
├── config.toml               # Active tag and settings
└── current-task              # Active task ID (for hooks)

.claude/
└── settings.local.json       # Claude Code hooks config

docs/
├── prd/                      # Product requirements
└── epics/                    # Feature descriptions

---

Development

# Build Rust CLI
cd scud-cli
cargo build --release

# The binary will be at:
# scud-cli/target/release/scud

---

Contributing

Issues and PRs welcome at github.com/pyrex41/scud

---

License

MIT

---

Learn More

• Complete Guide: docs/guides/COMPLETE_GUIDE.md
• Orchestrator Pattern: docs/orchestrator.md
• Quick Reference: docs/reference/QUICK_REFERENCE.md
• Parallel Features: docs/features/PARALLEL_FEATURES.md
• Implementation Logs: log_docs/

Happy building!