phoenixvc · JustAGhosT · Mar 31, 2026 · Mar 31, 2026
diff --git a/.github/workflows/pycharm.yml b/.github/workflows/pycharm.yml
@@ -1,10 +1,11 @@
-name: PyCharm Plugin
+name: JetBrains Plugin
 
 on:
   push:
     paths: ['extensions/pycharm/**']
   pull_request:
     paths: ['extensions/pycharm/**']
+  workflow_dispatch:
 
 jobs:
   build:
@@ -21,6 +22,6 @@ jobs:
         working-directory: extensions/pycharm
         run: ./gradlew buildPlugin
 
-      - name: Verify plugin
+      - name: Verify plugin (PyCharm + Rider)
         working-directory: extensions/pycharm
         run: ./gradlew verifyPlugin
diff --git a/docs/onboarding/README.md b/docs/onboarding/README.md
@@ -0,0 +1,41 @@
+# Retort IDE Plugin — Onboarding Overview
+
+Retort ships editor extensions for three IDEs. Each integrates with the
+[Retort framework](https://github.com/phoenixvc/retort) running in your terminal,
+surfacing commands, status, and (where supported) AI context injection directly
+inside your editor.
+
+| IDE | Extension | Status |
+|-----|-----------|--------|
+| [VS Code](vscode.md) | VSIX via Marketplace / manual | Available |
+| [JetBrains](jetbrains.md) | Plugin via Marketplace / local install | Available |
+| [Zed](zed.md) | Extension via Zed extension registry | Available |
+
+## Prerequisites
+
+All extensions require Retort to be installed in your project:
+
+```bash
+# Verify Retort is present
+cat .agentkit/spec/project.yaml   # must exist
+pnpm -C .agentkit retort:sync     # ensure generated files are up-to-date
+```
+
+The extension activates automatically when `.agentkit/` is detected at the
+workspace root. No manual configuration is needed for basic usage.
+
+## Common Features Across All IDEs
+
+| Feature | VS Code | JetBrains | Zed |
+|---------|---------|-----------|-----|
+| Command palette | ✓ | ✓ | ✓ (slash commands) |
+| Project tool window / sidebar | ✓ | ✓ | — |
+| Status bar widget | ✓ | ✓ | — |
+| Junie / AI context injection | — | ✓ (optional) | — |
+
+## Quick Links
+
+- [VS Code onboarding](vscode.md)
+- [JetBrains onboarding](jetbrains.md) — covers PyCharm, IntelliJ IDEA, Rider
+- [Zed onboarding](zed.md)
+- [Junie integration details](jetbrains.md#junie-integration)
diff --git a/docs/onboarding/jetbrains.md b/docs/onboarding/jetbrains.md
@@ -0,0 +1,142 @@
+# Retort — JetBrains Plugin
+
+The JetBrains plugin works across PyCharm, IntelliJ IDEA, Rider, and any
+other IDE built on the IntelliJ platform (build 233+). It provides a command
+palette, project tool window, and status bar widget. Optionally, when the
+[Junie](https://www.jetbrains.com/junie/) AI plugin is installed, Retort
+injects active team and task context into every Junie AI session.
+
+## Requirements
+
+- IntelliJ-based IDE build `233` or later (2023.3+), up to `251.*`
+  - PyCharm 2023.3+
+  - IntelliJ IDEA 2023.3+
+  - Rider 2023.3+
+- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
+- Gradle / JDK 17+ (for building from source only)
+
+## Installation
+
+### From JetBrains Marketplace (recommended)
+
+1. Open your IDE.
+2. Go to **Settings → Plugins → Marketplace**.
+3. Search for **Retort**.
+4. Click **Install** and restart the IDE when prompted.
+
+### Manual / dev install
+
+```bash
+cd extensions/pycharm
+./gradlew buildPlugin          # produces build/distributions/retort-*.zip
+```
+
+Then in the IDE: **Settings → Plugins → ⚙ → Install Plugin from Disk…** and
+select the generated `.zip`.
+
+### Building and running in a sandbox IDE
+
+```bash
+cd extensions/pycharm
+./gradlew runIde               # launches a sandboxed IDE with the plugin pre-installed
+```
+
+## Activation
+
+The plugin activates for any project that contains `.agentkit/` at its root.
+No manual configuration is required.
+
+## Available Commands
+
+Access via **Tools → Retort** in the menu bar, or press
+`Shift+Ctrl+Alt+R` (Windows/Linux) / `Shift+Cmd+Alt+R` (macOS) to open the
+**Run Command...** picker.
+
+| Menu Item | Description |
+|-----------|-------------|
+| Sync Configs | Regenerate all AI tool configs from spec |
+| Run Check | Lint + typecheck + tests |
+| Health Check | Full repo health check |
+| Orchestrate | Master coordinator — assess, plan, delegate |
+| Plan | Structured implementation planning |
+| Discover | Scan repo structure and tech stacks |
+| Validate | Validate spec against schema |
+| Show Backlog | Show consolidated backlog |
+| Handoff | Generate session handoff document |
+| Preflight | Pre-ship delivery checks |
+| Security Scan | Security audit |
+| Project Status | Unified PM dashboard |
+| **Run Command...** | Choose and run any Retort command |
+
+## Tool Window
+
+The **Retort** panel (right side bar) shows:
+
+- Active orchestration phase
+- In-progress tasks from `.claude/state/tasks/`
+- Quick-launch buttons for common commands
+
+## Status Bar Widget
+
+A widget on the right of the status bar shows the active phase. Click it to
+open the command picker.
+
+## Junie Integration
+
+> **Status:** The Junie third-party context API is not yet public. The
+> integration is pre-wired and will activate automatically once JetBrains
+> publishes a stable extension point.
+
+When both the Retort plugin and [Junie](https://plugins.jetbrains.com/plugin/24367-junie)
+are installed, Retort registers a workspace context provider that injects:
+
+- The active orchestration **phase** (Discovery / Planning / Implementation / Validation / Ship)
+- **In-progress task titles** from `.claude/state/tasks/`
+- The path to the **teams file** (`.agentkit/spec/teams.yaml` or `AGENT_TEAMS.md`)
+
+This context block is prepended to each Junie AI session so the assistant is
+immediately aware of what the team is working on and which slash commands are
+available.
+
+### How the optional dependency works
+
+The Junie integration is declared as an optional plugin dependency in
+`META-INF/plugin.xml`:
+
+```xml
+<depends optional="true" config-file="junie.xml">com.intellij.junie</depends>
+```
+
+- If Junie is **not** installed the `junie.xml` descriptor is never loaded and
+  no Junie classes are referenced — the plugin works exactly as before.
+- If Junie **is** installed, `RetortWorkspaceContextService` is registered as a
+  project service and wired to Junie's context provider once JetBrains publishes
+  the stable API.
+
+### Enabling context injection manually (until API is public)
+
+Until the official `JunieContextProvider` extension point ships you can copy the
+context string into a Junie session manually:
+
+1. Open the **Retort** tool window.
+2. Click **Copy Workspace Context** (shows active phase + tasks).
+3. Paste into the Junie chat as the first message.
+
+## Troubleshooting
+
+**Plugin not activating**
+: Ensure `.agentkit/spec/project.yaml` exists at the project root.
+  Check **Help → Show Log in Explorer/Finder** for `RetortPlugin` log lines.
+
+**Junie section missing in tool window**
+: The Junie section only renders when Junie is installed. Install it via
+  **Settings → Plugins → Marketplace → Junie**.
+
+**`gradlew buildPlugin` fails with SDK error**
+: Run `./gradlew wrapper` to refresh the Gradle wrapper, then check that a
+  JDK 17+ is configured in **File → Project Structure → SDKs**.
+
+**Build fails: `until-build` compatibility**
+: The plugin targets builds up to `251.*`. If your IDE build is newer, update
+  `until-build` in `plugin.xml` and `intellijPlatform { ... }` in
+  `build.gradle.kts`, then rebuild.
diff --git a/docs/onboarding/vscode.md b/docs/onboarding/vscode.md
@@ -0,0 +1,87 @@
+# Retort — VS Code Extension
+
+The VS Code extension surfaces Retort commands in the command palette,
+a sidebar view, and a status bar widget. It activates automatically when
+a `.agentkit/` directory is present at the workspace root.
+
+## Requirements
+
+- VS Code `^1.85.0`
+- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
+
+## Installation
+
+### From the Marketplace (recommended)
+
+1. Open VS Code.
+2. Press `Ctrl+Shift+X` to open the Extensions panel.
+3. Search for **Retort** (publisher: `phoenixvc`).
+4. Click **Install**.
+
+### Manual / dev install
+
+```bash
+cd extensions/vscode
+pnpm install
+pnpm run build        # compiles to out/extension.js
+```
+
+Then in VS Code: **Extensions → ⋯ → Install from VSIX...** and select
+`extensions/vscode/retort-*.vsix` (produced by `pnpm run package`).
+
+## Activation
+
+The extension activates when VS Code opens a workspace that contains `.agentkit/`
+at the root (`activationEvents: ["workspaceContains:.agentkit"]`). No manual
+enable step is required.
+
+## Available Commands
+
+Open the Command Palette (`Ctrl+Shift+P`) and type **Retort** to see all commands:
+
+| Command | Description |
+|---------|-------------|
+| `Retort: Sync Configs` | Regenerate AI tool configs from spec |
+| `Retort: Run Check` | Lint + typecheck + tests |
+| `Retort: Health Check` | Full repo health check |
+| `Retort: Orchestrate` | Master coordinator — assess, plan, delegate |
+| `Retort: Plan` | Structured implementation planning |
+| `Retort: Discover` | Scan repo structure and tech stacks |
+| `Retort: Validate` | Validate spec against schema |
+| `Retort: Show Backlog` | Show consolidated backlog |
+| `Retort: Handoff` | Generate session handoff document |
+| `Retort: Preflight` | Pre-ship delivery checks |
+| `Retort: Security Scan` | Security audit |
+| `Retort: Project Status` | Unified PM dashboard |
+| `Retort: Run Command...` | Choose and run any Retort command |
+
+## Keyboard Shortcut
+
+`Shift+Ctrl+Alt+R` — opens the **Run Command...** picker.
+
+## Sidebar
+
+The Retort sidebar view (Activity Bar icon) shows:
+
+- Active orchestration phase
+- In-progress tasks from `.claude/state/tasks/`
+- Quick-launch buttons for common commands
+
+## Status Bar
+
+A status bar item on the right shows the active phase (e.g. `Retort: Implementation`).
+Click it to open the command picker.
+
+## Troubleshooting
+
+**Extension not activating**
+: Ensure `.agentkit/spec/project.yaml` exists. The extension only activates when
+  `.agentkit/` is present at the workspace root — not in a subdirectory.
+
+**Commands not found in terminal**
+: The extension runs Retort in VS Code's integrated terminal. Ensure `pnpm` is
+  on your `PATH`. Check `Extensions → Retort → Output` for error details.
+
+**Sidebar is empty**
+: Run `Retort: Sync Configs` once to generate state files. The sidebar reads
+  `.claude/state/` which is created on first sync.
diff --git a/docs/onboarding/zed.md b/docs/onboarding/zed.md
@@ -0,0 +1,76 @@
+# Retort — Zed Extension
+
+The Zed extension adds Retort slash commands to Zed's AI assistant panel.
+It is implemented as a Rust `slash_command` extension.
+
+## Requirements
+
+- [Zed](https://zed.dev) stable or nightly
+- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
+- Rust toolchain (for building from source only)
+
+## Installation
+
+### From the Zed Extension Registry (recommended)
+
+1. Open Zed.
+2. Press `Cmd+Shift+X` (macOS) / `Ctrl+Shift+X` (Linux) to open extensions.
+3. Search for **Retort**.
+4. Click **Install**.
+
+### Manual / dev install
+
+```bash
+cd extensions/zed
+cargo build --release
+```
+
+Then in Zed: **Extensions → Install Dev Extension** and point to the
+`extensions/zed` directory.
+
+## Available Slash Commands
+
+Type `/` in the Zed AI assistant panel to see the Retort commands:
+
+| Command | Description |
+|---------|-------------|
+| `/retort-status` | Show active Retort agents and task status |
+| `/retort-teams` | List Retort agent teams |
+| `/retort-backlog` | Show open Retort backlog items |
+| `/retort-sync` | Instructions to run `retort sync` |
+
+## Usage Example
+
+```
+/retort-status
+# → Returns current phase, in-progress tasks, and team roster
+
+/retort-teams
+# → Lists all configured agent teams with their scope
+
+/retort-backlog
+# → Shows open items from AGENT_BACKLOG.md
+```
+
+## Limitations
+
+Compared to the VS Code and JetBrains extensions, the Zed extension is
+intentionally minimal — Zed's extension API currently supports slash commands
+only. There is no sidebar panel or status bar widget.
+
+As Zed's extension API matures, additional surface areas (status bar, sidebar)
+will be added.
+
+## Troubleshooting
+
+**Commands not appearing**
+: Ensure the extension is installed and Zed has been restarted. Slash commands
+  appear only when the AI assistant panel is open (`Cmd+?` or **View → AI Assistant**).
+
+**`cargo build` fails**
+: Ensure Rust stable is installed (`rustup update stable`). The extension uses
+  the `zed_extension_api` crate — check `Cargo.toml` for the pinned version.
+
+**Output is empty**
+: The extension reads `.claude/state/` files. Run `retort sync` in the terminal
+  first to generate state files, then retry the slash command.