Mandor - Deterministic Task Manager CLI for AI Agent Workflows

Stop writing markdown plans. Start shipping features with deterministic task tracking.

Dependency-aware | Structured storage | CLI-native | Built for AI agents

Installation •
Quick Start •
Why Mandor •
Core Concepts •
Commands •
Examples

---

Why Mandor

No More Markdown Plan Files

Traditional workflows scatter task state across markdown files, spreadsheets, and Slack messages. Dependencies are manual, status is fiction, and progress is invisible until code review.

Mandor brings deterministic task management to AI agent workflows:

- Single Source of Truth: All state in structured JSONL files—queryable, reproducible, auditable
- Automatic Dependency Resolution: Mark tasks done → dependents auto-transition to ready
- Schema-Driven: Enforce implementation steps, test cases, and library needs upfront
- CLI-Native: Works in terminal, scripts, and CI/CD pipelines
- Dependency Tracking: Full support for same-project and cross-project dependencies

Overview

Mandor is a CLI tool for managing tasks, features, and issues in AI agent workflows:

- Structured Storage: All data in JSONL format with full audit trail
- Real-Time Status: Query tasks/issues by status (ready, blocked, in_progress)
- Dependency Tracking: Automatic status transitions when dependencies complete
- Cross-Platform: Go binary for macOS, Linux, Windows (arm64 & x64)

---

Core Concepts

$3

| Type | Purpose | Status Values |
|------|---------|---------------|
| Workspace | Top-level container for all projects | (single instance per directory) |
| Project | Container for features and issues | (active/deleted) |
| Feature | Logical grouping of related tasks | draft, active, done, blocked, cancelled |
| Task | Work items within a feature | pending, ready, in_progress, done, blocked, cancelled |
| Issue | Problems, bugs, or improvement requests | open, ready, in_progress, resolved, wontfix, blocked, cancelled |

$3

- Task Dependencies: One task can depend on multiple tasks
- Feature Dependencies: Features can depend on other features
- Issue Dependencies: Issues can depend on other issues

$3

Tasks:
``
pending → {ready, in_progress, cancelled}
ready → {in_progress, cancelled}
in_progress → {done, blocked, cancelled}
blocked → {ready, cancelled}
done → (terminal)
cancelled → (terminal)
`

Features:
`
draft → {active, blocked, cancelled}
active → {done, blocked, cancelled}
blocked → {draft, active, done, cancelled}
done → {cancelled}
cancelled → {draft}
`

Issues:
`
open → {ready, in_progress, blocked, resolved, wontfix, cancelled}
ready → {in_progress, blocked, resolved, wontfix, cancelled}
in_progress → {blocked, resolved, wontfix, cancelled}
blocked → {ready, resolved, wontfix, cancelled}
resolved → (terminal, can reopen to any status)
wontfix → (terminal, can reopen to any status)
cancelled → (terminal, can reopen to any status)
`

---




Installation

$3

`bash
curl -fsSL https://raw.githubusercontent.com/sanxzy/mandor/main/scripts/install.sh | sh
mandor --help
`

$3

`bash
npm install -g @mandors/cli
mandor --help
`

---




Quick Start

$3

`bash
mandor init "My Project"
`

$3

`bash
mandor project create api --name "API Development" \
--goal "Build REST API service with authentication and endpoints"
`

$3

`bash
mandor feature create "Authentication" --project api \
--goal "Implement JWT-based authentication with login and refresh flows for secure API access" \
--scope backend
`

$3

`bash


Create first task (no dependencies)

mandor task create api-feature-xxxx "JWT Parser" \
--goal "Parse and validate JWT tokens in incoming requests with expiry and signature verification" \
--implementation-steps "Setup crypto library|Add token validation|Handle expiry|Return errors" \
--test-cases "Valid token accepted|Expired token rejected|Invalid signature rejected" \
--library-needs "golang-jwt" \
--priority P1

Create dependent task (depends on JWT Parser)

mandor task create api-feature-xxxx "Login Endpoint" \
--goal "Accept user credentials and return JWT token with refresh token flow" \
--implementation-steps "Setup endpoint|Validate credentials|Generate JWT|Return tokens" \
--test-cases "Valid creds return token|Invalid creds rejected|Tokens properly formatted" \
--depends-on api-feature-xxxx-task-xxxx \
--priority P1
`

$3

`bash


See all tasks in feature with visualization

mandor track feature api-feature-xxxx

Get task details

mandor task detail
`

$3

`bash


Get task ID from track output

mandor task update --status in_progress
mandor task update --status done

Dependent tasks auto-transition to "ready"

mandor track feature api-feature-xxxx # Now shows "Login Endpoint" as ready
`

---

Commands Reference

$3

`bash


Initialize a new workspace

mandor init [--workspace-name ] [-y]

View workspace and project status

mandor status [--project ] [--summary] [--json]

Manage configuration

mandor config get
mandor config set
mandor config list
mandor config reset

