l-agent-task-db

Files (3)

• SKILL.md
• scaffold.nu · scripts/
• task-dashboard.nu · scripts/

SKILL.md (first lines)

# Agent task db conventions (shared mechanics)

This is a mechanics-only skill: it has no orchestration behavior of its
own. `l-multi-agent-task-mode` and `l-single-agent-task-mode` both load it
for: db layout, scaffolding, tag vocabulary, `tasks/context/` conventions,
and the human-question workflow. `l-multi-agent-mode` (pure live/direct
orchestration, no task db) does not use this skill at all.

## One db per project root

Each project root (a git repo, or a standalone non-repo folder like a
research initiative) gets its OWN isolated taskwarrior+timewarrior
instance, never a db shared across multiple unrelated projects:

```
<project-root>/
  tasks/
    .taskrc              # generated by devenv enterShell; gitignored, local state
    .task/               # data.location; gitignored, local state
    .timewarrior/        # gitignored, local state
    .poll-backoff        # gitignored, local state (self-adjusting poll cron)
    context/
      research/
      design/
      questions/
    agents/              # per-claimed-task pipeline-internal state (l-multi-agent-task-mode)
  devenv.nix             # enterShell writes tasks/.taskrc, exports TASKRC/TIMEWARRIORDB
  .envrc                 # `use devenv`: direnv auto-sources it on cd
```

If the project root also needs plain human-facing todos unrelated to
agent work, they live in the SAME db (see `+agent-task` below). Never
create a second parallel db for "the human's stuff" vs. "the agent's
stuff" in one project.

## Dashboard: exactly what's queued, what stage, what needs you

```bash
<this-skill-dir>/scripts/task-dashboard.nu [project-dir]   # else $TASKRC, else ./tasks/.taskrc
```
Run this skill's own `scripts/task-dashboard.nu`, not the `task-dashboard`
command on PATH (that one is the human's curses TUI over `~/.config/task/taskrc` and
ignores the project-dir). Taskrc resolution: `<project-dir>/tasks/.taskrc`
if given, else `$TASKRC`, else `./tasks/.taskrc`. Prints and exits.
Read-only, human-facing view (never modifies the db): `+prompt` tasks
still awaiting decomposition, tickets blocked on `+human-clarification-needed`
(with their question file path), tickets sitting at `+human-review-ready`
(with the annotated PR link), tickets the human has
answered a question and wait for the agent (`+human-answered`), what's in progress,
what's ready/blocked, and recently completed tickets, each with its
`project:` family and `+stage-*`. Run this any time to see the whole queue
at a glance instead of hand-parsing `task list`/`task export`.

## Detecting / scaffolding

- Detect: the `TASKRC` env var (exported by devenv + direnv on `cd`), or a `<project-root>/tasks/.taskrc` used
  explicitly outside that shell (`TASKRC=./tasks/.taskrc task ...`).
- Neither: `taskwarrior-init [project-dir]` (default `$PWD`), safe to re-run and never touching existing db data or
  an existing repo's history; one db per root, an existing one is reused. What it writes:
  [references/scaffold.md](references/scaffold.md).

## Task lifecycle: start/stop discipline

`task <id> start` / `task <id> stop` aren't decorative: they drive the
`on-modify.timewarrior` hook, so they're the only source of truth for how
long a task was worked. Both task-mode skills follow this
without exception:

- The instant a task is claimed or resumed and real work begins,
  `task <id> start`, in the same beat as claiming it, not after.
- The instant work on it stops for this session (blocked on a human,
  handed to a worker that hasn't finished yet, or the poll pass is
  ending): `task <id> stop`. A task sitting `+human-clarification-needed`,
  `+human-review-ready`, or waiting for the next poll pass is PAUSED, not
  started; never leave it counted as "started" with no active work
  happening.
- Finishing (`task <id> done`, below) happens after the stop above; don't
  leave a dangling start or a double-stop.

## Completion: `task <id> done`

A ticket is finished with `task <id> done`; that is what unblocks the
tickets that `depends:` on it. The agent marks it done itself once the
ticket's deliverable exists and is verified AND its gate, if any, passed:

- A ticket that opened a PR is done when that PR merged (`gh pr view <n>
  --json state` says `MERGED`): the human merges a spec PR; a phase PR
  merges per the project's merge policy (`l-spec-driven-development`).
- A research/design ticket with no PR is done once its artifact is written
  and checked (research: its research review passed; design: its design
  review passed).

Stop it first and drop its current `+stage-*` tag (e.g. `task <id>
modify -stage-land`), then `task <id> done`.

## Parallelism

The concurrency budget and the 2-implementer cap live in
`l-spec-driven-development` ("Parallelism and model choice").

## Unattended polling

A self-polling orchestrator (a background loop or the backoff poll cron) runs under the `orchestrator` Hermes profile
(provisioned by the dotfiles' `programming/hermes`), never `default`; live sessions stay on the profile that
launched them. The cron reschedules itself with a linear backoff kept in `tasks/.poll-backoff`. Setup and the
per-run rules: [references/unattended.md](references/unattended.md).

## `project:` = one decomposed prompt

Taskwarrior's own `project:` field is reused as "which prompt/initiative
does this ticket belong to", not a separate sprint concept. One `+prompt`
task, once decomposed, becomes one `project:<slug>.*` family; every ticket
under it is one step from the task-planner's breakdown. The groupings
(full rules in `l-multi-agent-task-mode`, `references/intake.md`):
`project:<slug>.research`, `.design`, `.spec`, then one `.p<k>` per
`SPEC.md` Roadmap phase once the spec PR merged.

```bash
task add project:sale-tracker.research +agent-task "technical research"

From lsck0/arch-dotfiles, MIT.

More from lsck0/arch-dotfiles