![\"Mandor](\"logo.png\")
\n\n \n
\n Stop writing markdown plans. Start shipping features with deterministic task tracking.\n
\n\n\n Dependency-aware | Structured storage | CLI-native | Built for AI agents\n
\n\n\n Installation •\n Quick Start •\n Why Mandor •\n Core Concepts •\n Commands •\n Examples\n
\n\n---\n\n## Why Mandor\n\n**No More Markdown Plan Files**\n\nTraditional workflows scatter task state across markdown files, spreadsheets, and Slack messages. Dependencies are manual, status is fiction, and progress is invisible until code review.\n\nMandor brings **deterministic task management** to AI agent workflows:\n\n- **Single Source of Truth**: All state in structured JSONL files—queryable, reproducible, auditable\n- **Automatic Dependency Resolution**: Mark tasks done → dependents auto-transition to ready\n- **Schema-Driven**: Enforce implementation steps, test cases, and library needs upfront\n- **CLI-Native**: Works in terminal, scripts, and CI/CD pipelines\n- **Dependency Tracking**: Full support for same-project and cross-project dependencies\n\n## Overview\n\nMandor is a CLI tool for managing tasks, features, and issues in AI agent workflows:\n\n- **Structured Storage**: All data in JSONL format with full audit trail\n- **Real-Time Status**: Query tasks/issues by status (ready, blocked, in_progress)\n- **Dependency Tracking**: Automatic status transitions when dependencies complete\n- **Cross-Platform**: Go binary for macOS, Linux, Windows (arm64 & x64)\n\n---\n\n\n## Core Concepts\n\n### Entity Types\n\n| Type | Purpose | Status Values |\n|------|---------|---------------|\n| **Workspace** | Top-level container for all projects | (single instance per directory) |\n| **Project** | Container for features and issues | (active/deleted) |\n| **Feature** | Logical grouping of related tasks | draft, active, done, blocked, cancelled |\n| **Task** | Work items within a feature | pending, ready, in_progress, done, blocked, cancelled |\n| **Issue** | Problems, bugs, or improvement requests | open, ready, in_progress, resolved, wontfix, blocked, cancelled |\n\n### Dependency Types\n\n- **Task Dependencies**: One task can depend on multiple tasks\n- **Feature Dependencies**: Features can depend on other features\n- **Issue Dependencies**: Issues can depend on other issues\n\n### Status Transitions\n\n**Tasks:**\n```\npending → {ready, in_progress, cancelled}\nready → {in_progress, cancelled}\nin_progress → {done, blocked, cancelled}\nblocked → {ready, cancelled}\ndone → (terminal)\ncancelled → (terminal)\n```\n\n**Features:**\n```\ndraft → {active, blocked, cancelled}\nactive → {done, blocked, cancelled}\nblocked → {draft, active, done, cancelled}\ndone → {cancelled}\ncancelled → {draft}\n```\n\n**Issues:**\n```\nopen → {ready, in_progress, blocked, resolved, wontfix, cancelled}\nready → {in_progress, blocked, resolved, wontfix, cancelled}\nin_progress → {blocked, resolved, wontfix, cancelled}\nblocked → {ready, resolved, wontfix, cancelled}\nresolved → (terminal, can reopen to any status)\nwontfix → (terminal, can reopen to any status)\ncancelled → (terminal, can reopen to any status)\n```\n\n---\n\n\n## Installation\n\n### Install with curl\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/sanxzy/mandor/main/scripts/install.sh | sh\nmandor --help\n```\n\n### Install from npm\n\n```bash\nnpm install -g @mandors/cli\nmandor --help\n```\n\n---\n\n\n## Quick Start\n\n### 1. Initialize Workspace\n\n```bash\nmandor init \"My Project\"\n```\n\n### 2. Create a Project\n\n```bash\nmandor project create api --name \"API Development\" \\\n --goal \"Build REST API service with authentication and endpoints\"\n```\n\n### 3. Create a Feature\n\n```bash\nmandor feature create \"Authentication\" --project api \\\n --goal \"Implement JWT-based authentication with login and refresh flows for secure API access\" \\\n --scope backend\n```\n\n### 4. Create Tasks with Dependencies\n\n```bash\n# Create first task (no dependencies)\nmandor task create api-feature-xxxx \"JWT Parser\" \\\n --goal \"Parse and validate JWT tokens in incoming requests with expiry and signature verification\" \\\n --implementation-steps \"Setup crypto library|Add token validation|Handle expiry|Return errors\" \\\n --test-cases \"Valid token accepted|Expired token rejected|Invalid signature rejected\" \\\n --library-needs \"golang-jwt\" \\\n --priority P1\n\n# Create dependent task (depends on JWT Parser)\nmandor task create api-feature-xxxx \"Login Endpoint\" \\\n --goal \"Accept user credentials and return JWT token with refresh token flow\" \\\n --implementation-steps \"Setup endpoint|Validate credentials|Generate JWT|Return tokens\" \\\n --test-cases \"Valid creds return token|Invalid creds rejected|Tokens properly formatted\" \\\n --depends-on api-feature-xxxx-task-xxxx \\\n --priority P1\n```\n\n### 5. View Task Progress\n\n```bash\n# See all tasks in feature with visualization\nmandor track feature api-feature-xxxx\n\n# Get task details\nmandor task detail