@mandors/cli 0.6.0 → 0.6.2

package/README.md

@@ -1,626 +1,712 @@
-# Mandor - Deterministic Task Manager for AI Agent Workflows
+# Mandor - Deterministic Task Manager CLI for AI Agent Workflows
 
 <p align="center">
   <img src="logo.png" alt="Mandor Logo" width="600">
 </p>
 
 <p align="center">
-  <strong>Stop writing markdown plans that go stale.</strong>
+  <strong>Stop writing markdown plans. Start shipping features with deterministic task tracking.</strong>
 </p>
 
 <p align="center">
-  <strong>Deterministic task management with structured briefs, specifications, and blueprints.</strong>
-</p>
-
-<p align="center">
-  Gate-enforced | Dependency-aware | Structured storage | CLI-native
+  <strong>Dependency-aware | Structured storage | 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="#workflow">Workflow</a> •
+  <a href="#core-concepts">Core Concepts</a> •
   <a href="#commands">Commands</a> •
-  <a href="#best-practices">Best Practices</a>
+  <a href="#examples">Examples</a>
 </p>
 
 ---
 
 ## Why Mandor
 
-Traditional workflows scatter task state across markdown files, spreadsheets, and Slack. Dependencies are manual, status is fiction, and context is lost between sessions.
+**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**: Brief → Spec → Blueprint → Feature → Task pipeline
-- **Gate-Enforced Progression**: All three gates (brief read, spec read, session notes) required before starting work
-- **Automatic Dependency Resolution**: Mark task done → dependents auto-transition to ready
-- **Cross-Feature Dependencies**: Task A (Feature 1) can depend on Task B (Feature 2) with cascading unblocking
-- **Schema-Driven**: Enforce implementation steps, test cases, requirements upfront
+- **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)
 
 ---
 
-## Alternatives
 
-Mandor is one approach to deterministic task management. Other tools exist in this space:
+## Core Concepts
+
+### Entity Types
+
+| 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 |
+
+### Dependency Types
 
-- **Beads**: Git-backed issue tracker focusing on rapid iteration with minimal overhead
-  - GitHub: https://github.com/steveyegge/beads
+- **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
 
-- **OpenSpec**: Fluid, iterative specs with AI tool integration (Claude Code, Cursor, Copilot)
-  - GitHub: https://github.com/Fission-AI/OpenSpec
+### Status Transitions
+
+**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
 
-### Build from Source
+### Install with curl
 
 ```bash
-cd Mandor
-go build -o mandor ./cmd/mandor
-./mandor --help
+curl -fsSL https://raw.githubusercontent.com/sanxzy/mandor/main/scripts/install.sh | sh
+mandor --help
 ```
 
-### Install to PATH
+### Install from npm
 
 ```bash
-go build -o ~/.local/bin/mandor ./cmd/mandor
-export PATH="$HOME/.local/bin:$PATH"
+npm install -g @mandors/cli
 mandor --help
 ```
 
 ---
 
+
 ## Quick Start
 
 ### 1. Initialize Workspace
 
 ```bash
-mandor init -y
+mandor init "My Project"
 ```
 
-### 2. Create Project
+### 2. Create a Project
 
 ```bash
-mandor project create api --name "API Service" \
-  --goal "REST API with JWT authentication, user management, and data endpoints"
+mandor project create api --name "API Development" \
+  --goal "Build REST API service with authentication and endpoints"
 ```
 
-### 3. Create Brief (Project Intent & Capabilities)
+### 3. Create a Feature
 
 ```bash
-mandor brief create -p api \
-  --name "JWT Authentication" \
-  --why "Need secure, stateless authentication for API endpoints" \
-  --capabilities "jwt-auth:JWT login flow|refresh:Token refresh endpoint" \
-  --tech-stack "golang,jwt,redis"
+mandor feature create "Authentication" --project api \
+  --goal "Implement JWT-based authentication with login and refresh flows for secure API access" \
+  --scope backend
 ```
 
