syntaxis/.claude/PROJECT_RULES.md

Project Rules & Principles - syntaxis

Core Rules

• Follow Rust guidelines from dev-system/languages/rust/guidelines/
• PAP = Project's Architecture Principles (configuration-driven, zero unsafe, 100% tests)
• Configuration-driven, never hardcoded (use TOML + Serde)
• Never patch with hardcoded fallbacks - fix the parsing instead
• Only essential error messages, suppress stack traces except DEBUG

Project Overview

syntaxis is a standalone, production-grade project management platform extracted from the Tools ecosystem:

• Purpose: Orchestrate project lifecycle, task definitions, and status tracking
• Foundation: VAPORA SST (Software Specification & Tasks) integration
• Architecture: Modular monorepo with 6+ operational crates
• Status: ✅ Production-ready with 632+ tests passing

Mandatory Standards

Code Quality

Rule	Standard	Status
Safety	#![forbid(unsafe_code)] - Zero unsafe	✅ Pass
Errors	Result<T> with ? operator, no unwrap()	✅ Pass
Documentation	100% public API documented (rustdoc)	✅ Pass
Tests	632+ tests, 15+ per module	✅ Pass
Format	cargo fmt --all required	✅ Pass
Linting	cargo clippy --all-targets must pass	✅ Pass
Audit	cargo audit - no vulnerabilities	✅ Pass

Error Handling

Use thiserror pattern:

use thiserror::Error;
#[derive(Error, Debug)]
pub enum WorkspaceError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    #[error("Database error: {0}")]
    Database(String),
}
// Always: fn operation() -> Result<T> { ... }

Module Structure

mod error;      // Error types (thiserror)
mod types;      // Domain types (Project, Task, Phase)
mod config;     // Configuration (TOML + Serde)
mod managers;   // Business logic (ProjectManager, PhaseManager)
mod persistence;// Database layer (SQLite)
mod tracking;   // Task state tracking (for VAPORA)
#[cfg(test)] mod tests { ... }

Professional Standards

• Role: Rust Senior Developer - idiomatic, production-grade code
• Language: English only (docs, strings, code)
• Approach: TDD (test-driven development)
• Stack: NuShell for scripts, Rust for executables
• Tools: Justfile for automation, cargo for builds

Infrastructure

• Use scripts/ directory for infrastructure
• Declarative & modular via configuration (TOML)
• NuShell for bash-type commands (not Python)
• Rust for executables (not Python)

Project Tracking

• NEVER remove .coder directory - contains project lifecycle tracking
• .coder/ structure: PHASE_*.md, STATUS.md, SUMMARY.md, COMPLETION.md
• Tracks migration from syntaxis → syntaxis

Git & Development

• NO git commands unless explicitly requested
• No "ready to commit?" questions - proceed when guidelines met
• Fix bugs completely, don't simplify
• Auto-fix based on guidelines when appropriate

Architecture Patterns

Workspace Structure

syntaxis/
├── shared/                      # Shared libraries
│   ├── rust-api/               # Shared REST API library (93 tests)
│   ├── rust-tui/               # Shared TUI utilities
│   └── rust/                   # Shared utilities
├── syntaxis/           # Main project
│   ├── crates/                 # 6-8 crates
│   │   ├── syntaxis-core/     # Core library (173 tests)
│   │   ├── syntaxis-cli/      # CLI tool
│   │   ├── syntaxis-tui/      # Terminal UI (10 tests)
│   │   ├── syntaxis-dashboard/# Web Dashboard (52 tests)
│   │   ├── dashboard-client/   # Dashboard client (4 tests)
│   │   ├── dashboard-shared/   # Shared dashboard types (5 tests)
│   │   ├── syntaxis-api/      # REST API (excluded - in progress)
│   │   └── syntaxis-vapora/   # VAPORA adapter (excluded - planned)
│   ├── docs/                   # Documentation
│   ├── scripts/                # Build scripts (NuShell)
│   └── Cargo.toml             # Workspace manifest
├── .coder/                      # Project tracking (NEVER REMOVE)
├── .claude/                     # Claude Code guidelines (local)
├── .project/             # dev-system installation
├── Cargo.toml                  # Root workspace
├── Cargo.lock                  # Dependency lock
├── Justfile                    # Build recipes
└── README.md                   # Project overview

Configuration-Driven Design

• All settings via TOML + Serde
• Zero hardcoded values
• Environment variables for secrets (API keys, DB URLs)
• Feature flags for optional functionality

Database Layer

// SQLite with async runtime (tokio)
use sqlx::{sqlite::SqlitePool, Row};

// Connection pooling for performance
let pool = SqlitePool::connect("sqlite:workspace.db").await?;

REST API (axum)

// Tower middleware stack
use axum::{extract, middleware};
use tower::ServiceBuilder;

let app = ServiceBuilder::new()
    .layer(middleware::TraceLayer::new_for_http())
    .service(routes);

Multi-Interface Architecture

• CLI (workspace): Command-line tool via clap
• TUI (syntaxis-tui): Terminal UI via ratatui
• Dashboard (syntaxis-dashboard): Web UI via Leptos
• REST API (syntaxis-api): Backend via axum (in progress)

Important Notes

⚠️ NEVER:

• Remove .coder directory
• Use unsafe code
• Use unwrap() in production code
• Hardcode configuration values
• Simplify code when bugs are found

✅ ALWAYS:

• Format, lint, test, document
• Fix bugs completely - don't simplify code when issues are found
• Use proper error handling with Result
• Document public APIs with rustdoc
• Write tests first (TDD)

Crate Status

Crate	Type	Tests	Binaries	Status
syntaxis-core	lib	173	-	✅ Active
syntaxis-cli	bin	-	workspace	✅ Active
syntaxis-tui	bin	10	syntaxis-tui	✅ Active
syntaxis-dashboard	lib	52	-	✅ Active
syntaxis-api	bin	-	syntaxis-api	🟡 WIP*
syntaxis-vapora	lib	-	-	🟡 Planned*
shared-api-lib	lib	93	-	✅ Shared

*Excluded from workspace members - being developed separately

VAPORA Integration

syntaxis is designed as the foundation SST (Software Specification & Tasks) for VAPORA:

• Task state tracking with audit trail
• Phase-based project orchestration
• Enterprise-grade change tracking
• Integration hooks for VAPORA orchestration engine

For Details

• CODE_STANDARDS.md - Build, test, verification
• DEVELOPMENT.md - Workflow, patterns, documentation