dotfiles/home/.agents/skills/dev-tickets/SKILL.md

---
name: dev-tickets
description: Storage model for development tickets, specs, and planning maps, which live in the Obsidian vault as TaskNotes tasks and are read and written with the `ticket` CLI. Use when creating an effort or spec, writing implementation or decision tickets, finding the frontier, or claiming, annotating, and closing a ticket — and whenever /to-spec, /to-tickets, /wayfinder, or an implementor reads or writes them.
---

# Dev tickets

Tickets, specs, and planning maps live in the Obsidian vault as TaskNotes tasks. They are read and written with **`ticket`**, a file-based CLI that works on the markdown directly — no running Obsidian, no HTTP API — so it behaves the same on every host. This skill owns the storage model: the shape on disk, the metadata, and the verbs that read and write it. The skills that produce tickets (`/to-spec`, `/to-tickets`, `/wayfinder`) own their own process and defer here for everything below.

**Where the vault is** is what `ticket vault` prints. It is configured once per host, and the skill never names a path:

```sh
ticket vault --set <vault path>     # once per host; refuses a directory that is not the vault
```

If `ticket` says no vault is configured, ask the user for the path and run that. If `ticket` itself is missing, the dotfiles install script installs it (`npm ci` inside `~/.local/lib/dev-tickets`); the launcher prints the exact command when its dependencies are absent.

## Vocabulary

- **Vault** — the Obsidian vault, wherever it is on this host. The user-facing word for where tickets live.
- **Collection** — the vault as mdbase sees it: `mdbase.yaml` plus the `_types/task.md` schema that TaskNotes maintains. Used only when talking about the tool's mechanics.
- **Repo project** — the `[[repo]]` wikilink every effort in a repo shares. A note at that title is **optional**; see [Repo project notes](#repo-project-notes).
- **Effort** — one feature or change. A task whose body is the planning map, which graduates into the spec.
- **Decision ticket** — a subtask that answers a question. `/wayfinder`'s unit.
- **Implementation ticket** — a subtask that builds something. `/to-tickets`' unit.
- **Frontier** — the tickets that are open and not blocked.
- **Title** — a note's filename stem. It is the note's identity (every edge is a wikilink to it) and is never a frontmatter key.
- **Record** — what `--json` returns for a note: `path`, `title`, the derived `isBlocked`, then the frontmatter as it is on disk. `show --json` adds `body`.

## Shape

```
TaskNotes/Dev/atribot/
├── atribot.md                                   ← repo project note; optional, NOT a task
└── Network isolation/
    ├── Network isolation.md                     ← effort task
    ├── Should obsync share a namespace.md        ← decision ticket
    └── Split obsync into its own container.md    ← implementation ticket
```

One directory per repo, one per effort. Every note in an effort directory sits directly in it — the hierarchy is expressed by `projects`, not by nesting. `ticket create` owns this shape: it derives the directory and the parent link from `--repo` or `--effort`, so a note cannot be filed in the wrong place.

**A title is an identity.** Every parent and blocking edge is a `[[wikilink]]` to a title, so titles are globally unique across the vault and a published note is never renamed. Give each one a name that reads on its own — `Split obsync into its own container`, not `02-split-container`.

Uniqueness is **case-insensitive and vault-wide**, and it binds whether or not you created a note for the title: `projects: [[obsidian]]` would attach every ticket in that repo to a personal `Obsidian.md` anywhere in the vault. `ticket create` refuses a title that any note already carries, and `ticket show <title>` is the pre-check when choosing one (exit 2 means the title is free).

## Frontmatter

`ticket create` writes every one of these in a single call. The middle column names what sets it.

| Field | Set with | Values |
|---|---|---|
| `status` | `--status` at creation, then `claim` / `close` | `Open` · `In Progress` (claimed) · `Done` (complete, resolved) · `Wont Do` (abandoned, out of scope) |
| `contexts` | `--context` on an effort; tickets inherit the effort's | from the repo's `CLAUDE.local.md` |
| `projects` | derived: `--repo R` → `[[R]]`, `--effort E` → `[[E]]` | effort → `[[repo]]` · ticket → `[[effort]]` |
| actor tag | `--actor agent\|human` at creation; `close --actor` to correct it | `agent-step` · `human-step` — exactly one, durable, survives completion |
| `needs-info` | `stall` / `unstall` | tag, present only while stalled on an unanswered question |
| `blockedBy` | `--blocked-by` (repeatable) at creation; `set blockedBy+=` / `-=` later | list of `{uid, reltype}`; `reltype` is `FINISHTOSTART`; every blocker must resolve to an existing task |
| `ticket_type` | `--type` | `research` · `prototype` · `grilling` · `setup` · `implementation` |
| `git_branch` | `set git_branch=…` on the effort | effort tasks only; omit entirely when on main/master |
| `git_worktree` | `set git_worktree=…` on the effort | effort tasks only; omit entirely when the main worktree |
| `agent_session` | `claim` | `$CLAUDE_CODE_SESSION_ID`, overwritten each session that works the ticket |

The tool writes the rest itself: the `task` tag, `priority` (the vault's default), `date_created` and `date_modified` (bumped on every write), and `date_completed` at close. It never writes `date_scheduled` or a `title` key.

A ticket on disk reads:

```yaml
---
status: Open
priority: 2-Normal
contexts:
  - Obsidian
projects:
  - "[[Network isolation]]"
date_created: 2026-08-10T09:12:44.118-07:00
date_modified: 2026-08-10T09:12:44.118-07:00
blockedBy:
  - uid: "[[Verify internal network publish]]"
    reltype: FINISHTOSTART
tags:
  - task
  - agent-step
ticket_type: implementation
agent_session: 444e4dcb-de76-4f6b-8c39-7d08d6aa9f5f
---
```

Quoting varies by writer — `ticket` single-quotes wikilinks and dates, TaskNotes double-quotes and leaves them bare — and both are valid YAML; do not "fix" it.

`blocked` is not a status. `isBlocked` is derived from `blockedBy` and the live status of each blocker (TaskNotes does the same on the desktop), so blocking is recorded once, in `blockedBy`, and read back from `isBlocked` in every record. A blocker that does not resolve warns and does not block.

`ticket_type: setup` is groundwork that unblocks a decision — provisioning access, moving data — whose *result* later tickets depend on. It corresponds to `/wayfinder`'s "task" type.

## Body

Effort task — the map first, and the spec replacing `## Destination` once the way is clear. `/wayfinder` and `/to-spec` each own their own section content.

Ticket — `## Question` for a decision ticket, `## What to build` plus acceptance checkboxes for an implementation ticket. A resolved decision ticket gains `## Answer`.

Every effort and ticket task takes the same two trailing sections, which `ticket create` appends when the body lacks them:

```markdown
## Notes

### [[2026-08-10]]

Squid rejects CONNECT to the registry on first run; the allowlist needs the CDN host too, not just the API host.

## As Built
```

`## Notes` is a running log — hurdles, surprises, design changes — appended **while the work happens** with `ticket note`, under a sub-heading wikilinking the current date.

`## As Built` is written at completion with `ticket as-built`, and only when the implementation materially deviated from what the ticket asked for.

## Repo configuration

Each repo's `CLAUDE.local.md` carries the context to stamp on its notes:

```markdown
## Dev tickets

- context: Obsidian
- repo: atribot          # optional; defaults to the directory name
```

When a repo has no such block, ask the user for the context and offer to write the block. A guessed context files the effort under the wrong area and stays wrong.

## Creating

An effort names its repo and context; the tool files it at `TaskNotes/Dev/<repo>/<title>/<title>.md` with `projects: [[repo]]` and no actor tag:

```sh
ticket create --repo atribot --title 'Network isolation' --context Obsidian \
  --set git_branch=feat/network-isolation \
  --body-file - <<'BODY'
## Destination

...
BODY
```

A ticket names its effort; the tool files it beside the effort note with `projects: [[effort]]`, the effort's contexts, the actor tag, and `ticket_type`:

```sh
ticket create --effort 'Network isolation' --title 'Split obsync into its own container' \
  --type implementation --actor agent \
  --blocked-by 'Verify internal network publish' --blocked-by 'Provision the registry mirror' \
  --body-file - <<'BODY'
## What to build

- [ ] Move the compose service into its own namespace
BODY
```

`--type` and `--actor` are required for a ticket and refused for an effort; `--context` is the reverse. `--blocked-by` accepts bare or `[[bracketed]]` titles and every one must exist — a typo'd blocker would never block, so it is an error instead. Create in dependency order. `--set k=v` adds any other field (`git_worktree`, `timeEstimate`); `--json` prints the record.

Creation refuses — and writes nothing — when the target file exists or any note in the vault has the same title case-insensitively (exit 2). Resolving a collision is the user's choice.

### Repo project notes

Optional, and there is no need to create one. `projects: [[atribot]]` groups the repo's efforts whether or not a note by that name exists — queries match on the frontmatter value, so a dangling link queries exactly like a resolved one.

Create one only to give a repo a landing page. Its single job is to be the note Obsidian's Subtasks view renders on: `TaskNotes/Views/relationships.base` matches a task's `projects` against `this.file`, so with no note there is no page to see the effort list on. Nothing reads the note's own frontmatter — it is not a task, so TaskNotes skips it — which makes the body free-form. A description and the repo path is enough:

```markdown
Matrix bot and its companion services, deployed as compose stacks.

Repo: `/home/tgrosinger/code/atribot`
```

`ticket` only makes tasks. Write the file directly at `TaskNotes/Dev/<repo>/<repo>.md`.

## Routing tags

Two independent axes, neither of which is a status. `status` carries the lifecycle; these carry *who does this step* and *whether it can proceed*.

**Actor — `agent-step` or `human-step`.** Exactly one on every ticket, from creation onward. On an open ticket it names the intended next actor; on a closed ticket it records the actor who actually completed the work. It is durable: claiming and closing do not remove it, so a `Done` ticket still records whose step it was. Effort tasks carry no actor tag; only tickets do.

**Stall — `needs-info`.** Transient and orthogonal to the actor. It means the assigned actor cannot proceed without information from someone else; it does not reassign the ticket. Thus `agent-step` + `needs-info` means *agent work awaiting a human answer*, while `human-step` + `needs-info` means *human work awaiting information from another person or source*. Add it the moment work stalls, remove it when the question is answered.

The actor usually follows from `ticket_type`, and `/wayfinder` calls the same distinction HITL vs AFK:

| `ticket_type` | actor | why |
|---|---|---|
| `research` · `implementation` | `agent-step` | an agent drives it alone |
| `grilling` · `prototype` | `human-step` | resolves only through live exchange with the user |
| `setup` | either | depends on whether the agent can do the work itself |

`setup` is the case that must be decided per ticket — which is exactly why the actor is a tag and not derived from `ticket_type` at query time.

| Transition | `status` | actor tag | `needs-info` | verb |
|---|---|---|---|---|
| Created | `Open` | set, exactly one | absent | `create --actor` |
| Claimed | → `In Progress` | unchanged | unchanged | `claim` |
| Stalled on a question | unchanged | unchanged | **add** | `stall` |
| Question answered | unchanged | unchanged | **remove** | `unstall` |
| Reassigned to the other actor | unchanged | **swap** | unchanged | `set tags+=… tags-=…` |
| Completed | → `Done` | **swap if the other actor did the work** | must be absent | `close [--actor]` |
| Abandoned | → `Wont Do` | unchanged | remove if present | `close --wont-do` |

The verbs enforce the two rules that used to be easy to forget: `close` always clears `needs-info`, and `close --actor human` (or `agent`) corrects the actor tag when the other actor finished the work — which is what keeps `agent-step AND status:Done` a truthful record of what agents actually shipped. `set tags+=needs-info` and friends still work as an escape hatch, with a warning naming the verb that would have done it properly.

## Working a ticket

1. **Claim it** before any work, so a concurrent session skips it:
   ```sh
   ticket claim 'Split obsync into its own container'
   ```
   The session id comes from `$CLAUDE_CODE_SESSION_ID` (or `--session`). `claim` refuses a ticket that is blocked or already `In Progress` under another session; `--force` overrides both.
2. **Record the checkout** on the *effort* task. When the branch is not `main` or `master`, set `git_branch`. When working in a linked worktree rather than the repository's main worktree, also set `git_worktree` to the absolute root returned by `git rev-parse --show-toplevel`:
   ```sh
   ticket set 'Network isolation' git_branch=feat/network-isolation git_worktree=/home/tgrosinger/code/atribot-ni
   ```
   Omit `git_branch` on `main`/`master`, and omit `git_worktree` in the main worktree (`ticket set '<effort>' git_worktree=` removes it). If the checkout changes later, update both fields.
3. **Append notes as you go**; each lands under today's `### [[YYYY-MM-DD]]` heading (reused within a day), above `## As Built`:
   ```sh
   ticket note 'Split obsync into its own container' 'Squid rejects CONNECT to the registry on first run.'
   ticket note 'Split obsync into its own container' --file -   # longer text on stdin
   ```
4. **Stall it** if you hit a question only the user can answer — the tag and the logged question are one write:
   ```sh
   ticket stall 'Split obsync into its own container' 'Should the registry mirror share the proxy namespace?'
   ticket unstall 'Split obsync into its own container' 'Yes — same namespace.'
   ```
   Leave `status` at `In Progress` — the ticket is still yours, it just cannot proceed.
5. **Close it.** Write `## As Built` first if the implementation deviated, then:
   ```sh
   ticket as-built 'Split obsync into its own container' 'Kept the socket; a namespace split was not needed.'
   ticket close 'Split obsync into its own container'                  # Done
   ticket close 'Split obsync into its own container' --actor human    # the human finished it
   ticket close 'Split obsync into its own container' --wont-do        # abandoned
   ```
   `close` stamps `date_completed` and clears `needs-info`. Closing an **effort** is refused while any of its tickets is still open — close or `--wont-do` them first; it never cascades.

Closing a ticket unblocks its dependents automatically; there is nothing to update on them.

To resume a ticket: `cd` to its effort's `git_worktree`, then `claude --resume <agent_session>`. When `git_worktree` is absent, use the repository's main worktree: the repo project note records its path when that note exists; otherwise resume from an existing checkout of that repo and use its root from `git rev-parse --show-toplevel`.

## Querying

Every reference (`REF`, `EFFORT`) is a vault-relative path or a title — bare or `[[bracketed]]`, case-insensitive. An ambiguous title is refused with the candidates listed.

The **frontier** of one effort — open and unblocked — and the **agent frontier**, what an agent may pick up right now (also `agent-step` and not stalled):

```sh
ticket frontier 'Network isolation'
ticket frontier 'Network isolation' --actor agent --json
```

**Awaiting a human** — both axes reach the human, so the inbox is their union, minus completed work, across the whole vault:

```sh
ticket inbox
```

Everything else is `list`, scoped to `TaskNotes/Dev/` unless `--all`; the filters AND together:

```sh
ticket list --effort 'Network isolation'            # every ticket of the effort, any status
ticket list --repo atribot --open                   # the repo's open efforts
ticket list --open --where 'status == "In Progress"'
ticket list --all --where 'tags.contains("human-step") && exists("date_completed")'
```

`--where` is mdbase's expression language, not CEL: `==`, `!=`, `&&`, `||`, `!`, `.contains("x")`, `exists("field")`, `file.name`, indexing. `in` and CEL macros (`exists(t, …)`) are rejected as invalid expressions — the tool reports the error rather than returning nothing.

Text output is one row per note — status (with `blocked` / `needs-info` flags), actor, title, path. `--json` prints records; pipe to `jq`:

```sh
ticket frontier 'Network isolation' --actor agent --json | jq -r '.[0].path'
```

## Cheatsheet

```
ticket vault [--set PATH]                                            print the vault path, or record it for this host
ticket show REF                                                      print a note verbatim (--json: its record with body)
ticket list [--effort E] [--repo R] [--open] [--where EXPR] [--all]  tasks under TaskNotes/Dev (or the whole vault with --all)
ticket frontier EFFORT [--actor agent|human]                         the effort's tickets that are Open and unblocked
ticket inbox                                                         human-step or needs-info, not completed, vault-wide
ticket create --repo R --title T --context C [--set k=v] [--body-file F|-]
ticket create --effort E --title T --type TYPE --actor agent|human [--blocked-by B]... [--body-file F|-]
ticket claim REF [--session ID] [--force]                            In Progress under this session
ticket note REF TEXT|--file F [--date YYYY-MM-DD]                    append to ## Notes, above ## As Built
ticket as-built REF TEXT|--file F                                    append under ## As Built
ticket stall REF TEXT|--file F                                       add needs-info and log the question
ticket unstall REF [TEXT|--file F]                                   clear needs-info, optionally logging the answer
ticket close REF [--wont-do] [--actor agent|human]                   Done (or Wont Do), date_completed, needs-info cleared
ticket set REF k=v k= k+=v k-=v ...                                  edit frontmatter; += / -= on tags, contexts, projects, blockedBy
global: --vault PATH   --json   --help
```

Exit codes: `1` usage or error, `2` refused (collision, blocked, ambiguous, not found, open children, not a task), `3` the file changed between read and write — nothing was written; re-run the command.

## Guardrails

- **Create a new ticket rather than renaming a published one.** Every inbound `projects` and `blockedBy` edge points at the title.
- **Body by hand is fine; frontmatter goes through `ticket`.** `set` and the verbs stamp `date_modified`, refuse non-tasks, keep the schema's types, and refuse to clobber a file another writer changed underneath them. A direct frontmatter edit does none of that.
- **There is no delete.** `ticket` never removes a note, and neither should you without the user's explicit say-so.
- `ticket` does not talk to Obsidian. When Obsidian is running on the same host it picks the change up like any external edit; when it is not, sync carries it.

Why the model is shaped this way, and what was rejected on the way here: [README.md](./README.md).