feat(engineer-brain): require Atlassian MCP Jira signal for sync

.gitignore

@@ -44,3 +44,6 @@ supabase/.bootstrap-migrations.combined.sql
 # .engineer-brain/BRAIN.md
 # *.pdf
 # RESUME.md
+
+# Local-only workshop runbook (not published)
+docs/workshop-brainstack-day0.md

README.md

@@ -21,7 +21,8 @@
   <a href="#engineer-brain">engineer-brain</a> •
   <a href="#team-brain">Team Brain</a> •
   <a href="docs/architecture.md">Architecture</a> •
-  <a href="docs/team-brain-onboarding.md">Onboarding</a> •
+  <a href="docs/team-brain-onboarding.md">Team Onboarding</a> •
+  <a href="docs/engineer-brain-onboarding.md">engineer-brain Setup</a> •
   <a href="docs/roadmap.md">Roadmap</a> •
   <a href="docs/faq.md">FAQ</a>
 </p>
@@ -211,7 +212,7 @@ Bob's agent knows → suggests OAuth2 without re-researching
 Carol runs breakdown → draft includes Alice's auth decision
 ```
 
-> **Docs:** [Team Brain Overview](docs/team-brain.md) · [Onboarding](docs/team-brain-onboarding.md) · [Tutorial](docs/team-brain-tutorial.md) · [Demo](docs/team-brain-demo.md)
+> **Docs:** [Team Brain Overview](docs/team-brain.md) · [Team Onboarding](docs/team-brain-onboarding.md) · [engineer-brain Setup](docs/engineer-brain-onboarding.md) · [Tutorial](docs/team-brain-tutorial.md) · [Demo](docs/team-brain-demo.md)
 
 ---
 
@@ -472,6 +473,7 @@ brainstack/
 │   ├── scopes.md                      # Umbrella: engineer + team skills
 │   ├── team-brain.md                  # Team Brain overview
 │   ├── team-brain-onboarding.md       # Junior join path
+│   ├── engineer-brain-onboarding.md   # Standup signals (gh + Atlassian MCP)
 │   ├── team-brain-memory.md           # Collaborative memory plan (P0–P4)
 │   ├── brain-spec.md
 │   ├── vision.md

core/COMMANDS.md

@@ -11,7 +11,8 @@ for daily syncs and quarterly reviews.
    accurate than local commits alone
 3. **BRAIN.md** — the living document (located in the platform-specific directory or `core/BRAIN.md`)
 4. **Session/conversation history** (platform-specific: Cursor transcripts, Claude projects, etc.)
-5. **Jira / Linear / project tracker** (if integration available)
+5. **Jira** — **Cursor:** Atlassian MCP ([marketplace plugin](https://cursor.com/marketplace/atlassian), required for `sync`). **Other platforms:** `jira.sh` when `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` are set.
+6. **Linear / other trackers** (if integration available)
 
 **Critical:** Standup-relevant work is frequently *not* in authored git commits.
 Reviews, releases, demos, meetup/office-hours prep, and design-feedback work must
@@ -56,7 +57,7 @@ weekend, skip — standups don't happen on weekends.
    - Authored PRs updated in the window
    - Reviews given in the window
    - Recent releases on configured repos
-   - Tracker issues in the open sprint + BRAIN.md upcoming events
+   - BRAIN.md upcoming events
 
 2a. **Calendar signal (gcal, optional but preferred when available):**
    - If the `gcal` MCP is connected, call `status()` first.
@@ -73,6 +74,20 @@ weekend, skip — standups don't happen on weekends.
    - Calendar events are read-only signal only — never invent events that
      didn't come from `gcal`/BRAIN.md. Precision over recall.
 
+2b. **Jira signal (required on every `sync`):**
+   - **Hard rule:** Never finalize standup without querying Jira.
+   - **Cursor:** use **`plugin-atlassian-atlassian`** ([Atlassian plugin](https://cursor.com/marketplace/atlassian)).
+     If namespace missing / `needsAuth` → point user to `ONBOARDING.md` (installed) or
+     [engineer-brain-onboarding.md](../docs/engineer-brain-onboarding.md) Step 3; mark Jira **blocked** in standup.
+   - **Other platforms:** run `bash <path-to-scripts>/jira.sh done 1` (or `done 3` on Monday) when `JIRA_*` env is set.
+   - **When Atlassian MCP is connected (Cursor):**
+     1. `getAccessibleAtlassianResources` → `cloudId` (required for `searchJiraIssuesUsingJql`)
+     2. JQL — tickets updated in the standup window (e.g. `assignee = currentUser() AND updated >= startOfDay(-1)`)
+     3. JQL — `assignee = currentUser() AND statusCategory = "In Progress"` (matches `jira.sh active`)
+     4. Optional open sprint — merge into bullets with ticket keys (`PROJ-12345`).
+
+2c. **Platform note:** Atlassian MCP is **Cursor-only**. Claude Code, Copilot, Windsurf, Aider, and Continue.dev use `jira.sh` for the Jira signal — see [ONBOARDING.md](../docs/engineer-brain-onboarding.md) Step 5.
+
 3. Read `BRAIN.md` for sprint context, active tickets, and scheduled team
    events (`Upcoming Events` table — the fallback when gcal isn't configured).
 
@@ -204,6 +219,11 @@ Analyze current patterns and provide actionable feedback.
 
 Fetch your assigned Jira issues, grouped by status.
 
+**Preferred in Cursor:** Atlassian MCP (`plugin-atlassian-atlassian`) — see
+[ONBOARDING.md](../docs/engineer-brain-onboarding.md) Step 3 (installed copy: `.engineer-brain/ONBOARDING.md` or `.cursor/skills/engineer-brain/ONBOARDING.md`).
+
+**CLI fallback** (terminals / non-MCP platforms):
+
 **Usage:** `jira [filter] [days]`
 
 **Filters:**
@@ -225,7 +245,7 @@ Fetch your assigned Jira issues, grouped by status.
 **Required env vars:** `JIRA_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
 
 **Integration with other commands:**
