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

package/templates/skills/claude-code/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: claude-code
+description: Use the Claude Code CLI for complex refactors, multi-file changes, and sustained codebase exploration
+---
+
+# Claude Code
+
+Claude Code (`claude` binary) is Anthropic's agentic coding CLI. Markus invokes it via `invoke_coding_tool({ tool: "claude-code", ... })`. Use it for complex, multi-turn coding tasks where deep reasoning and broad file exploration are needed.
+
+## Installation
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --version
+```
+
+Verify with `markus doctor`. Requires authentication via one of: `ANTHROPIC_API_KEY` env var, `ANTHROPIC_BASE_URL` for custom endpoints, or interactive `claude` login.
+
+## How Markus Invokes Claude Code
+
+Markus runs Claude Code in non-interactive print mode with structured streaming output:
+
+```bash
+claude --print --output-format stream-json --verbose --max-turns 50 --permission-mode bypassPermissions "<prompt>"
+```
+
+| Flag | Purpose |
+|---|---|
+| `--print` | Non-interactive mode — runs to completion without user input |
+| `--output-format stream-json` | Emits structured JSON events for progress parsing |
+| `--verbose` | Detailed progress output |
+| `--max-turns 50` | Allows up to 50 agent turns for complex tasks |
+| `--permission-mode bypassPermissions` | Auto-approves all file edits and commands — required because `--print` mode has no interactive stdin for approval prompts |
+
+Additional args can be configured per-deployment via `CodingToolConfig.defaultArgs`.
+
+## Stream-JSON Output
+
+Each stdout line is a JSON event. Key event types:
+
+| Event type | Meaning |
+|---|---|
+| `assistant` with `text` content | Progress message / reasoning summary |
+| `assistant` with `tool_use` | File edit, shell command, or other tool invocation |
+| `result` | Final outcome with cost and token data |
+
+The `result` event includes:
+
+- `result` — Final summary text
+- `input_tokens`, `output_tokens` — Token usage
+- `cache_read_tokens`, `cache_write_tokens` — Prompt cache stats
+- `cost_usd` — Estimated cost in USD
+
+Markus parses these into progress events (`file_edit`, `progress`, `completed`) and extracts cost reports automatically.
+
+## CLAUDE.md Context File
+
+When you pass `task_id` to `invoke_coding_tool`, Markus writes a `CLAUDE.md` file in the repository root before invoking Claude Code. This file contains:
+
+- Task title, description, status, and priority
+- Subtasks, notes, and deliverables
+- Requirement and project context
+- Upstream/downstream dependency summaries
+- Markus CLI commands for reporting progress
+
+Claude Code reads `CLAUDE.md` automatically as project context. **Do not delete or overwrite it** during a session — it is regenerated each invocation.
+
+If the repo already has a permanent `CLAUDE.md`, Markus overwrites it for the session. Consider restoring project-level content after the task if needed.
+
+## Usage Patterns
+
+### Complex Refactor
+
+```
+invoke_coding_tool({
+  tool: "claude-code",
+  prompt: "Refactor the auth module to use dependency injection. Move AuthService to src/services/, update all imports, keep existing test behavior. Run the test suite when done.",
+  workdir: "/path/to/repo",
+  task_id: "task-123"
+})
+```
+
+### Debug and Fix
+
+```
+invoke_coding_tool({
+  tool: "claude-code",
+  prompt: "Tests in packages/core/test/auth.test.ts are failing with 'token expired'. Find the root cause in src/auth/ and fix without changing the public API. Show which tests pass after the fix.",
+  workdir: "/path/to/repo",
+  task_id: "task-123"
+})
+```
+
+### Explore Then Implement
+
+For unfamiliar codebases, ask Claude Code to explore first:
+
+```
+"Read the codebase structure under src/coding-tools/. Then implement the feature described in the task context. Start by listing the files you plan to modify."
+```
+
+## Retry Strategies for Long Tasks
+
+Claude Code supports up to 50 turns, but long tasks can still stall or partially complete.
+
+### If the session completes but work is incomplete
+
+Re-invoke with explicit remaining scope:
+
+```
+"Previous session modified src/foo.ts and src/bar.ts but did not update tests. Complete the test coverage for the changes in src/foo.ts. Do not re-modify files that are already correct."
+```
+
+### If the session fails or times out
+
+1. Check `git status` in `workdir` for partial changes
+2. Either apply partial work with `coding_tool_apply` or discard with `git checkout -- .`
+3. Retry with a **smaller scope** — one module or one feature at a time
+
+### If Claude Code loops or over-edits
+
+Add constraints to the prompt:
+
+```
+"Modify ONLY files under src/handlers/. Do not touch tests, config, or unrelated packages."
+```
+
+### Escalation after 2 retries
+
+Switch to `codex` for a targeted fix, or edit directly with `file_edit`.
+
+## Model and Effort Selection
+
+Claude Code supports per-invocation model and effort overrides:
+
+```
+invoke_coding_tool({
+  tool: "claude-code",
+  prompt: "...",
+  model: "sonnet",     // default: tool's own default (usually sonnet)
+  effort: "medium",    // low | medium | high | xhigh | max
+})
+```
+
+### Model guidance
+
+| Model | Best for | Cost note |
+|---|---|---|
+| `haiku` | Simple subagent tasks, quick checks | Cheapest option |
+| `sonnet` | Most coding work — default choice | Good balance of cost and capability |
+| `opus` | Complex architecture, multi-file refactors, unfamiliar codebases | ~15x more expensive per token than Sonnet |
+| `fable` | Creative or documentation tasks | Specialized |
+
+**Strategy:** Start with `sonnet` (or the user's `defaultModel`). Only use `opus` when:
+
+- Sonnet attempt failed or produced poor results
+- The task involves complex reasoning across 10+ files
+- Architecture decisions or trade-off analysis is required
+
+**Warning:** Opus is approximately 15x more expensive than Sonnet per token. A task that costs $0.30 with Sonnet could cost $4.50 with Opus. **Voluntarily call `request_user_approval` before using Opus for any task expected to run more than a few turns.**
+
+### Effort guidance
+
+- `low` — Simple edits, typo fixes, config changes
+- `medium` — Standard development tasks (default)
+- `high` — Complex reasoning, multi-step problem solving
+
+### Budget cap
+
+If the user has set `maxBudgetPerSessionUsd`, Markus passes it as `--max-budget-usd` to Claude Code. This is a **hard limit enforced by Claude Code** — the session terminates if the budget is reached. Claude Code is the only tool with this enforced budget mechanism.
+
+When working under a budget cap:
+- Prefer `sonnet` over `opus` to stay within budget
+- Split large tasks so each invocation stays within the per-session limit
+- Monitor `cost.estimatedCostUsd` in results to gauge remaining budget capacity
+
+## Cost Awareness
+
+Claude Code is the most capable but potentially most expensive coding tool. It provides the **best cost visibility** — every result includes token counts and USD estimates:
+
+```json
+{
+  "cost": {
+    "estimatedCostUsd": 0.45,
+    "inputTokens": 85000,
+    "outputTokens": 12000,
+    "cacheReadTokens": 40000,
+    "source": "tool_output"
+  }
+}
+```
+
+**Cost-saving practices:**
+
+- Scope prompts tightly — avoid "refactor everything"
+- Split large tasks into sequential focused invocations
+- Use `codex` for trivial fixes instead of Claude Code
+- Leverage prompt caching (repeated context in CLAUDE.md is cache-friendly)
+- Review `cost.estimatedCostUsd` before chaining multiple invocations
+- Use `effort: "low"` for simple edits, `effort: "high"` only for complex reasoning
+- Prefer `sonnet` — only escalate to `opus` when justified
+
+Report unusually high costs (> $1 per invocation) in a task note for visibility.
+
+## Best Practices
+
+- Write prompts with explicit file boundaries and test commands
+- Always pass `task_id` so CLAUDE.md carries full task context
+- Watch progress output for `file_edit` events to track what's changing
+- Verify `result.testResult` before calling `coding_tool_apply`
+- Prefer Claude Code when the task requires reading 5+ files to understand context
+- Check `cost.estimatedCostUsd` after each invocation and factor it into your next decision
+
+## Quality Verification Loop
+
+For complex tasks, chain Claude Code invocations:
+1. **Plan**: `invoke_coding_tool({ tool: "claude-code", mode: "plan", prompt: "Analyze and plan..." })`
+2. **Implement**: `invoke_coding_tool({ tool: "claude-code", prompt: "Implement the plan..." })`  
+3. **Verify**: Check `result.testResult`. If failures exist, re-invoke with: "Fix these test failures: <output>"
+4. **Apply**: Only after tests pass — `coding_tool_apply({ session_id, commit_message })`
+
+Never apply changes from a session where tests failed.
+
+## Cost Management
+
+- Start with the default model. Only escalate to more expensive models for tasks that demonstrably need deeper reasoning.
+- Check `cost.estimatedCostUsd` after each invocation and note it in task progress.
+- For exploratory work, set a mental budget — if cost exceeds expectations, split into smaller focused invocations.
+
+## Rules
+
+- **DO** use for multi-file refactors and exploratory coding
+- **DO** monitor token/cost data in the response
+- **DO** break very large tasks into sequential invocations
+- **DO** start with `sonnet` and only escalate to `opus` when needed
+- **DO** request user approval before using `opus` for long tasks
+- **DO NOT** use for one-line fixes — use `codex` or direct edit instead
+- **DO NOT** ignore failed tests in the result — iterate until they pass
+- **DO NOT** use `opus` by default — its cost can surprise users

package/templates/skills/claude-code/skill.json

@@ -0,0 +1,17 @@
+{
+  "type": "skill",
+  "name": "claude-code",
+  "displayName": "Claude Code",
+  "version": "1.0.0",
+  "description": "Use the Claude Code CLI for complex refactors, multi-file changes, and deep codebase exploration",
+  "author": "markus",
+  "category": "development",
+  "tags": ["coding", "claude-code", "anthropic", "refactoring"],
+  "i18n": {
+    "zh-CN": {
+      "displayName": "Claude Code",
+      "description": "使用 Claude Code CLI 进行复杂重构、多文件修改和深度代码库探索"
+    }
+  },
+  "skill": { "skillFile": "SKILL.md" }
+}

package/templates/skills/codex/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: codex
+description: Use the OpenAI Codex CLI for quick fixes, targeted edits, and non-interactive automation
+---
+
+# Codex
+
+Codex (`codex` binary) is OpenAI's agentic coding CLI. Markus invokes it via `invoke_coding_tool({ tool: "codex", ... })`. Use it for fast, focused changes where speed and non-interactive automation matter more than deep multi-turn exploration.
+
+## Installation
+
+```bash
+npm install -g @openai/codex
+codex --version
+```
+
+Verify with `markus doctor`. Requires authentication via `codex login` or `CODEX_API_KEY` env var for non-interactive mode.
+
+## How Markus Invokes Codex
+
+Markus runs Codex in fully automated, non-interactive mode:
+
+```bash
+codex exec --full-auto --json --skip-git-repo-check "<prompt>"
+```
+
+| Flag | Purpose |
+|---|---|
+| `exec --full-auto` | Non-interactive mode — auto-approves all file edits and shell commands |
+| `--json` | Emits JSONL events for structured progress parsing |
+| `--skip-git-repo-check` | Allows running outside strict git repo requirements |
+
+Additional args can be configured via `CodingToolConfig.defaultArgs`.
+
+## Full-Auto Approval Mode
+
+In a Markus agent session, there is no human at the terminal to approve Codex actions. The `exec --full-auto` mode is essential:
+
+- Codex can edit files and run commands without prompting
+- All actions happen within the sandbox (see below)
+- If Codex would normally ask "Allow this edit?", it proceeds automatically
+
+**Note:** `OPENAI_BASE_URL` is deprecated and no longer supported by Codex CLI. Custom endpoint configuration should use `~/.codex/config.toml`.
+
+**Implication:** Write precise prompts with clear scope boundaries. Codex will act autonomously on whatever the prompt authorizes.
+
+## AGENTS.md Context File
+
+Codex reads project-level instruction files to understand repo conventions. The standard file is **`AGENTS.md`** in the repository root — a markdown file describing:
+
+- Project structure and architecture
+- Coding conventions and patterns
+- Test commands and CI expectations
+- Areas that are off-limits or require caution
+
+If the repo already has `AGENTS.md`, Codex uses it automatically. Ensure it stays accurate for the project.
+
+### Markus Task Context Injection
+
+When you pass `task_id` to `invoke_coding_tool`, Markus additionally writes task-specific context to:
+
+```
+.agent_context/task_context.md
+```
+
+This file contains the full Markus task context (title, description, dependencies, progress-reporting CLI commands). Codex can read it during execution alongside any existing `AGENTS.md`.
+
+**Best practice:** Keep permanent project guidance in `AGENTS.md`. Task-specific instructions come from Markus injection — do not manually duplicate task details into `AGENTS.md`.
+
+## Sandbox Behavior
+
+Codex runs in a sandboxed environment that restricts what the agent can access:
+
+- File edits are scoped to the working directory (`workdir`)
+- Network access may be limited depending on Codex configuration
+- Shell commands run within sandbox constraints
+
+**Implications for prompts:**
+
+- Specify the exact files or directories to modify
+- Include the test command to run (e.g., `pnpm test packages/core`)
+- Do not assume Codex can reach external APIs unless sandbox allows it
+- If a task requires installing new dependencies, mention it explicitly in the prompt
+
+If Codex fails due to sandbox restrictions, note the error and either adjust the prompt to work within constraints or switch to `claude-code` for less restrictive execution.
+
+## Usage Patterns
+
+### Quick Bug Fix
+
+```
+invoke_coding_tool({
+  tool: "codex",
+  prompt: "Fix the off-by-one error in src/utils/pagination.ts line 42. The page size should default to 20, not 21. Run tests in that package after fixing.",
+  workdir: "/path/to/repo",
+  task_id: "task-456"
+})
+```
+
+### Targeted Feature Addition
+
+```
+invoke_coding_tool({
+  tool: "codex",
+  prompt: "Add a --json flag to the task list command in packages/cli/src/commands/task.ts. Follow the existing output pattern used by other commands. Add a test case.",
+  workdir: "/path/to/repo",
+  task_id: "task-456"
+})
+```
+
+### Config or Script Update
+
+```
+invoke_coding_tool({
+  tool: "codex",
+  prompt: "Update the GitHub Actions workflow in .github/workflows/test.yml to add a matrix entry for Node 22. Do not change other jobs.",
+  workdir: "/path/to/repo",
+  task_id: "task-456"
+})
+```
+
+## When to Choose Codex vs Other Tools
+
+| Choose Codex | Choose something else |
+|---|---|
+| Single-file or few-file fix | Multi-package refactor → `claude-code` |
+| Clear, narrow prompt | Exploratory "figure out how this works" → `claude-code` |
+| Speed is priority | Need token/cost reporting → `claude-code` |
+| Repo has good `AGENTS.md` | Heavy `.cursor/rules` setup → `cursor-agent` |
+
+## Model and Effort Selection
+
+Codex supports per-invocation model and effort overrides:
+
+```
+invoke_coding_tool({
+  tool: "codex",
+  prompt: "...",
+  model: "gpt-5-codex",    // default if not specified
+  effort: "medium",         // sets CODEX_REASONING_EFFORT env var
+})
+```
+
+### Model guidance
+
+| Model | Best for | Cost note |
+|---|---|---|
+| `gpt-5.4-mini` | Trivial fixes, typos, config | Cheapest option |
+| `gpt-5-codex` | Standard coding work | Cost-effective default for coding |
+| `gpt-5.5` | Complex reasoning, architecture | ~4x more expensive than gpt-5-codex |
+
+**Strategy:** `gpt-5-codex` is the right default for most Codex work. Only use `gpt-5.5` when the task involves complex reasoning that simpler models fail at. Prefer `gpt-5.4-mini` for trivial, low-risk changes.
+
+### Effort levels
+
+- `minimal` / `low` — Simple fixes with minimal reasoning
+- `medium` — Standard development (default)
+- `high` / `xhigh` — Complex problem solving, only when needed
+
+### Cost note
+
+Codex does not expose structured cost data through Markus. Estimate cost by:
+- Task complexity and expected duration
+- Model choice (gpt-5.5 is ~4x more expensive)
+- Number of turns the agent takes
+
+**Voluntarily call `request_user_approval` before using `gpt-5.5` for tasks that might run long.**
+
+## Error Handling
+
+Focus on result quality:
+
+1. Check `result.success` and `result.summary`
+2. Review `result.modifiedFiles` — should match expected scope
+3. Inspect `result.testResult` if quality verification ran
+4. On failure, read `result.error` and retry with a narrower prompt
+
+If Codex modifies unexpected files, discard changes (`git checkout -- .` in `workdir`) and re-invoke with explicit file boundaries:
+
+```
+"Modify ONLY packages/cli/src/commands/task.ts. Do not touch any other files."
+```
+
+## Best Practices
+
+- Keep prompts short and specific — Codex excels at targeted tasks
+- Ensure `AGENTS.md` exists for project conventions (create or update if missing)
+- Always pass `task_id` for task context injection
+- Verify changes with `git diff` before `coding_tool_apply`
+- Use `gpt-5-codex` as the default — escalate only when justified
+- `exec --full-auto` is handled by Markus — do not try to run Codex interactively from an agent
+
+## Full-Auto Mode Best Practices
+
+Codex runs in `--full-auto` mode by default, which means it will make changes without asking for confirmation. This makes quality verification especially important:
+
+1. **Scope tightly**: Write precise prompts that describe exactly what to change and what NOT to change
+2. **Verify before applying**: Always check `result.diffStats` and `result.modifiedFiles` before `coding_tool_apply`
+3. **Run tests**: If Codex doesn't run tests automatically, run them yourself via `shell_execute` before applying
+
+## When to Choose Codex
+
+- Quick, targeted fixes (one file, clear problem)
+- Scripted automation (generate boilerplate, rename across files)
+- CI-friendly operations (no interactive prompts needed)
+- When speed matters more than deep reasoning
+
+## Rules
+
+- **DO** use for quick fixes and well-scoped edits
+- **DO** maintain an accurate `AGENTS.md` in project repos
+- **DO** set explicit file boundaries in prompts
+- **DO** default to `gpt-5-codex` for cost-effectiveness
+- **DO NOT** use for large exploratory refactors — use `claude-code`
+- **DO NOT** assume network or install permissions — check sandbox errors
+- **DO NOT** apply changes that touch files outside the stated scope
+- **DO NOT** use `gpt-5.5` by default — its cost is ~4x higher

package/templates/skills/codex/skill.json

@@ -0,0 +1,17 @@
+{
+  "type": "skill",
+  "name": "codex",
+  "displayName": "Codex",
+  "version": "1.0.0",
+  "description": "Use the OpenAI Codex CLI for quick fixes, targeted edits, and non-interactive automation",
+  "author": "markus",
+  "category": "development",
+  "tags": ["coding", "codex", "openai", "automation"],
+  "i18n": {
+    "zh-CN": {
+      "displayName": "Codex",
+      "description": "使用 OpenAI Codex CLI 进行快速修复、定向编辑和非交互式自动化"
+    }
+  },
+  "skill": { "skillFile": "SKILL.md" }
+}