chitra-goals — Goal Management CLI

Chitra-goals is the user-facing CLI for managing session goals. It wraps the deterministic goals store (goals.py) and provides subcommands for enrollment, status queries, closure, holds, and ask/resolution workflows.

Subcommands

set — Enroll a session

chitra-goals set \
  --session-ref agent-1 \
  --goal "Implement user authentication for the API" \
  --done-when "API login endpoint accepts username+password and returns JWT" \
  --source "operator:trey" \
  --open-ask "Retrieve current auth library version"

Creates or updates a goal. On first write, the goal is immutable (lane_id, enrolled_done_when, enrolled_at are write-once). On later writes, only status and reasoning can change.

Validates:

Goal text is ≥6 words.
done_when is non-empty and plain language.
Status is one of: open, working, paused, held, complete, abandoned, redirected, deferred.

get — Query a goal

chitra-goals get --session-ref agent-1

Returns the current goal record (JSON or human-readable format).

list — List all goals

chitra-goals list --format cards

Formats: markdown (default), box (fixed-width Unicode), cards (full sentences).

close — Complete a goal

chitra-goals close \
  --session-ref agent-1 \
  --delivered-item "API login endpoint at POST /auth/login" \
  --delivered-item "JWT token generation and validation" \
  --close-note "All tests passing. Ready for review."

Blocks closure if the inventory count is short. Performs inventory-check: counts delivered items against enrolled goal conditions. If discrepancies exist, reports them and asks for operator acknowledgement.

hold — Pause a goal

chitra-goals hold \
  --session-ref agent-1 \
  --reason "Awaiting design review feedback"

Sets status to "held". Rate-limit-guard may also hold a session automatically.

resume — Unpause a goal

chitra-goals resume --session-ref agent-1

Sets status back to "open" or "working".

redirect — Change goal mid-stream

chitra-goals redirect \
  --session-ref agent-1 \
  --goal "Implement user authentication (updated scope: add MFA)" \
  --done-when "API login and MFA endpoints working" \
  --reason "Operator request: add MFA requirement"

Updates the goal with a reason. The old goal is kept in history; the redirect reason is recorded.

now — Current status

chitra-goals now --session-ref agent-1

Quick view of current status (open/working/paused/complete/etc).

check — Lint a goal

chitra-goals check --goal "My goal text"

Validates goal text (≥6 words, plain language, clear done_when). No state change; pure validation.

guidance — Canonical decision references

chitra-goals guidance --working-dir /path/to/session

Looks up canonical decision documents for the working directory (from policy config). Helpful for operator reference during goal setting.

due — Due date management

chitra-goals due \
  --session-ref agent-1 \
  --set "2025-01-20T00:00:00Z"

Set or view goal due date.

ask / resolve-ask — Open asks workflow

# Record an open ask
chitra-goals add-ask \
  --session-ref agent-1 \
  --open-ask "Clarify API versioning strategy"

# Resolve it
chitra-goals resolve-ask \
  --session-ref agent-1 \
  --ask-index 0 \
  --resolution "API v1.0 frozen; new features go to v2 branch"

Track questions/blockers during goal work.

scan-asks — List all open asks

chitra-goals scan-asks

Fleet view of all unresolved asks across all goals.

roster — Operator board

chitra-goals roster --format box

Renders the operator-facing terminal board (goals + unreviewed artifacts). This is the main dashboard.

Common tasks

Enroll a new session:

chitra-goals set \
  --session-ref my-agent \
  --goal "Build a REST API for task management" \
  --done-when "POST /tasks creates a task; GET /tasks returns all tasks; DELETE /tasks/:id removes a task. All tests pass." \
  --source "operator:trey"

View the fleet board:

chitra-goals roster --format box

Close a completed goal:

chitra-goals close \
  --session-ref my-agent \
  --delivered-item "POST /tasks endpoint with validation" \
  --delivered-item "GET /tasks list endpoint" \
  --delivered-item "DELETE /tasks/:id endpoint" \
  --delivered-item "100 tests passing" \
  --close-note "Ready for production"

Check for linting issues:

chitra-goals check --goal "Add feature"  # Fails: <6 words
chitra-goals check --goal "Implement comprehensive user authentication system"  # Passes

Validation and constraints

Goal text: Minimum 6 words, plain language, no abbreviations.
Done_when: Non-empty, plain language, clear observable condition.
Status: One of 8 values (open, working, paused, held, complete, abandoned, redirected, deferred).
Lane ID: Immutable once set; prevents re-enrollment under a fresh session ref.
Enrolled anchors: First write creates enrolled_done_when and enrolled_at; later writes checked against these.

Output formats

json: Raw JSON goal record.
markdown: Markdown rendering (default for list).
box: Fixed-width Unicode table (good for terminals).
cards: Full sentences, one per line (good for dashboards).