valerie

valerie — Task and Todo Management

Valerie manages tasks and todos using a configured backend (doob or sqlite). Valerie is the only skill that should talk to doob or run the GitHub issue sync loop. Other skills should use handoff-db/SQLite plus transient HANDOFF YAML only. Before any todo workflow, run the setup check. Then handle one of five workflows: direct CRUD, structured-source ingestion (council reports, HANDOFF files), HANDOFF cleanup/write-back, and audit/reconciliation. For HANDOFF sources, prefer the shared handoff-reconcile script over hand-written doob commands.

Default active-work loop:

1. Sync GitHub issues into doob
2. Read HANDOFF files as short-lived context for still-open work
3. Update issue/todo state in doob
4. Sync doob back to GitHub issues

HANDOFF files are not the backlog system. Active items should not retain closed work after sync, but the log section remains durable and should keep one-line completion records.

Setup Check (run first, every session)

Resolve the config file:

<plugin-cache-dir>/atelier/<version>/.claude-plugin/valerie.local.yaml

If the file does not exist, run the setup prompt before any todo operation:

valerie is not configured. Run setup now? [Y/n]

If yes — detect the user's shell ($SHELL) and run the appropriate setup script:

# sh
sh <plugin-cache>/valerie/<version>/skills/valerie/helpers/setup.sh

# nu (if $SHELL contains nu)
nu <plugin-cache>/valerie/<version>/skills/valerie/helpers/setup.nu

The script writes .claude-plugin/valerie.local.yaml:

backend: doob | sqlite
shell: sh | nu
configured: YYYY-MM-DD

If no — skip setup and assume backend: doob, shell: sh. Remind the user they can run setup later.

After setup, read the config and use the chosen backend for all commands in this session.

Backend: doob

doob is available; use native CLI commands (see references/doob-commands.md).

Verify: command -v doob exits 0.

Backend: sqlite

doob is not installed. Valerie scaffolds a thin sqlite wrapper at first use:

# check if wrapper exists
ls ~/.local/bin/doob 2>/dev/null || valerie_scaffold_sqlite_wrapper

See references/sqlite-fallback.md for the schema, wrapper code, and limitations. All subsequent commands use the same surface (doob todo add, doob todo list, etc.) but routed through the sqlite wrapper.

When to Invoke

Dispatch the valerie agent for:

• User mentions a task, todo, or "I need to..."
• User asks what to work on next
• A council analysis report is referenced or loaded (parse → todos)
• A HANDOFF file is open and tasks need capturing
• User asks to audit or reconcile todos against a HANDOFF
• Bulk todo operations (>3 items)

For single ad-hoc todos (one item, no source document), invoke the backend directly without dispatching the full agent.

Workflow 1 — Direct CRUD

Add, list, complete, remove individual todos. See references/doob-commands.md for full syntax.

Quick reference:

doob todo add "<description>" [--priority <n>] [-p <project>] [-t <tag1,tag2>]
doob todo list [--status pending|in_progress|completed] [-p <project>]
doob todo complete <id>
doob todo remove <id>

Workflow 2 — Council Report → Todos

When a council analysis report (devloop analyze output, *-council.md) is referenced:

1. Read the full report
2. Collect recommendations from all roles (creative-explorer, general-analyst, strict-critic) and the synthesis section
3. Deduplicate overlapping items across roles — synthesis items usually duplicate critic items
4. Map severity to priority:
   • critical / P0 → --priority 5
   • high / P1 → --priority 4
   • medium / P2 → --priority 3
   • low → --priority 2
   • unscored → --priority 1
5. Infer project and tags from the report filename or context
6. Create all unique todos via doob todo add
7. Report a summary table: count by priority level

Workflow 3 — HANDOFF Context → Todo Reconciliation

When a HANDOFF.*.yaml is the source:

handoff-reconcile sync --handoff <path-to-HANDOFF.yaml>

Use this as the default path. Only fall back to direct doob commands when extending or debugging the reconciler itself.

1. Run the configured GitHub issue sync into doob
2. Read the HANDOFF file (use handoff-detect if available)
3. Extract all items with status: open or status: blocked
4. For each item, reconcile it against the matching doob todo/issue:
   • description: normalized name when present, otherwise <title> (append [BLOCKED] if blocked)
   • priority: map P0→5, P1→4, P2→3
   • project: from HANDOFF project field
   • tags: handoff,<project>
5. Create a new todo only if no matching active todo/issue exists
6. Treat HANDOFF as context only. If the matching todo/issue is already closed, mark the HANDOFF item for removal during Workflow 4

Workflow 4 — HANDOFF Cleanup / Write-Back

After reconciling HANDOFF items with doob, update the HANDOFF file so its items only contain still-open context.

For each still-open item that was reconciled, optionally append to its extra array:

extra:
  - date: <today>
    type: note
    note: "reconciled with doob — todo id <doob-id>"

Remove any item whose matching todo/issue is complete, cancelled, or closed upstream. Do not retain closed items in committed items. Preserve or prepend a one-line log entry for finished work, ideally with commit hashes when known. Write back and commit:

git add .ctx/HANDOFF.*.*.yaml
git commit -m "docs: prune resolved handoff items"

Workflow 5 — Audit and Reconciliation

When asked to audit todos against a HANDOFF:

handoff-reconcile audit --handoff <path-to-HANDOFF.yaml>

Use this as the default audit path, then fall back to the manual checklist below only when you need to debug a mismatch.

1. Run the configured GitHub issue sync into doob
2. Read HANDOFF — collect all open/blocked item IDs and titles
3. Run doob todo list -p <project> --json — collect all pending/in-progress todos
4. Cross-reference:
   • HANDOFF items with no matching todo → not captured
   • Todos with no matching HANDOFF item → orphaned (may be from council reports)
   • Todos/issues marked complete or closed while HANDOFF item still exists → prune from HANDOFF
5. Report the reconciliation table:

Reconciliation — <project>
===========================
Captured (HANDOFF→doob):  N items
Not captured:             N items  [list titles]
Orphaned todos:           N items  [list descriptions]
Closed upstream:          N items  [list IDs]

5. Offer to: capture missing items, prune closed HANDOFF items, or remove orphaned todos

Behavior Rules

• Always run the setup check before the first todo operation in a session
• Always confirm after bulk operations (show count + summary, not every item)
• Infer project from cwd (git rev-parse --show-toplevel | xargs basename) if not specified
• Keep descriptions actionable: verb-first, specific, under 100 chars
• When deduplicating council recs, prefer the synthesis wording if available
• Valerie is the only skill that should touch doob; all other skills should use handoff-db/SQLite and HANDOFF YAML only
• For HANDOFF reconciliation, call handoff-reconcile first; direct doob commands are the fallback/debug path, not the default
• Never treat HANDOFF items as the source of truth for closed work; prune closed items after sync, but preserve durable log history
• Never write to HANDOFF files without confirming first, except for low-risk reconciliation cleanup after doob/GitHub sync

Additional Resources

• references/doob-commands.md — Full doob CLI syntax, flags, and output formats
• references/sqlite-fallback.md — SQLite schema, wrapper code, and limitations vs doob
• helpers/setup.sh — Interactive setup for sh users
• helpers/setup.nu — Interactive setup for nu users