dotmd-cli 0.28.0 → 0.28.2

package/README.md

@@ -89,19 +89,19 @@ Every document can have a `type` field in its frontmatter. Types determine which
 | Type | Purpose | Valid Statuses |
 |------|---------|----------------|
 | `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `partial`, `paused`, `awaiting`, `queued-after`, `archived` |
-| `doc` | Design docs, specs, ADRs, RFCs | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
-| `research` | Investigations, audits, analysis | `active`, `reference`, `archived` |
+| `doc` | Design docs, specs, ADRs, RFCs, reference material | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
+| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `claimed`, `archived` |
 
 Documents without a `type` field use the global `statuses.order` from config.
 
-Templates auto-set the type: `--template plan` sets `type: plan`, `--template adr` sets `type: doc`, `--template audit` sets `type: research`.
+`dotmd new <type> <name>` sets the `type:` field automatically (`plan`, `doc`, or `prompt`).
 
 Filter by type with `--type`:
 
 ```bash
 dotmd query --type plan --status active   # active plans
 dotmd list --type doc                     # all docs
-dotmd export --type research              # export research only
+dotmd export --type prompt                # export only saved prompts
 ```
 
 Customize types and their statuses in config with the `types` key. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs).
@@ -150,7 +150,6 @@ dotmd hud                    Three-line actionable triage (silent when clean —
 dotmd pickup <file>          Pick up a plan (in-session + print body or queued handoff)
 dotmd release [<file>]       Release in-session lease (alias: unpickup)
 dotmd handoff <file> [...]   Queue a resume-prompt sidecar + release
-dotmd finish <file>          Finish a plan (done or active)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
@@ -167,7 +166,8 @@ dotmd summary <file>         AI summary of a document
 dotmd glossary <term>        Look up domain terms + related docs
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
-dotmd new <name>             Create a new document from template
+dotmd new <type> <name>      Create a new doc (type: doc, plan, or prompt)
+dotmd prompts [sub]          List, claim, or archive saved prompts
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
 ```
@@ -197,32 +197,80 @@ dotmd query --status active --summarize --summarize-limit 3
 
 Flags: `--type`, `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
 
-### Scaffold with Templates
+### Create Documents
+
+The signature is `dotmd new <type> <name> [body]`. `<type>` is one of the built-in types (`doc`, `plan`, `prompt`) or a custom type from your config. If you omit `<type>`, it defaults to `doc`.
 
 ```bash
-dotmd new my-feature                                  # default (status + title)
-dotmd new my-plan --template plan                     # plan with module, surface, refs
-dotmd new my-decision --template adr                  # ADR: Context, Decision, Consequences
-dotmd new my-proposal --template rfc                  # RFC: Summary, Motivation, Design
-dotmd new my-audit --template audit                   # Audit: Scope, Findings, Recommendations
-dotmd new my-design --template design                 # Design: Goals, Non-Goals, Design
-dotmd new my-feature --status planned --title "Title" # custom status and title
-dotmd new my-doc --root modules                       # create in a specific root
-dotmd new --list-templates                            # show all available templates
+dotmd new plan auth-revamp                    # type: plan → docs/plans/auth-revamp.md
+dotmd new doc token-refresh-design            # type: doc → docs/token-refresh-design.md
+dotmd new my-feature                          # implicit type: doc
+dotmd new plan auth --status planned          # initial status override
+dotmd new doc my-doc --title "Custom Title"   # title override
+dotmd new doc my-doc --root modules           # create in a specific root
+dotmd new --list-types                        # show registered types
 ```
 
-Built-in templates: `default`, `plan`, `adr`, `rfc`, `audit`, `design`. Add custom templates in your config:
+Each built-in type has a template baked in:
+
+| Type | Default destination | Shape |
+|------|---------------------|-------|
+| `plan` | `docs/plans/<slug>.md` | Problem → Phases → Closeout, with phase status markers and Version History |
+| `doc` | `docs/<slug>.md` | Overview → Version History → Related (build-up shape lite) |
+| `prompt` | `docs/prompts/<slug>.md` | Body is required (see [Saved Prompts](#saved-prompts)) |
+
+Add custom types via `templates` in your config:
 
 ```js
 export const templates = {
   spike: {
     description: 'Timeboxed investigation',
-    frontmatter: (status, today) => `status: ${status}\nupdated: ${today}\ntimebox: 2d`,
+    defaultStatus: 'active',
+    targetRoot: 'spikes',  // in flat-array root configs, lands in the matching root
+    dir: 'spikes',          // in single-root configs, creates docs/spikes/<slug>.md
+    frontmatter: (status, today) => `type: spike\nstatus: ${status}\nupdated: ${today}\ntimebox: 2d`,
     body: (title) => `\n# ${title}\n\n## Hypothesis\n\n\n\n## Findings\n\n\n`,
   },
 };
 ```
 
+Then `dotmd new spike my-spike` creates a doc from your template.
+
+**Routing your custom type to a directory.** Two knobs:
+
+- `targetRoot: '<name>'` — name (basename or suffix) of a root entry. In configs with `root: ['docs/plans', 'docs/spikes', ...]` (flat-array layout), the new doc lands in the matching root.
+- `dir: '<subdir>'` — subdirectory under `config.docsRoot`. Used as the fallback when `targetRoot` doesn't match anything (typical single-root layout).
+
+Set both for portability. The `--root` CLI flag overrides both. **Overrides do not inherit builtin properties** — if you override `templates.prompt`, re-declare `targetRoot`, `dir`, `defaultStatus`, `requiresBody`, etc. that you want preserved.
+
+### Saved Prompts
+
+Saved prompts are `.md` files with `type: prompt` that capture a request meant to seed a future Claude session — "look at the remaining lint warnings tomorrow," "resume the payments refactor," "draft the on-call runbook." The body is the prompt; the frontmatter tracks status.
+
+```bash
+dotmd new prompt cleanup-tomorrow "look at remaining lint warnings"
+dotmd new prompt resume-foo - <<'EOF'
+multi-line
+prompt body
+EOF
+dotmd new prompt from-file @/tmp/draft.md
+```
+
+Manage them with the `prompts` command family:
+
+```bash
+dotmd prompts                     # list pending prompts (default)
+dotmd prompts list --all          # all statuses
+dotmd prompts next                # show + claim the oldest pending prompt (prints body)
+dotmd prompts use <file>          # claim a specific prompt (prints body, flips to claimed)
+dotmd prompts archive <file>      # archive a prompt
+dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
+```
+
+`dotmd hud` surfaces pending prompts on session start (alongside held leases and queued handoffs), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it.
+
+Statuses: `pending` (drafted, awaiting a session), `claimed` (consumed by a session), `archived`.
+
 ### Check & Fix
 
 ```bash
