Task & Bug Workflow

The full lifecycle of tracked work in gald3r: how tasks and bugs are created, claimed, completed, and verified. Every command on this page was run against a scratch project while writing it.

The state model: SQLite first, Markdown second

.gald3r/gald3r.db is the source of truth for task/bug status transitions. .gald3r/TASKS.md, .gald3r/BUGS.md, and the individual files under .gald3r/tasks/ and .gald3r/bugs/ are a generated, portable cache that a database write regenerates — never the other way around. If the database doesn't exist yet (fresh clone, or you've been hand-editing Markdown), gald3r db backfill imports the files into it:

gald3r db backfill

Backfilled 12 task(s), 4 bug(s), 9 document(s), 3 artifact record(s) into .gald3r/gald3r.db.
  Tasks: 12 valid, 0 normalized, 0 skipped, 0 FAILED.
  Bugs:  4 valid, 0 normalized, 0 skipped, 0 FAILED.
  Documents: 9 ingested, 0 skipped.
  Artifact records: 3 valid, 0 normalized, 0 skipped.

Other database-sync verbs:

gald3r db verify              # report drift between the DB and the .gald3r/ files
gald3r db rebuild             # regenerate the .gald3r/ files FROM the DB (opposite direction of backfill)
gald3r db regenerate-index    # rebuild slim indexes (TASKS.md / BUGS.md / ADRS.md / ...) from SELECT; --kind and --apply

Work clones install the compiled gald3r binary and talk to .gald3r/gald3r.db directly — no uv, no Python venv. uv run gald3r exists only in this source checkout. world_tree Postgres mapping for each board kind is specified in gald3r_project/board/worldtreesync and remains GATED while T684 / T836 / world_tree T1781 are blocked (the mapping does not pretend the server already has the kinds).

Tasks

Create

gald3r task add "Title" -d "Description" --type feature --priority medium

Task types: feature, bug_fix, refactor, docs, test, chore (see gald3r task add --help for the current, authoritative list — it's enforced at creation time, not just a convention). Priority: low / medium / high / critical, or a direct --priority-score 1-10 for finer-grained ranking (higher scores surface first when several tasks are ready at once).

Find what to work on

gald3r task ready

Lists every task that is pending, has no unmet dependencies:, and clears the active value floor — i.e. genuinely pickable right now. gald3r task next narrows that to a single recommendation. gald3r task list shows everything (any status), with a compact value-bar chart rather than a plain table:

gald3r task list

1        v8  high       pending    Write the landing page copy
2        v5  medium     in-progress  Fix broken footer link

Status indicators used across the CLI: pending, in-progress (claimed), awaiting-verification, completed, failed, paused, cancelled.

Claim and work

gald3r task update T1 --status in-progress

Moves a task from pending to in-progress and records the claim. In an autonomous/swarm run, gald3r go-preflight is the concurrency-safe way to claim several tasks at once — only one agent wins any given task even when several are racing for the same queue. See autopilot.md.

Acceptance criteria

Every task can carry an acceptance-criteria checklist. Tick items individually as you satisfy them (per-criterion attestation, not a single "done" flag):

gald3r task ac-check T1 1        # tick criterion #1
gald3r task ac-status T1         # see checked/unchecked status

Hand off for review

gald3r task update T1 --status awaiting-verification

Verify (reviewer side — never the implementer)

gald3r task verify T1 --pass    # -> completed
gald3r task verify T1 --fail    # -> back to pending, with the failure reason recorded

gald3r verify (no task id — the standalone verb) is the completion GATE: it checks whether a task's acceptance criteria are actually satisfied before you call it done, rather than trusting a self-report.

Housekeeping

gald3r task-sync-check           # validate TASKS.md against the tasks/ files (--fix repairs)
gald3r task archive               # move completed/failed/cancelled tasks into .gald3r/archive/
gald3r task delete T999           # HARD delete -- only for tasks created in the wrong project
gald3r task stale-claims           # find and resolve in-progress tasks whose claim has expired
gald3r db rebuild                  # regenerate TASKS.md and the task files from the database

Bugs

Bugs mirror the task shape (gald3r bug add/list/show/update/ac-check/archive/delete), with one difference at the terminal state: instead of task verify --pass, a bug is closed with:

gald3r bug add "Title" -d "What's broken" --severity high --file path/to/file.py --line 42
gald3r bug list
gald3r bug resolve BUG-1

Bug severity uses a 1-10 damage scale (a cosmetic typo is 1-2, a crash on a common path or a security gap is 7-8, secret leaks or data destruction top out at 9-10) — the mirror image of a task's value score. gald3r status renders open bugs on the same style of bar chart as tasks, scored by damage instead of value:

Bugs (1 open, 4 all statuses)
  9-10 (crit) │                                         0
  7-8 (high)  │████████████████████████████████████████ 1
  5-6 (med)   │                                         0
  1-4 (nit)   │                                         0

Validation and drift

gald3r validate            # schema/status-vocabulary/folder-placement checks on tasks|bugs
gald3r validate --fix      # normalize what's safely auto-fixable
gald3r db verify           # database-vs-Markdown drift report

gald3r validate is designed to run as a fail-closed pre-commit hook on staged .gald3r/tasks/** and .gald3r/bugs/** — a malformed frontmatter field, or an open-family task/bug filed under a retired per-status subfolder instead of the flat tasks/ / bugs/ root, is caught before it merges rather than discovered later by a human reading TASKS.md. Terminal records belong in tasks/completed|failed|cancelled/ and bugs/done|cancelled/.

Where next

• autopilot.md — letting gald3r work the task queue itself instead of running each step by hand
• verbs.md — the full CLI verb catalog, grouped by purpose