diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 511e2e0..f44d1ff 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,14 +5,14 @@ "name": "multica-ai" }, "metadata": { - "description": "Teach a local coding agent to operate Multica through the authenticated multica CLI", + "description": "Operate Multica and orchestrate workspace-aware business workflows through the authenticated multica CLI", "version": "1.1.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.", + "description": "Operate Multica and turn business goals into workspace-aware execution plans through the authenticated multica CLI.", "version": "1.1.0", "author": { "name": "multica-ai" diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b04db2e..9312779 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "multica-cli", - "description": "Teach a local coding agent to operate Multica through the authenticated multica CLI.", + "description": "Operate Multica and orchestrate workspace-aware business workflows through the authenticated multica CLI.", "version": "1.1.0", "author": { "name": "multica-ai" diff --git a/.cursor/rules/multica-cli.mdc b/.cursor/rules/multica-cli.mdc index c09cb45..7d602e5 100644 --- a/.cursor/rules/multica-cli.mdc +++ b/.cursor/rules/multica-cli.mdc @@ -43,6 +43,9 @@ around the missing flags. - **Never store or expose tokens**, and never bypass workspace permissions via private HTTP APIs. - **Say when the CLI can't do it.** Name the step and point at Multica Web rather than letting a partial run read as a completed one. +- **Orchestrate open-ended business goals.** Search only relevant workspace resources, + synthesize existing context and capabilities, prefer reuse, then present one complete + execution plan for confirmation. Follow `references/orchestration.md` for the full flow. ## Full reference diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 8b37adb..3c93468 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -78,6 +78,9 @@ jobs: - name: Lint regression tests run: scripts/test-lint.py + - name: Business orchestration contract + run: python3 scripts/test-orchestration-contract.py + - name: Lint documented commands run: | if [ "${{ matrix.cli }}" = "min" ]; then diff --git a/EXAMPLES.md b/EXAMPLES.md index 4255e0c..ef8cde3 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -54,6 +54,31 @@ multica issue assign --to-id `issue create` refuses when an active duplicate already exists. Read that issue before reaching for `--allow-duplicate`. +## Turn a business goal into an execution plan + +> Find the team's existing data-labeling workflow and capabilities, then plan +> weekly rainy-day dataset labeling. Execute it after I confirm. + +The agent should inspect relevant existing resources, including Issue +discussions where prior decisions may live, and synthesize what can be reused. +It then presents the complete resource choices, capability gaps, mutations, +dependencies, and acceptance criteria, and can execute it after one +confirmation: + +```bash +multica issue search "rainy data labeling" --include-closed --output json +multica project list --output json +multica agent list --output json +multica skill list --output json +multica autopilot list --output json +``` + +This is targeted discovery, not a full workspace dump. The agent gets details +only for plausible matches, cites their identifiers in the proposal, prefers +reuse when behavior need not change, and treats unknown sharing as shared. A +material difference discovered during execution pauses the affected step for a +revised confirmation. + ## Record progress without starting another run > Mark MUL-123 in progress — I'm already working on it. diff --git a/README.md b/README.md index 562a1bd..934127e 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ A portable skill that teaches any local coding agent — Claude Code, Codex, Cur and others — how to operate [Multica](https://github.com/multica-ai/multica) through the authenticated `multica` CLI: read and triage issues, reply to comments safely, manage metadata, and handle mention/status side effects. +For open-ended goals, it can discover relevant workspace context and +capabilities so teams reuse existing work instead of rebuilding it. English | [简体中文](./README.zh.md) @@ -31,6 +33,14 @@ drive Multica safely; it never bypasses workspace permissions or stores secrets. - Inspecting run history and token usage; cancelling a run when asked - Linking pull requests back to Multica issues - Saying so plainly when the CLI cannot do something, instead of faking it +- Turning open-ended goals into executable plans through targeted workspace + discovery +- Summarizing existing team context and matching available Agent and Skill + capabilities +- Reusing existing work instead of rebuilding it, with sharing-risk checks +- Presenting the complete business orchestration plan for one confirmation, + then executing it in dependency order (Agent and Skill mutations are + confirmed separately) ## Install @@ -85,6 +95,13 @@ Ask your agent to work with Multica once the skill is installed, for example: Read MUL-123 with the multica CLI and draft a reply for me to review. ``` +Or give it an outcome and let it find the relevant workspace context first: + +```text +Find the team's existing data-labeling workflow and capabilities, then propose +a plan for weekly rainy-day dataset labeling. Execute it after I confirm. +``` + For write operations (comments, status changes, mentions, new issues), the agent should ask before making state changes unless you have already clearly authorized that exact action. See [EXAMPLES.md](./EXAMPLES.md) for more. @@ -96,6 +113,7 @@ linted against a real `multica` binary: ```bash scripts/lint-skill-commands.py # or --verbose to see every check +python3 scripts/test-orchestration-contract.py ``` It fails when a documented command or flag no longer exists, and when a CLI diff --git a/README.zh.md b/README.zh.md index 42550e1..1fb3801 100644 --- a/README.zh.md +++ b/README.zh.md @@ -28,6 +28,11 @@ profile、当前 workspace，以及对每条命令的显式授权。这个 skill - 查看 run 历史与 token 用量；在被要求时取消 run - 把 pull request 关联回 Multica issue - CLI 做不到的事直说，并指向 Multica Web，而不是假装已完成 +- 针对开放式业务目标，定向检索 workspace 内相关资源并形成可执行方案 +- 归纳团队已有业务信息，匹配 Agent、Skill 等现有能力 +- 优先复用已有成果、避免重复建设，并根据共享风险决定是否新建隔离资源 +- 在聊天中展示完整业务编排方案，用户一次确认后按依赖顺序执行（Agent / Skill + 变更仍需单独确认） ## 安装 @@ -80,6 +85,12 @@ cp -R skills/multica-cli/* ~/.cursor/skills/multica-cli/ 用 multica CLI 读一下 MUL-123，帮我起草一条回复让我 review。 ``` +也可以直接描述业务目标，让 agent 先查找 workspace 内已有信息和能力： + +```text +查找团队已有的数据送标流程和能力，设计每周雨天数据送标方案，等我确认后执行。 +``` + 对于写操作（评论、状态变更、mention、新建 issue），除非用户已经明确授权这个具体动作， 否则 agent 应在改动状态前先确认。更多示例见 [EXAMPLES.md](./EXAMPLES.md)。 @@ -90,6 +101,7 @@ cp -R skills/multica-cli/* ~/.cursor/skills/multica-cli/ ```bash scripts/lint-skill-commands.py # 加 --verbose 可看到每一条检查 +python3 scripts/test-orchestration-contract.py ``` 当文档里写的命令或 flag 已经不存在、或者 CLI 里有 `SKILL.md` 从未提及的命令时， diff --git a/scripts/lint-skill-commands.py b/scripts/lint-skill-commands.py index 0b0d0b3..44696d1 100755 --- a/scripts/lint-skill-commands.py +++ b/scripts/lint-skill-commands.py @@ -54,6 +54,7 @@ # docs that get copy-pasted just as often, so they rot the same way. DOC_FILES = [ "skills/multica-cli/SKILL.md", + "skills/multica-cli/references/orchestration.md", "EXAMPLES.md", "README.md", "README.zh.md", diff --git a/scripts/test-orchestration-contract.py b/scripts/test-orchestration-contract.py new file mode 100644 index 0000000..c0bbb7f --- /dev/null +++ b/scripts/test-orchestration-contract.py @@ -0,0 +1,96 @@ +#!/usr/bin/env python3 +"""Pin the portable Skill's business-orchestration behavior.""" + +from __future__ import annotations + +import sys +from pathlib import Path + + +ROOT = Path(__file__).resolve().parent.parent + + +def require(path: str, anchors: list[str], failures: list[str]) -> None: + target = ROOT / path + if not target.is_file(): + failures.append(f"{path}: file is missing") + return + content = " ".join(target.read_text(encoding="utf-8").split()) + for anchor in anchors: + if anchor not in content: + failures.append(f"{path}: missing {anchor!r}") + + +def main() -> int: + failures: list[str] = [] + + require( + "skills/multica-cli/SKILL.md", + [ + "open-ended business goal", + "references/orchestration.md", + "Route by intent, not resource count", + ], + failures, + ) + require( + "skills/multica-cli/references/orchestration.md", + [ + "targeted read-only discovery", + "Issues, Projects, Agents, Squads, Skills, and Autopilots", + "search or list first", + "business context and available capabilities", + "dedicated", + "shared", + "unknown", + "Treat unknown as shared", + "Prefer reuse over creating a duplicate", + "The in-chat orchestration design is the execution plan", + "one user confirmation", + "execute the plan directly", + "separate confirmation immediately before changing an Agent or Skill", + "material deviation", + "Multica Web", + ], + failures, + ) + require( + "README.md", + [ + "targeted workspace discovery", + "reuse existing work instead of rebuilding it", + "one confirmation", + ], + failures, + ) + require( + "README.zh.md", + [ + "定向检索", + "避免重复建设", + "一次确认", + ], + failures, + ) + require( + "EXAMPLES.md", + [ + "Turn a business goal into an execution plan", + "inspect relevant existing resources", + "execute it after one confirmation", + ], + failures, + ) + + if failures: + print(f"{len(failures)} orchestration contract check(s) failed:", file=sys.stderr) + for failure in failures: + print(f" - {failure}", file=sys.stderr) + return 1 + + print("Business orchestration contract passed.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/multica-cli/SKILL.md b/skills/multica-cli/SKILL.md index bb1b237..d98b1a2 100644 --- a/skills/multica-cli/SKILL.md +++ b/skills/multica-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: multica-cli -description: "Use when a local coding agent (Codex, Claude Code, Cursor, or similar) needs to operate Multica through the authenticated `multica` CLI: reading or updating issues, comments, metadata, labels, custom properties, subscribers, projects, agents, squads, runtimes, repos, skills, autopilots, attachments, or workspace state; searching issues; inspecting or cancelling agent runs; replying to a Multica issue from an external agent; creating or triaging issues; checking linked pull requests; or safely handling Multica mention/status side effects without relying on the Multica hosted agent runtime." +description: "Use when a local coding agent (Codex, Claude Code, Cursor, or similar) needs to operate Multica through the authenticated `multica` CLI: reading or updating issues, comments, metadata, labels, custom properties, subscribers, projects, agents, squads, runtimes, repos, skills, autopilots, attachments, or workspace state; turning an open-ended business goal into a workflow; searching issues; inspecting or cancelling agent runs; replying to a Multica issue from an external agent; creating or triaging issues; checking linked pull requests; or safely handling Multica mention/status side effects without relying on the Multica hosted agent runtime." --- # Multica CLI @@ -173,6 +173,14 @@ with that number, and the prefix is not validated — pasting an identifier from another tracker can put an unrelated local issue at the top. The `match_source` field is a display hint, not a filter. +## Business Goal Orchestration + +For an open-ended business goal, resource-selection question, automation, or +set of dependent writes, read `references/orchestration.md` before proposing a +solution or changing state. Route by intent, not resource count. A concrete +operation on a known target stays in the direct read/write workflow in this +file. + ## Write Workflow Treat writes as side-effecting. If the user did not clearly ask for the write, diff --git a/skills/multica-cli/agents/openai.yaml b/skills/multica-cli/agents/openai.yaml index a878dca..1c1670a 100644 --- a/skills/multica-cli/agents/openai.yaml +++ b/skills/multica-cli/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Multica CLI" - short_description: "Operate Multica through the local CLI" - default_prompt: "Use $multica-cli to work with a Multica issue through the authenticated local CLI." + short_description: "Operate and orchestrate Multica through the local CLI" + default_prompt: "Use $multica-cli to operate Multica or turn a business goal into a workspace-aware execution plan through the authenticated local CLI." diff --git a/skills/multica-cli/references/orchestration.md b/skills/multica-cli/references/orchestration.md new file mode 100644 index 0000000..4c590a0 --- /dev/null +++ b/skills/multica-cli/references/orchestration.md @@ -0,0 +1,141 @@ +# Business Goal Orchestration + +Use this workflow when the user gives an outcome rather than a specific Multica +command: finding existing team knowledge, selecting capable resources, +coordinating dependent work, or defining a recurring automation. Keep a +concrete operation on a known target in the direct workflow from `SKILL.md`. + +## Clarify only material facts + +Resolve the profile and workspace first. Ask only for missing facts that change +the result: outcome, deliverable, frequency, data sources, constraints, +deadline, and acceptance criteria. Present two or more mutually exclusive +choices as a numbered list and accept a number-only reply. + +Classify the goal before choosing resources: + +- **one-time:** one Issue, optionally assigned to an Agent or attached to a + Project; +- **recurring:** an Autopilot whose description is the complete task prompt; +- **coordinated:** a parent Issue with staged child Issues, optionally using a + Squad when role separation adds real value. + +## Discover and synthesize + +The request authorizes targeted read-only discovery, not a full workspace +inventory. Query only resources that may supply relevant business context and +available capabilities: Issues, Projects, Agents, Squads, Skills, and +Autopilots. For each relevant resource, search or list first, then get only +plausible candidates. + +```bash +multica issue search "" --include-closed --output json +multica project list --output json +multica agent list --output json +multica squad list --output json +multica skill list --output json +multica autopilot list --output json +``` + +Use each namespace's `get --output json` command only for candidates that +may affect the proposal. Compare actual descriptions, instructions, bindings, +membership, status, active use, and relevant Issue discussions; do not select +a resource by name alone. + +Synthesize the evidence before proposing work: + +- what the workspace already knows about the goal; +- which existing resources provide each required capability; +- what is already in progress or previously decided; +- genuine capability or ownership gaps; +- source resource identifiers for every material conclusion. + +This synthesis is how the user discovers team knowledge and capabilities +without rebuilding work or creating a second, inconsistent source of truth. + +## Match capabilities and sharing risk + +Classify every resource that might be changed: + +- **dedicated:** evidence shows it serves this goal and has no known active + external dependency; +- **shared:** another Project, Squad, Autopilot, active Issue, or workflow uses + it; +- **unknown:** the available CLI reads cannot establish either state. + +Treat unknown as shared. Prefer reuse over creating a duplicate when an +existing resource matches the purpose and can be used unchanged. Modify a +dedicated resource only when the evidence is sufficient. Keep shared and +unknown resources unchanged; if reuse would alter their behavior, propose an +isolated resource instead. + +Use a Squad only when coordination or role separation adds value. An Autopilot +assigns an Agent, not a Squad; recurring coordinated work can assign the Squad +leader Agent and let that leader coordinate member Agents through child Issues. + +## Protect Agents and Skills + +Treat Agent and Skill mutations as high impact. Prefer an existing capable +Agent and already-installed Skills. The complete plan must show the exact +create, update, import, delete, binding, instruction, runtime, model, +permission, and environment delta without secret values. + +The plan-level approval is not enough for these mutations: get separate +confirmation immediately before changing an Agent or Skill. Assigning an +unchanged Agent to an Issue or adding it to a Squad uses the Agent without +changing its configuration, so the plan-level confirmation is sufficient. + +When no maintained Skill supplies a required capability, offer two choices: + +1. put clearly marked temporary instructions in the Issue or Autopilot + description when the Agent already has the required tools, permissions, + credentials, and data access; +2. stop while the user creates or imports a maintained Skill. + +Instructions cannot provide a missing tool or permission. For recurring work, +put the complete temporary instruction in the Autopilot description and remind +the user that stable rules belong in a maintained Skill. + +## Present one executable plan + +The in-chat orchestration design is the execution plan. It contains: + +- goal, deliverables, frequency, and acceptance criteria; +- relevant existing resources and the evidence for reuse or isolation; +- capability coverage and genuine gaps; +- task breakdown, dependencies, and every proposed mutation; +- the Agent, Squad, Issue, Project, Skill, and Autopilot relationships; +- temporary instructions and their limitations; +- CLI-unsupported steps that must be completed in Multica Web; +- risks, verification, and resume behavior. + +Get one user confirmation for the complete plan, except for the separate +Agent/Skill confirmation above. After confirmation, execute the plan directly +in dependency order. Do not create a repository design document, +specification, or software implementation plan unless the user explicitly asks +for that artifact. + +Approval covers only the listed mutations in the stated workspace. A material +deviation in target, fields, resource choice, dependency, or impact stops +execution before the changed step. Show the difference and request revised +confirmation; never adapt silently. + +## Execute and resume + +Use only the authenticated `multica` CLI and record returned resource IDs for +dependent steps. Keep work passive only while dependencies are incomplete: + +1. create or verify passive dependencies; +2. create an Issue directly as `todo` when it is ready to run; +3. use `backlog` only to park an Issue with unfinished dependencies; +4. create an Autopilot after its Agent, Project, and prompt are ready; +5. add or enable its trigger last. + +Do not create a ready Issue as `backlog` merely to move it immediately to +`todo`. On failure, stop dependent steps and report completed resources, their +IDs, the observed error, steps not run, and the exact resume point. Resume by +getting each recorded ID; never recreate a resource by name. + +If the CLI lacks a required operation, name it as a Multica Web step and wait +for the user to complete it before continuing dependent work. Never read a +saved token or call the Multica API directly as a fallback.