@mandors/cli 0.3.6 → 0.3.9

package/.mandor/projects/test-proj/events.jsonl

@@ -0,0 +1,20 @@
+{"layer":"project","type":"created","id":"test-proj","by":"BUDISANTOSO","ts":"2026-02-02T10:28:51.466422Z"}
+{"layer":"feature","type":"created","id":"test-proj-feature-qgFb","by":"BUDISANTOSO","ts":"2026-02-02T10:28:59.0611Z"}
+{"layer":"task","type":"created","id":"test-proj-feature-qgFb-task-9fse","by":"BUDISANTOSO","ts":"2026-02-02T10:29:14.29734Z"}
+{"layer":"task","type":"ready","id":"test-proj-feature-qgFb-task-9fse","by":"system","ts":"2026-02-02T10:29:14.29734Z"}
+{"layer":"task","type":"created","id":"test-proj-feature-qgFb-task-u4Sb","by":"BUDISANTOSO","ts":"2026-02-02T10:29:16.665464Z"}
+{"layer":"task","type":"ready","id":"test-proj-feature-qgFb-task-u4Sb","by":"system","ts":"2026-02-02T10:29:16.665464Z"}
+{"layer":"task","type":"created","id":"test-proj-feature-qgFb-task-CPT4","by":"BUDISANTOSO","ts":"2026-02-02T10:29:19.350275Z"}
+{"layer":"task","type":"ready","id":"test-proj-feature-qgFb-task-CPT4","by":"system","ts":"2026-02-02T10:29:19.350275Z"}
+{"layer":"task","type":"updated","id":"test-proj-feature-qgFb-task-9fse","by":"BUDISANTOSO","ts":"2026-02-02T10:29:29.806828Z","changes":["status"]}
+{"layer":"task","type":"updated","id":"test-proj-feature-qgFb-task-u4Sb","by":"BUDISANTOSO","ts":"2026-02-02T10:29:33.953761Z","changes":["status"]}
+{"layer":"task","type":"updated","id":"test-proj-feature-qgFb-task-CPT4","by":"BUDISANTOSO","ts":"2026-02-02T10:29:38.227724Z","changes":["status"]}
+{"layer":"task","type":"updated","id":"test-proj-feature-qgFb-task-CPT4","by":"BUDISANTOSO","ts":"2026-02-02T10:29:38.249316Z","changes":["status"]}
+{"layer":"issue","type":"created","id":"test-proj-issue-Kj2y","by":"BUDISANTOSO","ts":"2026-02-02T10:29:50.229194Z"}
+{"layer":"issue","type":"ready","id":"test-proj-issue-Kj2y","by":"system","ts":"2026-02-02T10:29:50.229194Z"}
+{"layer":"issue","type":"created","id":"test-proj-issue-NDVP","by":"BUDISANTOSO","ts":"2026-02-02T10:29:52.962947Z"}
+{"layer":"issue","type":"ready","id":"test-proj-issue-NDVP","by":"system","ts":"2026-02-02T10:29:52.962947Z"}
+{"layer":"issue","type":"created","id":"test-proj-issue-39iV","by":"BUDISANTOSO","ts":"2026-02-02T10:29:56.23988Z"}
+{"layer":"issue","type":"ready","id":"test-proj-issue-39iV","by":"system","ts":"2026-02-02T10:29:56.23988Z"}
+{"layer":"issue","type":"updated","id":"test-proj-issue-Kj2y","by":"BUDISANTOSO","ts":"2026-02-02T10:30:01.070387Z","changes":["status"]}
+{"layer":"issue","type":"updated","id":"test-proj-issue-NDVP","by":"BUDISANTOSO","ts":"2026-02-02T10:30:01.082771Z","changes":["status"]}

package/.mandor/projects/test-proj/features.jsonl

@@ -0,0 +1 @@
+{"id":"test-proj-feature-qgFb","project_id":"test-proj","name":"Test Feature","goal":"A test feature for testing tasks and issues in development environment with proper workflow","priority":"P3","status":"draft","created_at":"2026-02-02T10:28:59.0611Z","updated_at":"2026-02-02T10:28:59.0611Z","created_by":"BUDISANTOSO","updated_by":"BUDISANTOSO"}

package/.mandor/projects/test-proj/issues.jsonl

