syntaxis/.claude/DEVELOPMENT.md

Development Workflow - syntaxis

Feature Implementation Checklist

1. Update todo: /add-todo "Feature: description"
2. Write failing test first (TDD)
3. Implement feature (idiomatic Rust)
4. Run: cargo test --workspace
5. Run: cargo clippy --all-targets
6. Run: cargo fmt --all
7. Update docs & rustdoc
8. All tests passing (632+ tests)

Common Patterns

Error Handling

use thiserror::Error;
#[derive(Error, Debug)]
pub enum WorkspaceError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Database error: {0}")]
    Database(String),
}
pub fn operation() -> Result<String> {
    let data = std::fs::read_to_string("file.txt")?;
    Ok(data)
}

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_behavior() {
        assert_eq!(function(), expected);
    }
}

Integration Tests

Place in tests/ directory - test complete workflows with public APIs.

Logging

RUST_LOG=debug cargo run           # Debug mode
RUST_LOG=syntaxis-core=trace cargo test  # Specific module
RUST_LOG=info,syntaxis-cli=debug cargo run

use tracing::{debug, info, warn, error};
info!("Operation started: {}", name);
debug!("Processing: {:?}", item);
warn!("Unexpected state: {}", reason);
error!("Operation failed: {}", error);

Benchmarking

cargo bench                         # All benchmarks
cargo bench -p syntaxis-core       # Specific crate
cargo bench -- --verbose            # Detailed output

Documentation

Public API

/// Computes the factorial of a number
///
/// # Arguments
/// * `n` - A non-negative integer
///
/// # Returns
/// The factorial of n
///
/// # Examples
/// ```
/// assert_eq!(factorial(5), 120);
/// ```
pub fn factorial(n: u32) -> u32 {
    match n {
        0 | 1 => 1,
        _ => n * factorial(n - 1),
    }
}

Generate Docs

cargo doc --no-deps --open

Module Documentation

//! # syntaxis-core
//!
//! Core library for syntaxis project management.
//!
//! ## Features
//!
//! - Syntaxis management
//! - Task definition and tracking
//! - Phase-based orchestration

Version Control

Branch Naming

• feature/name - New features
• fix/issue - Bug fixes
• refactor/scope - Refactoring
• docs/description - Documentation
• test/description - Tests

Commit Format

feat: Add authentication system
fix: Resolve memory leak
refactor: Simplify error handling
docs: Update API docs
test: Add edge case tests

Important

• NO force push to main/master
• NO skip hooks (--no-verify)
• NO git commands unless requested
• Don't ask "ready to commit?" - proceed when guidelines met

TDD: Red-Green-Refactor

1. Red: Write failing test
2. Green: Minimal implementation
3. Refactor: Improve implementation

Deployment

Local Development

cd /Users/Akasha/Development/syntaxis
cargo check --workspace
cargo test --workspace
just fmt && just lint

Building Binaries

# Development
cargo build

# Production
cargo build --release

# Specific binaries
cargo build --release -p syntaxis-cli
cargo build --release -p syntaxis-tui
cargo build --release -p syntaxis-dashboard

Docker

docker-compose up -d
docker-compose logs -f
docker-compose down

VAPORA Integration

syntaxis is designed to integrate with VAPORA:

# Once VAPORA integration is complete
syntaxis-vapora run --config vapora.toml

Quick Commands

Command	Purpose
cargo check --workspace	Verify compilation
cargo test --workspace	Run all tests (632+)
cargo clippy --all-targets	Linting
cargo fmt --all	Format code
cargo build --release	Production build
cargo doc --no-deps --open	Generate docs
RUST_LOG=debug cargo run	Debug logging
cargo bench	Benchmarks
just check-all	fmt + lint + check + test

Multi-Interface Development

CLI Development (workspace)

cargo build -p syntaxis-cli
./target/debug/workspace --help
./target/debug/workspace project list

TUI Development (syntaxis-tui)

cargo build -p syntaxis-tui
./target/debug/syntaxis-tui

Dashboard Development (syntaxis-dashboard)

cargo build -p syntaxis-dashboard
# Web interface runs on http://localhost:3000

REST API Development (syntaxis-api)

# Currently excluded - under development
cargo build -p syntaxis-api
# Server runs on http://localhost:8080

Critical Rules

✅ ALWAYS:

• Write tests first (TDD)
• Format & lint before commit
• Document public APIs
• Fix bugs completely - don't simplify code when issues are found
• Run full test suite before pushing

❌ NEVER:

• Use unsafe code
• Use unwrap() in production
• Skip formatting & linting
• Simplify instead of fixing
• Remove .coder directory

Testing in syntaxis

Current test coverage:

• syntaxis-core: 173 tests ✅
• syntaxis-tui: 10 tests ✅
• syntaxis-dashboard: 52 tests ✅
• dashboard-shared: 5 tests ✅
• dashboard-client: 4 tests ✅
• shared-api-lib: 93 tests ✅
• shared/rust: 33 tests ✅
• shared/rust-tui: 262 tests ✅

Total: 632/632 tests passing ✅

For Details

• CODE_STANDARDS.md - Build & test commands
• PROJECT_RULES.md - Architecture & patterns