@@ -397,14 +445,18 @@ dotmd bulk archive docs/old-a.md docs/old-b.md   # archive multiple
 dotmd bulk archive docs/old-*.md -n               # preview
 ```
 
-### Pickup & Finish
+### Pickup & Closeout
 
 ```bash
 dotmd pickup docs/plans/my-plan.md       # set in-session + print body (or queued handoff)
-dotmd finish docs/plans/my-plan.md       # set done + bump date
-dotmd finish docs/plans/my-plan.md active  # back to active for more work
+dotmd archive docs/plans/my-plan.md      # fully shipped: archive + auto-release lease
+dotmd release docs/plans/my-plan.md      # need more work: release lease, flip to prior status
+dotmd status docs/plans/my-plan.md partial   # shipped + tail deferred (reference successors in body)
+dotmd status docs/plans/my-plan.md awaiting  # stuck on a human decision
 ```
 
+`finish` is a legacy command that defaults to `status: done`, which is no longer in the default plan vocabulary as of 0.16. Use `archive` (fully shipped) or `release` + `status` (anything else). If you need it back, add `done` to `types.plan.statuses` in your config.
+
 ### Handoff (resume-prompts attached to plans)
 
 When you're stopping mid-work and the next session will need to pick up where

package/bin/dotmd.mjs

@@ -571,12 +571,16 @@ Subcommands:
   list                       List pending prompts (default)
   next                       Consume the oldest pending prompt:
                              print body to stdout, flip status to archived
-  use <file>                 Consume a specific prompt (same as next, but
-                             targets <file> instead of picking oldest)
-  archive <file>             Archive a prompt without printing its body
+  use <file-or-slug>         Consume a specific prompt (same as next, but
+                             targets the named prompt instead of picking oldest)
+  archive <file-or-slug>     Archive a prompt without printing its body
   new <slug> [body]          Create a new prompt (alias for
                              \`dotmd new prompt <slug> [body]\`)
 
+\`<file-or-slug>\` accepts: an exact path (with or without .md), a bare
+slug matching a prompt basename, or a unique substring of a prompt
+path. Ambiguous substrings error with the candidate list.
+
 Default prompt statuses: pending, claimed, archived.
 
 Examples:
@@ -586,10 +590,11 @@ Examples:
   dotmd prompts --json                 # JSON output
 
   claude "$(dotmd prompts next)"       # consume oldest pending + run claude
-  claude "$(dotmd prompts use docs/prompts/foo.md)"
+  claude "$(dotmd prompts use resume-foo)"           # by slug
+  claude "$(dotmd prompts use docs/prompts/foo.md)"  # by path
 
   dotmd prompts next --dry-run         # preview without consuming
-  dotmd prompts archive docs/prompts/old.md
+  dotmd prompts archive old-thing
   dotmd prompts new my-prompt "Body text here"`,
 
   stale: `dotmd stale — list stale documents

package/dotmd.config.example.mjs

@@ -14,7 +14,7 @@ export const archiveDir = 'archived';
 export const excludeDirs = ['evidence'];
 
 // Document types — each type has its own status vocabulary and context layout.
-// Defaults: plan, doc, research. Override to customize statuses per type.
+// Defaults: plan, doc, prompt. Override to customize statuses per type, or add new types.
 //
 // Statuses can be defined as an array (names only) or as an object (rich form).
 // The object form co-locates all behavioral properties with each status,
@@ -66,6 +66,15 @@ export const excludeDirs = ['evidence'];
 //       'archived':   { context: 'counted', archive: true, terminal: true, quiet: true },
 //     },
 //   },
+//   prompt: {
+//     // Saved prompts that seed future Claude sessions. `dotmd hud` surfaces
+//     // pending prompts on session start; `dotmd prompts next` claims the oldest.
+//     statuses: {
+//       'pending':  { context: 'expanded', staleDays: 30 },
+//       'claimed':  { context: 'counted', quiet: true },
+//       'archived': { context: 'counted', archive: true, terminal: true, quiet: true },
+//     },
+//   },
 // };
 
 // ─── Array form (also supported) ────────────────────────────────────────────
@@ -166,6 +175,50 @@ export const presets = {
   mine: ['--owner', 'robert', '--status', 'active', '--all'],
 };
 
+// ─── Templates ───────────────────────────────────────────────────────────────
+// Define new types or override builtins. `dotmd new <type> <name>` looks here first.
+//
+// Properties:
+//   description:    string — shown in `dotmd new --list-types`
+//   defaultStatus:  string — initial status if `--status` not passed
+//   requiresBody:   boolean — error if no body input (see `prompt` builtin)
+//   targetRoot:     string — name (basename or suffix) of the root this type lives in.
+//                   In flat-array `root` configs (e.g. ['docs/plans', 'docs/prompts']),
+//                   the new doc lands in the matching root. Falls back to `config.docsRoot`
+//                   if no root matches. The `--root` CLI flag still overrides.
+//   dir:            string — subdirectory under `docsRoot` to use when `targetRoot` doesn't
+//                   match anything. Builtin `plan` and `prompt` set both for portability:
+//                   under `docsRoot='docs'`, `dir` puts files in `docs/plans/` and `docs/prompts/`;
+//                   under flat-array roots, `targetRoot` routes directly to the type-specific root.
+//   frontmatter:    (status, isoTime, ctx) => string
+//   body:           (title, ctx) => string
+//
+// Custom type example — adds a `spike` type that lives in the `spikes` root (or
+// under `docs/spikes/` in single-root layouts):
+// export const templates = {
+//   spike: {
+//     description: 'Timeboxed investigation',
+//     defaultStatus: 'active',
+//     targetRoot: 'spikes',  // for flat-array root configs
+//     dir: 'spikes',          // for single-root configs
+//     frontmatter: (s, d) => `type: spike\nstatus: ${s}\ncreated: ${d}\ntimebox: 2d`,
+//     body: (t) => `\n# ${t}\n\n## Hypothesis\n\n\n\n## Findings\n\n`,
+//   },
+//
+//   // Override a builtin (e.g. project-specific prompt frontmatter shape).
+//   // IMPORTANT: builtin properties are NOT inherited — re-declare `targetRoot`, `dir`,
+//   // `defaultStatus`, `requiresBody`, etc. that you want preserved.
+//   // prompt: {
+//   //   description: 'Project resume prompt',
+//   //   defaultStatus: 'pending',
+//   //   requiresBody: true,
+//   //   targetRoot: 'prompts',
+//   //   dir: 'prompts',
+//   //   frontmatter: (s, d, ctx) => `type: prompt\nstatus: ${s}\nproject_field: yes`,
+//   //   body: (t, ctx) => `\n${ctx?.bodyInput ?? ''}\n`,
+//   // },
+// };
+
 // ─── Notion ──────────────────────────────────────────────────────────────────
 // IMPORTANT: Use environment variables for tokens — never hardcode secrets in config files.
 // export const notion = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/init.mjs

