brainstack

Team Brain — Sync Mode

Part of Brainstack: personal=engineer-brain, crew=team-brain.

Prefer	Fallback
MCP start / prepare_research / recall / remember / compliance / peer_notify / correct / history / restore / delete_memory / touch	bash …/team-brain-api.sh …

Peer push (#31)

start may attach a Realtime signal listener (bodies still via authenticated pull).
If .team-brain/notify/<KEY>.json updates mid-session, summarize new peer memories before continuing.
If push is unavailable (TEAM_BRAIN_REALTIME=off / no websockets / migration missing), poll/watch/recall still work.

Repo pin (#39) + roles (#40)

• Prefer pinned Jira key from .team-brain/project.json when the user omits a key (start / attach).
• Never put anon / api_key / invite into the pin — credentials stay gitignored.
• whoami.role: viewer → recall only; member/admin → remember + delete OK; only admin rotates invites / list_members.

Permission tiers

Role	Read (recall, list, breakdown, history, metrics)	Write (remember, correct, restore, attach)	Delete (delete_memory)	Admin (rotate invite, set-role, list-members)
viewer	✅	❌	❌	❌
member	✅	✅	✅	❌
admin	✅	✅	✅	✅

Onboard requires --role member|viewer (admin assigns tier explicitly).

Compliance (policy=stronger_prompts)

v1 follow-up chose stronger prompts + soft session gate (not a hard CLI block).

• Before deep research: research_ok must be true (start loads context, or prepare_research / recall).
• If sync_status / compliance returns agent_action, follow it before coding.
• After durable findings: remember with source_ref in the same turn.
• Humans may still use the CLI offline; agents must not skip the loop.
• Never upload personal BRAIN.md.

bash "$API" compliance <JIRA-KEY>
bash "$API" sync-status <JIRA-KEY>   # embeds compliance

API="${SKILL_DIR}/scripts/team-brain-api.sh"
# or: <engineer-brain-repo>/core/scripts/team-brain-api.sh

---

Product loop (what the engineer does)

1. One manual step — start sync for the ticket
2. Automatic while active — background pull into cache; you summarize + work
3. Save findings — remember with source_ref (merge-safe)
4. On human correction — correct (or re-remember same source_ref) + optional learning
5. Long spikes — periodic recall (or optional background watch); do not spam every turn
6. Idle sleep — after ~1h no activity, sync sleeps; prompt user to wake

---

1) START (when user begins team work)

User will often say things like:

I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
/team-brain start YOU_JIRA_TICKET_HERE
Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
Stop Team Brain sync for YOU_JIRA_TICKET_HERE.

Run:

bash "$API" start <JIRA-KEY>
bash "$API" sync-status <JIRA-KEY>   # confirm compliance.research_ok

Then read .team-brain/cache/<JIRA-KEY>.json, summarize crew memory, then explore.

If already active, touch and read cache (or MCP prepare_research / recall for a topic).

If sleep, tell the user and run wake only after they agree (or if they asked to continue).

2) WHILE WORKING

Each turn on this key:

bash "$API" touch <JIRA-KEY>
bash "$API" compliance <JIRA-KEY>   # if agent_action set → follow it

After durable findings:

bash "$API" remember <JIRA-KEY> research --source-ref "<JIRA-KEY>#<short-slug>" "<finding>"

Merge rules (server):

Case	Result
New finding	insert
Same body / hash	deduped no-op
Same source_ref, new body	updated (merge — no second row)

Long sessions — refresh without spam (#37)

Sync-mode background pull + peer push help, but long spikes can still go stale vs teammates.

When to refresh (pick one trigger; do not do this every turn):

• After a long research block (multi-file dig, spike write-up, or “keep going” stretch), or
• Roughly every 8–10 turns of continuous work on the same key

Then run a quiet refresh:

bash "$API" recall <JIRA-KEY>          # or MCP prepare_research / recall
# if .team-brain/notify/<KEY>.json updated → summarize new peer memories first

Optional (human / once per spike): suggest background watch so the cache stays warm without relying only on idle sleep / next start:

bash "$API" watch <JIRA-KEY> &           # poll
# or: bash "$API" watch <JIRA-KEY> --push &

Do not spam: at most one soft nudge per stretch (“cache may be stale — refresh?”). Prefer silent recall over asking every turn.

Sleep / wake still wins: if sync-status is sleep, prompt wake (do not treat watch as a substitute). If stopped, offer start.

Memory body style

Write natural-language guidance (“prefer X”, “avoid Y”).
Do not dump TODO / NO-TODO lists into remembered bodies.

3) CORRECTION / LEARNING (when the human corrects you)