-Creates: `jwt-auth` (brief ID)
-
-### 4. Create Spec (Requirements with IAE Scenarios)
+### 4. Create Tasks with Dependencies
 
 ```bash
-mandor spec create -p api \
-  --capability jwt-auth \
-  --summary "JWT authentication specification" \
-  --requirements "Setup:Enable login:Import JWT lib|Validate:Verify token:Parse JWT|Refresh:Update token:Issue new JWT"
-```
+# 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
 
-Creates: `jwt-auth-spec` (spec ID with auto-generated requirement IDs: req-0001, req-0002, etc.)
+# 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
+```
 
-### 5. Create Blueprint (Technical Architecture)
+### 5. View Task Progress
 
 ```bash
-mandor blueprint create -p api \
-  --brief jwt-auth \
-  --problem "Secure API authentication without server-side session state" \
-  --decisions "Use JWT for stateless auth|HTTP-only cookies for token storage|Refresh tokens on expiry" \
-  --goals-in-scope "Authentication,Authorization,Token refresh"
-```
+# See all tasks in feature with visualization
+mandor track feature api-feature-xxxx
 
-Creates: `api-blueprint` (blueprint ID)
+# Get task details
+mandor task detail <task-id>
+```
 
-### 6. Create Feature (from Spec)
+### 6. Mark Tasks Complete
 
 ```bash
-mandor feature create "JWT Authentication" -p api \
-  --capability jwt-auth \
-  --spec-id jwt-auth-spec \
-  --scope backend \
-  -g "Implement JWT-based authentication with login flow, token validation, and refresh mechanism"
+# Get task ID from track output
+mandor task update <task-id> --status in_progress
+mandor task update <task-id> --status done
+
+# Dependent tasks auto-transition to "ready"
+mandor track feature api-feature-xxxx  # Now shows "Login Endpoint" as ready
 ```
 
-Creates: `jwt-tokens` (feature ID, one-to-one mapping to spec-id)
+---
 
-### 7. Create Tasks (with IAE Scenarios)
 
-```bash
-# Task 1: Setup JWT Library
-mandor task create jwt-tokens "Setup JWT Library" \
-  --spec-id jwt-auth-spec \
-  --iae-scenarios "req-0001:scenario-0001|req-0001:scenario-0002" \
-  -g "Configure golang-jwt library with crypto setup and validation" \
-  --implementation-steps "Import library|Configure settings|Add crypto|Add validation" \
-  --test-cases "JWT creates|JWT validates|JWT signature verifies" \
-  --library-needs "golang-jwt"
-```
+## Commands Reference
 
-Creates: `jwt-tokens-task-a7K2` (status=ready, all gates=false)
+### Workspace Commands
 
 ```bash
-# Task 2: Token Validation (depends on Task 1)
-mandor task create jwt-tokens "Token Validation Middleware" \
-  --spec-id jwt-auth-spec \
-  --iae-scenarios "req-0002:scenario-0001" \
-  --depends-on jwt-tokens-task-a7K2 \
-  -g "Implement middleware to validate JWT tokens on all protected endpoints" \
-  --implementation-steps "Create middleware|Extract token|Validate|Return errors" \
-  --test-cases "Valid passes|Expired rejects|Invalid rejects"
-```
+# Initialize a new workspace
+mandor init [--workspace-name <name>] [-y]
 
-Creates: `jwt-tokens-task-b3M8` (status=blocked, waiting for task-a7K2)
+# View workspace and project status
+mandor status [--project <id>] [--summary] [--json]
 
-### 8. Track Progress
+# Manage configuration
+mandor config get <key>
+mandor config set <key> <value>
+mandor config list
+mandor config reset <key>
 
-```bash
-# See feature with all tasks
-mandor track feature jwt-tokens
-```
+# Display all commands and best practices
+mandor populate
+
+# Show version
+mandor version
 
-Output shows:
-- Task 1: status=ready, gates=false
-- Task 2: status=blocked (waiting for Task 1)
+# Generate shell completions
+mandor completion [bash|zsh|fish]
 
-### 9. Set Gates & Start Work
+# AI-assisted documentation
+mandor ai --help
+```
+
+### Track Commands
 
 ```bash
