feat: add project guidance support for AI commands

- Add .scud/guidance/ folder for project-specific AI context
- All .md files in guidance folder automatically loaded for parse/expand
- Add --no-guidance flag to skip loading guidance
- Fix legacy README references (serve→view, grok-3-mini→grok-code-fast-1)
- Fix outdated command references (claim/release removed, whois→who-is)
- Update documentation with guidance feature

Closes: guidance context feature request

Author: pyrex41

README.md

@@ -45,7 +45,7 @@ scud set-status 1 in-progress
 scud set-status 1 done
 
 # Visualize in browser
-scud serve
+scud view
 ```
 
 **Quick reference:** [docs/reference/QUICK_REFERENCE.md](docs/reference/QUICK_REFERENCE.md)
@@ -101,7 +101,7 @@ Use orchestrator patterns to spawn multiple Claude Code agents in parallel, each
 - **Smart scheduling** - `scud next` finds ready tasks
 
 ### Web Dashboard
-- **Visual task board** - `scud serve` opens browser dashboard
+- **Visual task board** - `scud view` opens browser dashboard
 - **Mermaid diagrams** - dependency graph visualization
 - **Real-time stats** - progress tracking
 
@@ -149,25 +149,29 @@ scud waves [--tag <tag>]           # Show parallel execution waves
 
 ### Visualization
 ```bash
-scud serve                         # Start web dashboard (port 3000)
+scud view                          # Open task viewer in browser
 scud mermaid [--tag <tag>]         # Generate Mermaid diagram
 ```
 
 ### AI Commands (Requires XAI_API_KEY)
 ```bash
 scud parse <file> --tag <tag>      # Parse PRD/doc into tasks
+scud parse <file> --tag <tag> --no-guidance  # Parse without project guidance
 scud analyze-complexity            # Analyze task complexity
 scud expand --all                  # Break down complex tasks
