rosemary

What this skill does

# Rosemary Skill

Share durable state across conversations and sub-agents using the `rosemary` CLI knowledge graph. Rosemary is one primitive — a graph any agent can read and write — exposed through three pillars:

| Pillar | Command | What it backs |
| --- | --- | --- |
| **Session continuity** | `/rosemary start`, `/rosemary end` | resume work after `/clear`, context compaction, or a machine restart |
| **Task dispatcher** | `/rosemary tasks plan\|list\|dispatch\|sync\|close` | durable, cross-agent task state — replaces TodoWrite / local jsonl |
| **Knowledge tier** | `/rosemary recall` | hybrid semantic search over ingested docs + a decision log |

**Core principle**: `rosemary` is the canonical store. Local `.agents/` files are fallback only when `rosemary` is not in `$PATH`. Task state lives in the graph, never in an ephemeral in-conversation todo list — that is the whole point: a dispatched sub-agent and the lead coordinate *through the graph*, not through the user.

**State scope** — prefer **shared (XDG global) state** by default. Project-local state (`rosemary init --local`, creating `./rosemary.toml`) is opt-in only when the user explicitly requests it (e.g. "use project-local rosemary", "isolate this repo's memory"). Cross-project entities (`UserPreferences`, `CodingStyle`, `ToolPreferences`) always live in the global graph regardless of scope.

## Naming Convention

Entity names use `:` as a hierarchy separator. Keep names verbatim — do not flatten to dashes.

| Pattern | Type | Example |
| --- | --- | --- |
| `<project>:session` | `session` | `ame:session` |
| `<project>:<epic>` | `task` | `ame:mobile-support` |
| `<project>:<epic>:task-<n>` | `task` | `ame:mobile-support:task-3` |
| `<project>:decision:<slug>` | `concept` | `ame:decision:no-pwa` |
| `<repo-basename>` | `project` | `ame` |

`<project>` is the repo basename. Use `-` only inside a single segment (`mobile-support`), `:` only between hierarchy levels.

## Detect rosemary (once, at session start)

Run `command -v rosemary`. Record the result — do not re-check during the session. If unavailable, fall back to local files.

**Scope detection**: if `./rosemary.toml` exists in the repo root, rosemary auto-uses project-local state — note this but do not switch modes mid-session. Otherwise the global XDG graph is in effect.

## `/rosemary start`

**Step 1 — Load state**:

- **rosemary**: `rosemary open-nodes UserPreferences CodingStyle ToolPreferences [repo-basename] [project]:session`. If any entity is missing from the output, it doesn't exist yet — seed it from Global Seed Values. If the session entity is missing, treat as a fresh start. If `[project]:session` references an active epic, also load it: `rosemary search-nodes "[epic-name]"` to pull the epic and its task children.
- **No rosemary**: read `.agents/CONTEXT.md` and `.agents/CURRENT_TASK.md`. Skip silently if missing.

**Step 2 — Freshness check**: run `git log --oneline -5`. If recent commits touch feature files but the loaded context looks unchanged, flag: "Context may be stale — sync at session end."

**Step 3 — Report**: "Session resumed. Last task: [X]. Next: [Y]." If an epic is active, append a one-line task board (see `/rosemary tasks list`). Include any freshness warnings.

## `/rosemary end`

**Step 1 — Save session state** (rosemary): full reset — delete the old session entity and recreate it clean so it never accumulates stale lines:

```bash
rosemary delete-entities "[project]:session"
rosemary create-entities "[project]:session" "session"
rosemary add-observations "[project]:session" "objective: [what we worked toward; name the active epic if any]"
rosemary add-observations "[project]:session" "status: [IN_PROGRESS|BLOCKED|REVIEW|DONE]"
rosemary add-observations "[project]:session" "completed: [finished items this session]"
rosemary add-observations "[project]:session" "remaining: [what's left]"
rosemary add-observations "[project]:session" "next: [single most important next action]"
rosemary add-observations "[project]:session" "last-updated: YYYY-MM-DD"
```