-# Read brief, spec, and session notes first
-# Then set gates for Task 1:
-mandor task set-gate jwt-tokens-task-a7K2 --is-read-brief
-mandor task set-gate jwt-tokens-task-a7K2 --is-read-spec
-mandor task set-gate jwt-tokens-task-a7K2 --is-read-session-notes
+# Track workspace status
+mandor track
 
-# Transition to in_progress (requires all gates=true)
-mandor task update jwt-tokens-task-a7K2 --status in_progress
+# Track project status
+mandor track project <project-id>
 
-# Work on implementation...
+# Track feature with tasks
+mandor track feature <feature-id> [--verbose]
 
-# Mark complete
-mandor task update jwt-tokens-task-a7K2 --status done
+# Track specific task
+mandor track task <task-id>
 
-# Task 2 automatically transitions: blocked → ready
-mandor track feature jwt-tokens  # Now shows Task 2 as ready
+# Track issue
+mandor track issue <issue-id>
 ```
 
-### 10. Repeat for Task 2
+### Session Commands
 
 ```bash
-# Set gates for Task 2
-mandor task set-gate jwt-tokens-task-b3M8 --is-read-brief
-mandor task set-gate jwt-tokens-task-b3M8 --is-read-spec
-mandor task set-gate jwt-tokens-task-b3M8 --is-read-session-notes
+# Add a progress note (AI agents use this to track work)
+mandor session note "Completed v0.4.4 release and testing"
 
-# Start work
-mandor task update jwt-tokens-task-b3M8 --status in_progress
+# Read recent session notes (last 50 entries by default)
+mandor session note --read
+
+# Read more notes with offset
+mandor session note --read --offset 100
 ```
 
----
+### Project Commands
 
-## Workflow
+```bash
+# Create a project
+mandor project create <id> --name <name> --goal <goal> [OPTIONS]
 
-### Complete Pipeline
+# Show project details
+mandor project detail <project-id>
 
+# Update project
+mandor project update <project-id> [--name <name>] [--goal <goal>] [--status <status>]
 ```
-1. Brief (Intent & Capabilities)
-   ↓
-2. Spec (Requirements & IAE Scenarios)
-   ↓
-3. Blueprint (Architecture Decisions)
-   ↓
-4. Feature (Spec Mapping)
-   ↓
-5. Task (Work Items with IAE References)
-```
-
-### Gate Enforcement
 
-Every task has three read gates:
-- **IsReadBrief**: Have you read the Brief?
-- **IsReadSpec**: Have you read the Spec?
-- **IsReadSessionNotes**: Have you read session notes?
+### Feature Commands
 
-**All three gates MUST be true before ready → in_progress transition.**
-
-Gates are NOT required for:
-- ready → cancelled
-- in_progress → done
-- blocked → ready (auto-transition)
+```bash
+# Create a feature
+mandor feature create <name> --project <id> --goal <goal> [--scope <scope>] [--priority <priority>]
 
-### Dependency Auto-Resolution
+# List features
+mandor feature list --project <id>
 
-Tasks with `--depends-on`:
-- Auto-assigned `status=blocked` on creation
-- Stay blocked until ALL dependencies are `done`
-- Auto-transition `blocked → ready` when dependencies complete
-- Works cross-feature (Task A in Feature 1 depends on Task B in Feature 2)
-- Cascading: Task A done → unblocks Task B → Task B done → unblocks Task C
+# Show feature details
+mandor feature detail <feature-id> --project <id>
 
----
+# Update feature
+mandor feature update <feature-id> --project <id> [--name <text>] [--goal <goal>] [--scope <scope>] [--priority <priority>] [--status <status>] [--depends <ids>] [--cancel --reason <text>] [--reopen] [--dry-run]
+```
 
-## Commands
+### Task Commands
 
-### Essential Three Commands
+```bash
+# Create a task
+mandor task create <feature_id> <name> --goal <goal> \
+  --implementation-steps <steps> --test-cases <cases> \
+  --derivable-files <files> --library-needs <libs> \
+  [--priority <priority>] [--depends-on <ids>]
 
-#### 1. mandor populate
-View all available commands and usage instructions.
+# Show task details
+mandor task detail <task-id>
 
-```bash
-mandor populate                 # Full reference
-mandor populate | grep "brief"  # Find relevant sections
+# Update task
+mandor task update <task-id> [--name <text>] [--goal <goal>] [--priority <priority>] \
+  [--status <status>] [--depends-add <ids>] [--depends-remove <ids>] [--cancel --reason <text>] [--dry-run]
 ```
 
-#### 2. mandor track
-Check status of workspace, projects, features, tasks, issues.
+### Issue Commands
 
 ```bash
