From 124812873c8320a4ee27bbc0e64048b0eafac242 Mon Sep 17 00:00:00 2001 From: Maarten Carbonez Date: Tue, 13 Oct 2026 17:11:58 +0200 Subject: [PATCH 1/2] Document issue timeline and issue wakeup for CLI v0.6.x, raise floor to v0.6.0 The daily lint against the latest CLI has failed since the CLI added issue timeline and issue wakeup. Document both, drop the stale plugin entry from UNDOCUMENTED_OK, and tell agents to treat --help as the source of truth when the installed CLI is newer than the version the skill was last checked against. issue wakeup as documented (runs, delete, checkin, --until-status, --expires-in, --max-fires) first ships in v0.6.0; 0.5.x has an older shape. Raise MIN_CLI_VERSION and every stated minimum to 0.6.0, and bump the plugin to 1.2.0. --- .claude-plugin/marketplace.json | 4 +-- .claude-plugin/plugin.json | 2 +- .cursor/rules/multica-cli.mdc | 2 +- CURSOR.md | 4 +-- README.md | 4 +-- README.zh.md | 4 +-- scripts/lint-skill-commands.py | 8 +++--- skills/multica-cli/SKILL.md | 48 ++++++++++++++++++++++++++++++--- 8 files changed, 59 insertions(+), 17 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 511e2e0..5b79ca8 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b04db2e..36bfc74 100644 --- a/.claude-plugin/plugin.json +++ b/.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" }, diff --git a/.cursor/rules/multica-cli.mdc b/.cursor/rules/multica-cli.mdc index c09cb45..9fb36fb 100644 --- a/.cursor/rules/multica-cli.mdc +++ b/.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 diff --git a/CURSOR.md b/CURSOR.md index 4ea3f61..6ed86e7 100644 --- a/CURSOR.md +++ b/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) diff --git a/README.md b/README.md index 562a1bd..1d16e5e 100644 --- a/README.md +++ b/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 diff --git a/README.zh.md b/README.zh.md index 42550e1..0b84670 100644 --- a/README.zh.md +++ b/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` 显式传入。 diff --git a/scripts/lint-skill-commands.py b/scripts/lint-skill-commands.py index 0b0d0b3..d8d5c45 100755 --- a/scripts/lint-skill-commands.py +++ b/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", } diff --git a/skills/multica-cli/SKILL.md b/skills/multica-cli/SKILL.md index bb1b237..0db17fb 100644 --- a/skills/multica-cli/SKILL.md +++ b/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 --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 [--include-closed] [--limit N] --output json multica issue children --output json multica issue pull-requests --output json multica issue metadata list --output json +multica issue timeline [--activity-only] [--action ] [--since ] [--tail N] --output json # Comments (read) — see Reading Comments below before picking a mode multica issue comment list --roots-only --summary --compact --output json # scan threads cheaply @@ -112,6 +123,15 @@ multica issue run-messages [--issue ] [--since N] --output j multica issue usage --output json multica issue rerun --output json multica issue cancel-task [--issue ] + +# Wakeups — rules that start agent runs later; see Wakeups below +multica issue wakeup list --output json +multica issue wakeup get --output json +multica issue wakeup runs --output json +multica issue wakeup events +multica issue wakeup create (--event | --until-status | --kind at --after 10m | --kind every --every 1h | --kind cron --cron "") [--agent-id ] [--instruction-file ] [--expires-in 72h] [--max-fires N] [--parent ] +multica issue wakeup disable +multica issue wakeup delete ``` Note `issue assign` uses `--to` / `--to-id`, while `issue create` / `issue @@ -321,8 +341,13 @@ instead of guessing from comments. multica issue runs --output json # what ran, and how it ended multica issue run-messages --issue --output json # what that run actually did multica issue usage --output json # aggregated token cost +multica issue timeline --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 --issue # 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 --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 From 004cc2c706003085ef484378534514db31b2a2bd Mon Sep 17 00:00:00 2001 From: mcarbone Date: Sun, 18 Oct 2026 00:31:17 +0200 Subject: [PATCH 2/2] Isolate lint regression tests from the real UNDOCUMENTED_OK The fixtures inherited the repo's allowlist, so when the CLI dropped an exempted command (plugin, in v0.6.2) every expect-no-errors case failed as "stale" and CI stopped before the real drift report ran. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015FeG6aNDiBWFZNWTagUHVW --- scripts/test-lint.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/test-lint.py b/scripts/test-lint.py index 9ec0ba7..1f515d5 100755 --- a/scripts/test-lint.py +++ b/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: