Skip to content

Update cerebro-knowledge

TL;DR — Single contribution procedure for every kind of change to cerebro-knowledge (skill, workflow, wiki page, service catalog edit, etc.). Clone, branch from master with a flat name, edit per AGENTS.md, test live through the cerebro MCP by swapping SEC_MCP_BITBUCKET_BRANCH (strongly recommended — the agent must explicitly ask the developer before skipping), then open a PR with default reviewers.

Overview

cerebro-knowledge ships its contributing conventions inside the repo itself (AGENTS.md). This workflow does not restate them — it covers the procedural envelope around the change: clone, branch, optional local test, PR.

Before editing anything, read the relevant section of AGENTS.md for the artifact you are changing:

  • Editing a skill → AGENTS.md → Skills and AGENTS.md → Skill Authoring Guidelines.
  • Editing a workflow → AGENTS.md → Workflows.
  • Editing the wiki → AGENTS.md → Wiki.
  • Touching the service catalog → AGENTS.md → Services Catalog (note: the catalog files are auto-generated — do not edit them by hand).
  • For all artifact types → AGENTS.md → Conventions for Contributing.

The MCP integration details, env vars, full config block, and the branch-override mechanism used in Step 5 live on the wiki page: wiki/ai-tooling/cerebro-knowledge.md. This workflow only references them.

Inputs

Input Description
change_description A short summary of what is being changed (e.g. "add a new wiki page about X", "fix typo in nestjs skill").
artifact_type One of skill, workflow, wiki, index-update. If unsure, consult wiki/ai-tooling/cerebro-knowledge.md → What lives in cerebro-knowledge — that page describes each artifact type and is MCP-served, so you can decide before cloning. Drives which AGENTS.md section to read in Step 2 and which index.md to update later.
branch_name Short, kebab-case, no slashes (see Step 3).

Steps

Shell-session note — Each Bash invocation is a fresh subshell. Variables from previous steps do not persist; re-derive REPO_DIR from the filesystem as needed: 

REPO_DIR=$(ls -dt "$HOME"/.securitize/tmp/cerebro-knowledge-*/ 2>/dev/null | head -1)
REPO_DIR="${REPO_DIR%/}"

1. Clone cerebro-knowledge

REPO_DIR="$HOME/.securitize/tmp/cerebro-knowledge-$(date +%Y%m%d%H%M%S)"
mkdir -p "$HOME/.securitize/tmp"
git clone --depth 1 git@bitbucket.org:securitize_dev/cerebro-knowledge.git "$REPO_DIR"

# Confirm mainline is master — cerebro-knowledge branches from master
git -C "$REPO_DIR" rev-parse --abbrev-ref HEAD   # must print: master

If the clone fails, ask the developer to verify SSH access to securitize_dev, then stop. If the confirm command does not print master, stop and investigate — do not proceed on any other base.

2. Read AGENTS.md for the artifact type

# Always re-derive REPO_DIR in a fresh subshell (see shell-session note above)
sed -n '/^## /p' "$REPO_DIR/AGENTS.md"   # quick outline of section titles

Open $REPO_DIR/AGENTS.md and skim the section matching artifact_type (see Overview for the mapping). Do not start writing yet — the conventions there are mandatory and will save a round of review comments otherwise.

3. Create the branch (from master, flat name)

No slashes in the branch name

Use a flat hyphen-separated name (e.g. workflow-update-cerebro-knowledge, skill-fix-nestjs-config). The cerebro MCP picks branches via the SEC_MCP_BITBUCKET_BRANCH env var; slashes are awkward to pass through JSON / shell quoting and are a known foot-gun. See wiki/ai-tooling/cerebro-knowledge.md → Branch override for local testing.

cd "$REPO_DIR"
git checkout -b "<branch_name>" master   # explicit base = master, flat name

4. Make the changes

Edit files inside $REPO_DIR per the conventions you read in Step 2. Remember the core invariants from AGENTS.md:

  • Facts live in wiki/, principles in skills/, imperative procedures in workflows/. Do not blur the boundaries.
  • Strict SSOT. A new fact lives in exactly one wiki page; everything else links to it. Do not restate it inline elsewhere.
  • English only, factual tone, no personal opinions.
  • Update the relevant index.md when adding a new skill / workflow / wiki page. Each workflows/index.md entry must have both **Trigger when**: ... and a **NOT for X** negative clause where an adjacent category exists.
  • Service catalog files under services/ are auto-generated — do not edit them by hand.

Stage and commit when done:

cd "$REPO_DIR"
git add <files>
git commit -m "<conventional commit message>"

Always ask the developer before proceeding to Step 6

Do not skip this step silently. Before continuing to push, explicitly ask the developer:

"Want to test this through the cerebro MCP before opening the PR? Strongly recommended — it catches issues that the PR review will not, because reviewers see the markdown source but the MCP serves it through get_workflow_file / get_wiki_file calls with anchor resolution, frontmatter parsing, and so on. The test reveals integration problems the diff cannot."

Only skip when all of the following are true: (a) the developer explicitly declines, or (b) the change is a literal typo or whitespace fix with no behavioural impact AND the developer agreed to skip. A change to any frontmatter, any heading, any link, any new file, or any procedural step is not trivial — ask.

The mechanism, env-var name, and the table of default config-file paths per agent (Claude Code, Claude Desktop, Cursor, Windsurf, etc.) are in wiki/ai-tooling/cerebro-knowledge.md → Branch override for local testing. The procedure below is agent-agnostic — substitute $MCP_CONFIG with the path your agent uses.

# Pick whichever path your agent uses (see the wiki table linked above).
# Examples:
#   Claude Code:    MCP_CONFIG="$HOME/.claude.json"
#   Claude Desktop: MCP_CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
#   Cursor:         MCP_CONFIG="$HOME/.cursor/mcp.json"
#   Windsurf:       MCP_CONFIG="$HOME/.codeium/windsurf/mcp_config.json"
export MCP_CONFIG="<path to your agent's MCP config file>"
  1. Back up the config file first (avoid the foot-gun of breaking it with a bad edit): 
    mkdir -p "$HOME/.mcp-config-backups"
cp "$MCP_CONFIG" "$HOME/.mcp-config-backups/$(basename "$MCP_CONFIG").$(date +%Y%m%d-%H%M%S).bak"
  2. Edit the SEC_MCP_BITBUCKET_BRANCH value for the cerebro server entry inside $MCP_CONFIG, replacing master with <branch_name> from Step 3. Surgical edit only — do not touch the surrounding tokens.
  3. Validate the JSON parses cleanly: 
    python3 -c "import json; json.load(open('$MCP_CONFIG'))" && echo "JSON OK"
  4. Restart the agent (close and reopen, or reload the MCP server through whatever mechanism the agent provides). The MCP reads its env vars at startup; in-flight changes are ignored.
  5. Trigger a request that exercises the change (e.g. ask for the workflow you edited, or the wiki page) and verify the MCP returns the branch's content.
  6. When done testing, restore SEC_MCP_BITBUCKET_BRANCH to master and restart the agent again.

If something goes wrong with the edit, restore the backup from $HOME/.mcp-config-backups/ and restart the agent.

6. Push the branch

cd "$REPO_DIR"
git push -u origin "<branch_name>"

7. Open the Pull Request

Target: securitize_dev/cerebro-knowledge, source = the branch from Step 3, destination = master.

Preferred — open the PR through any Bitbucket-capable MCP you have available. Tool names and parameter shapes vary by server (mcp__bitbucket__*, mcp__atlassian__*, custom servers, etc.); scan your tool list for tools that act on Bitbucket pull requests. Whatever the surface, perform two operations:

  1. Resolve the repo's effective default reviewers for workspace=securitize_dev, repo=cerebro-knowledge. Keep the returned user identifiers.
  2. Create the pull request with:
  3. source = the branch from Step 3
  4. destination = master
  5. title = a conventional-commit-style summary of the change
  6. description = what changed and why; if any wiki/workflow content was added, include a one-line summary of each new piece
  7. reviewers = the identifiers from (1)

Fallback — no Bitbucket MCP available. Show the developer the manual URL and stop:

https://bitbucket.org/securitize_dev/cerebro-knowledge/pull-requests/new?source=<branch_name>&dest=master

In either path, show the final PR link to the developer.

8. Clean up

rm -rf "$REPO_DIR"

If Step 5 was exercised and the SEC_MCP_BITBUCKET_BRANCH env var is still pointing at the test branch, remind the developer to restore it to master (or to whichever branch they were on before) inside their agent's MCP config and restart the agent.

Verification

  • The PR is open on securitize_dev/cerebro-knowledge against master.
  • All changed index.md files include the new entry where applicable.
  • For each new skill / workflow / wiki page, the YAML frontmatter is present and well-formed.
  • If Step 5 was exercised, the MCP successfully served the new content from the branch.

Rollback

This workflow writes nothing outside the temporary clone until the branch is pushed (Step 6).

  • Before push (Steps 1-5): rm -rf "$REPO_DIR" discards everything. If the agent's MCP config was edited in Step 5, restore the backup created in Step 5.1 (from $HOME/.mcp-config-backups/).
  • After push, before merge: decline the PR in Bitbucket; delete the remote branch.
  • After merge: open a revert PR against master removing the merged change.

See also

Tags

workflow #cerebro #cerebro-knowledge #contribution #mcp