Skip to content

phase-hive — Team research layer

Hive is the team-level counterpart to flowie. Where flowie is the personal research OS (private, per-researcher), Hive is the shared lab OS (visible to all team members).

Privacy rule (enforced absolutely): Nothing from a personal .neuroflow/ project is ever automatically sent to Hive. Every share is an explicit, intentional action. The Hive is a shared workspace, not a surveillance layer.

Hive repo structure (GitHub org private repo)

{org}/{hive-repo}/
├── hive.md          ← team identity, norms, and active research directions
├── members.md       ← team roster: name, email, github, role
├── ideas.md         ← cross-project team hypotheses and open questions
├── sync.json        ← sync metadata: last pull per member, last push timestamps
├── projects/        ← lab project registry (same structure as flowie/projects/)
│   ├── projects.json
│   └── {id}.md
├── tasks/           ← team Kanban board (same structure as project tasks)
│   ├── inbox/
│   ├── ready/
│   ├── active/
│   ├── review/
│   ├── meeting/
│   ├── done/
│   └── archive/
├── meetings/        ← team meeting files (created by /meeting --level hive)
│   └── config.json
└── wiki/            ← team knowledge base (same structure as flowie wiki)
    ├── index.md
    ├── log.md
    ├── schema.md
    ├── raw/
    └── pages/

File formats

hive.md — team identity, norms, and directions (replaces old hive.md + directions.md): 

# {Team name}

{Team description — what the lab studies, approach, values}

## Norms
{collaboration norms, code standards, data policies}

