Document issue timeline and issue wakeup for CLI v0.6.x, raise floor to v0.6.0

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Teach a local coding agent to operate Multica through the authenticated multica CLI",
-    "version": "1.1.0"
+    "version": "1.2.0"
   },
   "plugins": [
     {
       "name": "multica-cli",
       "source": "./",
       "description": "Operate Multica from a local coding agent via the multica CLI: issues, comments, metadata, mentions, and status side effects.",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "author": {
         "name": "multica-ai"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "multica-cli",
   "description": "Teach a local coding agent to operate Multica through the authenticated multica CLI.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": {
     "name": "multica-ai"
   },

.cursor/rules/multica-cli.mdc

@@ -10,7 +10,7 @@ Use the local `multica` CLI as the source of truth for all Multica operations.
 This rule does not grant permissions — they come only from the user's installed,
 logged-in CLI and explicit approval to run commands.
 
-**Requires `multica` v0.4.26 or newer.** Commands below (notably `--no-start`)
+**Requires `multica` v0.6.0 or newer.** Commands below (notably `issue wakeup` and `--no-start`)
 do not exist in earlier versions. Check with `multica version`; if it reports
 anything older, stop and ask the user to upgrade
 (`brew upgrade multica-ai/tap/multica`, or `multica update`) instead of working

CURSOR.md

@@ -2,8 +2,8 @@
 
 There are two ways to use the Multica CLI skill in Cursor.
 
-Both require the `multica` CLI at **v0.4.26 or newer** — earlier versions lack
-commands the skill and the rule rely on (notably `--no-start`). Check with
+Both require the `multica` CLI at **v0.6.0 or newer** — earlier versions lack
+commands the skill and the rule rely on (notably `issue wakeup` and `--no-start`). Check with
 `multica version`.
 
 ## Option 1: Personal Agent Skill (recommended)

README.md

@@ -70,8 +70,8 @@ your tool loads skills or instructions from.
 
 ## Requirements
 
-- The `multica` CLI is installed locally, at **v0.4.26 or newer**. Earlier
-  versions lack commands the skill relies on (notably `--no-start`), and will
+- The `multica` CLI is installed locally, at **v0.6.0 or newer**. Earlier
+  versions lack commands the skill relies on (notably `issue wakeup` and `--no-start`), and will
   reject them. Check with `multica version`.
 - The user has run `multica login` (or `multica setup`) to authenticate.
 - The intended workspace/profile is selected, or passed explicitly with

README.zh.md

@@ -67,8 +67,8 @@ cp -R skills/multica-cli/* ~/.cursor/skills/multica-cli/
 
 ## 前置条件
 
-- 本机已安装 `multica` CLI，且版本 **不低于 v0.4.26**。更早的版本缺少本 skill 依赖的
-  命令（尤其是 `--no-start`），会直接报错。可用 `multica version` 确认。
+- 本机已安装 `multica` CLI，且版本 **不低于 v0.6.0**。更早的版本缺少本 skill 依赖的
+  命令（尤其是 `issue wakeup` 和 `--no-start`），会直接报错。可用 `multica version` 确认。
 - 用户已通过 `multica login`（或 `multica setup`）完成认证。
 - 已选择目标 workspace / profile，或通过 `--workspace-id`、`--profile` 显式传入。
 

scripts/lint-skill-commands.py

@@ -34,9 +34,10 @@
 
 # The oldest CLI every documented command works on. Raising this is a real
 # compatibility decision — the docs tell users to upgrade to it, so CI lints
-# against this version as well as the newest one. `--no-start` is what pins it
-# to 0.4.26; it does not exist in 0.4.25.
-MIN_CLI_VERSION = "0.4.26"
+# against this version as well as the newest one. `issue wakeup` is what pins
+# it to 0.6.0: 0.5.x ships an older wakeup without `runs`, `delete`, `checkin`,
+# `--until-status`, `--expires-in` and `--max-fires`.
+MIN_CLI_VERSION = "0.6.0"
 
 # Files that must state the minimum, so a reader learns it wherever they land.
 # Every file here is something a user can install *on its own* — the Cursor rule
@@ -68,7 +69,6 @@
 UNDOCUMENTED_OK = {
     "daemon": "runtime host concern, not an agent operation",
     "update": "CLI self-update, belongs in install docs",
-    "plugin": "workspace-private plugin authoring, out of scope for issue work",
     "issue reorder": "board cosmetics; no agent workflow needs it",
 }
 

scripts/test-lint.py

@@ -50,8 +50,9 @@ def run_case(linter, *, skill_body: str, undocumented_ok: dict[str, str] | None
         linter.DOC_FILES = [skill_rel]
         linter.COVERAGE_FILE = skill_rel
         linter.VERSION_DECLARED_IN = []
-        if undocumented_ok is not None:
-            linter.UNDOCUMENTED_OK = undocumented_ok
+        # Never inherit the real allowlist: when the CLI drops a command it
+        # exempts, every fixture would fail as "stale" and mask the drift report.
+        linter.UNDOCUMENTED_OK = undocumented_ok or {}
         try:
             return linter.check_validity(False) + linter.check_coverage(False)
         finally:

skills/multica-cli/SKILL.md

@@ -20,13 +20,23 @@ multica auth status
 multica config show
 ```
 
-**This skill requires `multica` v0.4.26 or newer.** Several commands it relies
-on — notably `--no-start` on `issue status` / `assign` / `update` — do not exist
+**This skill requires `multica` v0.6.0 or newer.** Several commands it relies
+on — notably `issue wakeup`, and `--no-start` on `issue status` / `assign` /
+`update` — do not exist
 in earlier versions, and an older CLI will reject them outright. If
-`multica version` reports anything below 0.4.26, stop and ask the user to
+`multica version` reports anything below 0.6.0, stop and ask the user to
 upgrade (`brew upgrade multica-ai/tap/multica`, or `multica update`) rather than
 working around the missing flags.
 
+**This file was last checked against `multica` v0.6.2.** The CLI ships faster
+than this skill. When `multica version` reports a newer version, assume
+commands or flags exist that this file does not describe: treat
+`multica <command> --help` as the source of truth, and check `multica --help`
+and `multica issue --help` before telling the user the CLI cannot do something.
+If this skill sits inside a checkout or plugin install of its repository,
+`scripts/lint-skill-commands.py` (two directories above this file) lists the
+drift in under a second; it only runs `--help`.
+
 If `multica auth status` reports no active session, the CLI is not logged in.
 Stop and have the user authenticate; do not try to fake credentials:
 
@@ -65,6 +75,7 @@ multica issue search <query> [--include-closed] [--limit N] --output json
 multica issue children <id> --output json
 multica issue pull-requests <id> --output json
 multica issue metadata list <id> --output json
+multica issue timeline <id> [--activity-only] [--action <a,...>] [--since <RFC3339>] [--tail N] --output json
 
 # Comments (read) — see Reading Comments below before picking a mode
 multica issue comment list <id> --roots-only --summary --compact --output json   # scan threads cheaply
@@ -112,6 +123,15 @@ multica issue run-messages <task-id> [--issue <issue-id>] [--since N] --output j
 multica issue usage <issue-id> --output json
 multica issue rerun <id> --output json
 multica issue cancel-task <task-id> [--issue <issue-id>]
+
+# Wakeups — rules that start agent runs later; see Wakeups below
+multica issue wakeup list <issue-id> --output json
+multica issue wakeup get <issue-id> <wakeup-id> --output json
+multica issue wakeup runs <issue-id> <wakeup-id> --output json
+multica issue wakeup events
+multica issue wakeup create <issue-id> (--event <type> | --until-status <s> | --kind at --after 10m | --kind every --every 1h | --kind cron --cron "<expr>") [--agent-id <uuid>] [--instruction-file <path>] [--expires-in 72h] [--max-fires N] [--parent <comment-id>]
+multica issue wakeup disable <issue-id> <wakeup-id>
+multica issue wakeup delete <issue-id> <wakeup-id>
 ```
 
 Note `issue assign` uses `--to` / `--to-id`, while `issue create` / `issue
@@ -321,8 +341,13 @@ instead of guessing from comments.
 multica issue runs <issue-id> --output json                       # what ran, and how it ended
 multica issue run-messages <task-id> --issue <issue-id> --output json  # what that run actually did
 multica issue usage <issue-id> --output json                      # aggregated token cost
+multica issue timeline <issue-id> --activity-only --output json   # status/assignee changes and run outcomes, oldest first
 ```
 
+`issue get` is the current state; `issue timeline` explains how the issue got
+there. A status change writes an activity record, never a comment, so "when did
+this move to in_review?" is answered by the timeline, not the comment list.
+
 `--issue` lets you pass a short task-id prefix instead of the full UUID.
 
 Two controls are genuinely disruptive — confirm both with the user first:
@@ -335,6 +360,23 @@ multica issue cancel-task <task-id> --issue <issue-id>   # interrupt a running a
 `cancel-task` interrupts an in-flight agent, so work in progress is lost. Never
 run it to "clean up" state you have not read.
 
+## Wakeups
+
+A wakeup is a rule on an issue that starts an ordinary agent run later: on an
+event (`--event`, see `multica issue wakeup events`), when a condition holds
+(`--until-status`, `--until-children-done`, `--until-pr`, ...), or on a timer
+(`--kind at|every|cron`). Every fire is a paid run, so creating, triggering or
+re-enabling one is a write that needs the user's approval.
+
+- Read before you write: `multica issue wakeup list <issue-id> --output json`.
+- Bound every repeating or waiting rule with `--expires-in` / `--expires-at` or
+  `--max-fires`; an unbounded `every` rule is a standing cost.
+- `create` replaces the complete configuration of that rule, it does not merge.
+- `multica issue wakeup checkin` is only for a run that an `every` or `cron`
+  wakeup started and that found nothing to report; it ends the run silently.
+- To stop a rule, `disable` keeps it for later; `delete` also withdraws runs
+  that have not started.
+
 ## Pull Requests
 
 When code changes are made for a Multica issue, include the routable issue key