scud/lib.rs
1//! # SCUD - Fast, DAG-driven Task Manager
2//!
3//! SCUD (Simple, Concurrent, Unified, Directed) is a task management system designed
4//! for AI-driven development workflows. It provides both a CLI tool and a library
5//! for managing tasks organized in directed acyclic graphs (DAGs).
6//!
7//! ## Features
8//!
9//! - **DAG-based execution**: Tasks have dependencies that form a directed acyclic graph,
10//! ensuring work proceeds in the correct order
11//! - **Multi-phase support**: Organize tasks into phases (tags) for different project areas
12//! - **File locking**: Safe concurrent access with atomic read/write operations
13//! - **SCG format**: Token-efficient text format for task storage
14//! - **AI integration**: Parse PRDs and expand complex tasks using LLM providers
15//!
16//! ## Library Usage
17//!
18//! SCUD can be used as a library to programmatically manage tasks:
19//!
20//! ```no_run
21//! use scud::storage::Storage;
22//! use scud::models::{Phase, Task, TaskStatus};
23//!
24//! // Initialize storage (uses current directory by default)
25//! let storage = Storage::new(None);
26//!
27//! // Load all phases (task groups by tag)
28//! let phases = storage.load_tasks().expect("Failed to load tasks");
29//!
30//! // Load a specific phase by tag
31//! let auth_phase = storage.load_group("auth").expect("Phase not found");
32//!
33//! // Find the next available task (dependencies met, status pending)
34//! if let Some(next_task) = auth_phase.find_next_task() {
35//! println!("Next task: {} - {}", next_task.id, next_task.title);
36//! }
37//!
38//! // Get phase statistics
39//! let stats = auth_phase.get_stats();
40//! println!("Progress: {}/{} done", stats.done, stats.total);
41//! ```
42//!
43//! ## Storage Format
44//!
45//! Tasks are stored in `.scud/tasks/tasks.scg` using the SCG (SCUD Graph) format.
46//! Multiple phases are separated by `---` delimiters:
47//!
48//! ```text
49//! @phase auth
50//!
51//! [1] Implement login endpoint
52//! status: pending
53//! complexity: 5
54//! deps: 2, 3
55//!
56//! ---
57//!
58//! @phase api
59//!
60//! [1] Create REST framework
61//! status: done
62//! ```
63//!
64//! ## CLI Usage
65//!
66//! The `scud` binary provides commands for task management:
67//!
68//! - `scud init` - Initialize a new SCUD project
69//! - `scud list` - List tasks in the active phase
70//! - `scud next` - Find and optionally claim the next available task
71//! - `scud show <id>` - Display task details
72//! - `scud set-status <id> <status>` - Update task status
73//! - `scud waves` - Show tasks organized by execution waves
74//! - `scud stats` - Display completion statistics
75//!
76//! ## Task Generation Pipeline
77//!
78//! SCUD provides a multi-phase pipeline for generating tasks from PRD documents.
79//! This can be invoked via the CLI (`scud generate`) or programmatically:
80//!
81//! ```no_run
82//! use scud::commands::generate::{generate, GenerateOptions};
83//! use std::path::PathBuf;
84//!
85//! #[tokio::main]
86//! async fn main() -> anyhow::Result<()> {
87//! // Create options with required fields
88//! let mut options = GenerateOptions::new(
89//! PathBuf::from("docs/prd.md"),
90//! "my-feature".to_string(),
91//! );
92//!
93//! // Customize the pipeline
94//! options.num_tasks = 15; // Generate up to 15 tasks
95//! options.verbose = true; // Show detailed output
96//! options.no_expand = false; // Run expansion phase
97//! options.no_check_deps = false; // Run dependency validation
98//!
99//! // Run the pipeline: parse → expand → check-deps
100//! generate(options).await?;
101//! Ok(())
102//! }
103//! ```
104//!
105//! The pipeline consists of three phases:
106//!
107//! 1. **Parse**: Convert a PRD document into initial tasks using AI
108//! 2. **Expand**: Break down complex tasks into subtasks
109//! 3. **Check Dependencies**: Validate and fix task dependencies
110//!
111//! Each phase can be skipped using `no_expand` and `no_check_deps` options.
112
113/// Backpressure validation for maintaining code quality during automated execution.
114///
115/// Runs programmatic validation (build, test, lint) after task completion.
116/// See [`backpressure::run_validation`] for the main entry point.
117pub mod backpressure;
118
119/// CLI command implementations.
120///
121/// This module contains the implementation of all SCUD CLI commands including
122/// task listing, status updates, AI-powered parsing, and more. Each submodule
123/// corresponds to a CLI subcommand.
124///
125/// Key submodules:
126/// - `ai` - AI-powered commands (parse PRD, expand tasks, analyze complexity)
127/// - `generate` - Multi-phase task generation pipeline (parse → expand → check-deps)
128/// - `list` - List tasks with filtering
129/// - `next` - Find next available task
130/// - `set_status` - Update task status
131/// - `waves` - Display execution waves
132/// - `stats` - Show completion statistics
133/// - `spawn` - Parallel task execution
134///
135/// ## Generate Pipeline
136///
137/// The [`commands::generate`] module provides a complete pipeline for task generation:
138///
139/// ```no_run
140/// use scud::commands::generate::{generate, GenerateOptions};
141/// use std::path::PathBuf;
142///
143/// # async fn example() -> anyhow::Result<()> {
144/// let options = GenerateOptions::new(
145/// PathBuf::from("prd.md"),
146/// "feature".to_string(),
147/// );
148/// generate(options).await?;
149/// # Ok(())
150/// # }
151/// ```
152pub mod commands;
153
154/// Configuration management for SCUD projects.
155///
156/// Handles loading and saving of `.scud/config.toml` which stores:
157/// - LLM provider settings (provider, model, API endpoints)
158/// - Model tiers (smart/fast models for different task types)
159/// - Token limits and other provider-specific settings
160///
161/// # Example
162///
163/// ```no_run
164/// use scud::config::Config;
165/// use std::path::Path;
166///
167/// let config = Config::load(Path::new(".scud/config.toml"))
168/// .unwrap_or_default();
169/// println!("Using provider: {}", config.llm.provider);
170/// ```
171pub mod config;
172
173/// Task graph serialization formats.
174///
175/// Provides parsers and serializers for the SCG (SCUD Graph) format,
176/// a token-efficient text format designed for AI context windows.
177///
178/// # Format Overview
179///
180/// ```text
181/// @phase my-project
182///
183/// [1] First task
184/// status: pending
185/// complexity: 3
186///
187/// [2] Second task
188/// status: done
189/// deps: 1
190/// ```
191///
192/// Key exports:
193/// - [`formats::parse_scg`] - Parse SCG text into a Phase
194/// - [`formats::serialize_scg`] - Serialize a Phase to SCG text
195/// - [`formats::Format`] - Enum of supported formats (SCG, JSON)
196pub mod formats;
197
198/// LLM client and prompt management.
199///
200/// Provides integration with various LLM providers for AI-powered features:
201/// - PRD parsing to generate initial task lists
202/// - Task expansion into subtasks
203/// - Complexity analysis and dependency detection
204///
205/// Supported providers:
206/// - `claude-cli` - Anthropic Claude via CLI
207/// - `anthropic` - Direct Anthropic API
208/// - `xai` - xAI/Grok API
209/// - `openai` - OpenAI API
210/// - `openrouter` - OpenRouter API
211/// - `codex` - OpenAI Codex CLI
212pub mod llm;
213
214/// Core data models for tasks and phases.
215///
216/// This module defines the fundamental types used throughout SCUD:
217///
218/// - [`models::Task`] - Individual work items with status, complexity, dependencies
219/// - [`models::Phase`] - A collection of related tasks (identified by a tag)
220/// - [`models::TaskStatus`] - Task lifecycle states (Pending, InProgress, Done, etc.)
221/// - [`models::Priority`] - Task priority levels (Critical, High, Medium, Low)
222/// - [`models::IdFormat`] - ID generation strategy (Sequential or UUID)
223///
224/// # Example
225///
226/// ```
227/// use scud::models::{Task, TaskStatus, Phase};
228///
229/// let mut phase = Phase::new("my-feature".to_string());
230///
231/// let mut task = Task::new(
232/// "1".to_string(),
233/// "Implement feature".to_string(),
234/// "Add the new functionality".to_string(),
235/// );
236/// task.complexity = 5;
237/// task.dependencies = vec!["setup:1".to_string()]; // Cross-phase dependency
238///
239/// phase.add_task(task);
240///
241/// // Find tasks ready to work on
242/// if let Some(next) = phase.find_next_task() {
243/// println!("Ready: {}", next.title);
244/// }
245/// ```
246pub mod models;
247
248/// File-based task storage with locking.
249///
250/// Manages reading and writing of task data to the filesystem with:
251/// - File locking for safe concurrent access
252/// - Caching of active phase selection
253/// - Atomic read-modify-write operations
254///
255/// The storage layer handles:
256/// - `.scud/tasks/tasks.scg` - Main task storage
257/// - `.scud/active-tag` - Currently selected phase
258/// - `.scud/config.toml` - Project configuration
259/// - `.scud/guidance/*.md` - AI context files
260///
261/// # Example
262///
263/// ```no_run
264/// use scud::storage::Storage;
265/// use scud::models::TaskStatus;
266///
267/// let storage = Storage::new(None); // Use current directory
268///
269/// // Load and modify a phase atomically
270/// let mut phase = storage.load_group("my-phase").unwrap();
271/// if let Some(task) = phase.get_task_mut("1") {
272/// task.set_status(TaskStatus::Done);
273/// }
274/// storage.update_group("my-phase", &phase).unwrap();
275/// ```
276pub mod storage;