@@ -0,0 +1,3 @@
+{"id":"test-proj-issue-39iV","project_id":"test-proj","name":"Issue Security 1","goal":"Security issue in test feature that needs immediate attention and comprehensive security testing","issue_type":"security","priority":"P1","status":"ready","affected_files":["file3.go"],"affected_tests":["test3.go"],"implementation_steps":["Security step 1"],"created_at":"2026-02-02T10:29:56.23988Z","last_updated_at":"2026-02-02T10:29:56.23988Z","created_by":"BUDISANTOSO","last_updated_by":"BUDISANTOSO"}
+{"id":"test-proj-issue-Kj2y","project_id":"test-proj","name":"Issue Bug 1","goal":"Bug in the test feature that needs fixing with proper analysis and solution steps for comprehensive testing","issue_type":"bug","priority":"P0","status":"in_progress","affected_files":["file1.go"],"affected_tests":["test1.go"],"implementation_steps":["Fix step 1","Fix step 2"],"created_at":"2026-02-02T10:29:50.229194Z","last_updated_at":"2026-02-02T10:30:01.070387Z","created_by":"BUDISANTOSO","last_updated_by":"BUDISANTOSO"}
+{"id":"test-proj-issue-NDVP","project_id":"test-proj","name":"Issue Improvement 1","goal":"Improve performance of the test feature with optimization strategies and benchmarking approaches for comprehensive testing","issue_type":"improvement","priority":"P2","status":"resolved","affected_files":["file2.go"],"affected_tests":["test2.go"],"implementation_steps":["Optimize step 1","Optimize step 2"],"created_at":"2026-02-02T10:29:52.962947Z","last_updated_at":"2026-02-02T10:30:01.082771Z","created_by":"BUDISANTOSO","last_updated_by":"BUDISANTOSO"}

package/.mandor/projects/test-proj/project.jsonl

@@ -0,0 +1,11 @@
+{
+  "id": "test-proj",
+  "name": "Test Project",
+  "goal": "A test project for CLI testing",
+  "status": "initial",
+  "strict": false,
+  "created_at": "2026-02-02T10:28:51.466422Z",
+  "updated_at": "2026-02-02T10:28:51.466422Z",
+  "created_by": "BUDISANTOSO",
+  "updated_by": "BUDISANTOSO"
+}

package/.mandor/projects/test-proj/schema.json

@@ -0,0 +1,29 @@
+{
+  "version": "mandor.v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "rules": {
+    "task": {
+      "dependency": "same_project_only",
+      "cycle": "disallowed"
+    },
+    "feature": {
+      "dependency": "cross_project_allowed",
+      "cycle": "disallowed"
+    },
+    "issue": {
+      "dependency": "same_project_only",
+      "cycle": "disallowed"
+    },
+    "priority": {
+      "levels": [
+        "P0",
+        "P1",
+        "P2",
+        "P3",
+        "P4",
+        "P5"
+      ],
+      "default": "P3"
+    }
+  }
+}

package/.mandor/projects/test-proj/tasks.jsonl

