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
```rust
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
```rust
#[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

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

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

## Benchmarking

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

## Documentation

### Public API
```rust
/// 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
```bash
cargo doc --no-deps --open
```

### Module Documentation
```rust
//! # 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
```bash
cd /Users/Akasha/Development/syntaxis
cargo check --workspace
cargo test --workspace
just fmt && just lint
```

### Building Binaries
```bash
# 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
```bash
docker-compose up -d
docker-compose logs -f
docker-compose down
```

### VAPORA Integration
syntaxis is designed to integrate with VAPORA:
```bash
# 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`)
```bash
cargo build -p syntaxis-cli
./target/debug/workspace --help
./target/debug/workspace project list
```

### TUI Development (`syntaxis-tui`)
```bash
cargo build -p syntaxis-tui
./target/debug/syntaxis-tui
```

### Dashboard Development (`syntaxis-dashboard`)
```bash
cargo build -p syntaxis-dashboard
# Web interface runs on http://localhost:3000
```

### REST API Development (`syntaxis-api`)
```bash
# 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](./.claude/CODE_STANDARDS.md) - Build & test commands
- [PROJECT_RULES.md](./.claude/PROJECT_RULES.md) - Architecture & patterns