Display all commands and best practices

mandor populate

Show version

mandor version

Generate shell completions

mandor completion [bash|zsh|fish]

AI-assisted documentation

mandor ai --help
`

$3

`bash


Track workspace status

mandor track

Track project status

mandor track project

Track feature with tasks

mandor track feature [--verbose]

Track specific task

mandor track task

Track issue

mandor track issue
`

$3

`bash


Add a progress note (AI agents use this to track work)

mandor session note "Completed v0.4.4 release and testing"

Read recent session notes (last 50 entries by default)

mandor session note --read

Read more notes with offset

mandor session note --read --offset 100
`

$3

`bash


Create a project

mandor project create --name --goal [OPTIONS]

Show project details

mandor project detail

Update project

mandor project update [--name ] [--goal ] [--status ]
`

$3

`bash


Create a feature

mandor feature create --project --goal [--scope ] [--priority ]

List features

mandor feature list --project

Show feature details

mandor feature detail --project

Update feature

mandor feature update --project [--name ] [--goal ] [--scope ] [--priority ] [--status ] [--depends ] [--cancel --reason ] [--reopen] [--dry-run]
`

$3

`bash


Create a task

mandor task create --goal \
--implementation-steps --test-cases \
--derivable-files --library-needs \
[--priority ] [--depends-on ]

Show task details

mandor task detail

Update task

mandor task update [--name ] [--goal ] [--priority ] \
[--status ] [--depends-add ] [--depends-remove ] [--cancel --reason ] [--dry-run]
`

$3

`bash


Create an issue

mandor issue create --project --type --goal \
--affected-files --affected-tests \
--implementation-steps [--priority ] [--depends-on ] [--library-needs ]

Show issue details

mandor issue detail --project

Update issue

mandor issue update [--name ] [--goal ] [--priority ] \
[--type ] [--status ] [--start] [--resolve] [--wontfix] [--reason ] [--cancel --reason ] [--dry-run]
`

$3

`bash


AI-assisted documentation generation


mandor ai agents
mandor ai claude
`

---

Common Workflows

$3

`markdown


PLAN.md

Phase 1: Authentication

- [ ] JWT parser (depends on cryptography)
- [ ] Login endpoint (depends on JWT parser)
- [ ] Refresh token (depends on JWT parser)

Status: Last updated 3 days ago (probably stale!)
`

$3

`bash


Create structured plan

mandor feature create "Authentication" --project api \
--goal "Implement JWT and login endpoints" \
--scope backend

Create tasks with explicit dependencies

mandor task create api-feature-xxxx "JWT Parser" \
--goal "Validate JWT tokens..." \
--implementation-steps "Step 1|Step 2" \
--test-cases "Test invalid tokens|Test expired" \
--library-needs "jsonwebtoken" \
--priority P1

mandor task create api-feature-xxxx "Login Endpoint" \
--goal "Accept credentials and return JWT..." \
--depends-on api-feature-xxxx-task-xxxx \
--priority P1

Real-time progress queries

mandor track feature api-feature-xxxx # See all tasks and status
mandor track task api-feature-xxxx-task-xxxx # See specific task details
`

Benefits:
- No file sync required
- Dependencies auto-validated
- Blocking tasks auto-detected
- Structured JSONL storage
- Queryable via CLI or JSON
- Works in CI/CD pipelines

$3

`bash


View all projects and their status

mandor status

Check a specific project

mandor status --project api

View feature dependencies and progress

mandor track project api

Create tasks with dependencies

mandor task create api-feature-xxxx "Task" \
--goal "..." \
--implementation-steps "..." \
--test-cases "..." \
--library-needs "..." \
--depends-on api-feature-xxxx-task-xxxx

See all feature tasks with status

mandor track feature api-feature-xxxx

Mark as done (auto-unblocks dependents)

mandor task update api-feature-xxxx-task-xxxx --status done

Verify dependents auto-transitioned to ready

mandor track feature api-feature-xxxx
`

$3

`bash


Create a bug issue

mandor issue create "Memory leak in auth handler" \
--project api \
--type bug \
--priority P0 \
--goal "Goroutine not cleaned up in token refresh handler..." \
--affected-files "src/handlers/auth.go|src/middleware/auth.go" \
--affected-tests "src/handlers/auth_test.go" \
--implementation-steps "Identify|Fix|Add tests|Verify" \
--library-needs "none"

View issue details

mandor issue detail api-issue-abc123

Start working on an issue

mandor issue update api-issue-abc123 --start

Mark as resolved

mandor issue update api-issue-abc123 --resolve

Mark as won't fix with reason

mandor issue update api-issue-abc123 --wontfix --reason "Working as intended"

See project issues with track

mandor track project api
`

$3

`bash


Set default priority

mandor config set default_priority P2

Enable strict mode

mandor config set strict_mode true

View all configuration

mandor config list

Get specific value

mandor config get default_priority

Reset to default

