feat(using-superpowers): add Claude Code to Platform Adaptation + claude-tools.md#1894
Open
gercotermaat wants to merge 20 commits into
Open
feat(using-superpowers): add Claude Code to Platform Adaptation + claude-tools.md#1894gercotermaat wants to merge 20 commits into
gercotermaat wants to merge 20 commits into
Conversation
Prompt: Jesse asked for a new worktree off the local superpowers dev branch to add the Codex manifest after diagnosing why github.com/obra/superpowers did not show installable Codex plugins. Root cause: Codex marketplace sources expect a .agents/plugins/marketplace.json at the marketplace root. The superpowers repo only had the Claude marketplace file and the Codex plugin manifest, so Codex could configure the marketplace name but found no installable plugin entries. Changes: add a repo-local Codex marketplace manifest for superpowers-dev that points at this same repository root via the same-root source pattern Codex already accepts; add a focused marketplace manifest test; remove the unsupported hooks field from .codex-plugin/plugin.json so the plugin validator accepts the manifest. Validation: bash tests/codex/test-marketplace-manifest.sh; uv run --with PyYAML python /Users/jesse/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py /Users/jesse/git/superpowers/superpowers/.worktrees/codex-marketplace-manifest; throwaway HOME codex plugin marketplace add/list/add; bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh; bash tests/kimi/test-plugin-manifest.sh; bash tests/shell-lint/test-lint-shell.sh; scripts/lint-shell.sh tests/codex/test-marketplace-manifest.sh.
Prompt: Jesse questioned whether the PR should remove the hooks config from the Codex plugin manifest. Runtime investigation showed Codex accepts a committed plugin manifest with hooks and installs the plugin successfully. Removing the field changes behavior: Codex falls back to the default hooks/hooks.json, which uses the non-Codex session-start hook and CLAUDE_PLUGIN_ROOT path, instead of hooks/hooks-codex.json and the session-start-codex script. Changes: restore .codex-plugin/plugin.json hooks to ./hooks/hooks-codex.json and update the Codex marketplace manifest test to require that Codex-specific hook pointer instead of rejecting hooks. Validation: bash tests/codex/test-marketplace-manifest.sh; scripts/lint-shell.sh tests/codex/test-marketplace-manifest.sh; bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh; bash tests/kimi/test-plugin-manifest.sh; bash tests/shell-lint/test-lint-shell.sh.
…clear|compact) Bug: the SessionStart hook matcher in hooks-codex.json included "resume", causing the superpowers bootstrap to re-fire on every Codex session resume. Fix: align with Claude's hooks/hooks.json matcher "startup|clear|compact": - drop "resume" (the bug: resume should not trigger re-bootstrap) - add "compact" (so bootstrap re-injects after context compaction, like Claude) Before: "matcher": "startup|resume|clear" After: "matcher": "startup|clear|compact"
Codex reliably triggers skills on its own, and the SessionStart hook made the UX worse rather than better. Drop the Codex hook config and its registration in the plugin manifest.
Google EOLed the Gemini CLI on 2026-06-18; the extension can no longer be installed or updated. Remove Gemini from the install docs, the subagent-capable platform lists, and the eval-harness description, and delete its tool-mapping reference.
The verbose action-to-tool tables and skill-loading explainers in the per-harness reference files restated guidance modern agents already follow. Trim each file to the harness-specific notes that still carry weight (subagent dispatch, task tracking, instructions-file paths), and delete claude-code-tools.md and copilot-tools.md, which had nothing left that wasn't generic.
The bootstrap is injected into every session, so its token cost is paid constantly. Condense it without dropping behavior-shaping content: - Replace the graphviz skill-flow diagram with the prose it encoded (the 1% rule, the plan-mode to brainstorm gate, announce + checklist to todos). - Fold the standalone Instruction-Priority section into User Instructions. - Drop the per-platform 'How to Access Skills' walkthrough. - Trim the Platform Adaptation pointer to the harnesses that still have a reference file (Codex, Pi, Antigravity). Keeps the full Red Flags rationalization table, skill priority framed as process-before-implementation, and user-instruction precedence.
Commit 1f0c76e removed the Codex SessionStart hook — dropping the hooks field from .codex-plugin/plugin.json and deleting hooks-codex.json — but left test-marketplace-manifest.sh asserting the old hooks pointer, so the test has failed on dev since. Assert the field is absent instead, locking in the no-Codex-hooks decision.
…ll, Gemini removed Bump all manifests to 6.1.0 and add RELEASE-NOTES for v6.1.0: - Compress the using-superpowers bootstrap and prune per-harness tool-mapping references (lower per-session token cost). - Add a Codex marketplace manifest so the plugin installs from Codex; drop the Codex SessionStart hook. - Remove Gemini CLI support (Google EOLed the Gemini CLI 2026-06-18).
…s object
Codex auto-discovers a plugin's hooks/hooks.json whenever the Codex
manifest has no `hooks` field: load_plugin_hooks falls back to a
hardcoded DEFAULT_HOOKS_CONFIG_FILE = "hooks/hooks.json" and registers
it. hooks/hooks.json is the Claude Code SessionStart hook, it is tracked
in this repo, and the Codex marketplace installs the whole repo root
(source url "./"), so the fallback re-registered the SessionStart hook
and its install-time trust prompt on Codex.
Removing the Codex hook file and the manifest `hooks` pointer (commit
"Remove Codex hooks") did not disable the hook on Codex — it removed the
explicit declaration that was overriding the fallback, so the fallback
took over and found the Claude hooks/hooks.json.
Declare an empty inline hooks object ({}) in .codex-plugin/plugin.json.
It parses as an empty inline hook set and stops Codex reaching the
auto-discovery fallback. An absent field, an empty array ([]), and an
empty inline list all collapse back to the fallback, so the value must
be exactly {}.
Update the test to assert the manifest declares hooks: {} (and that
hooks/hooks.json exists, which is what makes the declaration necessary),
replacing the prior assertion that the field was absent — which passed
while the hook was still being auto-discovered.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… docs hooks/session-start-codex has had no caller since "Remove Codex hooks" (obra#1845) deleted hooks-codex.json and its manifest registration; the Codex manifest now declares an empty hooks object so Codex registers no session-start hook at all. The script is Codex-specific dead code — nothing executes it on Codex or any other harness. - Delete hooks/session-start-codex. - tests/hooks/test-session-start.sh: drop the two Codex cases that are redundant with the generic session-start tests (nested-format and the legacy-warning omission are already covered by the Claude Code cases). Re-point the "wrapper dispatches" case to the live `session-start` script so run-hook.cmd dispatch coverage — used by Claude Code and Cursor in production — is preserved rather than lost. - docs/porting-to-a-new-harness.md: Codex is no longer a Shape A (shell-hook) harness, so re-anchor that worked example to Cursor (a live shell-hook harness that demonstrates the same per-harness field, schema, and matcher variance) and mark Codex as native skill discovery with no session-start hook. Clears the references to the deleted hooks-codex.json. - docs/windows/polyglot-hooks.md: the "check hooks-codex.json" pointer referenced a file deleted in obra#1845; re-point to hooks-cursor.json. RELEASE-NOTES.md keeps its historical mention of hooks-codex.json (it accurately records what that release did). The tests/codex-plugin-sync fixtures build their own synthetic session-start-codex and test the sync mechanism generically, so they are intentionally left as-is. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Who is submitting this PR? (required)
What problem does this PR solve? (required)
The
Platform Adaptationsection inskills/using-superpowers/SKILL.mdlists harness-specific reference files for Codex, Pi, and Antigravity — but does not mention Claude Code, which is the primary harness for this plugin. A Claude Code agent reading the bootstrap would not know to look for a Claude Code-specific tool mapping reference.Additionally, commit 4000288 deleted
claude-code-tools.mdbut left thewriting-skills/SKILL.mdfile referencingreferences/claude-code-tools.mdas the path to check — agents reading that file would find a broken link.This PR:
- Claude Code: \references/claude-tools.md`to the Platform Adaptation list inSKILL.md`skills/using-superpowers/references/claude-tools.mdwith Claude Code tool mappings (Skill, Agent/Task, TaskCreate/TaskUpdate/TaskList/TaskGet, instructions file path, personal skills directory)Is this change appropriate for core?
Yes. Claude Code is the primary harness documented in this repo. Adding a reference entry to the Platform Adaptation section and creating the corresponding tool-mapping file is factual reference material that benefits any Claude Code agent using Superpowers.
What alternatives did you consider?
Existing PRs
Searched open and closed PRs. The original
claude-code-tools.mdwas created in PR #1486 and subsequently deleted in commit 4000288 ("Prune per-harness tool-mapping boilerplate"). This PR restores Claude Code support to the Platform Adaptation section with a focused mapping file.Does this PR contain multiple unrelated changes?
No. Both changes (SKILL.md update + new claude-tools.md) are part of the same coherent change: adding Claude Code to the Platform Adaptation section.
Environment tested
Changes reviewed via GitHub web editor. The tool mapping content is based on the previously merged
claude-code-tools.mdfrom PR #1486 commit 2f5c75d, with theTodoWrite/TaskCreatenote from the dev branch history.