/brain-github-export

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