@@ -0,0 +1,3 @@
+{"id":"test-proj-feature-qgFb-task-9fse","feature_id":"test-proj-feature-qgFb","project_id":"test-proj","name":"Task 1","goal":"This is a comprehensive test task for testing the task summary command implementation in the CLI. The task involves comprehensive testing of all the features that were recently implemented. It should cover multiple scenarios including ready tasks, in-progress tasks, blocked tasks, pending tasks, and completed tasks. The implementation should handle all edge cases and error scenarios properly.\n\nThis task includes detailed testing of the markdown table output format to ensure proper alignment and formatting of all columns. The testing should verify that task IDs, names, priorities, and statuses are displayed correctly. It should also test filtering by priority levels and ensure that the output is properly sorted by creation date within each status group.\n\nThe task requires implementation of comprehensive error handling for invalid feature IDs and proper workspace initialization checks. The testing should cover scenarios where features don't exist, tasks don't exist, and various filter combinations. All error messages should be clear and helpful to the user.\n\nThe implementation should also include documentation and examples of how to use the new commands. This includes examples for each command type and explanation of the output format. The documentation should be clear and easy to follow for new users.","priority":"P3","status":"in_progress","implementation_steps":["Step 1","Step 2"],"test_cases":["Test 1","Test 2"],"derivable_files":["file1.go","file2.go"],"library_needs":["none"],"created_at":"2026-02-02T10:29:14.29734Z","updated_at":"2026-02-02T10:29:29.806828Z","created_by":"BUDISANTOSO","updated_by":"BUDISANTOSO"}
+{"id":"test-proj-feature-qgFb-task-u4Sb","feature_id":"test-proj-feature-qgFb","project_id":"test-proj","name":"Task 2","goal":"This is a comprehensive test task for testing the task summary command implementation in the CLI. The task involves comprehensive testing of all the features that were recently implemented. It should cover multiple scenarios including ready tasks, in-progress tasks, blocked tasks, pending tasks, and completed tasks. The implementation should handle all edge cases and error scenarios properly.\n\nThis task includes detailed testing of the markdown table output format to ensure proper alignment and formatting of all columns. The testing should verify that task IDs, names, priorities, and statuses are displayed correctly. It should also test filtering by priority levels and ensure that the output is properly sorted by creation date within each status group.\n\nThe task requires implementation of comprehensive error handling for invalid feature IDs and proper workspace initialization checks. The testing should cover scenarios where features don't exist, tasks don't exist, and various filter combinations. All error messages should be clear and helpful to the user.\n\nThe implementation should also include documentation and examples of how to use the new commands. This includes examples for each command type and explanation of the output format. The documentation should be clear and easy to follow for new users.","priority":"P0","status":"in_progress","implementation_steps":["Step 1","Step 2"],"test_cases":["Test 1","Test 2"],"derivable_files":["file1.go","file2.go"],"library_needs":["none"],"created_at":"2026-02-02T10:29:16.665464Z","updated_at":"2026-02-02T10:29:33.953761Z","created_by":"BUDISANTOSO","updated_by":"BUDISANTOSO"}
+{"id":"test-proj-feature-qgFb-task-CPT4","feature_id":"test-proj-feature-qgFb","project_id":"test-proj","name":"Task 3","goal":"This is a comprehensive test task for testing the task summary command implementation in the CLI. The task involves comprehensive testing of all the features that were recently implemented. It should cover multiple scenarios including ready tasks, in-progress tasks, blocked tasks, pending tasks, and completed tasks. The implementation should handle all edge cases and error scenarios properly.\n\nThis task includes detailed testing of the markdown table output format to ensure proper alignment and formatting of all columns. The testing should verify that task IDs, names, priorities, and statuses are displayed correctly. It should also test filtering by priority levels and ensure that the output is properly sorted by creation date within each status group.\n\nThe task requires implementation of comprehensive error handling for invalid feature IDs and proper workspace initialization checks. The testing should cover scenarios where features don't exist, tasks don't exist, and various filter combinations. All error messages should be clear and helpful to the user.\n\nThe implementation should also include documentation and examples of how to use the new commands. This includes examples for each command type and explanation of the output format. The documentation should be clear and easy to follow for new users.","priority":"P2","status":"done","implementation_steps":["Step 1","Step 2"],"test_cases":["Test 1","Test 2"],"derivable_files":["file1.go","file2.go"],"library_needs":["none"],"created_at":"2026-02-02T10:29:19.350275Z","updated_at":"2026-02-02T10:29:38.249316Z","created_by":"BUDISANTOSO","updated_by":"BUDISANTOSO"}

package/.mandor/workspace.json

@@ -0,0 +1,13 @@
+{
+  "id": "bPTh",
+  "name": "Mandor",
+  "version": "mandor.v1",
+  "schema_version": "mandor.v1",
+  "created_at": "2026-02-02T10:28:47.490328Z",
+  "last_updated_at": "2026-02-02T10:28:47.490328Z",
+  "created_by": "BUDISANTOSO",
+  "config": {
+    "default_priority": "P3",
+    "strict_mode": false
+  }
+}

package/README.md

@@ -1,12 +1,17 @@
 # Mandor - Event-Based Task Manager CLI for AI Agent Workflows
 
 <p align="center">
-  <strong>Deterministic JSONL output | Streaming-native architecture | Schema-driven task management</strong>
+  <strong>Stop writing markdown plans. Start shipping features with deterministic task tracking.</strong>
+</p>
+
+<p align="center">
+  <strong>Event-sourced | Dependency-aware | CLI-native | Built for AI agents</strong>
 </p>
 
 <p align="center">
   <a href="#installation">Installation</a> •
   <a href="#quick-start">Quick Start</a> •
+  <a href="#why-mandor">Why Mandor</a> •
   <a href="#core-concepts">Core Concepts</a> •
   <a href="#commands">Commands</a> •
   <a href="#examples">Examples</a>
@@ -14,14 +19,28 @@
 
 ---
 
+## 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 `events.jsonl`—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
+- **Event-Sourced**: Full audit trail of every status change
+
 ## Overview
 
 Mandor is a CLI tool for managing tasks, features, and issues in AI agent workflows:
 
