syntaxis/core/README.md

# 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:**
```bash
# 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:**
```bash
# 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](./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

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

### Run Tests

```bash
cargo test --workspace --lib
```

### Run CLI

```bash
cargo run -p syntaxis-cli -- --help
```

### Check

```bash
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