-mandor track                        # Workspace overview
-mandor track project <project-id>   # Project features
-mandor track feature <feature-id>   # Feature with tasks
-mandor track task <task-id>         # Task with gate status
-mandor track task <task-id> --json  # Machine-readable
-```
+# Create an issue
+mandor issue create <name> --project <id> --type <type> --goal <goal> \
+  --affected-files <files> --affected-tests <tests> \
+  --implementation-steps <steps> [--priority <priority>] [--depends-on <ids>] [--library-needs <libs>]
 
-#### 3. mandor session note
-Record and read session progress (for AI agents).
+# Show issue details
+mandor issue detail <issue-id> --project <id>
 
-```bash
-mandor session note "Completed Task 1 and dependencies"
-mandor session note --read           # Show last 50 notes
-mandor session note --read --offset 100  # Show more notes
+# Update issue
+mandor issue update <issue-id> [--name <text>] [--goal <goal>] [--priority <priority>] \
+  [--type <type>] [--status <status>] [--start] [--resolve] [--wontfix] [--reason <text>] [--cancel --reason <text>] [--dry-run]
 ```
 
-### Full Command Reference
-
-**For complete command documentation, run:**
+### AI Commands
 
 ```bash
-mandor populate     # Shows all commands with examples
-mandor -h          # Shows available commands
-mandor <cmd> -h    # Shows specific command help
+# AI-assisted documentation generation
+mandor ai agents
+mandor ai claude
 ```
 
-### Quick Command List
-
-| Category | Commands |
-|----------|----------|
-| **Workspace** | `init`, `config` |
-| **Project** | `create`, `detail`, `update`, `delete`, `reopen` |
-| **Brief** | `create`, `read`, `update`, `delete`, `validate` |
-| **Spec** | `create`, `detail`, `update`, `delete`, `validate` |
-| **Blueprint** | `create`, `detail`, `update`, `delete`, `validate` |
-| **Feature** | `create`, `detail`, `update`, `delete` |
-| **Task** | `create`, `detail`, `set-gate`, `read-gates`, `update` |
-| **Issue** | `create`, `detail`, `update` |
-| **Track** | `track` (workspace\|project\|feature\|task\|issue) |
-| **Session** | `session note` |
-
 ---
 
-## Best Practices
 
-### 1. Follow the Complete Workflow
+## Common Workflows
 
-Brief → Spec → Blueprint → Feature → Task
+### Replace This (Markdown Plan Files)
 
-Don't skip steps. Each phase builds context for the next.
+```markdown
+# PLAN.md
+## Phase 1: Authentication
+- [ ] JWT parser (depends on cryptography)
+- [ ] Login endpoint (depends on JWT parser)
+- [ ] Refresh token (depends on JWT parser)
 
-### 2. Write Comprehensive Briefs
+Status: Last updated 3 days ago (probably stale!)
+```
 
-Include:
-- Clear problem statement and motivation
-- Well-defined capabilities with descriptions
-- Technical stack that will be used
-- Affected systems and dependencies
+### With This (Mandor)
 
 ```bash
-mandor brief create -p api \
-  --name "Authentication" \
-  --why "Secure stateless API authentication" \
-  --capabilities "login:User login|tokens:Token management" \
-  --tech-stack "golang,jwt,postgres"
-```
+# Create structured plan
+mandor feature create "Authentication" --project api \
+  --goal "Implement JWT and login endpoints" \
+  --scope backend
 
-### 3. Detailed Specs with IAE Scenarios
+# 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
 
-Create specs with Intent-Action-Expectation scenarios:
+mandor task create api-feature-xxxx "Login Endpoint" \
+  --goal "Accept credentials and return JWT..." \
+  --depends-on api-feature-xxxx-task-xxxx \
+  --priority P1
 
-```bash
-mandor spec create -p api \
-  --capability login \
-  --summary "Login specification" \
-  --requirements "Login:User enters creds:Check password|Token:Generate JWT:Return token|Refresh:Extend session:Issue new token"
+# 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
 ```
 
-Specs become reference documents for tasks and gates.
+**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
 
-### 4. Link Tasks to Spec Requirements
-
-Tasks reference specific requirement-scenario pairs:
+### Dependency Management
 
 ```bash