-- **Event-Based Architecture**: All changes logged in `events.jsonl`
-- **JSONL Format**: Deterministic, append-only storage
-- **Dependency Tracking**: Automatic status based on dependencies
-- **Cross-Platform**: Go binary for macOS, Linux, Windows
+- **Event-Based Architecture**: All changes logged in `events.jsonl` with immutable timestamps
+- **JSONL Format**: Deterministic, append-only storage for reproducibility
+- **Dependency Tracking**: Automatic status transitions when dependencies complete
+- **Cross-Platform**: Go binary for macOS, Linux, Windows (arm64 & x64)
 
 ---
 
@@ -106,34 +125,72 @@ go build -o ./binaries/mandor ./cmd/mandor
 
 ```bash
 export MANDOR_ENV=development
-./binaries/mandor init --workspace-name "My Project"
+mandor init "My Project"
 ```
 
 ### 2. Create a Project
 
 ```bash
-./binaries/mandor project create api --name "API Development" \
-  --goal "Build REST API endpoints"
+mandor project create api --name "API Development" \
+  --goal "Build REST API service with authentication and endpoints"
 ```
 
 ### 3. Create a Feature
 
 ```bash
-./binaries/mandor feature create "Auth Feature" --project api \
-  --goal "Implement authentication system" \
+mandor feature create "Authentication" --project api \
+  --goal "Implement JWT-based authentication with login and refresh flows for secure API access" \
   --scope backend
 ```
 
-### 4. Create Tasks
+### 4. Create Tasks with Dependencies
 
 ```bash
-./binaries/mandor task create "JWT Parser" \
-  --feature api-feature-xxx \
-  --goal "Parse and validate JWT tokens" \
-  --implementation-steps "none" \
-  --test-cases "none" \
-  --derivable-files "none" \
-  --library-needs "none"
+# Create first task (no dependencies)
+mandor task create api-feature-xxx "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" \
+  --derivable-files "jwt_validator.go|jwt_test.go" \
+  --library-needs "golang-jwt" \
+  --priority P1
+
+# Create dependent task (depends on JWT Parser)
+mandor task create api-feature-xxx "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" \
+  --derivable-files "login_handler.go|login_test.go" \
+  --library-needs "none" \
+  --depends-on api-task-xxx-001 \
+  --priority P1
+```
+
+### 5. View Task Progress
+
+```bash
+# See all tasks in feature
+mandor task list api-feature-xxx
+
+# See tasks ready to work on
+mandor task ready api-feature-xxx
+
+# See blocked/waiting tasks
+mandor task blocked api-feature-xxx
+
+# See summary grouped by status
+mandor task summary api-feature-xxx
+```
+
+### 6. Mark Tasks Complete
+
+```bash
+# Get task ID from list
+mandor task update <task-id> --status in_progress
+mandor task update <task-id> --status done
+
+# Dependent tasks auto-transition to "ready"
+mandor task ready api-feature-xxx  # Now shows "Login Endpoint" as ready
 ```
 
 ---
