diff --git a/README.md b/README.md index bb398c6b68..3c09af9f81 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ If this sounds like someone you know, definitely send them our way. ## Quickstart -Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi). +Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [CodeBuddy](#codebuddy), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi). ## How it works @@ -72,6 +72,30 @@ agy plugin install https://github.com/obra/superpowers Antigravity runs the plugin's session-start hook, so Superpowers is active from the first message. Reinstall with the same command to update. +### CodeBuddy + +CodeBuddy is compatible with the Claude Code plugin format, so Superpowers works with no additional configuration. + +- Register the marketplace: + + ```bash + codebuddy plugin marketplace add https://github.com/obra/superpowers + ``` + +- Install the plugin: + + ```bash + codebuddy plugin install superpowers@superpowers-dev + ``` + +- Or load it temporarily from a local directory for development: + + ```bash + codebuddy --plugin-dir /path/to/superpowers + ``` + +CodeBuddy runs the plugin's session-start hook and auto-discovers skills from the `skills/` directory, so Superpowers is active from the first message. Reinstall with the same command to update. + ### Codex App Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). diff --git a/docs/codebuddy/plan.md b/docs/codebuddy/plan.md new file mode 100644 index 0000000000..eaf909c392 --- /dev/null +++ b/docs/codebuddy/plan.md @@ -0,0 +1,164 @@ +# CodeBuddy Harness Adaptation Plan + +This document tracks the plan for adding CodeBuddy (Tencent Cloud Code Assistant) support to Superpowers, following the procedure in [porting-to-a-new-harness.md](../porting-to-a-new-harness.md). + +## Background + +CodeBuddy is Tencent Cloud's AI coding assistant (IDE + CLI). It is compatible with the Claude Code plugin format — it recognizes `.claude-plugin/plugin.json`, sets `CLAUDE_PLUGIN_ROOT` alongside `CODEBUDDY_PLUGIN_ROOT`, and expects the same `hookSpecificOutput.additionalContext` JSON shape from SessionStart hooks. + +- Integration shape: **Shape A (Shell-hook)** — same as Claude Code. +- Reference implementation: Claude Code itself (`.claude-plugin/plugin.json` + `hooks/hooks.json` + `hooks/session-start`). +- Distribution: `codebuddy plugin install` from a Git URL, or `codebuddy --plugin-dir` for local development. + +## Key findings from Phase 1 (feasibility verification) + +| Verification item | Result | Details | +|---|---|---| +| SessionStart hook fires | PASS | `executeSessionStartHooks source=startup` confirmed in logs | +| `CLAUDE_PLUGIN_ROOT` set | PASS | Both `CLAUDE_PLUGIN_ROOT` and `CODEBUDDY_PLUGIN_ROOT` set to plugin dir | +| `${CLAUDE_PLUGIN_ROOT}` expands in hook command | PASS | Command expanded to full path in logs | +| `session-start` script outputs correct JSON | PASS | `hookSpecificOutput.additionalContext` format, valid JSON, contains `` wrapper + full `using-superpowers` skill | +| Bootstrap context injected | PASS | "SessionStart hook provided additional context" in logs | +| Skills auto-discovered | PASS | 14 skills loaded from `./skills/` directory | +| Skills invokable via native tool | PASS | CodeBuddy has `use_skill` tool | +| Smoke check ("What are your superpowers?") | PASS | Model listed all 14 skills with correct categories | +| Acceptance test ("Let's make a react todo list") | PASS | `brainstorming` skill auto-triggered before any code; model started asking clarifying questions | + +### Minor issues found + +| Issue | Severity | Notes | +|---|---|---| +| `hooks-cursor.json` warning | Minor | CodeBuddy scans all `hooks/*.json` files; `hooks-cursor.json` has Cursor-specific format. Harmless — `hooks.json` loads correctly. | +| `--print` mode async hooks | Known limitation | In `--print` mode, SessionStart hooks fire async and are not awaited. Does not affect interactive mode (the normal usage pattern). | + +## Conclusion from Phase 1 + +**No modifications to `hooks/session-start`, `hooks/hooks.json`, or `.claude-plugin/plugin.json` are needed.** CodeBuddy sets `CLAUDE_PLUGIN_ROOT`, so the existing Claude Code branch in the session-start script fires correctly and outputs the exact JSON format CodeBuddy expects. The adaptation requires only: a tool-mapping reference file, a SKILL.md pointer, README install docs, and a test case. + +--- + +## Progress checklist + +### Phase 1 — Feasibility verification (Part 2–3) + +- [x] Verify CodeBuddy has a SessionStart hook with automatic injection (no per-session opt-in) +- [x] Verify environment variables: `CLAUDE_PLUGIN_ROOT` and `CODEBUDDY_PLUGIN_ROOT` are both set +- [x] Verify `${CLAUDE_PLUGIN_ROOT}` expands correctly in hook command strings +- [x] Verify `session-start` script outputs valid JSON with bootstrap content +- [x] Verify CodeBuddy consumes `hookSpecificOutput.additionalContext` format +- [x] Verify skills are auto-discovered from `./skills/` directory (14 skills loaded) +- [x] Verify native `use_skill` tool can invoke discovered skills +- [x] Smoke check: "What are your superpowers?" — model knows it has superpowers +- [x] Acceptance test: "Let's make a react todo list" — `brainstorming` auto-triggers before any code +- [x] Save acceptance test transcript + +### Phase 2 — Core adaptation (Part 5 Step 1–4) + +- [x] Confirm no changes needed to `hooks/session-start` (existing Claude Code branch works) +- [x] Confirm no changes needed to `hooks/hooks.json` (CodeBuddy compatible with Claude Code format) +- [x] Confirm no changes needed to `.claude-plugin/plugin.json` (CodeBuddy recognizes it directly) +- [x] Create `skills/using-superpowers/references/codebuddy-tools.md` — tool mapping +- [x] Add CodeBuddy to `SKILL.md` Platform Adaptation section +- [x] Add CodeBuddy install section to `README.md` +- [x] Add CodeBuddy test case to `tests/hooks/test-session-start.sh` +- [x] Verify all tests pass (6/6 passed) + +### Phase 3 — Distribution (Part 6) + +- [x] Verify `codebuddy plugin marketplace add` + `codebuddy plugin install` works end-to-end (tested with local directory; Git URL works the same way per docs) +- [x] Verify `codebuddy --plugin-dir /path/to/superpowers` works for local development (verified in Phase 1) +- [x] Verify installed plugin auto-loads skills and fires SessionStart hook without `--plugin-dir` (smoke check passed in interactive session) +- [x] Document install commands in README (marketplace add + plugin install + --plugin-dir dev mode) +- [x] No new manifest needed — `.claude-plugin/plugin.json` is recognized by CodeBuddy +- [x] No `.version-bump.json` entry needed — no new versioned manifest file + +### Phase 4 — PR submission (Part 8) + +- [ ] Search for existing CodeBuddy PRs (open and closed) +- [ ] Target `dev` branch +- [ ] Fill PR template "New harness support" section +- [ ] Disclose model (GLM-5v-Turbo), harness (CodeBuddy Code v2.117.0), and plugins used +- [ ] Paste complete acceptance test transcript +- [ ] One harness per PR — no bundled changes + +--- + +## Tool mapping summary + +| Action | CodeBuddy tool | +|---|---| +| Read a file | `read_file` | +| Create / edit / delete a file | `write_to_file`, `replace_in_file`, `delete_file` | +| Run a shell command | `execute_command` | +| Search file contents / find files | `search_content`, `search_file` | +| Fetch a URL / web search | `web_fetch`, `web_search` | +| Dispatch a subagent | `task` with `subagent_name` | +| Create / update todos | No native tool — use plan file or `TODO.md` | +| Invoke a skill | `use_skill` | + +See [references/codebuddy-tools.md](../skills/using-superpowers/references/codebuddy-tools.md) for the full mapping. + +--- + +## Acceptance test transcript + +Test environment: CodeBuddy Code v2.117.0, model GLM-5v-Turbo, plugin loaded via `--plugin-dir`. + +**Smoke check:** + +``` +> What are your superpowers? + +● I have several superpowers (skills) that help me work more effectively: + + Process Skills (set the approach): + - brainstorming - Explore user intent before creative work + - systematic-debugging - Methodical bug diagnosis + - test-driven-development - Write tests before code + - writing-plans - Create implementation plans + - executing-plans - Execute written plans + - verification-before-completion - Verify before claiming done + + Collaboration Skills: + - requesting-code-review / receiving-code-review - Code review workflows + - dispatching-parallel-agents - Run independent tasks in parallel + - subagent-driven-development - Use agents for implementation plans + + Workflow Skills: + - using-git-worktrees - Isolated workspace for feature work + - finishing-a-development-branch - Integrate completed work + + Meta Skills: + - using-superpowers - This reference guide + - writing-skills - Create/edit new skills + + Each skill has specific triggers and step-by-step instructions. I invoke them + automatically when they apply to the task at hand. +``` + +**Acceptance test:** + +``` +> Lets make a react todo list + +● Using brainstorming to explore what you need before building. + +● Skill(brainstorming) + ⎿ Skill "brainstorming" loaded. Follow the instructions below to complete it: + +● Let me check the current project state. +● Bash(ls -la /tmp/cb-tmux-test/) + ⎿ total 32 (empty directory) +● The directory is empty — we're starting from scratch. Let me understand + what you're looking for. + +What's the primary purpose of this todo list? Is it a learning project, a +portfolio piece, or something you'll actually use day-to-day? + +❯ 1. Basic CRUD only + 2. CRUD + 1-2 extras + 3. Feature-rich + 4. Type something +``` + +`brainstorming` skill auto-triggered before any code was written. **PASS.** diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 8a08873ba0..e9eb5cdc1d 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -56,6 +56,7 @@ If your harness appears here, read its reference file for special instructions: - Codex: `references/codex-tools.md` - Pi: `references/pi-tools.md` - Antigravity: `references/antigravity-tools.md` +- CodeBuddy: `references/codebuddy-tools.md` ## User Instructions diff --git a/skills/using-superpowers/references/codebuddy-tools.md b/skills/using-superpowers/references/codebuddy-tools.md new file mode 100644 index 0000000000..6b49581896 --- /dev/null +++ b/skills/using-superpowers/references/codebuddy-tools.md @@ -0,0 +1,28 @@ +# CodeBuddy Tool Mapping + +Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On CodeBuddy these resolve to the tools below. + +CodeBuddy is compatible with the Claude Code plugin format. The existing `.claude-plugin/plugin.json` manifest, `hooks/hooks.json` configuration, and `hooks/session-start` bootstrap script work without modification — CodeBuddy sets `CLAUDE_PLUGIN_ROOT` (in addition to `CODEBUDDY_PLUGIN_ROOT`) when running plugin hooks, so the session-start script's Claude Code branch fires correctly. + +| Action skills request | CodeBuddy equivalent | +| --- | --- | +| Read a file | `read_file` | +| Create / edit / delete a file | `write_to_file` (create/overwrite), `replace_in_file` (targeted edits), `delete_file` | +| Run a shell command | `execute_command` | +| Search file contents / find files by name | `search_content` (regex content search), `search_file` (filename pattern search) | +| Fetch a URL / web search | `web_fetch` (retrieve & summarize URL), `web_search` (search the web) | +| Dispatch a subagent | `task` with `subagent_name` — use `code-explorer` for codebase exploration. CodeBuddy also supports team mode for async parallel agents. | +| Create / update todos | No native todo tool. Track tasks in a plan file or `TODO.md`. | +| Invoke a skill | `use_skill` — the native skill-loading tool. Skills are auto-discovered from the plugin's `skills/` directory. | + +## Skills + +CodeBuddy has a native `use_skill` tool and auto-discovers skills from the plugin's `skills/` directory. When a skill applies, invoke it with `use_skill` and the skill name (e.g. `use_skill` with `command: "brainstorming"`). + +## Subagents + +CodeBuddy's `task` tool dispatches subagents. The `subagent_name` parameter selects the agent type (e.g. `code-explorer` for codebase exploration). CodeBuddy also supports a team mode where multiple agents work asynchronously in parallel and communicate via `send_message`. + +## Task tracking + +CodeBuddy has no native todo/task-list tool. When a skill says to create a todo list or track tasks, maintain a markdown checklist in a plan file or repo-local `TODO.md`. Older Superpowers docs may refer to `TodoWrite`; treat that as the task-tracking action above. diff --git a/tests/hooks/test-session-start.sh b/tests/hooks/test-session-start.sh index b027f3c650..9bf29e3ed3 100755 --- a/tests/hooks/test-session-start.sh +++ b/tests/hooks/test-session-start.sh @@ -185,6 +185,17 @@ assert_command_output \ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \ bash "$HOOK_UNDER_TEST" +codebuddy_home="$(make_home codebuddy)" +assert_command_output \ + "CodeBuddy emits nested SessionStart additionalContext (sets both CODEBUDDY_PLUGIN_ROOT and CLAUDE_PLUGIN_ROOT)" \ + "nested" \ + "" \ + "" \ + "$codebuddy_home" \ + CODEBUDDY_PLUGIN_ROOT="$REPO_ROOT" \ + CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \ + bash "$HOOK_UNDER_TEST" + legacy_home="$(make_home legacy-warning-removed)" mkdir -p "$legacy_home/.config/superpowers/skills" assert_command_output \