-mandor task create feature-id "Implement Login" \
-  --spec-id spec-id \
-  --iae-scenarios "req-0001:scenario-0001|req-0002:scenario-0001"
-```
-
-Traces implementation back to requirements.
+# View all projects and their status
+mandor status
 
-### 5. Gate Enforcement Discipline
+# Check a specific project
+mandor status --project api
 
-Always follow the gate workflow:
+# View feature dependencies and progress
+mandor track project api
 
-1. Read Brief thoroughly
-2. Read Spec with requirements
-3. Read session notes from previous work
-4. Set all three gates
-5. Transition to in_progress
-6. Implement
-7. Mark done (auto-unblocks dependents)
+# 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
 
-```bash
-# Check task status
-mandor track task <task-id>
+# See all feature tasks with status
+mandor track feature api-feature-xxxx
 
-# Set gates
-mandor task set-gate <task-id> --is-read-brief
-mandor task set-gate <task-id> --is-read-spec
-mandor task set-gate <task-id> --is-read-session-notes
+# Mark as done (auto-unblocks dependents)
+mandor task update api-feature-xxxx-task-xxxx --status done
 
-# Start work
-mandor task update <task-id> --status in_progress
+# Verify dependents auto-transitioned to ready
+mandor track feature api-feature-xxxx
 ```
 
-### 6. Dependency Management
-
-Create dependent tasks with clear relationships:
+### Issue Tracking
 
 ```bash
-# Task A (no dependencies)
-mandor task create feature-id "Task A" \
-  --spec-id spec-id \
-  --iae-scenarios "req-0001:scenario-0001" \
-  -g "..." \
-  --implementation-steps "s1|s2" \
-  --test-cases "t1|t2"
+# 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"
 
-# Task B (depends on Task A)
-mandor task create feature-id "Task B" \
-  --spec-id spec-id \
-  --iae-scenarios "req-0002:scenario-0001" \
-  --depends-on <task-a-id> \
-  -g "..." \
-  --implementation-steps "s1|s2" \
-  --test-cases "t1|t2"
-```
+# View issue details
+mandor issue detail api-issue-abc123
 
-Task B auto-blocks until Task A is done.
+# Start working on an issue
+mandor issue update api-issue-abc123 --start
 
-### 7. Configuration for Your Team
+# Mark as resolved
+mandor issue update api-issue-abc123 --resolve
 
-Set defaults early, rarely change:
+# 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
+```
+
+### Configuration
 
 ```bash
+# Set default priority
 mandor config set default_priority P2
+
+# Enable strict mode
 mandor config set strict_mode true
-mandor config set goal.lengths.task 500
+
+# View all configuration
+mandor config list
+
+# Get specific value
+mandor config get default_priority
+
+# Reset to default
+mandor config reset default_priority
 ```
 
-### 8. Document Status Changes
+---
+
+
+## Best Practices
+
+### 1. Use Meaningful IDs
 
-Always explain why you're cancelling or changing status:
+Project and feature IDs should be:
+- Short but descriptive
+- Lowercase with hyphens
+- Consistent naming convention
 
 ```bash
-mandor task update <task-id> --status cancelled \
-  --reason "Superseded by feature X"
+# Good
+mandor project create user-auth
+mandor feature create jwt-tokens
+
+# Avoid
+mandor project create p1
+mandor feature create f123
 ```
 