@@ -193,52 +250,98 @@ mandor feature update <id> --project <id> --cancel --reason "Reason"
 ### Task Commands
 
 ```bash
-# Create a task
-mandor task create "Name" --feature <id> -g "Goal" \
-  --implementation-steps "step1|step2" \
-  --test-cases "test1|test2" \
-  --derivable-files "file1|file2" \
+# Create a task (positional arguments: feature_id, name)
+mandor task create <feature_id> "<name>" \
+  --goal "Task description (min 500 chars)" \
+  --implementation-steps "step1|step2|step3" \
+  --test-cases "test1|test2|test3" \
+  --derivable-files "file1.go|file2.go" \
   --library-needs "lib1|lib2" \
   [--priority <P0-P5>] \
   [--depends-on <task-id>]
 
-# List tasks
-mandor task list --feature <id> [--status <value>] [--priority <value>]
+# List tasks in a feature (positional argument: feature_id)
+mandor task list <feature_id> [--status <value>] [--priority <value>] [--json]
+
+# Show ready tasks (available to work on)
+mandor task ready <feature_id> [--priority <P0-P5>] [--json]
+
+# Show blocked tasks (waiting on dependencies)
+mandor task blocked <feature_id> [--priority <P0-P5>] [--json]
+
+# Show task summary (grouped by status)
+mandor task summary <feature_id>
 
 # Show task details
 mandor task detail <task-id> [--include-deleted] [--events] [--dependencies]
 
-# Update task
-mandor task update <id> [--status <value>] \
-  [--cancel --reason] [--reopen] \
-  [--depends <ids>] [--depends-add <ids>] [--depends-remove <ids>]
+# Update task status
+mandor task update <id> --status <value>
 
-# Complete a task (in_progress → done)
+# Transition task to work on it
 mandor task update <id> --status in_progress
+
+# Mark task complete (auto-unblocks dependents)
 mandor task update <id> --status done
+
+# Block task manually (external dependency)
+mandor task update <id> --status blocked --reason "Waiting on API response"
+
+# Cancel task
+mandor task update <id> --cancel --reason "Superseded by feature X"
+
+# Reopen cancelled task
+mandor task update <id> --reopen
 ```
 
 ### Issue Commands
 
 ```bash
 # Create an issue
-mandor issue create "Name" --project <id> -t <type> -g "Goal" \
-  --affected-files "file1" \
-  --affected-tests "test1" \
-  --implementation-steps "step1" \
+mandor issue create <project_id> "<name>" \
+  --type <type> \
+  --goal "Issue description (min 200 chars)" \
+  --affected-files "file1|file2" \
+  --affected-tests "test1|test2" \
+  --implementation-steps "step1|step2" \
   [--priority <P0-P5>] \
   [--depends-on <issue-id>]
 
-# List issues
-mandor issue list --project <id> [--status <value>] [--type <value>]
+# List issues in a project
+mandor issue list <project_id> [--status <value>] [--type <value>] [--json]
+
+# Show ready issues (available to fix)
+mandor issue ready <project_id> [--type <type>] [--priority <P0-P5>] [--json]
+
+# Show blocked issues (waiting on dependencies)
+mandor issue blocked <project_id> [--type <type>] [--priority <P0-P5>] [--json]
+
+# Show issue summary (grouped by status)
+mandor issue summary <project_id>
 
 # Show issue details
 mandor issue detail <issue-id> [--include-deleted]
 
-# Update issue
-mandor issue update <id> [--status <value>] [--start] [--resolve] \
-  [--wontfix --reason] [--reopen] \
-  [--depends-on <ids>]
+# Update issue status
+mandor issue update <id> --status <value>
+
+# Start working on an issue
+mandor issue update <id> --start
+
+# Mark issue resolved
+mandor issue update <id> --resolve
+
+# Mark issue as won't fix
+mandor issue update <id> --wontfix --reason "Working as intended"
+
+# Reopen a resolved/wontfix issue
+mandor issue update <id> --reopen
+
+# Block issue manually
+mandor issue update <id> --status blocked --reason "Waiting on infrastructure"
+
+# Cancel issue (duplicate/no longer relevant)
+mandor issue update <id> --cancel --reason "Duplicate of issue #123"
 ```
 
 ---
