feat: migrate open-brain plugin to ai-brain repo#16
Merged
Conversation
Design for migrating the open-brain Claude Code plugin out of flippyhead/radar into this repo, renaming to ai-brain, upgrading skills for v3 server capabilities (hybrid search, progressive disclosure, timeline, citations), and publishing via a thin distribution repo (flippyhead/ai-brain-plugin) mirrored by CI. Co-Authored-By: Claude <noreply@anthropic.com>
21 tasks across 4 phases: migrate plugin from radar to ai-brain, upgrade three existing skills (brain-init, brain-sync, weekly-review) for v3 server shape + citations, add two new skills (brain-thread, brain-context) leveraging timeline_thoughts, publish via CI mirror to flippyhead/ai-brain-plugin. Includes skill->tool drift check script + workflow to prevent server/plugin drift. Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Renamed env var prefixes OPEN_BRAIN_* to AI_BRAIN_*. Updated nudge text to mention the new brain-thread and brain-context skills. clientInfo now identifies as ai-brain-hook v3.0.0. Co-Authored-By: Claude <noreply@anthropic.com>
Renamed all 'Open Brain' references to 'AI Brain'. Added note about new compact-index return shape of search_thoughts and how to use get_thoughts to confirm duplicate candidates. Report step now cites each captured thought as thought:<id> and suggests the two new navigation skills. Co-Authored-By: Claude <noreply@anthropic.com>
Step 3 reworked into 3a/3b/3c: triage via compact search_thoughts index, select up to 5 hydration candidates, fetch full content via get_thoughts. Diff now operates on hydrated docs only. Report cites each captured thought and each unchanged prior thought as thought:<id>. Co-Authored-By: Claude <noreply@anthropic.com>
Step 2 replaces ad-hoc recent-thought fetching with an explicit timeline_thoughts(aroundMs=weekStartMs, before=0, after=50) call. Step 4 hydrates up to 10 noteworthy thoughts via get_thoughts before the synthesis. Every section of the output now requires citations — thought:<id>, insight:<id>, list:<id>. The saved summary itself includes the grounding citations so future reviews can trace back. Co-Authored-By: Claude <noreply@anthropic.com>
New skill walks timeline_thoughts around a seed (topic or thought ID), hydrates 3-5 substantive neighbors via get_thoughts, and produces a citable markdown narrative. Enforces thought:<id> citations for every claim in the output. Co-Authored-By: Claude <noreply@anthropic.com>
New skill resolves a time reference (date, range, or event-like phrase resolved via search_thoughts), pulls a timeline window via timeline_thoughts, hydrates 5-8 diverse thoughts via get_thoughts, and produces a cited markdown brief. Enforces thought:<id> citations throughout. Co-Authored-By: Claude <noreply@anthropic.com>
Install instructions, skill descriptions, tips, and troubleshooting. Written for end users, not plugin developers. Co-Authored-By: Claude <noreply@anthropic.com>
Documents skill conventions (progressive disclosure, citations, graceful empty-brain), version source of truth, local test procedure, and CI checks. Co-Authored-By: Claude <noreply@anthropic.com>
Scans SKILL.md files and hook scripts for mcp__ai-brain__<tool> references, cross-checks against the MCP_TOOL_NAMES registry in apps/web/src/lib/mcp/tools.ts, and exits non-zero on drift. Prevents the class of breakage where a server tool rename leaves skill prompts pointing at nothing. Co-Authored-By: Claude <noreply@anthropic.com>
- Registered tools: slice to MCP_TOOL_NAMES block before scanning, so unrelated snake_case strings in tools.ts can't pollute the set. - Hook refs: require method: "tools/call" context before matching name: "<tool>", so other JSON-RPC methods (e.g. future resources calls) don't create false positives. - Allow digits in tool names via [a-z0-9_]+ for forward-compat. Co-Authored-By: Claude <noreply@anthropic.com>
Runs on any PR or push that touches plugin skills, the tool registry, the drift check script itself, or its workflow. Fails the PR if a skill references an unregistered tool. Co-Authored-By: Claude <noreply@anthropic.com>
Reads the plugin version and metadata from plugins/ai-brain/.claude-plugin/plugin.json and emits a flat marketplace.json suitable for a single-plugin distribution repo (source: "./"). Keeps version as single source of truth. Co-Authored-By: Claude <noreply@anthropic.com>
Triggered on version tag push (v*) or manual dispatch. Clones the distribution repo with SSH deploy key, wipes contents except .git and README.md, copies plugins/ai-brain/* to the root, generates a flat marketplace.json, commits, tags, and pushes. Version tags are mirrored exactly from source to distribution. Co-Authored-By: Claude <noreply@anthropic.com>
- Pass all ${{ }} variables through env: to eliminate script injection
risk (github.event_name, inputs.tag, steps.ref.outputs.tag).
- Detect distribution default branch instead of hardcoding main.
- Add idempotent tag check: fail fast with a clear message if the
source tag already exists in the distribution repo.
- Add permissions: contents: read for least privilege.
- Add concurrency group to prevent race on concurrent tag pushes.
Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Review Summary by QodoMigrate open-brain plugin to ai-brain repo with v3 upgrades and distribution CI
WalkthroughsDescription• Migrates the open-brain plugin from flippyhead/radar to this repo as ai-brain with comprehensive v3 server upgrades (hybrid search, progressive disclosure, timeline, citations) • Implements 5 skills: brain-init (zero-input bootstrapping), brain-sync (project context sync), weekly-review (timeline-based synthesis), brain-thread (topic evolution tracing), brain-context (temporal memory retrieval) • Adds SessionStart hook (check-brain-status) to detect empty brains and suggest initialization • Establishes CI/CD infrastructure: skill→tool drift validation workflow, plugin distribution mirror publishing to flippyhead/ai-brain-plugin on version tag push • Includes marketplace configurations for dev installs and distribution, plugin manifest as single source of truth for versioning • Provides comprehensive documentation: design spec, implementation plan, user guide, and developer maintenance guidelines Diagramflowchart LR
radar["flippyhead/radar<br/>open-brain plugin"]
migration["Migration Process"]
aibrain["ai-brain repo<br/>5 skills + hook"]
cicheck["Skill→Tool<br/>Drift Check"]
publish["Publish Workflow<br/>on tag push"]
distmirror["flippyhead/ai-brain-plugin<br/>Distribution Mirror"]
radar -- "migrate & upgrade" --> migration
migration --> aibrain
aibrain -- "validate" --> cicheck
aibrain -- "trigger on version tag" --> publish
publish -- "sync plugin source" --> distmirror
File Changes1. docs/superpowers/plans/2026-04-20-ai-brain-plugin-migration.md
|
Code Review by Qodo
1. Tag mirror skipped
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+98
to
+123
| - name: Commit and tag | ||
| id: publish | ||
| env: | ||
| TAG: ${{ steps.ref.outputs.tag }} | ||
| run: | | ||
| cd dist | ||
| git add -A | ||
| if git diff --staged --quiet; then | ||
| echo "No changes — skipping commit/tag." | ||
| echo "changed=false" >> "$GITHUB_OUTPUT" | ||
| exit 0 | ||
| fi | ||
| git commit -m "release: ai-brain $TAG (from flippyhead/ai-brain@$TAG)" | ||
| git tag "$TAG" | ||
| echo "changed=true" >> "$GITHUB_OUTPUT" | ||
|
|
||
| - name: Push commit and tag to distribution | ||
| if: steps.publish.outputs.changed == 'true' | ||
| env: | ||
| TAG: ${{ steps.ref.outputs.tag }} | ||
| BRANCH: ${{ steps.distbranch.outputs.branch }} | ||
| run: | | ||
| cd dist | ||
| git push origin "$BRANCH" | ||
| git push origin "$TAG" | ||
|
|
There was a problem hiding this comment.
1. Tag mirror skipped 🐞 Bug ≡ Correctness
In publish-plugin.yml, the workflow exits early when there are no staged file changes, so it never creates/pushes the distribution tag even though the tag was verified not to exist. This breaks the “mirror tags exactly” behavior and can leave the distribution repo missing the version tag users expect.
Agent Prompt
## Issue description
The publish workflow currently skips `git tag` (and the subsequent push) when `git diff --staged --quiet` indicates no content changes in the distribution repo. This can cause a source tag (e.g. `v3.0.0-rc.1`) to *not* be mirrored to the distribution repo even though the workflow verified the tag doesn’t already exist.
## Issue Context
Even if the mirrored plugin contents are identical to the previous distribution commit, the distribution repo should still receive the new tag so that tags mirror the source repo’s versioning contract.
## Fix Focus Areas
- .github/workflows/publish-plugin.yml[98-123]
## Implementation guidance
- Separate “commit if changed” from “tag always”.
- If no changes:
- Create the tag pointing at the current checked-out commit in `dist`.
- Push the tag (and optionally skip pushing the branch).
- If changes:
- Commit, create the tag, and push both branch and tag.
- Ensure the push step(s) run when a tag was created, not only when a commit was created.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit cf43130. Configure here.
| { | ||
| "name": "ai-brain", | ||
| "description": "Personal AI memory — hybrid search, timeline retrieval, citable thoughts.", | ||
| "version": "3.0.0", |
There was a problem hiding this comment.
Root marketplace version hardcoded despite "single source of truth" design
Medium Severity
The root .claude-plugin/marketplace.json hardcodes "version": "3.0.0", but CLAUDE.md states the version's single source of truth is plugin.json and says "Don't hand-edit marketplace versions." Only the distribution marketplace is generated from plugin.json by CI; the root marketplace is a static file with no sync mechanism. On the next version bump to plugin.json, the root marketplace will silently drift — and the CLAUDE.md guidance actively discourages the manual fix needed to correct it.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit cf43130. Configure here.
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
1 participant
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.
Summary
Migrates the
open-brainplugin out offlippyhead/radarinto this repo, renamed toai-brain, upgraded for the v3 server (hybrid search, progressive disclosure, timeline, citations). Publishes toflippyhead/ai-brain-pluginvia CI mirror on version tag push.Spec
docs/superpowers/specs/2026-04-20-ai-brain-plugin-migration-design.mdWhat's in this PR
plugins/ai-brain/— 3 upgraded skills + 2 new skills + hookTest Plan
🤖 Generated with Claude Code
Note
Medium Risk
Adds a new Claude Code plugin plus GitHub Actions that publish to an external distribution repo via SSH deploy key; mistakes could break releases or push incorrect contents/tags. No server-side logic changes, but CI automation and install surface area are significant.
Overview
Introduces a new
ai-brainClaude Code plugin (v3.0.0) inplugins/ai-brain/, including a SessionStart hook (check-brain-status.mjs) and five skills (migratedbrain-init,brain-sync,weekly-reviewplus newbrain-threadandbrain-context) updated to use progressive disclosure (search_thoughtsindex +get_thoughtshydration),timeline_thoughts, and explicitthought:<id>/insight:<id>/list:<id>citation requirements.Adds plugin packaging + automation: a repo-root
.claude-plugin/marketplace.jsonfor dev installs, a script to generate a flat distributionmarketplace.jsonfromplugins/ai-brain/.claude-plugin/plugin.json, a CI drift-check that verifies skill/hook tool references matchMCP_TOOL_NAMES, and a tag-triggeredpublish-pluginworkflow that mirrors the plugin intoflippyhead/ai-brain-plugin(with tag/branch handling and safety checks).Reviewed by Cursor Bugbot for commit cf43130. Bugbot is set up for automated code reviews on this repo. Configure here.