-- When running `sync`, also run `jira done 1` (or `jira done 3` on Monday) to include recently closed Jira tasks in standup notes.
+- **`sync`:** Cursor uses Atlassian MCP when the plugin is connected (see step 2b). Other platforms: `jira done 1` (or `jira done 3` on Monday) when MCP is unavailable.
 - When running `quarterly`, also run `jira quarterly` to include all closed Jira tasks for the quarter in the review content.
 - When running `reflect`, check `jira all` for stale assigned issues that haven't been updated recently.
 
@@ -396,9 +416,10 @@ After each `update`, compare current state against previous state:
 
 ## Integration Points
 
-- **Daily sync**: Run `sync` before standup meetings
+- **Daily sync**: Run `sync` before standup meetings — always includes Jira (Atlassian MCP on Cursor; `jira.sh` elsewhere)
+- **Onboarding**: [engineer-brain-onboarding.md](../docs/engineer-brain-onboarding.md) — installed as `ONBOARDING.md` beside your skill or `.engineer-brain/`
 - **Weekly reflection**: Run `reflect` on Fridays
 - **Monthly update**: Run `update` at month start
 - **Quarterly prep**: Run `quarterly` before performance reviews
-- **Jira integration**: Run `jira` command to pull assigned tasks, completed work, and sprint data
+- **Jira CLI fallback**: `jira` command when Atlassian MCP unavailable and `JIRA_*` env is set
 - **Session analyzer**: If session analytics are available, pull AI usage stats

core/scripts/doctor.sh

