syntaxis/.claude/projec_best_practices.md

syntaxis Best Practices

Project-Specific Guidelines

1. Configuration Management

• All configuration in TOML files (never hardcoded)
• Support environment variable overrides
• Validate configuration at startup
• Document all configuration options

Example:

#[derive(Deserialize)]
pub struct WorkspaceConfig {
    pub project_root: String,
    pub database_url: String,
    pub cache_ttl_secs: u64,
}

let config = WorkspaceConfig::from_file("workspace.toml")?;

2. Task State Tracking

syntaxis-core provides TaskStatus and TaskStateChange for tracking task evolution:

#[derive(Debug, Clone, Copy)]
pub enum TaskStatus {
    Pending,
    InProgress,
    Blocked,
    Completed,
    Cancelled,
}

pub struct TaskStateChange {
    pub id: String,
    pub task_id: String,
    pub from_state: TaskStatus,
    pub to_state: TaskStatus,
    pub changed_at: DateTime<Utc>,
    pub changed_by: String,
    pub reason: Option<String>,
    pub metadata: serde_json::Value,
}

3. Phase-Based Project Orchestration

Projects follow distinct phases defined in PROJECT_RULES.md:

// Use PhaseManager for orchestration
let mut phase_manager = PhaseManager::new(project_id);
phase_manager.advance_phase(CurrentPhase::InitialSetup)?;
phase_manager.validate_prerequisites()?;

4. Multi-Interface Consistency

Ensure consistency across all interfaces (CLI, TUI, Dashboard, API):

• Same error messages and codes
• Consistent naming conventions
• Unified configuration
• Shared domain models (syntaxis-core)

5. Database Interaction

Use SQLx with proper connection pooling:

use sqlx::sqlite::SqlitePool;

let pool = SqlitePool::connect("sqlite:workspace.db").await?;
let project = sqlx::query!("SELECT * FROM projects WHERE id = ?", project_id)
    .fetch_one(&pool)
    .await?;

6. Error Responses

API and CLI errors should be consistent:

#[derive(Error, Debug)]
pub enum WorkspaceError {
    #[error("Project not found: {0}")]
    ProjectNotFound(String),

    #[error("Invalid task state transition: {from} -> {to}")]
    InvalidTransition { from: String, to: String },

    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),
}

7. Logging Best Practices

Use structured logging throughout:

use tracing::{info, error, span, Level};

let span = span!(Level::INFO, "project_creation", project_id = ?id);
let _enter = span.enter();
info!("Creating new project");

// Automatic context logging

8. Testing Strategy

• Unit tests for business logic
• Integration tests for workflows
• Property-based tests for edge cases
• Benchmark critical paths

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_phase_transition() {
        let mut manager = PhaseManager::new("test");
        assert!(manager.advance_phase(Phase::InitialSetup).is_ok());
    }
}

9. Documentation Standards

Public APIs must have:

• Clear description of purpose
• Parameter documentation
• Return type documentation
• Example usage
• Error conditions

/// Creates a new project with validation
///
/// # Arguments
/// * `name` - Project name (non-empty)
/// * `description` - Project description
///
/// # Returns
/// * `Ok(Project)` - Successfully created project
/// * `Err(WorkspaceError)` - If validation fails
///
/// # Errors
/// - `InvalidName` - If name is empty
/// - `Database` - If database operation fails
///
/// # Example
/// ```
/// let project = ProjectManager::create("my-project", "desc")?;
/// ```
pub fn create(name: &str, description: &str) -> Result<Project> {
    // Implementation
}

10. VAPORA Integration Points

syntaxis is designed for VAPORA integration:

• Task state changes trigger VAPORA events
• Phase transitions notify orchestration engine
• Project metadata supports VAPORA requirements
• REST API (in progress) will provide integration hooks

11. Code Organization

Keep related functionality together:

syntaxis-core/
├── error.rs              # Error types
├── types/
│   ├── project.rs       # Project domain
│   ├── task.rs          # Task domain
│   └── phase.rs         # Phase domain
├── managers/
│   ├── project.rs       # ProjectManager
│   ├── phase.rs         # PhaseManager
│   └── task.rs          # TaskManager
├── persistence/
│   ├── mod.rs           # PersistenceLayer trait
│   ├── memory.rs        # In-memory implementation
│   └── sqlite.rs        # SQLite implementation
└── lib.rs               # Module root & exports

12. Performance Considerations

• Use connection pooling for database
• Cache frequently accessed data
• Lazy load relationships
• Profile with flamegraph for hot paths
• Benchmark critical operations

# Profile performance
cargo flamegraph --bin syntaxis-cli -- --help

# Benchmark specific operation
cargo bench -p syntaxis-core

13. Security Practices

• Never log sensitive data
• Validate all user input
• Use environment variables for secrets
• Audit API access (when API is enabled)
• Regular dependency audits

# Check for vulnerabilities
cargo audit

# Check specific crate
cargo audit -p syntaxis-core

14. Dependency Management

• Keep dependencies minimal
• Use workspace.dependencies for consistency
• Pin security-critical versions
• Review breaking changes before updates
• Document why each dependency is needed

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
thiserror = "2.0"
tokio = { version = "1", features = ["full"] }

15. Backward Compatibility

• Avoid breaking public API changes
• Use feature flags for experimental features
• Deprecate gradually before removal
• Document migration paths for users

Quick Reference: Common Tasks

Adding a new feature to syntaxis-core

1. Create types in syntaxis-core/src/types/
2. Create manager in syntaxis-core/src/managers/
3. Add persistence layer support
4. Write 15+ unit tests
5. Add integration test to syntaxis-cli
6. Update documentation

Adding a CLI command

1. Create handler in syntaxis-cli/src/handlers/
2. Wire up in syntaxis-cli/src/main.rs
3. Test with actual workspace project
4. Update help/documentation

Adding Dashboard component

1. Create component in syntaxis-dashboard/src/components/
2. Integrate with state in syntaxis-dashboard/src/state/
3. Write HTML rendering tests
4. Test in browser at http://localhost:3000

For Details

• PROJECT_RULES.md - Architecture & standards
• CODE_STANDARDS.md - Testing & verification
• DEVELOPMENT.md - Development workflow