---
name: devmark
description: Record meaningful development events and user-selected deferred work with the Devmark CLI, and find or update existing records. Use when the user asks to use Devmark or project instructions already enable Devmark logging.
---

# Devmark

Use the installed `devmark` CLI for a local Journal and independent Todos. A request to search or update a record does not enable ongoing logging for unrelated work. This skill does not install Devmark or change agent configuration.

## Recording policy

<!-- devmark:prompt:start -->
Use Devmark to remember meaningful development progress and deliberately deferred work.

- Record completed implementation phases, releases, deployments, migrations, and accepted decisions that materially change scope, architecture, or operations. Record blocker changes only when they materially affect milestone progress.
- Skip routine turns, checks, reviews, commits, and discussions. If an event does not clearly qualify, skip it.
- Create a Todo only when the user asks for a reminder or has explicitly chosen to defer that work. Recording a Todo does not authorize executing it. Completing or reopening a Todo must not create a Journal entry.
- Run from the relevant project directory so Devmark can infer its path. Use the user's preferred language for records and the user's active timezone.
- Confirm each write succeeds. Reuse the same `event_key` and unchanged payload when retrying a Journal event; never silently replace a conflicting event.
- Consult the Devmark skill for commands and JSON examples. If it is unavailable, use `devmark --help` or `devmark todo --help`. If the CLI is missing or a write fails, report it without claiming success and continue unrelated work.
<!-- devmark:prompt:end -->

## Use the CLI

Check `command -v devmark`. The executable must be on PATH; do not assume another user's absolute installation path. Use `devmark --help` and `devmark todo --help` for additional flags or installed-version differences. Use CLI commands rather than editing SQLite directly.

Run writes from the project directory. Git subdirectories and linked worktrees infer the main repository path. A project is optional source metadata, not a registered project name; use `--no-project` for an intentionally unscoped record. Journal and Todo list commands span all projects by default, so add `--project .` when the request is about the current project. Tags organize records across projects.

For isolated tests, pass `--db /absolute/path/to/test.db` after the command and before any positional ID (for example, `devmark add --db /absolute/path/to/test.db --json -`). Do not seed the user's normal database with examples.

## Record a Journal event

Replace example values with the actual verified event. Omit unnecessary fields.

```sh
devmark add --json - <<'JSON'
{
  "kind": "milestone",
  "summary": "Completed search and tag filters",
  "details": "Added keyword search and tag filtering. Relevant checks passed.",
  "tags": ["search", "ux"],
  "event_key": "search-and-tags-v1"
}
JSON
```

`kind` and `summary` are required. Allowed kinds are `milestone`, `release`, `deployment`, `migration`, `decision`, and `blocker`. Optional fields are `details`, `tags`, `event_key`, `source_ref`, `project`, `occurred_at`, and `timezone`.

- Include `source_ref` only for a real commit, PR, or other reference.
- `project` is an existing absolute directory path; omit it to infer the current project. An empty string explicitly omits the project.
- `occurred_at` is an RFC3339 timestamp. `timezone` accepts an IANA timezone or UTC offset. Set it when the user's active timezone differs from the CLI default; otherwise project and time are inferred.
- Reuse a stable, event-specific `event_key`. An unchanged retry returns `existing`; different content under that project's key fails. Investigate a conflict instead of inventing another key to bypass it.

Successful adds return JSON with an `id` and `status` (`created` or `existing`). Nonzero exit status and stderr indicate failure. Submit exactly one JSON object, with no unknown fields, using a quoted heredoc or stdin file so shell substitution cannot alter the content.

## Capture and manage Todos

Use tags for categories and Markdown details for the context needed to resume. Keep each Todo to one deferred action.

```sh
devmark todo add --json - <<'JSON'
{
  "title": "Add a helpful empty state for search",
  "details": "Keep the active filters and offer a way to clear them.",
  "tags": ["ux", "follow-up"]
}
JSON
```

`title` is required. Optional Todo fields are `details`, `tags`, and `project`. Use `"project": ""` for an unscoped JSON Todo; do not combine Todo JSON with title, details, tag, or project flags. Todo JSON does not support `event_key`. Every add creates a new Todo; after an uncertain result, search for the existing item before retrying.

```sh
devmark todo list --project . --status open --search "empty state"
devmark todo show TODO_ID
devmark todo update TODO_ID --details "Keep filters and add keyboard support."
devmark todo done TODO_ID
devmark todo reopen TODO_ID
```

Use a real returned ID in place of `TODO_ID`. Completion or reopening changes only the Todo. Updating tags replaces the whole tag list; repeat `--tag` for multiple tags or use `--clear-tags` to remove them all.

## Find previous work

```sh
devmark list --project . --tag ux --limit 20
devmark list --search "search filters" --limit 20
devmark show ENTRY_ID
devmark todo list --status all --tag follow-up --limit 20
```

Use a real ID in place of `ENTRY_ID`. Start with a bounded query and inspect relevant records; do not dump the whole database into context. List results are JSON. Search matches literal substrings in summaries/titles and details; ASCII matching is case-insensitive.

## Recaps

Recaps are generated manually in the App. The CLI has no recap-generation command. Do not schedule generation, read ChatGPT credentials, or send records to an inference API as part of this skill.