9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
191 lines
6.7 KiB
Markdown
191 lines
6.7 KiB
Markdown
# 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:
|
|
```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),
|
|
}
|
|
// Always: fn operation() -> Result<T> { ... }
|
|
```
|
|
|
|
### Module Structure
|
|
```rust
|
|
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
|
|
```rust
|
|
// 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)
|
|
```rust
|
|
// 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<T>
|
|
- 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](./.claude/CODE_STANDARDS.md) - Build, test, verification
|
|
- [DEVELOPMENT.md](./.claude/DEVELOPMENT.md) - Workflow, patterns, documentation
|