## Active research directions
{Directions as bullet list or ## subsections — maintained by PI/leads}

members.md — team roster with contacts for meeting invitations: 

# Team Members

| name | email | github | role |
|------|-------|--------|------|
| {name} | {email} | {handle} | {PI/researcher/student} |

ideas.md — lab-wide cross-project hypotheses (analogous to flowie/ideas.md but team-level): 

# Team Ideas

Open hypotheses, cross-project questions, and speculative directions the lab is exploring.

---

projects/projects.json — machine index of all lab projects (same schema as flowie projects): 

{ "projects": [ { "id": "...", "description": "...", "current_phase": "...", "status": "..." } ] }

Local hive cache (global, per-user)

Hive data is cached at the user level — not inside any project repo.

~/.neuroflow/hives/{org-repo}/
├── hive.md          ← local copy of team identity + directions
├── members.md       ← local copy of team roster
├── ideas.md         ← local copy of team ideas
└── sync.json        ← hive_repo URL, last_pull, last_push, member_handle

One cache folder per hive the user belongs to. Created by /hive --init. Never committed to any project repo.

Command modes

--init

Connect the current neuroflow project to a Hive repo for the first time.

  1. Check flowie profile first: if ~/.neuroflow/flowie/profile.md exists and contains a hives: list, show it as a picker before asking freeform: 

    Your flowie profile lists these hives:
  [1] acme-neuroscience/hive-lab
  [2] another-org/hive-research
  [3] Enter a different repo
    If the user picks one, pre-fill the org/repo. Otherwise ask freeform.

  2. Ask for the GitHub org and repo name: {org}/{hive-repo}

  3. Ask for the researcher's GitHub handle (used as member_handle in sync.json)
  4. Check if the hive repo already exists (via gh CLI or GitHub API)

If joining an existing hive repo: - Clone or fetch to read hive.md, members.md, and sync.json - Create ~/.neuroflow/hives/{org-repo}/ with local copies + initial sync.json - Update .neuroflow/flow.md + project_config.md - Show team identity from hive.md and members from members.md

If creating a new hive repo: - Scaffold full structure (all folders and files from the structure above) - Ask: "Team name and description?" - Ask: "Active research directions? (one per line)" → write to ## Active research directions in hive.md - Ask: "Add team members? (name, email, GitHub handle, role — one per line, Enter to skip)" → write to members.md - Push to GitHub: gh repo create {org}/{hive-repo} --private

--sync

Pull latest state and show a digest of what changed since last pull.

  1. Record current state: git -C (local hive cache) log --oneline or note last_pull timestamp
  2. Fetch hive.md, members.md, ideas.md, and sync.json from hive repo
  3. Update local ~/.neuroflow/hives/{org-repo}/ copies
  4. Update sync.json with last_pull: [timestamp]
  5. Digest: compare old and new versions and print a structured change summary: 
    Hive sync — 2026-04-20 10:00
─────────────────────────────
directions: 1 new (Alpha modulation → fMRI feasibility)
members: no changes
ideas: 2 new entries
wiki: 3 pages updated, 1 new (method: ICA pipeline)
tasks: 2 new in inbox, 1 moved → done
─────────────────────────────
  6. If any new directions overlap with the current project's modality or research question, highlight them: "New team direction may be relevant: {direction}"

--view

Display current local Hive state without syncing.

  1. Read ~/.neuroflow/hives/{org-repo}/hive.md and members.md
  2. Read sync.json for last sync timestamp
  3. Print team identity, directions, member count, last sync
  4. Print: "Run /hive --sync to fetch the latest updates."

--members

View and edit the team roster.

  1. Read members.md from hive repo (pull first)
  2. Display the members table
  3. Options: add member, remove member, update role/email
  4. Write updated members.md, push to hive repo

--projects

View and manage the lab project registry (analogous to /flowie --projects).

  1. Pull projects/projects.json from hive repo
  2. Display all lab projects as ASCII phase timeline (same format as flowie projects)
  3. Sub-flags: --projects --add to register a new lab project (asks id, description, repos, current phase, status)
  4. Push changes to hive repo

--ideas

View and append to lab-wide cross-project ideas.

  1. Pull ideas.md from hive repo
  2. Display current ideas
  3. Ask: "Add a new idea?" — if yes, append to ideas.md, push
  4. Also triggered from wiki ingest when synthesis spans multiple projects

--tasks

Read and manage the team Kanban board at {hive-repo}/tasks/. Same ASCII box rendering rules as /flowie --tasks --level hive. Tasks get level: hive and responsible: @name in frontmatter. Pull first, push after writes. Supports --tasks, --tasks --list, --tasks --add, --tasks --move, --tasks --done.

--recommend

Get team-aware recommendations for the current project phase.

  1. Read local hive.md (directions section) and members.md
  2. Read current project's project_config.md
  3. Check wiki/ for relevant methods and synthesis pages (search index.md)
  4. Surface:
  5. Team directions overlapping this project's modality or research question
  6. Methods from hive wiki relevant to the current phase
  7. Ideas from ideas.md that connect to this project
  8. Present as compact digest: "Your team has N relevant items for your current phase"

--wiki, --wiki-ingest, --wiki-query, --wiki-lint, --wiki-add, --wiki-schema

Operate on the hive-level team wiki at {hive-repo}/wiki/. Load neuroflow:wiki skill with level: hive. Same modes as /flowie --wiki-* but all git operations target the hive repo. This replaces the old shared/ folder — use --wiki-ingest to contribute findings, methods, and literature to the team knowledge base.

Collaborator join flow

When a new team member joins a project that already has neuroflow set up, they follow this sequence:

  1. Clone the project repo — .neuroflow/ is present (tasks/, notes/, project_config.md are all git-tracked)
  2. Run /neuroflow — detects existing .neuroflow/project_config.md, shows current state, prompts for their own name and flowie setup
  3. Run /flowie — set up or link their own private flowie profile; clones to ~/.neuroflow/flowie/ (each collaborator has a separate private flowie repo, never inside the project)
  4. Run /hive --sync — pull team directions, member list, and shared content; cached to ~/.neuroflow/hives/{org-repo}/

What is shared vs. private:

Path Shared in project repo?
.neuroflow/project_config.md Yes — shared context for all
.neuroflow/tasks/ Yes — shared project Kanban
.neuroflow/notes/ Yes — shared meeting notes
.neuroflow/sessions/ No — gitignored (personal logs)
~/.neuroflow/flowie/ No — global per-user, never in project
~/.neuroflow/hives/{org-repo}/ No — global per-user cache, never in project

Privacy and data governance

What Shared to Hive?
Research question Never automatically — only if user explicitly runs --share
Session logs Never
Raw data paths or outputs Never
Analysis results Never automatically — only with --share
Personal project_config.md fields Never
Something the user explicitly approves via --share Yes, after confirmation

The Hive is pull-first: the researcher benefits from team knowledge without being required to share anything back.

Authentication

Hive uses the same GitHub credentials as the user's local git config. The gh CLI (GitHub CLI) is preferred for push operations — check with gh auth status. If not available, fall back to constructing GitHub API calls with a PAT (personal access token) that the user provides.

Authentication instructions: 

gh auth login   # recommended
# or configure git credentials for HTTPS push

Relevant skills

  • neuroflow:neuroflow-core — read first; defines the command lifecycle and .neuroflow/ write rules
  • neuroflow:phase-flowie — the personal-project counterpart to Hive; understand flowie before implementing Hive to avoid overlap