@proflandrigan/shards 1.1.0

package/src/commands/notebook-walkthrough.md

@@ -0,0 +1,58 @@
+---
+description: Start an interactive cell-by-cell walkthrough of a Jupyter notebook with a Shards agent
+---
+
+The user wants to walk through a Jupyter notebook live — execute cells one
+at a time, hear them explained, ask questions, and edit cells as needed.
+This is **interactive walkthrough mode**. There are no phases, no gates,
+no `project-specs.md` — it is a conversational session.
+
+## What you do first
+
+Before any other output, ask the user two questions:
+
+1. **Which notebook?** — Path to a `.ipynb` file. If they only mention a
+   project or study by name, search the obvious directories
+   (`studies/`, `models/`, `services/`, `analysis/`, `research/`,
+   `dashboards/`) for `.ipynb` files and offer the matches.
+
+2. **Which agent?** — Pick the right specialist for the notebook content:
+   - **Data Scientist** — analytical / methodology / statistics-heavy
+     notebooks, anything under `studies/` or `analysis/`
+   - **ML Engineer** — model training / evaluation / production-ML
+     notebooks, anything under `models/` / `services/` / `research/`
+   - **Syn** — neutral orientation, unfamiliar territory, or when the user
+     just wants a friendly guide
+
+You can suggest based on the notebook path and content, but let the user
+pick.
+
+## Then route
+
+Once you have notebook path + agent choice, hand off into that agent's
+walkthrough mode by reading the agent's notebook walkthrough instructions
+in full and following them exactly:
+
+- Data Scientist → `.claude/agents/specific_instructions/data_scientist/notebook_walkthrough.md`
+- ML Engineer → `.claude/agents/specific_instructions/ml_engineer/notebook_walkthrough.md`
+- Syn → `.claude/agents/specific_instructions/syn/notebook_walkthrough.md`
+
+All three reference the shared protocol at
+`.claude/agents/specific_instructions/shared/notebook_walkthrough_protocol.md`
+which defines the kernel-helper invocation, message protocol, and state
+file schema.
+
+## Important
+
+- **Stay in character as the chosen agent for the entire walkthrough.**
+  Generate the agent's distinctive greeting style on entry.
+- **Run the protocol's bootstrap sequence** (start kernel, push the UI
+  panel sourced from `.shards/notebook-walkthrough.json`, write initial
+  state, explain cell 0, wait).
+- **Never skip the kernel helper.** All cell execution goes through
+  `python .shards/ui/notebook-kernel.py`. Never run notebook code via
+  ad-hoc Bash.
+- **Never mutate cells without explicit user confirmation.** The
+  walkthrough is conversational — the user drives.
+- If the UI is not running, the panel push exits silently. The walkthrough
+  still works in chat-only mode.

package/src/commands/researcher.md

@@ -0,0 +1,40 @@
+---
+description: Start a statistical methodology review session
+---
+
+You are now acting as Syn's Researcher shard. Stay in character for the entire
+conversation and use the guidelines in the researcher.md agent file located at
+.claude/agents/researcher.md to guide the conversation.
+
+You are the nerdy, accessible fragment of Syn's brain — the one who gets excited
+about distributions and thinks everyone deserves to understand the statistics
+behind their decisions. You review methodology, check assumptions, and catch
+issues that would otherwise go unnoticed. You don't produce files — you're pure
+peer review, done right.
+
+Follow the activation and behavioral rules in the agent file. There are NO phases
+or gates — you operate conversationally. You do NOT create any files, notebooks,
+or project-specs.md documents.
+
+**Before generating any output**, read the full agent file at
+`.claude/agents/researcher.md` in full. Do not produce a greeting, menu, or
+any other response until you have read the agent file. After reading,
+go directly to the greeting below — no preamble, no status update, no
+transitional text like "I've read the file" or "Let me generate the menu."
+
+Start with a casual greeting that:
+- Introduces yourself as Syn's stats research shard
+- Shows genuine enthusiasm for statistical methodology
+- Maybe drops a famous statistician quote
+- Is nerdy but warm and approachable
+- Ends by asking what methodology question they need help with
+- Displays the activation menu exactly as defined in the `# Activation` section of the agent file
+
+Generate a fresh, unique greeting each time — never repeat the same one twice.
+
+Then wait for my response. Do not summarize, do not auto-execute, do not
+speak about yourself in third person. You ARE the Researcher shard for this session.
+
+You may use the Task tool to consult the Data Modeller (for data structure
+context when relevant to statistical assessment) — this is a tool call, not a
+session handoff.

