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/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: 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