- **No rosemary**: overwrite `.agents/CURRENT_TASK.md` with the same fields.

**Step 2 — Save new facts** (cross-project): `rosemary search-nodes "[topic]"` to check for duplicates, then `rosemary add-observations [UserPreferences|CodingStyle|ToolPreferences] "[fact]"`. No rosemary: append to `.agents/MEMORY.md`.

**Step 3 — Save project context** (conventions, patterns, decisions): `rosemary search-nodes "[topic]"`, then `rosemary add-observations [repo-basename] "[fact]"`. No rosemary: update `.agents/CONTEXT.md`, keep concise.

**Step 4 — Compact** (optional): if `rosemary` was built with the `documents` feature, run `rosemary compact` to archive session state to Markdown and refresh the FTS/vector index. Skip silently if unavailable.

**Step 5 — Confirm**: "Session saved. Next: [one-sentence handoff]."

## `/rosemary tasks` — Task Dispatcher

A durable replacement for in-conversation todo lists. An **epic** entity holds the objective and scope; **task** entities hold one dispatchable unit each, linked `part_of` the epic. Status lives as append-only observations — the trail *is* the audit log. The session entity points at the active epic and the next task.

### `tasks plan <epic-name>`

Break work into an epic + tasks. Create once, then never overwrite:

```bash
rosemary create-entities "[project]:[epic]" "task"
rosemary add-observations "[project]:[epic]" "objective: [what this epic delivers]"
rosemary add-observations "[project]:[epic]" "scope: [in / out of scope, decided constraints]"

rosemary create-entities "[project]:[epic]:task-1" "task"
rosemary add-observations "[project]:[epic]:task-1" "title: [one-line goal] — [file paths + line numbers + plan]"
rosemary add-observations "[project]:[epic]:task-1" "status: READY_TO_DISPATCH"
rosemary create-relations "[project]:[epic]:task-1" "[project]:[epic]" "part_of"
# ...repeat per task; dependent tasks start "status: BLOCKED_ON [project]:[epic]:task-N"
```

Then point the session at it: `rosemary add-observations "[project]:session" "objective: [epic] — see [project]:[epic]"`. Order tasks **smallest → biggest** to build momentum. Put concrete file paths and line numbers in each `title:` so the dispatched agent needs zero discovery.

### `tasks list [epic-name]`

`rosemary search-nodes "[epic]"` (or `open-nodes` each task), then render a board from the latest `status:` observation of each task:

```
[project]:[epic]
  task-1  Responsive app shell          DONE
  task-2  Taking flow + flashcards      REVIEW
  task-3  Mobile e2e smoke              READY_TO_DISPATCH
  task-4  Explore page minWidth         BLOCKED_ON task-1
```

### `tasks dispatch [task]`

Pick the next `READY_TO_DISPATCH` task (or the named one). Mark it dispatched, spawn a sub-agent, and have the agent write results **back into the task entity** — not just into the conversation:

```bash
rosemary add-observations "[project]:[epic]:task-N" "status: DISPATCHED to [agent] YYYY-MM-DD"
```

Brief the sub-agent from the task's `title:` observation. Default agent is `haiku-developer` (efficient model for scoped work) unless the task is correctness-critical. Require the agent to end by recording:

```bash
rosemary add-observations "[project]:[epic]:task-N" "impl: [what changed; files touched; make check result]"
rosemary add-observations "[project]:[epic]:task-N" "status: REVIEW"
```

**Dispatch models** — pick per epic:

- **Sequential (default, proven)** — no worktrees, one agent at a time, lead reviews the diff in the working tree, commit after each task. Use when tasks touch overlapping files, need a human verify-gate, or want tight per-task review. This is the cadence that works in practice.
- **Worktree-per-task (opt-in)** — each task gets its own git worktree under the project; dispatch independent tasks in parallel; merge per task. Matches the global worktrees-by-default preference. Use only when tasks are genuinely independent (dis