@@ -401,6 +401,16 @@ if [ "$S_IDENTITY" -ge 50 ] && { [ "$SCAN_AVAILABLE" -eq 1 ] || [ "$S_SPRINT" -g
   STANDUP_READY=1
 fi
 
+JIRA_CLI_READY=0
+if [ -n "${JIRA_URL:-}" ] && [ -n "${JIRA_EMAIL:-}" ] && [ -n "${JIRA_API_TOKEN:-}" ]; then
+  JIRA_CLI_READY=1
+fi
+
+GH_READY=0
+if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+  GH_READY=1
+fi
+
 QUARTERLY_READY=0
 if [ "$S_IDENTITY" -ge 50 ] && [ "$S_SKILLS" -ge 30 ] && [ "$S_VELOCITY" -ge 30 ]; then
   QUARTERLY_READY=1
@@ -450,8 +460,15 @@ if [ "$SCAN_AVAILABLE" -eq 1 ]; then
   printf "Active This Week:        %d\n" "$ACTIVE_THIS_WEEK"
 fi
 printf "Skills Updated:          %s\n" "$(check_mark "$SKILLS_UPDATED")"
+printf "GitHub CLI (gh):         %s\n" "$(check_mark "$GH_READY")"
+printf "Jira CLI (JIRA_* env):   %s\n" "$(check_mark "$JIRA_CLI_READY")"
 printf "Standup Ready:           %s\n" "$(check_mark "$STANDUP_READY")"
 printf "Quarterly Review Ready:  %s\n" "$(check_mark "$QUARTERLY_READY")"
+if [ "$JIRA_CLI_READY" -eq 0 ]; then
+  echo ""
+  echo "Jira signal: Cursor → install Atlassian MCP (Settings → Plugins)."
+  echo "             Other platforms → set JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN (see ONBOARDING.md)."
+fi
 
 if [ "${#COOLING_REPOS[@]}" -gt 0 ]; then
   echo ""

docs/architecture.md

@@ -217,6 +217,17 @@ configured, falling back to BRAIN.md's `Upcoming Events` table otherwise.
 
 See [mcp/gcal/README.md](../mcp/gcal/README.md).
 
+### Integration: Jira
+
+Required for **`engineer-brain sync`** — ticket work often has no git/PR signal.
+
+| Platform | Jira signal |
+|----------|-------------|
+| **Cursor** | [Atlassian marketplace plugin](https://cursor.com/marketplace/atlassian) + OAuth → `plugin-atlassian-atlassian` MCP |
+| **Other adapters** | `core/scripts/jira.sh` when `JIRA_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` are set |
+
+Setup: [engineer-brain-onboarding.md](engineer-brain-onboarding.md) (installed as `ONBOARDING.md` beside your skill or under `.engineer-brain/`).
+
 ---
 
 ## Layer 3: Delivery (Platform Adapters)

docs/engineer-brain-onboarding.md

@@ -0,0 +1,165 @@
+# engineer-brain — onboarding
+
+**Who this is for:** anyone using `engineer-brain sync` for daily standups.  
+**Time:** ~15 minutes (one-time setup).  
+**You need:** an AI assistant with Brainstack installed, git repos in your workspace, GitHub CLI, and a Jira signal (see below).
+
+---
+
+## What gets configured
+
+| Signal | Required? | Setup |
+|--------|-----------|--------|
+| Git history | Yes | Clone team repos under your workspace |
+| GitHub PRs/reviews | Yes | `gh auth login` |
+| **Jira tickets** | **Yes** | **Atlassian MCP** (Cursor) or **`jira.sh`** (other platforms) |
+| Google Calendar | Optional | [gcal MCP](https://github.com/Hrithik-Gavankar/brainstack/blob/main/mcp/gcal/README.md) — demos, workshops, meetups |
+| `BRAIN.md` | Yes (identity) | Fill name/role/team after `install.sh` |
+
+`sync` **always** pulls Jira. Do not run standup prep without a working Jira signal.
+
+---
+
+## Step 1 — Install engineer-brain
+
+```bash
+git clone https://github.com/Hrithik-Gavankar/brainstack.git
+cd brainstack
+bash install.sh cursor ~/path/to/your-workspace   # or claude-code, vscode-copilot, etc.
+```
+
+Verify (Cursor example):
+
+```bash
+ls ~/.cursor/skills/engineer-brain/SKILL.md
+ls ~/.cursor/skills/engineer-brain/ONBOARDING.md
+ls ~/.cursor/rules/engineer-brain.mdc
+```
+
+Open `BRAIN.md` in your platform skill directory (or `.engineer-brain/BRAIN.md`) and fill **Identity** + **Current Sprint Context**.
+
+---
+
+## Step 2 — GitHub CLI
+
+```bash
+gh auth login
+gh auth status
+```
+
+Used by `scan.sh` for authored PRs, reviews, and releases.
+
+---
+
+## Step 3 — Jira signal (required)
+
+### Cursor — Atlassian MCP (recommended)
+
+Jira is **not** configured in `~/.cursor/mcp.json`. Use the official **Cursor marketplace plugin** (OAuth — no API token in shell).
+
+#### 3.1 Install the plugin
+
+1. Open **Cursor**.
+2. Go to **Settings** → **Plugins** (or open [cursor.com/marketplace/atlassian](https://cursor.com/marketplace/atlassian)).
+3. Find **Atlassian** (by Atlassian) and click **Install** / **Enable**.
+4. Reload Cursor if prompted.
+
+The plugin registers MCP namespace `plugin-atlassian-atlassian` and points at Atlassian's hosted server (`https://mcp.atlassian.com/v1/mcp/authv2`). You do **not** add a manual `mcpServers` block for Jira.
+
+#### 3.2 Authorize (first use)
+
+1. Start a Cursor chat in your workspace.
+2. Ask: *"Who am I on Atlassian?"* or run `/engineer-brain sync`.
+3. When the OAuth browser window opens, sign in with your **company Atlassian** account (e.g. `you@company.com` on `your-org.atlassian.net`).
+4. Approve the requested Jira/Confluence scopes.
+
+First-time site install may require a user who has access to the Jira projects you use; after that, other crew members can authorize individually.
+
+> **Example (Red Hat):** `you@redhat.com` on `redhat.atlassian.net`, project keys like `AAP-xxxxx`.
+
+#### 3.3 Verify
+
+In chat, the agent should succeed on:
+
+- `atlassianUserInfo` — returns your name and email
+- `getAccessibleAtlassianResources` — returns your site cloud id (e.g. `your-org.atlassian.net`)
+- `searchJiraIssuesUsingJql` — returns your assigned issues (requires `cloudId` from the previous call)
+
+If the agent reports **no Jira namespace** or **needsAuth**:
+
+| Symptom | Fix |
+|---------|-----|
+| Plugin not listed in Settings → Plugins | Re-install from marketplace; restart Cursor |
+| OAuth never appeared | Retry a Jira tool call; check pop-up blocker |
+| `401` / expired session | Re-authenticate via plugin settings or repeat OAuth flow |
+| Org blocks Rovo MCP | Ask your Atlassian admin — [control settings](https://support.atlassian.com/security-and-access-policies/docs/control-atlassian-rovo-mcp-server-settings/) |
+
+#### 3.4 What `sync` queries (automatic)
+
+When you run `/engineer-brain sync`, the agent **must**:
+
+1. Resolve `cloudId` via `getAccessibleAtlassianResources`
+2. Run JQL for tickets **updated in the standup window** (yesterday, or Friday-only on Mondays)
+3. Run JQL for your **active** assignments (`statusCategory = "In Progress"`)
+4. Optionally check open sprint (`sprint in openSprints()`) — many teams do not sprint-tag every ticket; the in-progress query is the fallback
+
+**Sample JQL** (replace `CLOUD_ID` with the id from `getAccessibleAtlassianResources`):
+
+```text
+# Tuesday–Friday: tickets you touched yesterday
+assignee = currentUser() AND updated >= startOfDay(-1) ORDER BY updated DESC
+
+# Monday standup: Friday only
+assignee = currentUser() AND updated >= startOfDay(-3) AND updated < startOfDay(-1) ORDER BY updated DESC
+
+# Carry-forward for "today" section
+assignee = currentUser() AND statusCategory = "In Progress" ORDER BY updated DESC
+```
+
+Tickets surface in standup as `PROJ-12345` (your project key) with impact language, not raw JQL dumps.
+
+### Other platforms — `jira.sh` CLI
+
+Claude Code, Copilot, Windsurf, Aider, and Continue.dev do **not** have the Atlassian Cursor plugin. For `sync` on those platforms, configure the CLI fallback (Step 5) and ensure `install.sh` copied `jira.sh` into your `.engineer-brain/scripts/` (or platform skill `scripts/`).
+
+---
+
+## Step 4 — Optional: Google Calendar
+
+For hackathons, demos, workshops, and meetups that never appear in git:
+
+See [gcal MCP setup](https://github.com/Hrithik-Gavankar/brainstack/blob/main/mcp/gcal/README.md) — one-time OAuth via `gcal.sh authorize`.
+
+---
+
+## Step 5 — Optional: `jira.sh` CLI fallback
+
+For **terminals, non-Cursor platforms, and CI** — not a substitute for Atlassian MCP in Cursor when the plugin is connected.
+
+```bash
+export JIRA_URL="https://your-org.atlassian.net"
+export JIRA_EMAIL="you@company.com"
+export JIRA_API_TOKEN="..."   # https://id.atlassian.com/manage-profile/security/api-tokens
+bash .engineer-brain/scripts/jira.sh active
+```
+
+Add the exports to `~/.zshrc` if you want shell scripts to work. **Cursor `sync` prefers Atlassian MCP** when the plugin is connected.
+
+---
+
+## Daily use
+
+```
+/engineer-brain sync
+```
+
+Or: *"Help me with sync up notes for today."*
+
+Expected sources in every run: **git** + **gh** + **Jira** + **BRAIN.md** + **gcal** (if configured).
+
+---
+
+## Related docs
+
+- [core/COMMANDS.md](https://github.com/Hrithik-Gavankar/brainstack/blob/main/core/COMMANDS.md) — full command reference
+- [team-brain-onboarding.md](https://github.com/Hrithik-Gavankar/brainstack/blob/main/docs/team-brain-onboarding.md) — crew shared memory (separate from personal standup)

docs/faq.md

@@ -119,11 +119,18 @@ Configure your workspace path to a common parent directory, or run the scanner m
 
 | Command | Recommended Frequency |
 |---------|----------------------|
-| `sync` | Daily, before standup |
+| `sync` | Daily, before standup — includes **Jira** + git + `gh` |
 | `update` | Monthly, or after major project changes |
 | `quarterly` | Once per quarter, before reviews |
 | `reflect` | Weekly (Fridays work well) |
 
+### How do I set up Jira for `sync`?
+
+**Cursor:** install the **[Atlassian Cursor plugin](https://cursor.com/marketplace/atlassian)** and complete OAuth once.
+Step-by-step: [engineer-brain-onboarding.md](engineer-brain-onboarding.md). `sync` will not skip Jira when the plugin is connected.
+
+**Other platforms** (Claude Code, Copilot, Windsurf, etc.): configure `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN`, then use `jira.sh` — see [engineer-brain-onboarding.md](engineer-brain-onboarding.md) Step 5 and [core/COMMANDS.md](../core/COMMANDS.md).
+
 ### Do I need to run commands manually?
 
 Yes, for now. Commands are triggered by typing them into your AI assistant. Future versions may support scheduled automation.

docs/team-brain-onboarding.md

@@ -52,6 +52,7 @@ Ask a teammate (crew admin) for **secrets** (Slack/chat is fine). The **Jira key
 Also make sure you have:
 
 - [ ] This repo cloned (`brainstack`) **and/or** the product repo with `.team-brain/project.json`
+- [ ] **Atlassian MCP** for Jira — required if you use `engineer-brain sync` ([setup](engineer-brain-onboarding.md#step-3--atlassian-mcp-jira--required))
 - [ ] A terminal (macOS Terminal, iTerm, VS Code/Cursor terminal)
 - [ ] `curl` and `jq` installed (`brew install jq` if needed)
 - [ ] Copy `supabase/project.public.env.example` → `supabase/project.public.env` (or use `bootstrap --write-env`) with the crew’s URL + anon

install.sh

@@ -137,10 +137,13 @@ install_core() {
   cp "$SCRIPT_DIR/core/scripts/scan.sh" "$WORKSPACE/.engineer-brain/scripts/scan.sh"
   cp "$SCRIPT_DIR/core/scripts/doctor.sh" "$WORKSPACE/.engineer-brain/scripts/doctor.sh"
   cp "$SCRIPT_DIR/core/scripts/watch.sh" "$WORKSPACE/.engineer-brain/scripts/watch.sh"
+  cp "$SCRIPT_DIR/core/scripts/jira.sh" "$WORKSPACE/.engineer-brain/scripts/jira.sh"
   cp "$SCRIPT_DIR/core/COMMANDS.md" "$WORKSPACE/.engineer-brain/COMMANDS.md"
+  cp "$SCRIPT_DIR/docs/engineer-brain-onboarding.md" "$WORKSPACE/.engineer-brain/ONBOARDING.md"
   chmod +x "$WORKSPACE/.engineer-brain/scripts/scan.sh"
   chmod +x "$WORKSPACE/.engineer-brain/scripts/doctor.sh"
   chmod +x "$WORKSPACE/.engineer-brain/scripts/watch.sh"
+  chmod +x "$WORKSPACE/.engineer-brain/scripts/jira.sh"
   success "Core files installed (.engineer-brain/)"
 }
 
@@ -182,17 +185,20 @@ install_cursor() {
   cp "$SCRIPT_DIR/platforms/cursor/rules/engineer-brain.mdc" "$WORKSPACE/.cursor/rules/"
   cp "$SCRIPT_DIR/platforms/cursor/rules/team-brain.mdc" "$WORKSPACE/.cursor/rules/"
   cp "$SCRIPT_DIR/platforms/cursor/skills/engineer-brain/SKILL.md" "$WORKSPACE/.cursor/skills/engineer-brain/"
+  cp "$SCRIPT_DIR/docs/engineer-brain-onboarding.md" "$WORKSPACE/.cursor/skills/engineer-brain/ONBOARDING.md"
   cp "$SCRIPT_DIR/core/BRAIN.md" "$WORKSPACE/.cursor/skills/engineer-brain/BRAIN.md"
   cp "$SCRIPT_DIR/core/scripts/scan.sh" "$WORKSPACE/.cursor/skills/engineer-brain/scripts/scan.sh"
   cp "$SCRIPT_DIR/core/scripts/doctor.sh" "$WORKSPACE/.cursor/skills/engineer-brain/scripts/doctor.sh"
   cp "$SCRIPT_DIR/core/scripts/watch.sh" "$WORKSPACE/.cursor/skills/engineer-brain/scripts/watch.sh"
+  cp "$SCRIPT_DIR/core/scripts/jira.sh" "$WORKSPACE/.cursor/skills/engineer-brain/scripts/jira.sh"
   cp "$SCRIPT_DIR/platforms/cursor/skills/team-brain/SKILL.md" "$WORKSPACE/.cursor/skills/team-brain/"
   cp "$SCRIPT_DIR/core/scripts/team-init.sh" "$WORKSPACE/.cursor/skills/team-brain/scripts/team-init.sh"
   cp "$SCRIPT_DIR/core/scripts/team-brain-api.sh" "$WORKSPACE/.cursor/skills/team-brain/scripts/team-brain-api.sh"
   cp "$SCRIPT_DIR/core/team/TEAM_COMMANDS.md" "$WORKSPACE/.cursor/skills/team-brain/TEAM_COMMANDS.md"
   chmod +x "$WORKSPACE/.cursor/skills/engineer-brain/scripts/scan.sh"
   chmod +x "$WORKSPACE/.cursor/skills/engineer-brain/scripts/doctor.sh"
   chmod +x "$WORKSPACE/.cursor/skills/engineer-brain/scripts/watch.sh"
+  chmod +x "$WORKSPACE/.cursor/skills/engineer-brain/scripts/jira.sh"
   chmod +x "$WORKSPACE/.cursor/skills/team-brain/scripts/team-init.sh"
   chmod +x "$WORKSPACE/.cursor/skills/team-brain/scripts/team-brain-api.sh"
   success "Cursor rules and skills installed (.cursor/) — engineer-brain + team-brain (agent loop)"