brain-github-export

Export accumulated brain knowledge as CONVENTIONS.md and open a GitHub PR so your whole team can review what the AI team learned.

Trigger

This skill activates when the user runs /brain-github-export or /claude-teams-brain:brain-github-export.

Workflow

Step 1 — Export conventions from brain

Run the following command and capture the JSON output:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/brain_engine.py" export-conventions "${CLAUDE_PROJECT_DIR}"

Parse the JSON response:

• content — the full Markdown content for CONVENTIONS.md
• rules_count — number of manual rules/conventions
• decisions_count — number of architectural decisions
• files_count — number of key files tracked

Write the content field to ${CLAUDE_PROJECT_DIR}/CONVENTIONS.md.

If the content is empty or there is no brain data yet, tell the user:

"No brain data found for this project. Run some Agent Team sessions first to build memory, then try again."

Step 2 — Check GitHub CLI availability

gh auth status

If gh is not installed or not authenticated, tell the user:

"GitHub CLI (gh) is required. Install it from https://cli.github.com and run gh auth login, then retry."

Stop here if gh is not available.

Step 3 — Check git repo

Verify this is a git repo:

git -C "${CLAUDE_PROJECT_DIR}" rev-parse --git-dir

If not a git repo, tell the user and stop.

Step 4 — Check for changes

cd "${CLAUDE_PROJECT_DIR}"
git diff --quiet CONVENTIONS.md 2>/dev/null || echo "changed"
git ls-files --others --exclude-standard CONVENTIONS.md 2>/dev/null

If CONVENTIONS.md has no changes and is not a new file, tell the user:

"CONVENTIONS.md is already up to date. No PR needed."

Step 5 — Create branch, commit, and open PR

cd "${CLAUDE_PROJECT_DIR}"
BRANCH="brain/conventions-$(date +%Y%m%d-%H%M)"
git checkout -b "$BRANCH"
git add CONVENTIONS.md
git commit -m "docs: update CONVENTIONS.md from claude-teams-brain session"
git push -u origin HEAD

Then open a PR:

gh pr create \
  --title "🧠 AI Team Conventions Update" \
  --body "$(cat <<'EOF'
## AI Team Conventions Update

This PR was automatically generated by [claude-teams-brain](https://github.com/Gr122lyBr/claude-teams-brain) from accumulated Agent Team session memory.

### What's in this PR

This file captures everything your AI team has learned about this codebase:
- Project rules & conventions (set via `/brain-remember`)
- Architectural decisions made by Agent Team teammates
- Key files and which agents have worked on them

### Why review this?

Merging `CONVENTIONS.md` makes your AI team's institutional knowledge visible to the whole human team. It also seeds future AI sessions with verified, human-reviewed conventions.

### What to do

1. Review the conventions — remove anything outdated or incorrect
2. Merge to share with your team
3. The brain will keep updating this as your AI team learns more

---
_Generated by [claude-teams-brain](https://github.com/Gr122lyBr/claude-teams-brain) — persistent memory for Claude Code Agent Teams_
EOF
)"

Step 6 — Return the PR URL

Parse the output of gh pr create to get the PR URL and show it to the user:

"✅ PR opened: https://github.com/your-org/your-repo/pull/123"

Also mention:

"💡 You can automate this with the GitHub Actions template at ${CLAUDE_PLUGIN_ROOT}/profiles/github-actions-conventions.yml — copy it to .github/workflows/ in your repo."

Error handling

• If git push fails (e.g., no remote, permission denied): show the error and suggest the user push manually
• If branch already exists: append a random suffix or increment a counter
• If no changes after writing CONVENTIONS.md: tell user nothing changed and skip PR
• Always clean up by returning to the original branch on failure: git checkout -

Notes

• ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} are set by Claude Code in the hook environment and in the shell environment when running commands
• The skill works best after at least 2-3 Agent Team sessions so there is meaningful data to export
• Run /brain-stats to see how much data is in the brain before exporting