@@ -487,117 +590,238 @@ grep '"type":"status_changed"' .mandor/events.jsonl | wc -l
 ### Complete Feature Workflow
 
 ```bash
-# Setup
-mandor init --workspace-name "API Project"
-mandor project create api --name "API" --goal "Build REST API"
-mandor feature create "Auth" --project api --goal "Authentication" --scope backend
+# Initialize and create project
+export MANDOR_ENV=development
+mandor init "API Project"
+mandor project create api --name "REST API" --goal "Build production REST API with authentication"
 
-# Create tasks with dependencies
-mandor task create "JWT Parser" --feature auth-xxx \
-  -g "Parse JWT tokens" --implementation-steps "none" \
-  --test-cases "none" --derivable-files "none" --library-needs "none"
+# Create feature (structured epic)
+mandor feature create "Authentication" --project api \
+  --goal "Implement JWT-based auth with login, logout, and token refresh flows" \
+  --scope backend
 
-mandor task create "JWT Validator" --feature auth-xxx \
-  -g "Validate JWT tokens" --implementation-steps "none" \
-  --test-cases "none" --derivable-files "none" --library-needs "none" \
-  --depends-on jwt-parser-task-id
+# Create first task (no dependencies)
+mandor task create api-feature-xxx "JWT Parser" \
+  --goal "Parse and validate JWT tokens with signature verification and expiry checks" \
+  --implementation-steps "Import crypto library|Implement token parsing|Add signature validation|Handle expiry" \
+  --test-cases "Valid token accepted|Invalid signature rejected|Expired token rejected" \
+  --derivable-files "jwt_parser.go|jwt_parser_test.go" \
+  --library-needs "golang-jwt" \
+  --priority P1
+
+# Create dependent task
+mandor task create api-feature-xxx "JWT Validator" \
+  --goal "Create middleware to validate JWT tokens in incoming requests" \
+  --implementation-steps "Create middleware|Validate token|Check expiry|Return errors" \
+  --test-cases "Valid requests pass|Invalid requests rejected|Error responses correct" \
+  --derivable-files "auth_middleware.go|auth_middleware_test.go" \
+  --library-needs "none" \
+  --depends-on <jwt-parser-id> \
+  --priority P1
+
+# Create another dependent task
+mandor task create api-feature-xxx "Login Endpoint" \
+  --goal "Accept credentials and return JWT token pair with refresh token" \
+  --implementation-steps "Setup endpoint|Validate credentials|Generate JWT|Store refresh token|Return tokens" \
+  --test-cases "Valid creds return tokens|Invalid creds rejected|Tokens formatted correctly" \
+  --derivable-files "login_handler.go|login_handler_test.go" \
+  --library-needs "none" \
+  --depends-on <jwt-parser-id> \
+  --priority P1
+
+# View progress and blocking status
+mandor task list api-feature-xxx              # See all tasks
+mandor task ready api-feature-xxx             # Only JWT Parser is ready
+mandor task blocked api-feature-xxx           # Validator and Login waiting on Parser
+mandor task summary api-feature-xxx           # Grouped summary
 
 # Execute workflow
-mandor task update jwt-parser-id --status in_progress
-mandor task update jwt-parser-id --status done
+mandor task update <jwt-parser-id> --status in_progress
+mandor task update <jwt-parser-id> --status done
+
+# Now Validator and Login auto-transition to ready
+mandor task ready api-feature-xxx             # Both now ready to start
+
+# Work on dependent tasks
+mandor task update <jwt-validator-id> --status in_progress
+mandor task update <jwt-validator-id> --status done
 
-# Validator automatically becomes ready
-mandor task update jwt-validator-id --status in_progress
-mandor task update jwt-validator-id --status done
+mandor task update <login-endpoint-id> --status in_progress
+mandor task update <login-endpoint-id> --status done
 
-# Mark feature done
-mandor feature update auth-xxx --project api --status active
-mandor feature update auth-xxx --project api --status done
+# Mark feature complete
+mandor feature update api-feature-xxx --project api --status active
+mandor feature update api-feature-xxx --project api --status done
 ```
 
 ### Multi-Project Dependencies
 
 ```bash
-# Create projects with cross-project enabled
-mandor project create core --name "Core" --goal "Core library"
-mandor project create api --name "API" --goal "API layer" --task-dep cross_project_allowed
-
-# Create task in core
-mandor feature create lib --project core --goal "Core library"
-mandor task create "DB Connection" --feature lib-xxx \
-  -g "Database connection" --implementation-steps "none" \
-  --test-cases "none" --derivable-files "none" --library-needs "none"
+# Create projects with cross-project dependencies enabled
+mandor project create core --name "Core Library" \
+  --goal "Shared database and utility libraries"
+mandor project create api --name "API Service" \
+  --goal "REST API service" --task-dep cross_project_allowed
+
+# Create shared library feature and task
+mandor feature create "Database Layer" --project core \
+  --goal "Connection pool and query builder for database access" \
+  --scope backend
 
-# Create task in api depending on core task
-mandor feature create endpoints --project api --goal "API endpoints"
-mandor task create "User Endpoint" --feature endpoints-xxx \
-  -g "User API endpoint" --implementation-steps "none" \
-  --test-cases "none" --derivable-files "none" --library-needs "none" \
-  --depends-on db-connection-task-id
+mandor task create core-feature-xxx "Database Connection Pool" \
+  --goal "Implement connection pool with health checks and auto-reconnect" \
+  --implementation-steps "Create pool|Setup health check|Auto-reconnect|Connection limits" \
+  --test-cases "Pool creates connections|Health check works|Reconnect on failure" \
+  --derivable-files "db_pool.go|db_pool_test.go" \
+  --library-needs "pgx|pgxpool" \
+  --priority P0
+
+# Create API feature depending on core library task
+mandor feature create "User Endpoints" --project api \
+  --goal "User CRUD endpoints backed by database" \
+  --scope backend
 
-# Complete core task, api task becomes ready
-mandor task update db-connection-id --status in_progress
-mandor task update db-connection-id --status done
+mandor task create api-feature-xxx "User API Handler" \
+  --goal "Create REST endpoints for user CRUD operations" \
+  --implementation-steps "Setup handler|Implement GET|Implement POST|Implement DELETE" \
+  --test-cases "GET returns user|POST creates user|DELETE removes user" \
+  --derivable-files "user_handler.go|user_handler_test.go" \
+  --library-needs "gin|none" \
+  --depends-on <db-pool-task-id> \
+  --priority P0
+
+# Check progress
+mandor task list core-feature-xxx          # DB Pool ready to start
+mandor task blocked api-feature-xxx        # User Handler blocked on DB Pool
+
+# Complete core task, dependents auto-unblock
+mandor task update <db-pool-task-id> --status in_progress
+mandor task update <db-pool-task-id> --status done
+
+# API task now ready
+mandor task ready api-feature-xxx          # User Handler now ready
 ```
 
 ### Issue Tracking with Dependencies
 
 ```bash
-# Create blocking issues
-mandor issue create "Data Validation Bug" --project api -t bug \
-  -g "Fix data validation" --affected-files "validate.js" \
-  --affected-tests "validate_test.js" --implementation-steps "step1"
-
-mandor issue create "Cache Issue" --project api -t bug \
-  -g "Fix cache issue" --affected-files "cache.js" \
-  --affected-tests "cache_test.js" --implementation-steps "step1"
-
-# Create dependent issue
-mandor issue create "Database Crash" --project api -t bug \
-  -g "Fix crash" --affected-files "db.js" \
-  --affected-tests "db_test.js" --implementation-steps "step1" \
-  --depends-on data-validation-id|cache-issue-id
-
-# Resolve blocking issues
-mandor issue update data-validation-id --resolve
-mandor issue update cache-issue-id --resolve
-
-# Dependent issue automatically becomes ready
-mandor issue update database-crash-id --start
-mandor issue update database-crash-id --resolve
+# Create blocker issues
+mandor issue create api "Data Validation Bug" \
+  --type bug \
+  --goal "Fix data validation allowing invalid emails to pass through" \
+  --affected-files "validate.go|email_validator.go" \
+  --affected-tests "validate_test.go|email_validator_test.go" \
+  --implementation-steps "Add email regex|Add domain check|Add test cases" \
+  --priority P0
+
+mandor issue create api "Cache Consistency Issue" \
+  --type bug \
+  --goal "Fix race condition in cache invalidation causing stale data" \
+  --affected-files "cache.go|invalidation.go" \
+  --affected-tests "cache_test.go" \
+  --implementation-steps "Add mutex|Refactor invalidation|Add concurrency tests" \
+  --priority P0
+
+# Create dependent issue (depends on blockers)
+mandor issue create api "High Memory Usage in Production" \
+  --type bug \
+  --goal "Fix memory leak causing OOM errors in production due to cache and validation issues" \
+  --affected-files "main.go|memory.go" \
+  --affected-tests "memory_test.go" \
+  --implementation-steps "Profile memory|Identify leaks|Fix validation and cache" \
+  --depends-on <data-validation-bug-id>|<cache-issue-id> \
+  --priority P0
+
+# Check status
+mandor issue ready api          # Both blockers ready
+mandor issue blocked api        # Memory issue blocked
+
+# Resolve blocking issues (order doesn't matter)
+mandor issue update <data-validation-bug-id> --start
+mandor issue update <data-validation-bug-id> --resolve
+
+mandor issue update <cache-issue-id> --start
+mandor issue update <cache-issue-id> --resolve
+
+# Check progress
+mandor issue ready api          # Memory issue now ready
+mandor issue summary api        # See all status groups
+
+# Fix dependent issue
+mandor issue update <memory-issue-id> --start
+mandor issue update <memory-issue-id> --resolve
 ```
 
 ### Cancel and Reopen Workflow
 
 ```bash
-# Create feature and tasks
-mandor feature create "Experiment" --project api --goal "Try something"
-mandor task create "Try X" --feature experiment-xxx -g "Test X" \
-  --implementation-steps "none" --test-cases "none" \
-  --derivable-files "none" --library-needs "none"
+# Create experimental feature and tasks
+mandor feature create "OAuth2 Investigation" --project api \
+  --goal "Research OAuth2 integration options" \
+  --scope backend
 
-# Cancel the feature
-mandor feature update experiment-xxx --project api --cancel --reason "Not needed"
+mandor task create api-feature-xxx "Compare OAuth2 Libraries" \
+  --goal "Research and compare auth0, okta, and open-source options" \
+  --implementation-steps "Create comparison spreadsheet|Evaluate pros/cons|Estimate effort" \
+  --test-cases "Evaluation complete|Team consensus reached" \
+  --derivable-files "oauth2_comparison.md" \
+  --library-needs "none" \
+  --priority P2
+
+mandor task create api-feature-xxx "Proof of Concept" \
+  --goal "Build minimal OAuth2 integration demo" \
+  --implementation-steps "Setup oauth lib|Create login flow|Test flow" \
+  --test-cases "Login works|Token refresh works" \
+  --derivable-files "poc_oauth.go|poc_oauth_test.go" \
+  --library-needs "none" \
+  --priority P2
 
-# Cannot create new tasks in cancelled feature
-mandor task create "Try Y" --feature experiment-xxx -g "Test Y" \
-  --implementation-steps "none" --test-cases "none" \
-  --derivable-files "none" --library-needs "none"
-# Error: "Cannot create task for cancelled feature"
+# List tasks
+mandor task list api-feature-xxx             # Show feature tasks
 
-# Reopen the feature
-mandor feature update experiment-xxx --project api --reopen
+# Change requirements, decide not to pursue OAuth2
+mandor feature update api-feature-xxx --project api \
+  --cancel --reason "Sticking with JWT, OAuth2 adds too much complexity"
 
-# Can create tasks again
-mandor task create "Try Y" --feature experiment-xxx -g "Test Y" \
-  --implementation-steps "none" --test-cases "none" \
-  --derivable-files "none" --library-needs "none"
+# Try to create new task (fails)
+mandor task create api-feature-xxx "Integration Tests" \
+  --goal "Add integration tests" \
+  --implementation-steps "none" \
+  --test-cases "none" \
+  --derivable-files "none" \
+  --library-needs "none"
+# Error: "Cannot create task for cancelled feature"
+
+# Change mind - reopen the feature to continue research
+mandor feature update api-feature-xxx --project api --reopen
+
+# Can now create tasks again
+mandor task list api-feature-xxx             # Previous tasks still exist
+mandor task create api-feature-xxx "Hybrid Approach" \
+  --goal "Combine JWT with optional OAuth2 for third-party apps" \
+  --implementation-steps "Design hybrid flow|Implement dual auth|Test both flows" \
+  --test-cases "JWT still works|OAuth2 works|Both interoperable" \
+  --derivable-files "hybrid_auth.go" \
+  --library-needs "oauth2lib" \
+  --priority P3
 ```
 
 ---
 
 ## Best Practices
 
