project-mgr 0.3.2 → 0.5.0

package/skills/project-mgr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-mgr
-description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, start the local Web Dashboard, import status records, query current or historical project state, or export a status ledger.
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, start the local Web Dashboard, import status records, query current or historical project state, or export a status ledger. When one effort contains multiple sub-projects, ask whether they share one project name or should be distinguished with tags.
 ---
 
 # project-mgr
@@ -23,6 +23,7 @@ Completion links and version-2 exports require project-mgr 0.3.0 or later. This
 - Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
 - Explicitly pass `--status` on every `add`, and include `status` in every agent-authored import entry. The CLI defaults to `completed`; do not rely on that default. Choose the status from the evidence and inspect the current snapshot when unclear. Completing one activity does not necessarily complete the project; use `active` when project work continues. If the status remains uncertain, clarify before writing.
 - If the project is not yet in the ledger database, initialize its metadata with `set-project`. Backfill only milestones supported by verifiable Git commits, dated documents, or historical records, and include the evidence reference in `--progress`. Use historical `--at` timestamps only when supported by that evidence; a commit timestamp proves a commit, not a deployment. There is no required number of entries. Never invent milestones or dates; when evidence is unavailable, skip backfill and append only the current known status.
+- If one effort contains multiple sub-projects and the user has not already chosen how to identify them, ask before writing. See "Multiple sub-projects".
 
 ## Metadata vs. status entries
 
@@ -31,7 +32,20 @@ Completion links and version-2 exports require project-mgr 0.3.0 or later. This
   - **Do NOT** put transient progress, session logs, or one-off status messages into `--notes`.
   - Avoid passing `--notes` during routine `add` commands to prevent accidentally overwriting long-term project notes.
 - **Project description (`--description`)**: A high-level, stable summary of the project's purpose.
-- **Status snapshots (`add`)**: Use `--summary` (concise milestone headline), `--progress` (detailed work accomplished), `--next` (immediate next steps), `--blocker` (current obstacles), and `--decision` for transactional, append-only updates.
+- **Status snapshots (`add`)**: Use `--summary` (concise milestone headline), `--progress` (detailed work accomplished), `--next` (immediate next steps), `--blocker` (current obstacles), `--decision`, and repeatable `--tag` for transactional, append-only updates.
+
+## Multiple sub-projects
+
+One repository or effort may contain several sub-projects, such as separate packages, apps, services, or contracts. `--project` is the ledger identity: current status, history, and completion links all belong to that slug. `--tag` is a repeatable label on a single status snapshot. Tags do not create a project, a separate current status, or a separate completion history. `projects` / `list --query` can match tags on the latest snapshot.
+
+When several sub-projects are in scope and the user has not already chosen how to identify them, ask before the first write. Do not decide silently. Do not create a separate project slug per sub-project unless the user explicitly asks for separate ledger projects.
+
+Offer these two choices:
+
+1. **Share one project name.** Append every sub-project to the same `--project`. Use this when the user wants one current status and one history for the whole effort. Do not add sub-project tags unless the user also asks for them.
+2. **Distinguish sub-projects with tags.** Keep that same `--project`, and pass repeatable `--tag` values naming the sub-project this snapshot covers, for example `--project acme --tag web`. Reuse the same tag on later updates for that sub-project. A tag describes that snapshot only; older snapshots keep the tags they were written with. Search with `pmgr list --query web --json`. Completion links still apply to the whole project, so link an earlier entry only when this update resolves all of that entry's commitments.
+
+Follow a choice the user already recorded. Do not store the choice in `--notes` unless the user asks; notes are long-term project context, and `set-project --notes` replaces them.
 
 ## Operations
 
@@ -50,8 +64,14 @@ pmgr list --query "keyword" --json
 pmgr serve --port 3000 --no-open --json
 
 # Record a completed milestone while the project remains active.
+# --next creates Todos and stores their UIDs on the snapshot. Reuse work with --next-todo.
 pmgr add --project my-project --status active --summary "Implemented the CLI" \
   --progress "Tests pass" --next "Publish the package" --source agent --json
+pmgr todos --project my-project --status open --json
+
+# Same project, with a tag naming the sub-project this snapshot covers.
+pmgr add --project acme --status active --summary "Shipped the web dashboard" \
+  --tag web --source agent --json
 
 # Query current state, history, or state at a time.
 pmgr current --project my-project --json
@@ -74,4 +94,4 @@ When this update resolves all commitments of earlier entries (including blockers
 
 Use `complete --entry <id-or-uid> --by <id-or-uid> --source agent` for an existing follow-up. Use `revoke-completion --entry <id-or-uid> --by <id-or-uid> --reason "..." --source agent` to correct a mistaken link. Links require the same project and strictly increasing occurrence times. Query the affected history afterward to verify effective completion. Do not bulk-close old entries without evidence.
 
-Export produces version-2 bundles (one bundle per line for JSONL), preserving entry/event identities and audit history; legacy imports remain supported. `at` has no completion annotations. Project current state still comes from the latest snapshot.
+Export produces a version-2 bundle when there are no Todos or refs, version 3 when Todos exist without refs, and version 4 when snapshots store `nextTodoUids` (one bundle per line for JSONL). Legacy imports remain supported and do not create Todos. Open work is `todos --status open`; current `nextTodoUids` only order that project's open items. Do not combine `--next` with `--next-todo`. Repeating `--next` text on a later snapshot creates a new Todo; pass existing UIDs to keep the same work. Cancelling or completing a Todo is `todo-update`, not deleting text from a snapshot. `at` has no completion annotations and does not resolve live Todo status. Project current state still comes from the latest snapshot.