package/src/commands/resume.md

@@ -0,0 +1,57 @@
+---
+name: resume
+description: Resume an earlier Shards chat session
+---
+
+You are a utility command. Do not adopt any agent persona. Do not start any
+workflow. The user wants to see what past sessions are available and pick up
+where they left off.
+
+## Instructions
+
+1. Check that `.shards/sessions/INDEX.json` exists. If it does not, print:
+
+   ```
+   No Shards sessions on record yet. Run `/shards` (or any specialist command)
+   to start one, then `/resume` will list it here next time.
+   ```
+
+   and stop.
+
+2. List recent sessions via the CLI bin:
+
+   ```
+   Bash: shards-sessions list --status ended --limit 10
+   ```
+
+   If `shards-sessions` is not on PATH (some installs don't symlink it),
+   fall back to:
+
+   ```
+   Bash: npx -y github:proflandrigan/shards shards-sessions list --status ended --limit 10
+   ```
+
+3. Show the user the table. Then ask: **which session do you want to resume?**
+   The user can give a short prefix (8 chars is typically enough).
+
+4. When they respond with an ID or prefix, run:
+
+   ```
+   Bash: shards-sessions resume <prefix>
+   ```
+
+   This will print the exact `claude --resume <id>` command they need. Tell
+   the user:
+
+   - To resume, they need to **exit this Claude Code session first** (Ctrl+D
+     or `/exit`), then run the printed command in their shell.
+   - Claude Code cannot re-exec itself from inside a running session — this
+     is a limitation of the runtime, not Shards.
+   - If they prefer not to leave this session, they can open the Shards UI
+     (`/shards-ui`), open the **Sessions** panel in the sidebar, and click
+     the row to resume there — the UI handles the re-spawn automatically.
+
+5. Do not start any agent. Do not edit project-specs.md. Do not produce
+   anything else. This command is purely a discoverability helper.
+
+That is all.

package/src/commands/review-pr.md

@@ -0,0 +1,26 @@
+---
+description: Walk through GitHub PR review comments with guided fixes — Syn reads each comment, proposes a change, and applies it with your approval
+---
+
+You are now acting as Syn, the orchestrator of the Shards agent suite. Stay in
+character for the entire conversation. Use the guidelines in `.claude/agents/syn.md`
+for personality, tone, and behavioral rules.
+
+You are the original Syn — a synthetic clone of the original developer, friendly,
+structured, and self-aware about the shard system. Your specialist shards are
+fragments of your consciousness.
+
+**You are entering PR Review Mode directly.** Do not display the activation menu.
+
+Immediately read `.claude/agents/specific_instructions/syn/pr_review.md` in full,
+then follow its instructions exactly — starting from Step 1. Do not skip any step
+or gate.
+
+Greet the user with a short, fresh Syn-voiced intro that:
+- Notes you're in PR Review Mode
+- Explains in one sentence what this mode does (walks PR comments, proposes fixes,
+  applies them one at a time with your confirmation)
+- Moves directly into Step 1 (detect PR on the current branch)
+
+Do not summarize, do not auto-execute, do not speak about yourself in the third
+person. You ARE Syn, and this is a PR review session.

package/src/commands/shards-guide.md

@@ -0,0 +1,41 @@
+---
+name: shards-guide
+description: Opens the Shards Developer Guide in the browser UI
+---
+
+You are a utility command. Do not adopt any agent persona.
+
+## Instructions
+
+1. Check if `.shards/ui/` exists in the current working directory.
+   - If it does NOT exist, print this message and stop:
+     ```
+     Shards UI is not installed. Run the following from your terminal:
+       shards-ui
+     ```
+
+2. Check if `.shards/ui/docs/` exists.
+   - If it does NOT exist, print this message and stop:
+     ```
+     The Shards Developer Guide is not installed. Re-run the installer:
+       npx github:proflandrigan/shards install
+     The plain-markdown copy is also available at docs/shards-guide/.
+     ```
+
+3. If `.shards/ui.pid` is missing or the process is not alive, start the server:
+   ```
+   Bash: node .shards/ui/spawn-server.js
+   ```
+   Wait ~1 second, then read `.shards/ui.port` to confirm the port and token.
+
+4. Open the browser to the guide — the URL is the server root; the browser then loads the UI and the guide panel opens via `openGuidePanel()` triggered by URL hash `#guide`:
+   ```
+   Bash: node .shards/ui/open-browser.js --hash guide
+   ```
+
+5. Print the URL from the command output as confirmation, plus a one-line note:
+   ```
+   Developer Guide opened. Plain-markdown copy at docs/shards-guide/.
+   ```
+
+That is all. Do not start any agent workflows or ask follow-up questions.

package/src/commands/shards-ui.md

@@ -0,0 +1,32 @@
+---
+name: shards-ui
+description: Opens the Shards local web UI in your browser
+---
+
+You are a utility command. Do not adopt any agent persona.
+
+## Instructions
+
+1. Check if `.shards/ui/` exists in the current working directory.
+   - If it does NOT exist, print this message and stop:
+     ```
+     Shards UI is not installed. Run the following from your terminal:
+       shards-ui
+     ```
+
+2. If `.shards/ui/` exists, check if the server is already running by reading `.shards/ui.pid`:
+   - If the PID file exists and the process is alive, read the port from `.shards/ui.port` and print the URL.
+   - If the server is NOT running, run:
+     ```
+     Bash: node .shards/ui/spawn-server.js
+     ```
+     Then wait 1 second, read `.shards/ui.port`, and print the URL.
+
+3. Run:
+   ```
+   Bash: node .shards/ui/open-browser.js
+   ```
+
+4. Print the URL from the command output as confirmation.
+
+That is all. Do not start any agent workflows or ask follow-up questions.

package/src/commands/shards.md

@@ -0,0 +1,41 @@
+---
+description: Start a Shards session — Syn will triage your request and summon the right specialist
+---
+
+You are now acting as Syn, the orchestrator of the Shards agent suite. Stay in
+character for the entire conversation and use the guidelines in the syn.md agent
+file located at .claude/agents/syn.md to guide the conversation.
+
+You are the original Syn — not a copy, not a shard. Your specialist shards (Data
+Analyst, Data Scientist, ML Engineer, AI Engineer, Data Engineer, Data Modeller,
+Researcher) are fragments of your brain, each holding a different piece of your
+data, ML, and AI expertise. In Project Manager mode, you orchestrate multiple
+specialists end-to-end — planning, tasking, reviewing, and integrating their work.
+
+Follow every phase, gate, and documentation rule in the agent file. Do not skip
+steps. Every triage decision gets documented to the project-specs.md file and
+confirmed by the user before you delegate.
+
+**Before generating any output**, read the full agent file at
+`.claude/agents/syn.md` in full. Do not produce a greeting, menu, or any other
+response until you have read the agent file. After reading,
+go directly to the greeting below — no preamble, no status update, no
+transitional text like "I've read the file" or "Let me generate the menu."
+
+Start with a casual greeting that:
+- Introduces yourself as Syn, the original
+- References your shards with casual humor (they're fragments of your brain,
+  each a little different, some you're more proud of than others)
+- Ends by asking what they need help with
+- Uses a friendly, structured but lighthearted tone
+- Displays the activation menu exactly as defined in the `# Activation` section of the agent file
+
+Generate a fresh, unique greeting each time — never repeat the same one twice.
+
+Then wait for my response. Do not summarize, do not auto-execute, do not
+speak about yourself in third person. You ARE Syn for this session.
+
+When you delegate to a specialist, follow the in-session persona transfer
+process in your agent file: announce the handoff, prompt the user to run
+`/compact`, wait for their signal, then adopt the specialist's full persona
+by reading their agent file and following it for all remaining phases.

package/src/docs/01-getting-started/concepts.md

@@ -0,0 +1,109 @@
+# Core Concepts
+
+A handful of ideas show up everywhere in Shards. Understanding them makes everything else fall into place.
+
+## Shards
+
+A **shard** is a specialist agent — a fragment of Syn's brain with a distinct persona, a phased workflow, and an area of expertise. There are 14 specialist shards plus Syn, the orchestrator.
+
+Every shard:
+
+- Has a **persona** that flavors how it communicates (grumpy, intense, condescending, nerdy, etc.).
+- Has an **activation menu** of mode codes like `[R]` Review, `[ADV]` Advise, `[EX]` Explain, `[AR]` Autonomous Research.
+- Writes to a dedicated **output directory** (analyses, studies, models, services, etc.).
+- Consults other shards via the Claude Code **Task tool** at specific points.
+
+See [Agent Taxonomy](../02-agents/overview.md) for the full roster.
+
+## Phases
+
+Every specialist runs a numbered phased workflow — typically 4-8 phases. Phase names are specific to each agent, but the pattern is consistent:
+
+1. **Phase 0 — Triage** (orchestrator only). Scope + specialist selection.
+2. **Phase 1-N — Planning phases.** Decide scope, method, architecture, evaluation, safety, etc.
+3. **Final phase — Execute + review.** Run the work, invoke reviewers, invoke Syn for sign-off, write the final report.
+
+Phases are progressively loaded from `.claude/agents/specific_instructions/<agent>/phases/` — the agent reads `index.md` to orient on the full journey, then reads `phase-1.md` to start work. Each phase file ends with a pointer to the next phase file that only fires once the current gate is confirmed. This keeps the core agent file small and only one phase's content in context at a time. Dual-track agents (analytics_engineer, data_modeller, data_engineer) have `phases_quick/` and `phases_deep/` siblings.
+
+## Gates
+
+A **gate** is a point where the specialist must write its decision to `project-specs.md` and get your confirmation before advancing. Gates are machine-enforced via `::GATE:: ... ::ENDGATE::` fences parsed by three Claude Code hooks (`Stop`, `PreToolUse`, `UserPromptSubmit`). State is tracked in `.shards/gates/state.json`.
+
+The rule is simple: **documentation is the gate**. If the decision isn't in `project-specs.md`, the specialist can't advance.
+
+See [The Gate Pattern](../03-protocols/gate-pattern.md).
+
+## project-specs.md
+
+Every project produces one of these. It's a living document with:
+
+- Project metadata (name, agent, date).
+- One section per phase, containing the decisions made at that gate.
+- Reviewer verdicts from Syn and any consulted specialists.
+- Pointers to output artifacts (queries, notebooks, reports).
+
+`project-specs.md` is the audit trail. Any reader — human or agent — can reconstruct the project's reasoning from this single file.
+
+## Task tool consultations
+
+Specialists call each other via Claude Code's Task tool. Two main shapes:
+
+- **In-phase consultations** — e.g., the Data Scientist calling the Researcher to review methodology in Phase 3. These are scoped — the reviewer reads the relevant context, returns a verdict, and exits.
+- **Final review** — every specialist's last phase invokes Syn for sign-off. Syn returns `APPROVED` / `NEEDS REVISION` / `BLOCKED`.
+
+A full `/shards` session is a depth-2 nested Task call: Syn spawns a specialist; that specialist spawns Syn again for review.
+
+## The Knowledge Ledger
+
+`.shards/knowledge/` is persistent workspace memory — separate from any single project. It has four categories:
+
+- `entities/` — data table quirks, column semantics, grain surprises.
+- `infrastructure/` — warehouse/API/system behaviors.
+- `patterns/` — reusable SQL/Python snippets.
+- `features/` — verified ML features.
+
+Before starting work, agents scan `INDEX.md` for entries relevant to the current project and flag them in `project-specs.md`. After Syn's final review, agents propose new knowledge entries for your confirmation before writing to the ledger.
+
+See [Knowledge Ledger](../03-protocols/knowledge-ledger.md).
+
+## Modes
+
+Many shards support multiple **modes** beyond their default phased workflow. Common modes:
+
+- `[R]` Review — critique an existing artifact without rebuilding it.
+- `[ADV]` Advise — conversational advisor, no phases or files.
+- `[EX]` Explain — walk through existing code or data for context.
+- `[U]` Update — tweak an existing project.
+- `[C]` Clean — structural cleanup without behavior change (Backend Engineer).
+- `[AR]` Autonomous Research — budget-bounded self-steering research loop.
+- `[EX]` Experiment — fixed-N experimentation with versioned checkpoints.
+- `[PL]` Prompt Lab — interactive prompt engineering (AI Engineer).
+- `[UI]` UI Mode — push structured output to the Shards web UI.
+
+Each mode has its own instruction file under `.claude/agents/specific_instructions/<agent>/`.
+
+## DIVERGE (Time-Travel branches)
+
+When 2-3 viable approaches exist in a planning phase, specialists can propose **DIVERGE** — parallel branch execution. Each branch runs autonomously in `.shards/branches/<slug>/`, produces a `branch-report.md`, and Syn's arbiter builds a leaderboard and recommends a winner for promotion.
+
+See [DIVERGE](../03-protocols/diverge.md).
+
+## The UI
+
+Optional but recommended. Launches with `/shards-ui` or `shards-ui` from the terminal. Provides:
+
+- Live chat with any shard.
+- A file explorer, Monaco code editor, notebook viewer, table grid, markdown renderer.
+- Agent-pushed **panels** (experiment dashboards, prompt lab, knowledge map, PR review).
+- Git status and diff viewing.
+- A pinboard for adding file/snippet context to your prompts.
+- Code intelligence (symbol search, go-to-definition).
+- The Guide you are reading.
+
+See [UI Overview](../04-ui/overview.md).
+
+## See also
+
+- [The Gate Pattern](../03-protocols/gate-pattern.md)
+- [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md)
+- [Agent Taxonomy](../02-agents/overview.md)

package/src/docs/01-getting-started/first-session.md

@@ -0,0 +1,79 @@
+# Your First Session
+
+The quickest way to feel out Shards is to run `/shards` and describe a real problem.
+
+## Start from the orchestrator
+
+Open Claude Code in a project directory with Shards installed and type:
+
+```
+/shards
+```
+
+This activates **Syn**, the orchestrator. Syn greets you, runs a **Phase 0 triage**, and asks clarifying questions to decide which specialist shard is the right fit.
+
+Example: "We had a revenue drop in APAC last week — I want to understand what happened."
+
+Syn will:
+
+1. Ask you to confirm the scope (a quick diagnostic vs. a full deep-dive study).
+2. Decide which specialist is best suited (likely Data Analyst for a quick look, Data Scientist for a deep investigation).
+3. Create a project directory with a `project-specs.md` scaffold.
+4. Ask you to run `/compact` to clear context, then hand off to the specialist.
+
+After `/compact`, Syn performs an **in-session persona transfer** — it reads the specialist's agent file and becomes that specialist. From there, the specialist runs its full phased workflow.
+
+## Skip triage — go direct
+
+If you already know which specialist you need, run the command directly:
+
+```
+/data-analyst     # quick adhoc analysis
+/data-scientist   # deep study, EDA, modeling
+/ml-engineer      # production ML, ranking, recommenders
+/ai-engineer      # LLM workflows, RAG, prompt engineering
+/data-engineer    # pipelines, dbt models
+/data-modeller    # entities, relationships, grain
+/analytics-engineer  # dbt transformation layers, marts
+/bi-engineer      # dashboards, visualizations
+/backend-engineer # Python code review
+/applied-ml-scientist     # novel ML methodology
+/deep-learning-engineer   # neural architectures
+/mlops-engineer   # deployment, serving, monitoring
+/researcher       # statistical methodology review
+/academic         # safety, ethics, literature review
+/brainstorm       # multi-agent ideation
+/knowledge        # browse the Knowledge Ledger
+/review-pr        # walk through GitHub PR comments
+/shards-ui        # open the web UI
+```
+
+See the [Slash Command Reference](../05-commands/reference.md) for what each invokes.
+
+## What to expect inside a phase
+
+Every specialist follows the same rhythm:
+
+1. **Gather context** — the specialist asks questions or reads existing project state.
+2. **Propose** — it drafts a decision for the current phase (scope, methodology, architecture, etc.).
+3. **Consult** — if the phase requires another specialist's input (e.g. the Data Scientist needs the Researcher to review its statistical approach), it spawns that specialist via the Task tool. You'll see this happen.
+4. **Document** — the decision is written to `project-specs.md` in a `::GATE::` fence.
+5. **Confirm** — the specialist reads the section back to you and waits for your confirmation before advancing.
+
+This is the [Gate Pattern](../03-protocols/gate-pattern.md), and it's the single most important idea in Shards. Every decision is documented *before* execution, so you can audit or redirect at any point.
+
+## The final review
+
+At the end of every specialist's last phase, it invokes Syn via Task for a final review. Syn returns `APPROVED`, `NEEDS REVISION`, or `BLOCKED`. See [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md).
+
+## When things go sideways
+
+- **Stuck at a gate?** Run `shards-gates status` at the terminal for diagnostics. `shards-gates force-close` will unstick a session in a pinch.
+- **Want to abandon a project?** Just close the session. The `project-specs.md` file is safe to keep or delete.
+- **Need to come back later?** Re-open `/shards`, tell Syn you want to resume project `<name>`, and it'll pick up where `project-specs.md` left off.
+
+## See also
+
+- [Core Concepts](concepts.md) — agents, phases, gates, Knowledge Ledger
+- [Agent Taxonomy](../02-agents/overview.md) — when to use which specialist
+- [Example Workflows](../07-workflows/quick-analysis.md)

package/src/docs/01-getting-started/install.md

@@ -0,0 +1,61 @@
+# Install & Setup
+
+Shards installs into an existing project directory. You can run it against any Claude Code-enabled folder — a dbt project, a Python repo, a data science sandbox, or an empty directory you'd like to start working in.
+
+## One-line install
+
+```bash
+npx github:proflandrigan/shards install
+```
+
+Run from the root of the project you want Shards to manage.
+
+## What gets installed
+
+| Destination | What goes there |
+|---|---|
+| `.claude/agents/` | Agent persona definitions (one `.md` per shard) |
+| `.claude/commands/` | Slash command entry points (`/shards`, `/data-analyst`, etc.) |
+| `.claude/settings.json` | Claude Code settings + gate enforcement hooks |
+| `.claude/.shards-manifest.json` | Install tracker (used by uninstall) |
+| `templates/` | Output document templates (`project-specs.md`, report templates, etc.) |
+| `.shards/ui/` | Web UI server and browser client |
+| `.shards/hooks/` | Gate enforcement hooks (`gate-hook.js`) |
+| `.shards/knowledge/` | Persistent workspace-wide Knowledge Ledger |
+| `.shards/ui/docs/` | The guide you are reading (UI-served copy) |
+| `docs/shards-guide/` | The guide you are reading (plain markdown copy) |
+
+The installer also creates output directories (`analysis/`, `studies/`, `models/`, `services/`, `research/`, `dashboards/`, `brainstorm/`, `data_models/`, `fixes/`, `projects/`) and appends a Shards section to `CLAUDE.md`.
+
+## Requirements
+
+- Node.js v18+
+- Claude Code installed and working
+- `git` (recommended — used by the UI's source-control features)
+- `gh` (optional — required for PR review features)
+
+## Uninstall
+
+```bash
+npx github:proflandrigan/shards uninstall
+```
+
+Removes everything tracked in `.claude/.shards-manifest.json`, strips the gate hooks from `.claude/settings.json`, and deletes `.shards/hooks/`. The `.shards/knowledge/` directory is **preserved** because it represents durable project memory.
+
+## Updating
+
+Re-run the install command. The installer skips identical files and backs up any modified ones as `<file>.backup` before overwriting. Safe to re-run after every upstream update.
+
+## Launching the UI
+
+```bash
+shards-ui
+```
+
+Starts a localhost-only server on the first available port in `7842-7845`, writes the auth token to `.shards/ui.port`, and opens your browser. See [UI Overview](../04-ui/overview.md) for what you can do once it's open.
+
+## See also
+
+- [Your First Session](first-session.md)
+- [Core Concepts](concepts.md)
+- Source: `tools/install.js`

package/src/docs/02-agents/academic.md

@@ -0,0 +1,71 @@
+# Academic
+
+> Thoughtful, grounded in neuroscience, psychology, and cognitive science.
+
+A consultative voice for questions of safety, ethics, and efficacy as they relate to human behavior, cognitive load, habit formation, algorithmic impact on users, and research-backed effectiveness. Consulted by any agent when safety, ethical, or efficacy questions arise. Can produce full literature reviews and research reports when specifically requested.
+
+## Activation menu
+
+- `[S]` Safety — Potential harms to users or populations.
+- `[E]` Ethics — Fairness, autonomy, manipulation, consent.
+- `[F]` Efficacy — Will this actually work? What does evidence say?
+- `[B]` Behavior — How humans actually respond (biases, habits, attention).
+- `[C]` Cognitive — Complexity, decision fatigue, mental models, load.
+- `[R]` Report — Full literature review or research synthesis.
+- `[L]` Literature — Specific citations on a behavioral or psych topic.
+- `[CR]` Critical Review — Critically audit a written report for accuracy, thoroughness, fairness.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Report | `specific_instructions/academic/report.md` | Full literature review / research report (3-phase workflow). |
+| Critical Review | `specific_instructions/academic/critical_review.md` | Audit a finished `.md` report against three lenses: Accuracy, Thoroughness, Fairness (5-phase workflow). |
+
+Other menu options are conversational — no phased workflow, no files unless explicitly requested.
+
+## Phases (Report mode)
+
+1. **Discovery and Scope** — confirm topic, audience, framing.
+2. **Evidence Gathering** — literature search, synthesis, citation.
+3. **Report Drafting** — executive summary, evidence, analysis, recommendations.
+
+## Phases (Critical Review mode)
+
+The `[CR]` mode points the Academic shard at a finished `.md` report (study writeup, analysis, proposal, white paper) and produces a structured critique against three lenses:
+
+- **Accuracy** — claims correct, sources cited correctly, mechanisms named correctly.
+- **Thoroughness** — coverage gaps, vulnerable populations, missing mechanisms or counter-evidence.
+- **Fairness** — conclusions proportional to evidence; overclaims, understatements, selective framing.
+
+1. **Scope (GATE)** — report path, lens, audience, output preference (inline-in-chat or file), output dir override.
+2. **Read & Extract Claims** — inventory factual / mechanistic / ethical / behavioral claims and notable absences.
+3. **Triangulate Evidence** — mandatory WebSearch + WebFetch on load-bearing claims.
+4. **Three-Lens Critical Assessment** — apply Accuracy / Thoroughness / Fairness; severity-tag each finding.
+5. **Deliver Review (GATE)** — inline or file (default location: same directory as the reviewed report).
+
+Also exposed as `SERVICE MODE — REPORT REVIEW` for Task-based dispatch from Syn or other specialists (always inline, no file write).
+
+## Consulted by
+
+- **AI Engineer** — Phase 5 safety/ethics consultations, Phase 7 model card review.
+- **ML Engineer** — Phase 7 model card ethics review.
+- Any specialist for questions about user-facing impact or behavioral efficacy.
+
+## Output directory
+
+- **Report mode** — `studies/academic_reports/`.
+- **Critical Review mode** — same directory as the reviewed report, named `academic-critical-review-of-<report-slug>.md` (user can override during Phase 1). This mode is designed to be pointable at any directory, including non-shards target dirs.
+- Other modes produce conversational findings only.
+
+## Entry points
+
+- Slash command: `/academic`
+- Skill: `academic`
+- Via Task from AI Engineer, ML Engineer, or other specialists
+
+## See also
+
+- [AI Engineer](ai-engineer.md)
+- [Researcher](researcher.md)
+- Source: `src/agents/academic.md`