-### 9. Use Pipe Separators for Lists
+### 2. Write Clear Goals (min char requirement enforced)
+
+Goals should include:
+- What is being built/fixed
+- Why it matters
+- Technical requirements
+- Acceptance criteria
 
 ```bash
---implementation-steps "Step 1|Step 2|Step 3"
---test-cases "Test 1|Test 2|Test 3"
---iae-scenarios "req-0001:scenario-0001|req-0002:scenario-0001"
---depends-on "task-1|task-2|task-3"
+# Good
+--goal "Implement JWT-based authentication with login and refresh flows for secure API access"
+
+# Avoid
+--goal "Add authentication"
 ```
 
-### 10. Track Regularly Before Starting
+### 3. Use Scopes for Features
 
-Always check status first:
+Organize by scope:
+- `frontend`, `backend`, `fullstack`
+- `cli`, `desktop`, `android`, `flutter`, `react-native`, `ios`, `swift`
 
 ```bash
-mandor track feature <feature-id>   # See all task states
-mandor track task <task-id>         # Check gate status and dependencies
+mandor feature create "Login UI" --project api --scope frontend
+mandor feature create "Login API" --project api --scope backend
 ```
 
-### 11. AI Agent Session Management
+### 4. Keep Dependencies Shallow
 
-Log your progress between sessions:
+Deep dependency chains (>5 levels) are hard to manage. Consider breaking into smaller features.
 
 ```bash
-# End of session
-mandor session note "Completed task setup and testing, next: validation middleware"
+# 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
 
-# Start of session
-mandor session note --read  # See what was done
+# Consider splitting if: task chains exceed 5 levels
 ```
 
----
+### 5. Use Issues for Bugs, Tasks for Features
 
-## Status Transitions
+- **Tasks**: Feature work, implementation, refactoring
+- **Issues**: Bugs, improvements, technical debt, security, performance
 
-### Task Lifecycle
+```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
 ```
-New (with depends-on)          New (no depends)
-    ↓                              ↓
-blocked                          ready
-    ↓                              ↓
-    └──────→ ready ←──────┐        │
-             ↓  ↑          │       │
-    in_progress │          │       │
-             ↓  │          │       │
-           done ├──cancelled│──────┤
-                │          │       │
-                └──────────┴───────┘
+
+### 6. Document Cancellation Reasons
+
+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"
 ```
 
-**Rules:**
-- New task without `--depends-on`: status=ready, all gates=false
-- New task with `--depends-on`: status=blocked
-- blocked → ready: auto-transition when dependencies done
-- ready → in_progress: requires all three gates=true
-- ready → cancelled: allowed without gates
-- in_progress → done: allowed without gates
-- done: immutable, no transitions out
-- Error messages show which gates are unmet
+### 7. Use Pipe Separators For Lists
 
----
+For flags accepting multiple values, use pipe separators:
 
-## File Structure
+```bash
+# Implementation steps
+--implementation-steps "Step 1|Step 2|Step 3"
 
-```
-.mandor/
-├── workspace.json          # Workspace metadata
-├── config.json             # Configuration
-├── session-notes.jsonl     # AI session progress (NDJSON)
-└── projects/
-    └── <project-id>/
-        ├── project.json
-        ├── briefs/
-        │   └── <brief-id>.md          # Brief document
-        ├── specs/
-        │   └── <spec-id>.md           # Spec with requirements
-        ├── blueprints.jsonl           # Blueprint records
-        ├── features.jsonl             # Feature records
-        ├── tasks.jsonl                # Task records
-        └── issues.jsonl               # Issue records
-```
+# Test cases
+--test-cases "Case 1|Case 2|Case 3"
 
----
+# Dependencies
+--depends-on task-1|task-2|task-3
+```
 
-## Configuration
+### 8. Use --dry-run Before Major Changes
 
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `default_priority` | string | P3 | Default priority for new entities (P0-P5) |
-| `strict_mode` | boolean | false | Enable strict 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 |
+Before making significant updates, preview with `--dry-run`:
 
 ```bash