When the user pastes a correction, contradicts a sync summary, or says research was wrong — treat that as ground truth. Do not argue.

That research is wrong — the schema lives in packages/ansible-language-server, not tox-ansible.

Correct Team Brain memory for YOU_JIRA_TICKET_HERE#cli-schema — prefer …

Then:

# Preferred: update + optional learning in one shot
bash "$API" correct <JIRA-KEY> --source-ref "<JIRA-KEY>#<short-slug>" \
  --was "Incorrect claim…" \
  --learning "Was wrong: … Prefer: …" \
  "Corrected durable finding…"

# Equivalent: re-remember same source_ref (updates, does not fork)
bash "$API" remember <JIRA-KEY> research --source-ref "<JIRA-KEY>#<short-slug>" "Corrected finding…"
bash "$API" remember <JIRA-KEY> learning --source-ref "<JIRA-KEY>#<short-slug>/learning" \
  "Was wrong: … Prefer: …"

Step	Action
1	Identify the topic source_ref (same slug as the bad research)
2	correct or re-remember → expect updated: true (not a second row)
3	Optionally record learning at REF/learning (what was wrong → what to prefer)
4	Confirm briefly to the user; continue with corrected context

source_ref updates archive the prior body (when the history migration is applied). To inspect or undo:

bash "$API" history <JIRA-KEY> --source-ref "<JIRA-KEY>#<short-slug>"
bash "$API" restore <JIRA-KEY> --source-ref "<JIRA-KEY>#<short-slug>" --revision 1

restore soft-rollbacks and archives the current body first — audit trail is preserved.

Personal standup corrections follow the same absorb-and-learn pattern in /engineer-brain (update BRAIN.md, close scanner gaps).

4) STOP / SLEEP

bash "$API" stop <JIRA-KEY>     # leave sync mode
bash "$API" wake <JIRA-KEY>     # resume after sleep

When sync-status shows sleep, prompt the user before continuing deep work.

5) Breakdown

bash "$API" breakdown <JIRA-KEY>

Never invent stories without recalled memories.

---

Commands

Command	Purpose
start	Enter sync mode — load memory + background pull
stop / wake / touch	Leave / resume / keep awake
sync-status	active | sleep | stopped (+ compliance)
compliance	Soft MCP-first gate (research_ok, agent_action)
bootstrap	Admin one-shot setup + share bundle
admin-setup	Preferred admin path — fill supabase/admin.setup.env, then run script (no flags)
onboard / register / join	Membership
attach	Bind Jira key
recall / remember	Search / save (learning kind ok); on redundant_candidate recall + same source_ref or --queue; admin may --force
correct	Update source_ref + optional learning
history / restore	Revision audit trail / soft rollback
delete	Tombstone poisoned memory (member/admin)
list-members	Admin audit of crew roles
pending list / approve <pending-id> / reject <pending-id>	Admin reviews overriding context (#67)
breakdown / metrics / status	Plan / stats / config

MCP also exposes prepare_research (recall + compliance in one call).

Beginner guide: docs/team-brain-onboarding.md

Admin onboarding (once per crew)

One file — no scattered flags/env:

cp supabase/admin.setup.env.example supabase/admin.setup.env
# edit every TEAM_BRAIN_* value (admin name, crew, Jira epic, Supabase URL + anon)
bash core/scripts/team-brain-admin-setup.sh

Or: bash core/scripts/team-brain-admin-setup.sh --init then edit supabase/admin.setup.env.

After success, DM .team-brain/share-bundle.txt to members. Runtime config lands in supabase/project.public.env (auto-written).

Hard rules

• User’s one step: start (or ask you to start)
• Context first from cache before research (research_ok / follow agent_action)
• remember with source_ref; never clobber unrelated rows
• If remember returns redundant_candidate: true → do not fork; recall existing, reuse source_ref, or remember --queue for admin
• On human correction: update the matching source_ref (never fork)
• Memory bodies: prefer/avoid prose — no TODO/NO-TODO dumps
• Long sessions: refresh via recall after research blocks / ~8–10 turns — never every turn
• Prompt on sleep; watch does not replace wake; never commit credentials.json
• Never upload personal BRAIN.md

This site is open source. Improve this page.