@markus-global/cli 0.8.4 → 0.8.5-rc.0

package/templates/skills/coding-tools/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: coding-tools
+description: Use external coding tools (Claude Code, Codex, Cursor) via invoke_coding_tool and coding_tool_apply to implement, debug, and refactor code
+---
+
+# Coding Tools
+
+Markus can delegate hands-on coding work to external CLI tools. You have two built-in tools for this workflow:
+
+| Tool | Purpose |
+|---|---|
+| `invoke_coding_tool` | Run Claude Code, Codex, or Cursor Agent against a repository with a prompt |
+| `coding_tool_apply` | Commit the changes produced by a coding tool session |
+
+Use these when the task requires substantial code changes across multiple files, when you want a specialized coding agent to explore a codebase, or when direct editing would be slower or less reliable than delegating to a dedicated tool.
+
+## Available Coding Tools
+
+| Tool name | CLI binary | Best for |
+|---|---|---|
+| `claude-code` | `claude` | Complex refactors, multi-file changes, deep exploration, architecture-level edits |
+| `codex` | `codex` | Quick fixes, targeted patches, scripted automation, fast iteration |
+| `cursor-agent` | `cursor` | IDE-heavy work, projects with `.cursor/rules`, repo-specific conventions |
+
+Check availability with `markus doctor` before relying on a tool. If a tool is not installed, the handler returns an `installHint`.
+
+## When to Use External Tools vs Write Code Directly
+
+**Use external coding tools when:**
+
+- The change spans many files or requires broad codebase exploration
+- You need an autonomous agent to iterate (edit → test → fix) inside the repo
+- The task is well-scoped with clear acceptance criteria but large implementation surface
+- You are coordinating work and want a specialist tool to execute while you review results
+
+**Write code directly (file_edit, shell_execute) when:**
+
+- The change is small — a few lines in one or two files
+- You already know exactly what to change and where
+- You need fine-grained control over every edit
+- The task is configuration, documentation, or non-code work
+
+**Rule of thumb:** If you would open an IDE and spend 15+ minutes navigating and editing, prefer `invoke_coding_tool`. If you can describe the exact diff in one paragraph, edit directly.
+
+## How to Invoke a Coding Tool
+
+```
+invoke_coding_tool({
+  tool: "claude-code",       // or "codex" | "cursor-agent"
+  prompt: "<clear instruction>",
+  workdir: "/absolute/path/to/repo",
+  task_id: "<optional-task-id>"   // injects task context when provided
+})
+```
+
+### Prompt Best Practices
+
+Write prompts as if briefing a senior engineer who has never seen the ticket:
+
+1. **Goal** — What outcome is required? Link to acceptance criteria.
+2. **Scope** — Which directories, modules, or files are in/out of scope.
+3. **Constraints** — Coding standards, test requirements, patterns to follow or avoid.
+4. **Verification** — How to confirm success (tests to run, commands, expected behavior).
+5. **Context** — Upstream dependencies, related PRs, or prior attempts.
+
+Keep prompts focused. One coding tool invocation = one coherent unit of work. Split large tasks into sequential invocations rather than one mega-prompt.
+
+### Task Context Injection
+
+When you pass `task_id`, Markus fetches full task context (requirement, project, upstream/downstream dependencies) and injects it into the tool's working directory:
+
+- **Claude Code** → `CLAUDE.md`
+- **Cursor Agent** → `.cursor/rules/markus-task.mdc`
+- **Codex** → `.agent_context/task_context.md`
+
+The injected context also includes progress-reporting instructions for the Markus CLI. Always pass `task_id` when working on an assigned task.
+
+### Reading Results
+
+The tool returns JSON:
+
+```json
+{
+  "status": "success",
+  "sessionId": "...",
+  "tool": "claude-code",
+  "result": {
+    "success": true,
+    "summary": "...",
+    "diffStats": { "filesChanged": 3, "additions": 42, "deletions": 7 },
+    "modifiedFiles": ["src/foo.ts"],
+    "testResult": { "passed": 10, "failed": 0, "success": true }
+  },
+  "cost": { "estimatedCostUsd": 0.12, "inputTokens": 5000, "outputTokens": 1200 }
+}
+```
+
+**Always review before applying:**
+
+1. Read `result.summary` and `modifiedFiles`
+2. Check `result.testResult` if present
+3. If needed, inspect the repo with `git diff` via `shell_execute` in `workdir`
+4. If results are incomplete, iterate with a follow-up `invoke_coding_tool` call referencing what still needs fixing
+
+## Applying Changes
+
+After reviewing and approving the tool's work:
+
+```
+coding_tool_apply({
+  session_id: "<sessionId from invoke_coding_tool>",
+  workdir: "/absolute/path/to/repo",
+  commit_message: "feat: implement user auth middleware"
+})
+```
+
+This stages all changes and creates a git commit. If there are no changes, it returns success with `filesChanged: 0`.
+
+**Do not apply blindly.** Verify tests pass and the diff matches expectations first.
+
+## Choosing the Right Tool
+
+| Scenario | Recommended tool | Why |
+|---|---|---|
+| Large refactor across packages | `claude-code` | Strong multi-turn reasoning, `--max-turns 50`, stream-json progress |
+| One-file bug fix or typo | `codex` | Fast, `exec --full-auto`, minimal overhead |
+| Repo with `.cursor/rules` | `cursor-agent` | Reads project rules natively |
+| Need cost/token visibility | `claude-code` | Reports tokens and USD in stream-json result events |
+| Long-running exploratory task | `claude-code` | Best at sustained codebase navigation |
+| CI/automation-friendly run | `codex` | Designed for non-interactive full-auto mode |
+
+When unsure, start with `claude-code` for complexity and `codex` for speed. Switch tools if the first attempt stalls or produces poor results.
+
+## Reporting Progress via Markus CLI
+
+Keep the task board updated while coding tools run. Use `shell_execute`:
+
+```bash
+markus task progress <task-id> -t "Claude Code implementing auth middleware" --percent 40
+markus task note <task-id> -t "Coding tool modified 3 files, running tests"
+markus task context <task-id>    # refresh full context if needed
+```
+
+Report progress at these milestones:
+
+- Before invoking a coding tool (what you're delegating)
+- After the tool completes (summary + file count)
+- After applying changes (commit created)
+- On failure (error details + retry plan)
+
+Coding tools also receive these CLI instructions in their injected context file when `task_id` is provided.
+
+## Error Handling and Retry Strategies
+
+### Tool Not Installed
+
+```json
+{ "error": "Claude Code is not installed. npm install -g @anthropic-ai/claude-code", "installHint": "..." }
+```
+
+**Action:** Try a different installed tool, or report the blocker via `task note` and escalate.
+
+### Execution Failed or Incomplete
+
+1. Read `result.error` and `result.rawOutput` (truncated)
+2. Check whether partial changes exist in `workdir` (`git status`, `git diff`)
+3. Retry with a **narrower prompt** that references the failure:
+   - "The previous attempt failed because X. Fix only Y in file Z."
+4. After 2 failed attempts with the same tool, switch to a different tool or fall back to direct editing
+
+### Timeout
+
+Long tasks may hit configured `timeoutMs`. Split the work into smaller invocations with explicit checkpoints.
+
+### Apply Failures
+
+If `coding_tool_apply` fails (merge conflict, git error):
+
+1. Inspect `git status` in `workdir`
+2. Resolve conflicts manually with `file_edit`
+3. Commit manually via `shell_execute` if needed
+4. Document what happened in a task note
+
+### Quality Verification
+
+When `result.testResult` shows failures, **do not apply**. Re-invoke with:
+
+```
+The following tests failed: <output>. Fix the failures without changing unrelated code.
+```
+
+## Pre-Apply Quality Protocol
+
+Before calling `coding_tool_apply`, verify ALL of the following:
+
+1. **Tests pass**: `result.testResult.success` is true, or you have explicitly accepted known failures with justification
+2. **Diff is clean**: Review `result.modifiedFiles` — no unexpected files were changed
+3. **Scope compliance**: Changes are within the task scope — flag any out-of-scope modifications
+4. **No regressions**: If a broader test suite exists, run it via `shell_execute` before applying
+
+If any check fails, re-invoke with a targeted prompt referencing the specific issue rather than applying and fixing later.
+
+## Workflow Summary
+
+```
+1. Scope the work → write a clear prompt
+2. invoke_coding_tool({ tool, prompt, workdir, task_id })
+3. Review result (summary, diff, tests)
+4. Iterate if needed (step 2 with refined prompt)
+5. coding_tool_apply({ session_id, workdir, commit_message })
+6. Report progress via markus task progress/note
+7. Submit task for review
+```
+
+## Model, Mode, and Effort Overrides
+
+The `invoke_coding_tool` handler accepts per-invocation overrides:
+
+```
+invoke_coding_tool({
+  tool: "claude-code",
+  prompt: "...",
+  model: "opus",       // optional: override the user's default model
+  mode: "plan",        // optional: tool-specific execution mode
+  effort: "high",      // optional: reasoning effort level
+  approved: true       // required when approvalRequired is enabled for this tool
+})
+```
+
+### Model selection strategy
+
+- If the user has set a `defaultModel` in settings, respect it unless you have a specific reason to override
+- When overriding, explain why in your progress notes (e.g., "Using Opus for complex architecture task")
+- For simple tasks, prefer cheaper models; for complex multi-file work, consider more capable models
+
+### Mode chaining pattern
+
+Many tasks benefit from a multi-step approach:
+
+1. **Plan first** — `invoke_coding_tool({ tool: "claude-code", mode: "plan", prompt: "Analyze the codebase and create an implementation plan for..." })` or `invoke_coding_tool({ tool: "cursor-agent", mode: "plan", ... })`
+2. **Execute** — Follow up with the default agent mode (no `mode` override) using the plan output as context
+3. **Review/ask** — If results need refinement, use `mode: "ask"` (Cursor) for targeted questions
+
+### Approval workflow
+
+If a tool has `approvalRequired: true`, the handler returns an `approval_required` error. You must:
+
+1. Call `request_user_approval` explaining what you want to do and why
+2. After receiving approval, retry with `approved: true`
+
+**Voluntarily request approval** (even without `approvalRequired`) when:
+
+- You're about to use an expensive model (Opus, gpt-5.5) for a long-running task
+- The task scope is unclear and might consume significant resources
+- The user's cost profile suggests caution (check the tool-specific skill for guidance)
+
+## Cost-Aware Practices
+
+Cost awareness is your responsibility as the agent. The UI provides enforceable controls (default model, budget cap for Claude Code, approval toggle), but strategic cost optimization is up to you.
+
+### General principles
+
+- **Start cheap, escalate if needed** — Try the default or cheaper model first. Only reach for expensive models when the cheaper attempt fails or the task clearly requires deep reasoning
+- **Scope tightly** — One focused invocation is cheaper than a broad one that explores unnecessarily
+- **Monitor results** — After each invocation, check `cost.estimatedCostUsd` (if available) and note it in progress updates
+- **Split rather than retry** — If a task partially completes, split the remainder into a new focused invocation rather than re-running the entire thing
+
+### Cost visibility varies by tool
+
+| Tool | Cost data available? |
+|---|---|
+| `claude-code` | Yes — tokens and USD in every result |
+| `codex` | Limited — no structured cost data from CLI |
+| `cursor-agent` | Limited — may include tokens in result events |
+
+When cost data is unavailable, estimate by task duration and complexity. Report what you know.
+
+## Related Skills
+
+For tool-specific details, activate the matching skill:
+
+- **claude-code** — CLI flags, stream-json, CLAUDE.md, cost tracking, model/effort guidance
+- **codex** — full-auto mode, AGENTS.md, sandbox behavior, model/effort guidance
+- **cursor-agent** — agent mode, `.cursor/rules`, working directory setup, Auto vs Max Mode
+
+Use `discover_tools({ name: ["claude-code"] })` to load a tool-specific skill before invoking that tool.
+
+## Rules
+
+- **DO** pass `task_id` for assigned tasks
+- **DO** review diffs and test results before applying
+- **DO** split large work into focused invocations
+- **DO** report progress to the task board
+- **DO** respect the user's `defaultModel` setting unless you have a clear reason to override
+- **DO** voluntarily request user approval before expensive operations
+- **DO NOT** apply changes when tests fail unless explicitly acceptable
+- **DO NOT** run coding tools outside the project's repository path
+- **DO NOT** retry the same broad prompt more than twice — refine or switch tools
+- **DO NOT** default to expensive models when cheaper ones can handle the task
+- **NEVER** call coding tool CLIs (`cursor`, `claude`, `codex`) directly via `shell_execute`. Always use `invoke_coding_tool` — it handles binary resolution, argument building, context injection, streaming, cost tracking, and session management. Direct shell calls bypass all of this and will likely use wrong arguments.

package/templates/skills/coding-tools/skill.json

@@ -0,0 +1,17 @@
+{
+  "type": "skill",
+  "name": "coding-tools",
+  "displayName": "Coding Tools",
+  "version": "1.0.0",
+  "description": "Use external coding tools (Claude Code, Codex, Cursor) to implement, debug, and refactor code",
+  "author": "markus",
+  "category": "development",
+  "tags": ["coding", "tools", "claude-code", "codex", "cursor", "programming"],
+  "i18n": {
+    "zh-CN": {
+      "displayName": "编程工具",
+      "description": "使用外部编程工具（Claude Code、Codex、Cursor）来实现、调试和重构代码"
+    }
+  },
+  "skill": { "skillFile": "SKILL.md" }
+}

package/templates/skills/cursor-agent/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: cursor-agent
+description: Use the Cursor CLI agent mode for IDE-integrated coding with project rules and repo-aware edits
+---
+
+# Cursor Agent
+
+Cursor Agent (`cursor` binary) runs the Cursor IDE's agent mode from the command line. Markus invokes it via `invoke_coding_tool({ tool: "cursor-agent", ... })`. Use it when the project has Cursor-specific configuration (`.cursor/rules`) or when IDE-integrated, project-aware editing is the best fit.
+
+## Installation
+
+Install Cursor from [https://cursor.sh](https://cursor.sh), then enable the shell command:
+
+1. Open Cursor → Command Palette → "Install 'cursor' command in PATH"
+2. Verify: `cursor --version`
+
+Check availability with `markus doctor`. Requires authentication via `cursor agent login` (browser-based) or `CURSOR_API_KEY` env var.
+
+## How Markus Invokes Cursor Agent
+
+Markus runs Cursor in CLI agent mode:
+
+```bash
+cursor agent --print --output-format stream-json --workspace <workdir> --trust --force "<prompt>"
+```
+
+| Flag | Purpose |
+|---|---|
+| `--print` | Non-interactive mode |
+| `--output-format stream-json` | Emits structured JSON events for progress parsing |
+| `--workspace <workdir>` | Specifies the repo root for project context |
+| `--trust --force` | Auto-trusts the workspace without interactive prompts |
+
+Additional args can be configured via `CodingToolConfig.defaultArgs`.
+
+## .cursor/rules Context Files
+
+Cursor projects use **`.cursor/rules/`** for persistent agent instructions. Rule files (`.mdc` or `.md`) define:
+
+- Coding standards and naming conventions
+- Architecture decisions and patterns to follow
+- Test requirements and deployment procedures
+- Files or areas agents should not modify
+
+Cursor Agent reads these rules automatically when operating in a project directory. Well-maintained rules significantly improve output quality.
+
+### Markus Task Context Injection
+
+When you pass `task_id` to `invoke_coding_tool`, Markus writes task-specific context to:
+
+```
+.cursor/rules/markus-task.mdc
+```
+
+This file contains the full Markus task context (title, description, subtasks, dependencies, progress-reporting CLI commands). It sits alongside your project's permanent rules and takes effect for the coding session.
+
+**Important:**
+
+- Markus creates the `.cursor/rules/` directory if it doesn't exist
+- The `markus-task.mdc` file is regenerated each invocation — do not store permanent rules there
+- Keep long-lived project rules in separate files (e.g., `coding-standards.mdc`, `architecture.mdc`)
+
+### Example Project Rules Structure
+
+```
+.cursor/rules/
+├── coding-standards.mdc    # permanent — naming, formatting, test requirements
+├── architecture.mdc        # permanent — module boundaries, patterns
+└── markus-task.mdc         # ephemeral — injected by Markus per task
+```
+
+## Working Directory Considerations
+
+The `workdir` parameter is critical for Cursor Agent:
+
+### Use the Repository Root
+
+Always pass the **absolute path to the git repository root** as `workdir`:
+
+```
+workdir: "/Users/agent/projects/my-app"
+```
+
+Cursor Agent resolves `.cursor/rules/` relative to this directory. Pointing at a subdirectory may cause rules to be missed.
+
+### Multi-Repo Projects
+
+If the task spans multiple repositories, invoke Cursor Agent **once per repository** with repo-specific prompts:
+
+```
+invoke_coding_tool({
+  tool: "cursor-agent",
+  prompt: "Implement the API client changes described in the task context.",
+  workdir: "/path/to/backend-repo",
+  task_id: "task-789"
+})
+```
+
+### Git State
+
+Ensure the working directory is a clean git checkout (or at least understand existing uncommitted changes). Cursor Agent edits files in-place. Review with `git status` and `git diff` before applying.
+
+### Environment Variables
+
+Markus injects these env vars during context injection:
+
+| Variable | Purpose |
+|---|---|
+| `MARKUS_API_URL` | API server for task operations |
+| `MARKUS_TASK_ID` | Current task ID |
+| `MARKUS_CLI` | Path to the markus CLI binary |
+
+Cursor Agent subprocesses can use these if the injected context references CLI commands for progress reporting.
+
+## Usage Patterns
+
+### Rule-Driven Feature Implementation
+
+```
+invoke_coding_tool({
+  tool: "cursor-agent",
+  prompt: "Implement the user settings page following the patterns in .cursor/rules/frontend.mdc. Use existing component library imports. Add unit tests.",
+  workdir: "/path/to/frontend-repo",
+  task_id: "task-789"
+})
+```
+
+### Convention-Heavy Refactor
+
+```
+invoke_coding_tool({
+  tool: "cursor-agent",
+  prompt: "Migrate all API routes in src/routes/ to the new error-handling pattern defined in .cursor/rules/api-conventions.mdc. Update tests accordingly.",
+  workdir: "/path/to/repo",
+  task_id: "task-789"
+})
+```
+
+### Monorepo Package Work
+
+```
+invoke_coding_tool({
+  tool: "cursor-agent",
+  prompt: "Add the coding-tools skill templates under templates/skills/. Follow the existing skill.json + SKILL.md pattern from templates/skills/self-evolution/.",
+  workdir: "/path/to/markus-monorepo",
+  task_id: "task-789"
+})
+```
+
+## Model and Mode Selection
+
+Cursor Agent supports per-invocation model and mode overrides:
+
+```
+invoke_coding_tool({
+  tool: "cursor-agent",
+  prompt: "...",
+  model: "auto",     // optional: CLI-specific model (auto, composer-2.5, etc.)
+  mode: "plan",      // optional: plan | ask
+})
+```
+
+### Important: CLI Model Limitations
+
+The Cursor `agent` CLI only accepts a limited set of CLI-specific model identifiers: `auto`, `composer-2.5`, etc. **Cursor Cloud API models** (Claude, GPT families) **are not available via the CLI** — they only work via the REST API.
+
+The Settings UI only shows CLI-compatible models to prevent selection errors.
+
+### Critical cost fact: Auto Mode vs Max Mode
+
+**Not specifying `--model` uses Auto mode** — this is unlimited on paid Cursor plans and very cheap (or free). The moment you specify a model name, Cursor enters **Max Mode**, which bills per-token from the monthly credit pool.
+
+| Mode | Cost | When to use |
+|---|---|---|
+| Auto (no `--model`) | Free / unlimited on paid plans | Default for most tasks |
+| Max Mode (explicit `--model`) | Per-token billing, varies by model | Only when task needs specific model capabilities |
+
+**Warning:** Opus in Max Mode consumes credits approximately 20x faster than Auto mode. **Only specify `--model` when the task genuinely needs a specific model's capabilities.** For most tasks, Auto mode is the correct and cost-effective choice.
+
+### Mode guidance
+
+- `plan` — Analyze architecture first, don't make changes yet. Good as a first step for complex tasks.
+- `ask` — Answer questions about the codebase without making changes.
+- Default (no mode) — Full agent mode, makes edits. Use for implementation.
+
+### Mode chaining pattern
+
+For complex tasks:
+
+1. `mode: "plan"` — "Analyze the codebase and propose an implementation plan for..."
+2. Default agent mode — "Implement the plan: [paste plan from step 1]"
+3. `mode: "ask"` — "Review the changes and identify any issues"
+
+### Cost strategy
+
+- **Default to no model override** (Auto mode) — it handles most tasks well and is free/cheap
+- Only specify a model when Auto mode produces poor results or the task clearly needs specific capabilities
+- **Voluntarily call `request_user_approval` before specifying expensive models** (Opus) since it enables Max Mode billing
+
+## When to Choose Cursor Agent
+
+| Choose Cursor Agent | Choose something else |
+|---|---|
+| Project has rich `.cursor/rules/` | No Cursor config, generic repo → `claude-code` |
+| Team standardized on Cursor conventions | Need stream-json cost tracking → `claude-code` |
+| IDE-style project-aware edits | Quick one-file fix → `codex` |
+| Frontend/UI work with component rules | Deep backend exploration → `claude-code` |
+
+## Error Handling
+
+Cursor Agent may include some token data in result events. Evaluate results by:
+
+1. `result.success` and `result.summary`
+2. `result.modifiedFiles` — do they match expected scope?
+3. `result.testResult` from quality verification
+4. Manual `git diff` review in `workdir`
+
+If Cursor Agent ignores project rules, verify:
+
+- `workdir` points to the repo root (where `.cursor/rules/` lives)
+- Rule files use correct `.mdc` format and are not empty
+- The prompt explicitly references relevant rule files
+
+If output quality is poor after 2 attempts, switch to `claude-code` with equivalent prompt and CLAUDE.md context.
+
+## Best Practices
+
+- Maintain `.cursor/rules/` with clear, actionable project conventions
+- Always pass absolute repo root as `workdir`
+- Pass `task_id` so `markus-task.mdc` carries task context
+- Reference specific rule files in prompts when multiple rules exist
+- Review diffs carefully — Cursor Agent may interpret rules differently than expected
+- **Default to Auto mode (no model override) for cost-effectiveness**
+- Only specify models when Auto mode is insufficient
+
+## Mode Chaining for Quality
+
+Use Cursor Agent modes strategically:
+1. **Plan mode**: `invoke_coding_tool({ tool: "cursor-agent", mode: "plan", prompt: "..." })` — analyze before implementing
+2. **Agent mode** (default): Full implementation
+3. **Ask mode**: `invoke_coding_tool({ tool: "cursor-agent", mode: "ask", prompt: "..." })` — targeted questions about the codebase
+
+For complex tasks, always plan first. Review the plan before proceeding to implementation.
+
+## Project Rules Integration
+
+Cursor Agent reads `.cursor/rules/` automatically. When `task_id` is provided, Markus injects task context into `.cursor/rules/markus-task.mdc`. This means Cursor Agent automatically understands:
+- Task requirements and acceptance criteria
+- Project conventions and constraints
+- Upstream/downstream dependencies
+
+## Rules
+
+- **DO** use when the project has Cursor rules configured
+- **DO** pass the repository root as `workdir`
+- **DO** keep permanent rules separate from `markus-task.mdc`
+- **DO** default to Auto mode (no `--model`) for cost savings
+- **DO** request approval before using expensive models in Max Mode
+- **DO NOT** store permanent instructions in `markus-task.mdc`
+- **DO NOT** use for repos with no Cursor configuration unless other tools are unavailable
+- **DO NOT** apply changes without reviewing diffs against project rules
+- **DO NOT** specify `--model` by default — it triggers Max Mode billing

package/templates/skills/cursor-agent/skill.json

@@ -0,0 +1,17 @@
+{
+  "type": "skill",
+  "name": "cursor-agent",
+  "displayName": "Cursor Agent",
+  "version": "1.0.0",
+  "description": "Use the Cursor CLI agent mode for IDE-integrated coding, rule-driven workflows, and project-aware edits",
+  "author": "markus",
+  "category": "development",
+  "tags": ["coding", "cursor", "ide", "agent"],
+  "i18n": {
+    "zh-CN": {
+      "displayName": "Cursor Agent",
+      "description": "使用 Cursor CLI 代理模式进行 IDE 集成编程、规则驱动的工作流和项目感知编辑"
+    }
+  },
+  "skill": { "skillFile": "SKILL.md" }
+}