-mandor config list                                  # Show all
-mandor config get default_priority                  # Get one
-mandor config set default_priority P2               # Set one
-mandor config reset default_priority                # Reset to default
+mandor task update api-feature-xxxx-task-xxxx --status done --dry-run
+mandor feature update api-feature-xxxx --project api --cancel --reason "..." --dry-run
 ```
 
----
+### 9. Dependency Auto-Resolution
 
-## Troubleshooting
+- Mark task done → dependents auto-transition to ready
+- Mark issue resolved → dependents auto-transition to ready
+- Manual block → must manually unblock
+
+### 10. Configure Early, Rarely Change
 
-### Gate Transition Error
+Configure workspace defaults at the start:
 
-**Error:** "Cannot transition to in_progress: gates not set"
+```bash
+mandor init "Project Name"
+mandor config set default_priority P2
+mandor config set strict_mode true
+```
 
-**Solution:** Set all three gates before transitioning
+### 11. Review Status Regularly
 
 ```bash
-mandor track task <task-id>  # Check which gates are false
+# Workspace overview
+mandor status
 
-mandor task set-gate <task-id> --is-read-brief
-mandor task set-gate <task-id> --is-read-spec
-mandor task set-gate <task-id> --is-read-session-notes
+# Project summary
+mandor status --project api
 
-mandor task update <task-id> --status in_progress
+# 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
 ```
 
-### Task Blocked by Dependencies
+---
 
-**Error:** "Task is blocked by dependencies"
 
-**Solution:** Complete all blocking tasks first
+## Troubleshooting
 
-```bash
-mandor track task <task-id>  # See which tasks are blocking
+### "Command not found"
 
-# Complete each blocking task
-mandor task update <blocking-task-id> --status done
+Ensure mandor is in your PATH:
 
-# Dependent task auto-transitions to ready
-mandor track task <task-id>
+```bash
+export PATH="$HOME/.local/bin:$PATH"
 ```
 
-### Feature Not Found
-
-**Error:** "Feature not found" or "Entity not found"
+### "Project not found"
 
-**Solution:** Verify ID and check workspace
+Check the project ID and ensure you're in the correct workspace:
 
 ```bash
-mandor track project <project-id>  # List all features
-mandor track feature <feature-id>  # Check if exists
+mandor status
 ```
 
----
+### "Entity not found"
+
+Verify the entity ID exists:
+
+```bash
+mandor track feature <feature-id>
+mandor track project <project-id>
+```
 
-## Development
+### "Cross-project dependency detected"
 
-### Build
+The project doesn't allow cross-project dependencies:
 
 ```bash
-cd Mandor
-go build -o mandor ./cmd/mandor
+# Check project config
+mandor project detail <project-id>
+
+# Create new project with cross-project enabled
+mandor project create <id> --name "..." --goal "..." --task-dep cross_project_allowed
 ```
 
-### Run Tests
+### "Invalid status transition"
+
+The transition isn't allowed by the state machine:
 
 ```bash
-go test ./...
+# Tasks: pending → ready → in_progress → done
+# Features: draft → active → done
+# Issues: open → ready → in_progress → resolved
 ```
 
-### View All Commands
+### "Cannot create task for cancelled feature"
+
+Reopen the feature first:
 
 ```bash
-./mandor --help
-./mandor populate  # Full reference with examples
+mandor feature update <feature-id> --project <project-id> --reopen
 ```
 
 ---
 
-## Key Features
 
-✓ **Structured Workflow**: Brief → Spec → Blueprint → Feature → Task
-✓ **Gate Enforcement**: Three read gates required before starting work
-✓ **Dependency Tracking**: Auto-blocking and auto-unblocking with cascading
-✓ **Cross-Feature Dependencies**: Tasks can depend across feature boundaries
-✓ **Session Tracking**: Session notes for AI agent progress
-✓ **CLI-Native**: Terminal, scripts, CI/CD pipelines
-✓ **Deterministic**: Single source of truth in JSONL files
-✓ **Auditable**: Full change history
+## 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-id>/
+        ├── 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
 
-- **Documentation**: Run `mandor populate` for complete command reference
-- **Help**: `mandor <command> --help` for any command
-- **Repository**: https://github.com/budisantoso/mandor
+- Issues: https://github.com/sanxzy/mandor/issues
+- Documentation: `/docs` directory
+- Repository: https://github.com/sanxzy/mandor
 
 ---
 
+
 **Built for AI Agent Workflows**