@@ -169,7 +169,9 @@ export function runInit(cwd, config) {
     }
   }
 
-  process.stdout.write(`\nReady. Create your first doc:\n`);
-  process.stdout.write(`  dotmd new my-doc\n`);
-  process.stdout.write(`  dotmd list\n\n`);
+  process.stdout.write(`\nReady. A few starting points:\n`);
+  process.stdout.write(`  dotmd new doc my-doc            # scaffold a reference doc\n`);
+  process.stdout.write(`  dotmd new plan my-plan          # scaffold an execution plan\n`);
+  process.stdout.write(`  dotmd list                      # see what you've got\n`);
+  process.stdout.write(`  dotmd hud                       # session-start triage (ideal SessionStart hook)\n\n`);
 }

package/src/new.mjs

@@ -44,6 +44,7 @@ const BUILTIN_TEMPLATES = {
   plan: {
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
     dir: 'plans',
+    targetRoot: 'plans',
     defaultStatus: 'active',
     frontmatter: (s, d) => [
       'type: plan',
@@ -124,6 +125,7 @@ Status markers (put in heading text):
   prompt: {
     description: 'Saved prompt to seed a future Claude session — body is required',
     dir: 'prompts',
+    targetRoot: 'prompts',
     defaultStatus: 'pending',
     requiresBody: true,
     frontmatter: (s, d, ctx) => [
@@ -244,8 +246,11 @@ export async function runNew(argv, config, opts = {}) {
   // Title
   const docTitle = title ?? namePart.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 
-  // Resolve target root
+  // Resolve target root. Precedence: CLI --root > template.targetRoot > config.docsRoot.
+  // When the chosen root is a first-class type-container (matched by --root or targetRoot),
+  // we skip the `template.dir` join — the root already points at the right directory.
   let targetRoot = config.docsRoot;
+  let routedToTypeRoot = false;
   if (rootName) {
     const roots = config.docsRoots || [config.docsRoot];
     const match = roots.find(r => r.endsWith(rootName) || path.basename(r) === rootName);
@@ -254,10 +259,19 @@ export async function runNew(argv, config, opts = {}) {
       die(`Unknown root: ${rootName}\nAvailable: ${available}`);
     }
     targetRoot = match;
+    routedToTypeRoot = true;
+  } else if (typeof template === 'object' && template.targetRoot) {
+    const roots = config.docsRoots || [config.docsRoot];
+    const match = roots.find(r => r.endsWith(template.targetRoot) || path.basename(r) === template.targetRoot);
+    if (match) {
+      targetRoot = match;
+      routedToTypeRoot = true;
+    }
   }
 
-  // Template-declared subdirectory (e.g., prompt → 'prompts')
-  if (typeof template === 'object' && template.dir && !nameDir) {
+  // Template-declared subdirectory (e.g., prompt → 'prompts') — only relevant when we
+  // didn't already land in a type-specific root via --root or targetRoot.
+  if (typeof template === 'object' && template.dir && !nameDir && !routedToTypeRoot) {
     nameDir = path.join(path.relative(config.repoRoot, targetRoot), template.dir);
   }
 

package/src/prompts.mjs

@@ -1,4 +1,5 @@
 import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
 import { buildIndex } from './index.mjs';
@@ -74,11 +75,46 @@ function runPromptsNext(argv, config, opts = {}) {
   consumePrompt(head.abs, config, opts);
 }
 
+// Resolve user input to a prompt path. Tries (in order): exact path,
+// path + '.md', exact basename match across type: prompt docs, substring
+// match across type: prompt docs. Returns the absolute path or dies with a
+// helpful message (no match / ambiguous match).
+function resolvePromptInput(input, config) {
+  const direct = resolveDocPath(input, config);
+  if (direct) return direct;
+
+  if (!input.endsWith('.md')) {
+    const withExt = resolveDocPath(input + '.md', config);
+    if (withExt) return withExt;
+  }
+
+  const index = buildIndex(config);
+  const prompts = index.docs.filter(d => d.type === 'prompt');
+  if (prompts.length === 0) die(`No prompts in the index.`);
+
+  const slug = input.replace(/\.md$/, '');
+
+  const byBasename = prompts.filter(d => path.basename(d.path, '.md') === slug);
+  if (byBasename.length === 1) return path.resolve(config.repoRoot, byBasename[0].path);
+  if (byBasename.length > 1) {
+    die(`Multiple prompts match "${input}" by basename:\n${byBasename.map(d => '  ' + d.path).join('\n')}`);
+  }
+
+  const bySubstring = prompts.filter(d =>
+    d.path.includes(slug) || path.basename(d.path).includes(slug),
+  );
+  if (bySubstring.length === 1) return path.resolve(config.repoRoot, bySubstring[0].path);
+  if (bySubstring.length > 1) {
+    die(`Multiple prompts match "${input}":\n${bySubstring.map(d => '  ' + d.path).join('\n')}`);
+  }
+
+  die(`No prompt found matching: ${input}`);
+}
+
 function runPromptsUse(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts use <file>');
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
+  if (!input) die('Usage: dotmd prompts use <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
   consumePrompt(filePath, config, opts);
 }
 
@@ -113,9 +149,8 @@ function consumePrompt(filePath, config, opts) {
 
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts archive <file>');
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
+  if (!input) die('Usage: dotmd prompts archive <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);