+scud expand --all --no-guidance    # Expand without project guidance
 ```
 
-Default model: `grok-3-mini`. Configure with `scud config --provider <provider> --model <model>`.
+Default model: `grok-code-fast-1`. Configure with `scud config set-provider <provider> --model <model>`.
+
+Project guidance files in `.scud/guidance/*.md` are automatically included in AI prompts.
 
 ### Orchestrator Commands
 ```bash
-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
+scud assign <id> <name>            # Assign task to a developer
+scud who-is [--tag <tag>]          # See who's working on what
+scud next-batch [--limit 5]        # Get multiple ready tasks
+scud doctor [--tag <tag>]          # Diagnose stuck workflow states
 ```
 
 ### Utilities
@@ -207,8 +211,8 @@ scud stats --tag auth-system
 # Shows progress: 8/10 complete
 
 # 6. Visualize
-scud serve
-# Opens web dashboard with task graph
+scud view
+# Opens task viewer in browser
 ```
 
 See [docs/orchestrator.md](docs/orchestrator.md) for parallel execution patterns.
@@ -262,9 +266,31 @@ Alternative providers: Anthropic (`ANTHROPIC_API_KEY`), OpenAI (`OPENAI_API_KEY`
 ├── config.toml               # Provider/model settings
 ├── active-tag                # Currently active tag
 ├── current-task              # Active task ID (for commits)
+├── guidance/                 # Project guidance for AI prompts
+│   └── *.md                  # Markdown files auto-loaded
 └── logs/                     # Task log entries
 ```
 
+### Project Guidance
+
+You can provide project-specific context that will be automatically included in AI prompts. Create markdown files in `.scud/guidance/`:
+
+```bash
+# Example: Add coding standards
+echo "# Coding Standards
+- Use TypeScript strict mode
+- All functions must have JSDoc comments
+- Maximum function length: 50 lines" > .scud/guidance/coding-standards.md
+
+# Example: Add architecture notes
+echo "# Architecture
+- Frontend: React with hooks
+- Backend: Express.js
+- Database: PostgreSQL" > .scud/guidance/architecture.md
+```
+
+All `.md` files in this folder are automatically loaded when running `scud parse` or `scud expand`. Use `--no-guidance` to skip loading guidance.
+
 ---
 
 ## Development

docs/reference/QUICK_REFERENCE.md

@@ -22,8 +22,7 @@ scud stats [--tag <tag>]           # Show statistics
 
 ### Visualization
 ```bash
-scud serve                         # Start web dashboard (port 3000)
-scud serve --port 8080             # Custom port
+scud view                          # Open task viewer in browser
 scud mermaid                       # Generate Mermaid diagram
 scud mermaid --all-tags            # All tags in one diagram
 scud waves [--tag <tag>]           # Show parallel execution waves
@@ -32,22 +31,25 @@ scud waves [--tag <tag>]           # Show parallel execution waves
 ### AI Commands (require XAI_API_KEY)
 ```bash
 scud parse <file> --tag <tag>      # Parse PRD into tasks
+scud parse <file> --tag <tag> --no-guidance  # Skip guidance
 scud analyze-complexity            # Score all tasks
 scud analyze-complexity --task <id> # Score specific task
 scud expand <id>                   # Split complex task
 scud expand --all                  # Split all tasks >13
+scud expand --all --no-guidance    # Skip guidance
 ```
 
-Default model: `grok-3-mini`. Configure with `scud config`.
+Default model: `grok-code-fast-1`. Configure with `scud config set-provider <provider> --model <model>`.
+
+Project guidance in `.scud/guidance/*.md` is automatically included in prompts.
 
 ### Orchestrator Commands
 ```bash
-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 assign <id> <name>            # Assign task to a developer
+scud who-is [--tag <tag>]          # See who's working on what
+scud next-batch [--limit 5]        # Get multiple ready tasks
 scud doctor [--tag <tag>]          # Diagnose stuck states
 scud doctor --fix                  # Auto-fix stale locks
-scud next-batch [--count 5]        # Get multiple ready tasks
 ```
 
 ### Utilities
@@ -115,7 +117,7 @@ scud set-status <id> done          # Complete
 
 # 6. Track progress
 scud stats
-scud serve  # Web dashboard
+scud view  # Task viewer
 ```
 
 ---
@@ -128,11 +130,28 @@ scud serve  # Web dashboard
 ├── config.toml         # Provider/model settings
 ├── active-tag          # Currently active tag
 ├── current-task        # Active task ID
+├── guidance/           # Project guidance for AI
+│   └── *.md            # Auto-loaded markdown files
 └── logs/               # Task log entries
 ```
 
 ---
 
+## Project Guidance
+
+Provide project context for AI commands by adding `.md` files to `.scud/guidance/`:
+
+```bash
+.scud/guidance/
+├── coding-standards.md    # Your coding conventions
+├── architecture.md        # System architecture notes
+└── tech-stack.md          # Technology decisions
+```
+
+Files are automatically loaded for `parse` and `expand`. Use `--no-guidance` to skip.
+
+---
+
 ## SCG Format
 
 Tasks are stored in SCG (SCUD Graph) format. See [SCG_FORMAT_SPEC.md](SCG_FORMAT_SPEC.md).
@@ -166,7 +185,7 @@ export XAI_API_KEY=xai-...
 # export OPENROUTER_API_KEY=sk-or-...
 
 # Configure provider/model:
-scud config --provider xai --model grok-3-mini
+scud config set-provider xai --model grok-code-fast-1
 ```
 
 ---

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scud-task",
-  "version": "1.26.0",
+  "version": "1.29.0",
   "description": "SCUD Task Manager - Fast, AI-powered task management for building software",
   "main": "src/validators/scud-validator.js",
   "bin": {

scud-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "scud-cli"
-version = "1.28.1"
+version = "1.29.0"
 edition = "2021"
 authors = ["SCUD Team"]
 description = "Fast, simple task master for AI-driven development"

scud-cli/src/commands/ai/expand.rs

@@ -38,6 +38,7 @@ pub async fn run(
     task_id: Option<&str>,
     all_tags: bool,
     tag: Option<&str>,
+    no_guidance: bool,
 ) -> Result<()> {
     let storage = Storage::new(project_root.clone());
     let mut all_tasks = storage.load_tasks()?;
@@ -49,6 +50,23 @@ pub async fn run(
         LLMClient::new()?
     });
 
+    // Load guidance unless disabled
+    let guidance = if no_guidance {
+        None
+    } else {
+        match storage.load_guidance() {
+            Ok(g) if !g.is_empty() => {
+                println!("{}", "Loading project guidance...".blue());
+                Some(g)
+            }
+            Ok(_) => None,
+            Err(e) => {
+                eprintln!("{} Failed to load guidance: {}", "Warning:".yellow(), e);
+                None
+            }
+        }
+    };
+
     // Determine which tags to process
     let tags_to_process: Vec<String> = if all_tags {
         // --all flag: expand across ALL tags
@@ -172,6 +190,9 @@ pub async fn run(
             .progress_chars("█▓░"),
     );
 
+    // Clone guidance for async blocks
+    let guidance_arc = Arc::new(guidance);
+
     // Process tasks in parallel with bounded concurrency
     let results: Vec<Result<TaskExpansionResult, (String, String, anyhow::Error)>> =
         stream::iter(tasks_to_expand)
@@ -180,6 +201,7 @@ pub async fn run(
                     let client = Arc::clone(&client);
                     let mp = multi_progress.clone();
                     let overall = overall_progress.clone();
+                    let guidance_clone = Arc::clone(&guidance_arc);
 
                     async move {
                         let spinner = mp.add(ProgressBar::new_spinner());
@@ -199,6 +221,7 @@ pub async fn run(
                             complexity,
                             details.as_deref(),
                             recommended_subtasks,
+                            guidance_clone.as_deref(),
                         );
 
                         // Retry logic

scud-cli/src/commands/ai/parse_prd.rs

@@ -24,6 +24,7 @@ pub async fn run(
     tag: &str,
     num_tasks: u32,
     append: bool,
+    no_guidance: bool,
 ) -> Result<()> {
     let storage = Storage::new(project_root.clone());
 
@@ -35,6 +36,23 @@ pub async fn run(
     println!("{} {}", "Reading PRD from:".blue(), file_path.display());
     let prd_content = storage.read_file(file_path)?;
 
+    // Load guidance unless disabled
+    let guidance = if no_guidance {
+        None
+    } else {
+        match storage.load_guidance() {
+            Ok(g) if !g.is_empty() => {
+                println!("{}", "Loading project guidance...".blue());
+                Some(g)
+            }
+            Ok(_) => None,
+            Err(e) => {
+                eprintln!("{} Failed to load guidance: {}", "Warning:".yellow(), e);
+                None
+            }
+        }
+    };
+
     // Create LLM client with proper project root
     let client = match project_root {
         Some(root) => LLMClient::new_with_project_root(root)?,
@@ -52,7 +70,7 @@ pub async fn run(
     spinner.enable_steady_tick(std::time::Duration::from_millis(100));
 
     // Call LLM to parse the PRD
-    let prompt = Prompts::parse_prd(&prd_content, num_tasks);
+    let prompt = Prompts::parse_prd(&prd_content, num_tasks, guidance.as_deref());
     let parsed_tasks: Vec<ParsedTask> = client.complete_json(&prompt).await?;
 
     spinner.finish_with_message(format!(

scud-cli/src/llm/prompts.rs

@@ -1,10 +1,27 @@
 pub struct Prompts;
 
 impl Prompts {
-    pub fn parse_prd(phase_content: &str, num_tasks: u32) -> String {
+    pub fn parse_prd(phase_content: &str, num_tasks: u32, guidance: Option<&str>) -> String {
+        let guidance_section = guidance
+            .filter(|g| !g.is_empty())
+            .map(|g| {
+                format!(
+                    r#"
+## Project Guidance
+
+The following project-specific guidance should inform your task breakdown:
+
+{}
+
+"#,
+                    g
+                )
+            })
+            .unwrap_or_default();
+
         format!(
             r#"You are a Scrum Master parsing a phase into actionable development tasks.
-
+{}
 Phase Content:
 {}
 
@@ -36,7 +53,7 @@ Guidelines:
 - Each task should have clear success criteria
 
 Return ONLY the JSON array, no additional explanation."#,
-            phase_content, num_tasks, num_tasks
+            guidance_section, phase_content, num_tasks, num_tasks
         )
     }
 
@@ -93,14 +110,32 @@ Return ONLY the JSON object, no additional explanation."#,
         complexity: u32,
         existing_details: Option<&str>,
         recommended_subtasks: usize,
+        guidance: Option<&str>,
     ) -> String {
         let context = existing_details
             .map(|d| format!("\nExisting Technical Details:\n{}\n", d))
             .unwrap_or_default();
 
+        let guidance_section = guidance
+            .filter(|g| !g.is_empty())
+            .map(|g| {
+                format!(
+                    r#"
+## Project Guidance
+
+The following project-specific guidance should inform your subtask breakdown:
+
+{}
+
+"#,
+                    g
+                )
+            })
+            .unwrap_or_default();
+
         format!(
             r#"You are breaking down a development task into smaller, manageable subtasks.
-
+{}
 Original Task (Complexity {}): {}
 Description: {}{}
 
@@ -135,6 +170,7 @@ Guidelines:
 - DO NOT include "complexity" field - subtasks are all assumed to be small and manageable
 
 Return ONLY the JSON array, no additional explanation."#,
+            guidance_section,
             complexity,
             task_title,
             task_description,