FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

$FLOWCTL --help
$FLOWCTL <command> --help   # e.g., $FLOWCTL task --help

# Check if .flow exists
$FLOWCTL detect --json

# Initialize (if needed)
$FLOWCTL init --json

# List everything (epics + tasks grouped)
$FLOWCTL list --json

# List all epics
$FLOWCTL epics --json

# List all tasks (or filter by epic/status)
$FLOWCTL tasks --json
$FLOWCTL tasks --epic fn-1-add-oauth --json
$FLOWCTL tasks --status todo --json

# View epic with all tasks
$FLOWCTL show fn-1-add-oauth --json
$FLOWCTL cat fn-1-add-oauth              # Spec markdown

# View single task
$FLOWCTL show fn-1-add-oauth.2 --json
$FLOWCTL cat fn-1-add-oauth.2            # Task spec

# What's ready to work on?
$FLOWCTL ready --epic fn-1-add-oauth --json

# Create task under existing epic
$FLOWCTL task create --epic fn-1-add-oauth --title "Fix bug X" --json

# Set task description and acceptance (combined, fewer writes)
$FLOWCTL task set-spec fn-1-add-oauth.2 --description /tmp/desc.md --acceptance /tmp/accept.md --json

# Or use stdin with heredoc (no temp file):
$FLOWCTL task set-description fn-1-add-oauth.2 --file - --json <<'EOF'
Description here
EOF

# Start working on task
$FLOWCTL start fn-1-add-oauth.2 --json

# Mark task done
echo "What was done" > /tmp/summary.md
echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > /tmp/evidence.json
$FLOWCTL done fn-1-add-oauth.2 --summary-file /tmp/summary.md --evidence-json /tmp/evidence.json --json

# Validate structure
$FLOWCTL validate --epic fn-1-add-oauth --json
$FLOWCTL validate --all --json

# All epics
$FLOWCTL epics --json

# All tasks
$FLOWCTL tasks --json

# Tasks for specific epic
$FLOWCTL tasks --epic fn-1-add-oauth --json

# Ready tasks for an epic
$FLOWCTL ready --epic fn-1-add-oauth --json

$FLOWCTL show fn-1-add-oauth.2 --json   # Metadata
$FLOWCTL cat fn-1-add-oauth.2           # Full spec

$FLOWCTL epic create --title "Epic title" --json
# Returns: {"success": true, "id": "fn-N-epic-title", ...}