diff --git a/.gitignore b/.gitignore index 4e7673e..ff08a1d 100644 --- a/.gitignore +++ b/.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 diff --git a/README.md b/README.md index 9762e4f..c58f876 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ engineer-brain • Team Brain • Architecture • - Onboarding • + Team Onboarding • + engineer-brain Setup • Roadmap • FAQ

@@ -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 diff --git a/core/COMMANDS.md b/core/COMMANDS.md index f066413..9fa1b55 100644 --- a/core/COMMANDS.md +++ b/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 /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 diff --git a/core/scripts/doctor.sh b/core/scripts/doctor.sh index fd3a868..86899bd 100755 --- a/core/scripts/doctor.sh +++ b/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 "" diff --git a/docs/architecture.md b/docs/architecture.md index aac00cc..80bd1b9 100644 --- a/docs/architecture.md +++ b/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) diff --git a/docs/engineer-brain-onboarding.md b/docs/engineer-brain-onboarding.md new file mode 100644 index 0000000..d0d6018 --- /dev/null +++ b/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) diff --git a/docs/faq.md b/docs/faq.md index 8333188..f03f8e6 100644 --- a/docs/faq.md +++ b/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. diff --git a/docs/team-brain-onboarding.md b/docs/team-brain-onboarding.md index a8de3fe..f6fbd3f 100644 --- a/docs/team-brain-onboarding.md +++ b/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 diff --git a/install.sh b/install.sh index c70aaf3..6f610ab 100755 --- a/install.sh +++ b/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,10 +185,12 @@ 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" @@ -193,6 +198,7 @@ install_cursor() { 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)" diff --git a/platforms/claude-code/CLAUDE.md b/platforms/claude-code/CLAUDE.md index 5854424..7bd2e65 100644 --- a/platforms/claude-code/CLAUDE.md +++ b/platforms/claude-code/CLAUDE.md @@ -43,6 +43,10 @@ When the user says "engineer-brain sync", "daily sync", "standup", "update brain "watch PRs", "PR digest", "review queue", or asks about their work patterns, follow the command logic in `.engineer-brain/COMMANDS.md`. +**Jira for `sync`:** This platform does **not** have the Atlassian Cursor plugin. +Configure `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN`, then use `jira.sh` during `sync` +(see `.engineer-brain/ONBOARDING.md` Step 5). Never finalize standup without a Jira signal. + **Available commands:** - `sync` — generate daily standup notes - `update` — refresh BRAIN.md from git history @@ -60,6 +64,7 @@ or asks about their work patterns, follow the command logic in `.engineer-brain/ - Jira script: `.engineer-brain/scripts/jira.sh` - Watch script: `.engineer-brain/scripts/watch.sh` - Command reference: `.engineer-brain/COMMANDS.md` +- Onboarding (Jira + setup): `.engineer-brain/ONBOARDING.md` ## Hard Rules diff --git a/platforms/cursor/README.md b/platforms/cursor/README.md index 4f34e02..10cca5a 100644 --- a/platforms/cursor/README.md +++ b/platforms/cursor/README.md @@ -1,5 +1,14 @@ # Brainstack — Cursor IDE Setup +## Prerequisites + +- **Git** + repos in your workspace +- **GitHub CLI** — `gh auth login` (PRs, reviews, releases in `sync`) +- **Atlassian MCP** — [Cursor marketplace plugin](https://cursor.com/marketplace/atlassian) + OAuth (required for Jira in `sync`) +- Optional: **gcal MCP** — [setup](../../mcp/gcal/README.md) for hackathons, demos, workshops + +Full walkthrough: [engineer-brain-onboarding.md](../../docs/engineer-brain-onboarding.md) (installed copy: `.cursor/skills/engineer-brain/ONBOARDING.md`). + ## Installation ### Option 1: Auto-install (recommended) @@ -19,6 +28,8 @@ cp -r platforms/cursor/rules /path/to/your/workspace/.cursor/rules cp -r platforms/cursor/skills /path/to/your/workspace/.cursor/skills cp core/scripts/scan.sh /path/to/your/workspace/.cursor/skills/engineer-brain/scripts/ cp core/scripts/doctor.sh /path/to/your/workspace/.cursor/skills/engineer-brain/scripts/ +cp core/scripts/jira.sh /path/to/your/workspace/.cursor/skills/engineer-brain/scripts/ +cp docs/engineer-brain-onboarding.md /path/to/your/workspace/.cursor/skills/engineer-brain/ONBOARDING.md cp core/BRAIN.md /path/to/your/workspace/.cursor/skills/engineer-brain/BRAIN.md mkdir -p /path/to/your/workspace/.cursor/skills/team-brain/scripts cp core/scripts/team-init.sh /path/to/your/workspace/.cursor/skills/team-brain/scripts/ diff --git a/platforms/cursor/rules/engineer-brain.mdc b/platforms/cursor/rules/engineer-brain.mdc index 5688e41..541339f 100644 --- a/platforms/cursor/rules/engineer-brain.mdc +++ b/platforms/cursor/rules/engineer-brain.mdc @@ -41,7 +41,7 @@ You are assisting **[YOUR NAME]**, a [YOUR ROLE] at [YOUR COMPANY], with [X]+ ye 3. [Instruction — e.g. "Reference my existing test patterns when writing tests"] 4. [Instruction — e.g. "Flag security implications proactively"] 5. [Instruction — e.g. "Remind me to leverage underused skills"] -6. **For standups**: `/engineer-brain sync` | **For quarterly reviews**: `/engineer-brain quarterly` | **Health check**: `/engineer-brain doctor` | **PR digest**: `/engineer-brain watch` +6. **For standups**: `/engineer-brain sync` (always pulls Jira — [setup](.cursor/skills/engineer-brain/ONBOARDING.md)) | **Quarterly**: `/engineer-brain quarterly` | **Health**: `/engineer-brain doctor` | **PR digest**: `/engineer-brain watch` 7. **For shared spikes/epics**: `/team-brain attach ` | **capture** findings | **breakdown** stories — never mix personal BRAIN.md into team initiative files ## Living Document diff --git a/platforms/cursor/skills/engineer-brain/ONBOARDING.md b/platforms/cursor/skills/engineer-brain/ONBOARDING.md new file mode 100644 index 0000000..d0d6018 --- /dev/null +++ b/platforms/cursor/skills/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) diff --git a/platforms/cursor/skills/engineer-brain/SKILL.md b/platforms/cursor/skills/engineer-brain/SKILL.md index f255f6f..c4652d0 100644 --- a/platforms/cursor/skills/engineer-brain/SKILL.md +++ b/platforms/cursor/skills/engineer-brain/SKILL.md @@ -26,7 +26,8 @@ for daily syncs and quarterly reviews. accurate than local commits alone 3. **BRAIN.md** at `${SKILL_DIR}/BRAIN.md` (the living document) 4. **Agent transcripts** in the Cursor projects folder (demos, skill work, non-commit tasks) -5. **Jira / Linear / project tracker** via MCP or integration skill (if available) +5. **Jira** — **Cursor:** Atlassian MCP (marketplace plugin, required for `sync`). **Other platforms:** `jira.sh` CLI when `JIRA_*` env is set. +6. **Linear / other trackers** via integration skill (if available) **Critical:** Standup-relevant work is frequently *not* in authored git commits. Reviews, releases, demos, office-hours/meetup prep, cross-team notifications, and @@ -73,8 +74,7 @@ weekend, skip — standups don't happen on weekends. # Recent releases (configure RELEASE_REPOS in scan.sh) gh release list --repo your-org/your-repo --limit 3 ``` - Plus tracker issues assigned in the open sprint, and BRAIN.md - "Current Sprint Context" / upcoming events (demos, office hours, meetups). + Plus BRAIN.md "Current Sprint Context" / upcoming events (demos, office hours, meetups). 2a. **Calendar signal (gcal MCP, optional but preferred when connected):** - Call `status()` on the `gcal` MCP server first. @@ -94,6 +94,26 @@ weekend, skip — standups don't happen on weekends. didn't come from `gcal` or BRAIN.md. Precision over recall: when unsure, omit the meeting or ask the user once. +2b. **Jira signal (Atlassian MCP — required on every Cursor `sync`):** + - **Hard rule:** Never finalize standup without querying Jira. Git/`gh` alone miss + ticket work, ops/verify closes, hackathon filings, and doc-only deliverables. + - Prefer **`plugin-atlassian-atlassian`** (Cursor marketplace [Atlassian plugin](https://cursor.com/marketplace/atlassian)). + Do **not** rely on `jira.sh` in Cursor unless MCP is unavailable **and** `JIRA_*` env vars are set. + - If the namespace is missing or `needsAuth` → tell the user to complete + [ONBOARDING.md](ONBOARDING.md) Step 3; + list Jira as **blocked** in standup — do not silently omit ticket context. + - When connected: + 1. `getAccessibleAtlassianResources` → `cloudId` (pass to every `searchJiraIssuesUsingJql` call) + 2. `searchJiraIssuesUsingJql` — tickets **updated in the standup window** + (Monday: Friday only; Tue–Fri: prior calendar day). Example Tue–Fri: + `assignee = currentUser() AND updated >= startOfDay(-1) ORDER BY updated DESC` + 3. `searchJiraIssuesUsingJql` — `assignee = currentUser() AND statusCategory = "In Progress" ORDER BY updated DESC` + (aligns with `jira.sh active`; works across custom workflow status names) + 4. Optional: `sprint in openSprints()` — may be empty; in-progress query is the fallback + 5. `getJiraIssue` for top 1–2 active keys when summary/epic context helps + - Fold tickets into standup bullets with impact language (`PROJ-12345`, epic name). + Prefer recently updated + In Progress over a raw issue dump. + 3. Read `${SKILL_DIR}/BRAIN.md` for sprint context, active tickets, and scheduled team events (`Upcoming Events` table — the fallback when gcal isn't configured). @@ -141,7 +161,7 @@ human paste → absorb as ground truth → record what was wrong → close the g When the user pastes or describes their real standup after a generated sync: -1. Diff what was missed vs what `scan.sh` + `gh` returned. +1. Diff what was missed vs what `scan.sh` + `gh` + **Jira MCP** returned. 2. Update BRAIN.md sprint context immediately (overwrite stale bullets for that day). 3. Capture a short **learning** in BRAIN.md Learning Log or Growth Areas: what the sync got wrong → what to prefer next time. @@ -385,10 +405,11 @@ 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) +- **Onboarding**: [ONBOARDING.md](ONBOARDING.md) — Jira + platform setup (also at `docs/engineer-brain-onboarding.md` in the brainstack repo) - **Weekly reflection**: Run `reflect` on Fridays - **Monthly update**: Run `update` at month start - **Quarterly prep**: Run `quarterly` before performance reviews -- **Jira context**: If `jira-integration` skill is available, pull sprint data +- **Jira CLI fallback**: `jira.sh` only when Atlassian MCP unavailable and `JIRA_*` env is set - **Session analyzer**: If `session-analyzer` skill is available, pull AI usage stats - **PR awareness**: Run `watch` to see review queue, stale PRs, and team activity