@mandors/cli 0.3.7 → 0.3.9

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.7",
+  "version": "0.3.9",
   "description": "Event-based task manager CLI for AI agent workflows",
   "main": "npm/lib/index.js",
   "bin": {