docs: add CodeBuddy CLI installation section to README

[m9rco]

Update (2026-05-21)

Re-targeting this PR at dev and removing the harness-specific verify step per @obra's review feedback (comment). README now adds only the install commands for CodeBuddy CLI, positioned alphabetically between Claude Code and Codex App to match upstream/dev's existing ordering. Final diff: +15 / -1, README.md only.

The PlanMode-trap context below is preserved for historical accuracy of the original investigation, but the README no longer contains the verify/warning text it references.

---

What problem are you trying to solve?

I am a daily user of CodeBuddy CLI (Claude-Code-compatible coding agent). I expected Superpowers to "just work" via CodeBuddy's documented Claude Code Hooks compatibility (CodeBuddy CLI v1.16.0+ implements the full Claude Code Hooks spec, supports ${CLAUDE_PLUGIN_ROOT}, and recognizes .claude-plugin/ directories per its official compatibility documentation). The installation experience left me stuck because:

1. README has no entry point for CodeBuddy users. Among 8 supported harnesses listed, CodeBuddy is absent. I had to reverse-engineer the install command from the Claude Code section.

2. First attempted session failed mysteriously due to a CodeBuddy-specific trap. When I sent "Let's make a react todo list" in my first CodeBuddy session, the agent went into CodeBuddy's built-in PlanMode (toggled with Tab), not Superpowers' brainstorming skill:

   ● Entered plan mode
     ⎿  CodeBuddy is now exploring and designing an implementation approach.
   
   Do you want to create this as a new standalone React project (e.g., using Vite or Create React App), or add it to the existing codebase here?
   
   1. New Vite project
   ...
   

   I mistakenly believed Superpowers wasn't installed.

3. After clearing PlanMode and starting a fresh session, brainstorming auto-triggered correctly:

   ● Skill(brainstorming)
     ⎿ Skill "brainstorming" loaded. Follow the instructions below to complete it:
   
   ● Using brainstorming to design the React todo list before implementation.
   

So the integration already works at the code level via CodeBuddy's native skill auto-invocation — what's missing is README documentation telling CodeBuddy users (a) it's supported and (b) the install command.

What does this PR change?

Adds a ### CodeBuddy CLI installation section to README.md, inserted alphabetically between ### Claude Code and ### Codex App to match the strict alphabetical ordering already established on dev. Adds the corresponding [CodeBuddy CLI](#codebuddy-cli) entry in the README quickstart anchor list, also alphabetically positioned. No code changes, no new files, no changes to skills/hooks/plugin manifests. Single file diff: +15 / -1.

The harness-specific verify step / PlanMode warning from the original revision has been removed per maintainer feedback — every other harness section is install-only, and this section now matches that convention.

Is this change appropriate for the core library?

Yes. README.md already documents installation entry points for 9 harnesses on dev (Claude Code, Codex App, Codex CLI, Cursor, Factory Droid, Gemini CLI, GitHub Copilot CLI, OpenCode, Pi). CodeBuddy CLI joins as the 10th — pure documentation increment with identical structural treatment. Not a third-party promotion: CodeBuddy's Claude Code Hooks compatibility is a unilateral choice by CodeBuddy team to align with Anthropic's Claude Code spec, and Superpowers' existing plugin layout works there unchanged.

Does this PR contain multiple unrelated changes?

No. Single concern: README adds one more harness installation section. SessionStart hook investigation remains deferred to a separate follow-up per "one problem per PR".

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
CodeBuddy CLI	2.79.1	Claude-Opus-4.6

Host OS: macOS 14.7.3 (build 23H417), shell zsh.

New harness support (required if this PR adds a new harness)

This PR is on the boundary: code-level support already exists in upstream CodeBuddy CLI v1.16.0+ (no Superpowers code change needed). The "newness" is README documentation only.

The acceptance test from the PR template — "Let's make a react todo list" auto-triggers brainstorming in a clean session — passes via CodeBuddy's native skill auto-invocation:

Clean-session transcript for "Let's make a react todo list"

> /clear
  ⎿ (No content)

> Let's make a react todo list

● Skill(brainstorming)
  ⎿ Skill "brainstorming" loaded. Follow the instructions below to complete it:

 The user wants to make a React todo list. I need to follow the brainstorming skill process. Let me start by:
 1. Exploring the project context
 2. Asking clarifying questions one at a time
 ... 1 more lines (press Ctrl+O to expand)

● Using brainstorming to design the React todo list before implementation.

