syntaxis/core

Syntaxis

A comprehensive Rust-based system for managing the complete lifecycle of software projects.

Overview

Syntaxis is a unified tool for orchestrating all aspects of project development, from initial creation through publication, maintenance, and archival. It provides:

• Phase Management: Move projects through creation → devel → update → review → status → publish → archive
• Tool Orchestration: Enable/disable tools (tracking, docs, provisioning, etc.) per phase
• Template Engine: Auto-generate project structures from templates with variables
• Checklist System: Track progress with customizable checklists per phase
• Configuration-Driven: TOML-based configuration for project settings
• Multi-Language Support: Works with Rust, NuShell, and other languages
• Integration-Ready: Integrates with existing tools (doc-syntaxis, tracking-manager, provisioning)
• Dual Interfaces: Terminal UI (TUI) for power users and Web Dashboard for teams
• Advanced Task Management: Priority levels, task types, flexible sorting, and statistics (Phase 12 ✅)

Project Status

Phase 12: Task Management & Feature Parity ✅ COMPLETE

• Added task priority levels (Critical, High, Medium, Low)
• Added task type classifications (Feature, BugFix, Documentation, Testing, Deployment, Maintenance)
• Extended sort options from 4 to 6 (added priority-based sorting)
• Added statistics calculation and visualization with progress bar
• Achieved feature parity between TUI and Dashboard
• 64+ tests passing (52 TUI + 12 Dashboard)
• Full backward compatibility with older API versions
• Production-ready implementation

Previous Phases ✅ COMPLETE

• Phase 0: Foundation - Workspace structure, core types
• Phase 1-11: Core library, CLI, API, TUI development

Architecture

syntaxis/
├── crates/
│   ├── syntaxis-core/          # Core library (Phase, Tool, Checklist managers)
│   ├── syntaxis-cli/           # CLI tool with clap
│   ├── syntaxis-api/           # REST API server (axum)
│   ├── syntaxis-tui/           # TUI dashboard with ratatui
│   ├── syntaxis-dashboard/     # Web dashboard with React/Vue
│   └── vapora-project-lifecycle/        # VAPORA adapter
├── templates/                   # Project templates
├── schemas/                     # Validation schemas
├── docs/                        # Documentation
└── justfiles/                  # Modular recipes

Interfaces

Terminal User Interface (TUI)

For command-line power users and remote SSH sessions

• Built with ratatui and crossterm
• Vim-style keyboard navigation (hjkl keys)
• Real-time task management with 6 sort options
• Statistics display with progress visualization
• Minimal resource usage, works over SSH
• Full feature parity with Dashboard (Phase 12 ✅)

Getting Started:

# Start the REST API server
cargo run -p syntaxis-api

# In another terminal, start the TUI
cargo run -p syntaxis-tui

Web Dashboard

For team collaboration and visual project overview

• Modern responsive web interface
• Mouse and keyboard support
• Advanced filtering and analysis
• Per-priority/type statistics
• Mobile-friendly design
• Integration-ready REST API

Getting Started:

# Start the REST API server (same as TUI)
cargo run -p syntaxis-api

# Dashboard accessible at http://localhost:3000

Comparison & Feature Parity

See FEATURES.md for complete feature comparison between TUI and Dashboard, including:

• Task sorting options (6 variants)
• Statistics calculations
• Priority levels and task types
• Filtering capabilities
• User interface differences

Quick Start

Build

cd /Users/Akasha/Development/syntaxis
cargo build --release

Run Tests

cargo test --workspace --lib

Run CLI

cargo run -p syntaxis-cli -- --help

Check

cargo check --workspace

Implementation Timeline

Phase	Duration	Status	Deliverable
0	Week 1	✅ DONE	Foundation setup
1-11	Weeks 2-12	✅ DONE	Core library, CLI, API, TUI/Dashboard
12	Week 13	✅ DONE	Task Management & Feature Parity
13+	TBD	⏳ NEXT	Advanced features, integrations, v1.0.0 release

Features Overview

Phase Management

• Automatic phase transitions with validation
• Phase history tracking
• Required checklist completion before transition
• Allowed transition configuration

Tool Management

• Enable/disable tools per project
• Phase-specific tool activation
• Tool dependency validation
• Built-in tool registry (tracking, docs, provisioning, dev-system, presentation)

Task Management (Phase 12 ✨)

• Priority Levels: Critical, High, Medium (default), Low
• Task Types: Feature, BugFix, Documentation, Testing, Deployment, Maintenance
• Flexible Sorting: 6 sort options (newest, oldest, priority-based, completion-based)
• Real-time Statistics: Total, completed, pending counts with percentage and progress bar
• Advanced Filtering: Filter by completion status, search by description
• Dual Interfaces: Both TUI and Web Dashboard with feature parity

Checklist System

• Create checklists per phase
• Mark items as complete
• Track by priority and type
• Export to Markdown
• Track completion percentage
• Add custom items

Configuration

• TOML-based configuration
• Project metadata
• Tool settings
• Template variables
• Phase transitions

Configuration

This tool searches for configuration in this order (uses first found):

1. .project/lifecycle.toml - If using Tools in your project
2. .vapora/lifecycle.toml - If VAPORA project (automatically used if .project/ doesn't exist)

The tool uses the first existing location. You don't need all directories.

Configuration Examples

Scenario 1: VAPORA project (no .project/)

your-project/
└── .vapora/
    └── lifecycle.toml  ← Tool finds and uses this automatically

Scenario 2: Using Tools

your-project/
├── .project/
│   └── lifecycle.toml  ← Tool uses this (priority)
└── .vapora/
    └── lifecycle.toml  ← Tool ignores (has .project/)

Configuration Template

Create in one of the locations above with syntaxis settings.

Code Quality

• ✅ No unsafe code (forbid unsafe)
• ✅ Zero unwrap() → Result/Option + ?
• ✅ Comprehensive docs (rustdoc)
• ✅ 15+ unit tests with good coverage
• ✅ Idiomatic Rust throughout

Development Guidelines

Follow these principles:

1. No unsafe code - forbid entirely unless documented
2. Error handling - Use Result/Option with ? operator
3. Documentation - All public items documented with rustdoc
4. Testing - Unit tests for all critical logic
5. Formatting - cargo fmt + cargo clippy

Next Steps (Phase 1)

• Expand Phase manager with advanced transitions
• Add provisioning configuration parsing
• Implement publication target management
• Create status/health check system
• Add persistence layer (SQLite)
• Write 20+ additional unit tests

Integration Points

• doc-syntaxis: Tool enablement and integration
• tracking-manager: Change tracking integration
• dev-system: Profile and hooks management
• provisioning: K8s deployment integration
• Claude Code: .claude/ directory management

Contributing

See CLAUDE.md for project guidelines and requirements.

License

MIT