foundry-implementation

Foundry Implementation Patterns

CLI Command Structure

Standard Pattern

// All commands: async fn execute(args: XxxArgs) -> Result<XxxResponse>
pub async fn execute(args: CreateProjectArgs) -> Result<CreateProjectResponse> {
    validate_args(&args).context("Invalid arguments")?;
    let result = perform_operation(&args).context("Operation failed")?;
    Ok(build_response(result))
}

Response Format (REQUIRED)

#[derive(Serialize, Debug)]
pub struct CommandResponse {
    // Core data (project, spec, etc.)
    pub next_steps: Vec<String>,        // REQUIRED: Workflow guidance
    pub validation_status: String,      // REQUIRED: "complete", "partial", "failed"

    #[serde(skip_serializing_if = "Option::is_none")]
    pub workflow_hints: Option<Vec<String>>,  // OPTIONAL: LLM guidance
}

Error Handling

Context Pattern

use anyhow::{Context, Result};

// Add meaningful context to all operations
std::fs::create_dir_all(&project_dir)
    .context(format!("Failed to create project directory: {}", project_dir.display()))?;

// Validate early, fail fast
validate_project_name(&args.project_name)
    .context("Invalid project name format")?;

Validation Functions

pub fn validate_project_name(name: &str) -> Result<()> {
    if name.is_empty() || !name.chars().all(|c| c.is_alphanumeric() || c == '-' || c == '_') {
        anyhow::bail!("Project name must use kebab-case (alphanumeric and hyphens only)");
    }
    Ok(())
}

User Memory Compliance

Function Returns (Memory #7066344)

• ONLY return what's needed - avoid unused return values
• Use #[serde(skip_serializing_if = "Option::is_none")] for optional fields
• Focus responses on immediate workflow needs

Content Creation (Memory #7065075)

• NEVER implement automatic content generation or summarization
• ALWAYS require LLMs to provide complete content as arguments
• CLI validates format and length, but NOT content quality

// ✅ Good: LLM provides content
pub struct CreateProjectArgs {
    pub project_name: String,
    pub vision: String,      // LLM-provided content
    pub tech_stack: String,  // LLM-provided content
}

// ❌ Bad: CLI generates content
pub fn generate_summary_from_vision(vision: &str) -> String {
    // Never implement this
}