● Bash(ls /Users/marcopu/t/lab/superpowers)
  ⎿ AGENTS.md             LICENSE               docs                  package.json
    CLAUDE.md             README.md             gemini-extension.json scripts
    CODE_OF_CONDUCT.md    RELEASE-NOTES.md      hooks                 skills
    ...+1 line (ctrl+o to expand)

 This is the superpowers plugin repo itself, not a project where we'd build a React todo list. The user wants to
 create a React todo list — this is a brainstorming exercise. Let me check if there's any existing React project
 structure or if we need to start fresh.

● Read(package.json)
  ⎿ Read 7 lines (ctrl+o to expand)

● I see the current directory is the superpowers plugin repo itself — not a project where we'd build a todo app. We'll
   want to create the React todo list as a separate project.

  Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put
  together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be
  token-intensive. Want to try it? (Requires opening a local URL)

The brainstorming skill not only triggered but loaded its body and executed the workflow (initial codebase exploration, recognition that this is a plugin repo not a target project, offer of the visual brainstorming companion).

For honesty, I had a prior failed session caused by CodeBuddy's built-in PlanMode being toggled on, which intercepts skill auto-invocation. This was the original motivation for adding a verify step to the README; per maintainer feedback that harness-specific verify steps don't belong in README, that text has been removed from this PR.

Failed session transcript (PlanMode interception, before PlanMode toggled off)

> Let's make a react todo list

● Entered plan mode
  ⎿  CodeBuddy is now exploring and designing an implementation approach.

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
←  ☐ Project setup  ☐ Features  ✔ Submit  →

Do you want to create this as a new standalone React project (e.g., using Vite or Create React App), or add it to the existing
codebase here?

  1. New Vite project
     Create a fresh React + Vite project in a new directory
  2. New CRA project
     Create a fresh project using Create React App
  3. Add to existing
     Add the todo list within the current checkersvrd project
  4. Type something
  Next

Note: the failure case shows CodeBuddy's built-in PlanMode flow ("CodeBuddy is now exploring and designing"), distinct from Skill(brainstorming) invocation.

Evaluation

• Initial prompt that started the session leading to this change: "Let's make a react todo list" (the PR template's own acceptance-test prompt) — sent in CodeBuddy CLI as a self-check, observed first failure (PlanMode interception), then success after PlanMode toggle off.
• Eval sessions run AFTER making the change: 1 fresh-session run in the superpowers checkout itself (cwd shown in transcript above). brainstorming auto-triggered, loaded the skill body, began the workflow (initial clarifying question, codebase exploration via ls and package.json read, visual-brainstorming companion offer), with PlanMode confirmed off. I have not independently re-verified in additional working directories within this PR cycle.
• Outcomes: Before this PR, CodeBuddy users have no entry point in README. After this PR, they have a clear install path consistent with all other harness sections.

Rigor

• If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (paste results below)

• N/A — no skill content modified.

• This change was tested adversarially, not just on the happy path

• First session unintentionally hit the PlanMode auto-trap (real failure, not contrived). Subsequent fresh session with PlanMode off triggered brainstorming and executed the skill workflow correctly.

• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals

• N/A — README only.

Known limitations & follow-up

CodeBuddy CLI does not load plugin-level SessionStart hooks declared in hooks/hooks.json. --debug confirms zero hook activity, and /hooks panel shows "No matchers configured yet" even with the plugin enabled. As a result, the using-superpowers bootstrap (the framing) is not injected at session start in CodeBuddy.

This does not break the acceptance test, because CodeBuddy's native skill auto-invocation triggers brainstorming from the skill's own description frontmatter alone. But it does mean the bootstrap-driven behavior reinforcement that other harnesses receive is missing on CodeBuddy.

I will investigate and propose a fix in a separate PR per "one problem per PR". This PR does not block on that.

Human review

• A human has reviewed the COMPLETE proposed diff before submission

[obra]

Hi, would you mind retargeting the dev branch instead of main and I don't think we want harness specific test instructions that are really the same test instruction.

[m9rco]

Okay, got it. I split it into two MRs due to issues with hook script installation. ：）

[m9rco]

Updated per your review:

• Re-targeted at dev (was main).
• Dropped the CodeBuddy-specific verify step — the section is now install-only, matching every other harness section on dev.
• Rebased on upstream/dev; reconciled the alphabetical ordering it introduced (CodeBuddy CLI now slots between Claude Code and Codex App in both the quickstart anchor list and the install section).

Final diff: +15 / -1, README.md only. New head SHA: 7074b79. PR body updated to reflect these changes; the failed-session transcript is kept as historical context but no longer references README verify text.

Sorry for the closed/reopen churn — hook-script work is being split off into a separate PR as planned.