+### Mandor vs. Markdown Plan Files
+
+| Problem | Markdown Plans | Mandor |
+|---------|---|---|
+| Single source of truth | ❌ Scattered across multiple files | ✓ Centralized `events.jsonl` |
+| Dependency tracking | ❌ Manual, often wrong | ✓ Automatic status transitions |
+| Progress visibility | ❌ Requires manual updates | ✓ Real-time status queries |
+| Audit trail | ❌ Git history only | ✓ Immutable event log |
+| Blocking detection | ❌ Must review files | ✓ `mandor task blocked <id>` |
+| Schema validation | ❌ Free-form text | ✓ Enforced structure |
+| Automation | ❌ Parse text with regex | ✓ JSON queryable for scripts |
+
 ### 1. Use Meaningful IDs
 
 Project and feature IDs should be:
@@ -664,6 +888,54 @@ mandor config set default_priority P2
 mandor config set strict_mode true
 ```
 
+### 9. Stop Writing Markdown Plan Files
+
+Replace this workflow:
+
+```markdown
+# PLAN.md
+## Phase 1: Authentication
+- [ ] JWT parser (depends on cryptography)
+- [ ] Login endpoint (depends on JWT parser)
+- ...
+# Status: Last updated 3 days ago
+```
+
+With this:
+
+```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 "JWT Parser" --feature auth-xxx \
+  -g "Validate JWT tokens..." \
+  --implementation-steps "Step 1|Step 2" \
+  --test-cases "Test invalid tokens|Test expired" \
+  --library-needs "jsonwebtoken" \
+  --priority P1
+
+mandor task create "Login Endpoint" --feature auth-xxx \
+  -g "Accept credentials and return JWT..." \
+  --depends-on jwt-parser-id \
+  --priority P1
+
+# Real-time progress queries
+mandor task ready auth-xxx           # See what's available now
+mandor task blocked auth-xxx         # See what's waiting
+mandor task summary auth-xxx         # See grouped status
+```
+
+Benefits:
+- No file sync required
+- Dependencies auto-validated
+- Blocking tasks auto-detected
+- Reproducible state (`events.jsonl`)
+- Queryable via CLI or JSON
+- Works in CI/CD pipelines
+
 ---
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandors/cli",
-  "version": "0.3.6",
+  "version": "0.3.9",
   "description": "Event-based task manager CLI for AI agent workflows",
   "main": "npm/lib/index.js",
   "bin": {