mandor config reset default_priority
`

---

Best Practices

$3

Project and feature IDs should be:
- Short but descriptive
- Lowercase with hyphens
- Consistent naming convention

`bash


Good

mandor project create user-auth
mandor feature create jwt-tokens

Avoid

mandor project create p1
mandor feature create f123
`

$3

Goals should include:
- What is being built/fixed
- Why it matters
- Technical requirements
- Acceptance criteria

`bash


Good

--goal "Implement JWT-based authentication with login and refresh flows for secure API access"

Avoid

--goal "Add authentication"
`

$3

Organize by scope:
- frontend, backend, fullstack
- cli, desktop, android, flutter, react-native, ios, swift

`bash
mandor feature create "Login UI" --project api --scope frontend
mandor feature create "Login API" --project api --scope backend
`

$3

Deep dependency chains (>5 levels) are hard to manage. Consider breaking into smaller features.

`bash


Good: tasks depend on other tasks in same feature

mandor task create api-feature-xxxx "Task B" \
--goal "..." \
--implementation-steps "..." \
--test-cases "..." \
--depends-on api-feature-xxxx-task-xxxx

Consider splitting if: task chains exceed 5 levels

`

$3

- Tasks: Feature work, implementation, refactoring
- Issues: Bugs, improvements, technical debt, security, performance

`bash


Feature work

mandor task create api-feature-xxxx "Add OAuth2" \
--goal "..." \
--implementation-steps "..." \
--test-cases "..." \
--library-needs "oauth2-lib"

Bug fix

mandor issue create "Fix auth timeout" --project api --type bug
`

$3

Always provide clear reasons when cancelling:

`bash
mandor task update api-feature-xxxx-task-xxxx --cancel --reason "Superseded by feature X"
mandor feature update api-feature-xxxx --project api --cancel --reason "Sticking with JWT, OAuth2 adds too much complexity"
`

$3

For flags accepting multiple values, use pipe separators:

`bash


Implementation steps

--implementation-steps "Step 1|Step 2|Step 3"

Test cases

--test-cases "Case 1|Case 2|Case 3"

Dependencies

--depends-on task-1|task-2|task-3
`

$3

Before making significant updates, preview with --dry-run:

`bash
mandor task update api-feature-xxxx-task-xxxx --status done --dry-run
mandor feature update api-feature-xxxx --project api --cancel --reason "..." --dry-run
`

$3

- Mark task done → dependents auto-transition to ready
- Mark issue resolved → dependents auto-transition to ready
- Manual block → must manually unblock

$3

Configure workspace defaults at the start:

`bash
mandor init "Project Name"
mandor config set default_priority P2
mandor config set strict_mode true
`

$3

`bash


Workspace overview

mandor status

Project summary

mandor status --project api

See feature progress

mandor track project api

See feature tasks

mandor track feature api-feature-xxxx

See task details

mandor track task api-feature-xxxx-task-xxxx
`

---

Troubleshooting

$3

Ensure mandor is in your PATH:

`bash
export PATH="$HOME/.local/bin:$PATH"
`

$3

Check the project ID and ensure you're in the correct workspace:

`bash
mandor status
`

$3

Verify the entity ID exists:

`bash
mandor track feature
mandor track project
`

$3

The project doesn't allow cross-project dependencies:

`bash


Check project config

mandor project detail

Create new project with cross-project enabled

mandor project create --name "..." --goal "..." --task-dep cross_project_allowed
`

$3

The transition isn't allowed by the state machine:

`bash


Tasks: pending → ready → in_progress → done

Features: draft → active → done

Issues: open → ready → in_progress → resolved

`

$3

Reopen the feature first:

`bash
mandor feature update --project --reopen
`

---




Configuration Keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| default_priority | string | P3 | Default priority for new entities (P0-P5) |
| strict_mode | boolean | false | Enable strict dependency validation |
| goal.lengths.project | integer | 500 | Min chars for project goal |
| goal.lengths.feature | integer | 300 | Min chars for feature goal |
| goal.lengths.task | integer | 500 | Min chars for task goal |
| goal.lengths.issue | integer | 200 | Min chars for issue goal |

---




File Structure

`
.mandor/
├── workspace.json # Workspace metadata
├── config.json # Workspace configuration
├── session-notes.jsonl # AI agent session progress notes (NDJSON)
└── projects/
└── /
├── project.json # Project metadata
├── features.jsonl # Feature records
├── tasks.jsonl # Task records
└── issues.jsonl # Issue records
`

Session Notes Format (session-notes.jsonl):
`json
{"timestamp":"2026-02-04T12:45:00Z","note":"Completed v0.4.4 release and testing"}
{"timestamp":"2026-02-04T14:20:00Z","note":"Started performance optimization - blocked on benchmarks"}
`

---




Support

- Issues: https://github.com/sanxzy/mandor/issues
- Documentation: /docs` directory
- Repository: https://github.com/sanxzy/mandor

---

Built for AI Agent Workflows