Skip to content

Commit 01ee9ec

Browse files
JustAGhosTclaude
JustAGhosT
and
claude
committed
feat(jetbrains): add Junie context integration and IDE onboarding docs
- Add optional Junie dependency in plugin.xml (loaded only when Junie is installed) - Add junie.xml descriptor registering RetortWorkspaceContextService - Implement RetortWorkspaceContextService to build phase/task/teams context block - Rename CI workflow to "JetBrains Plugin", add workflow_dispatch trigger - Add docs/onboarding/ with per-IDE guides (VS Code, JetBrains, Zed) and overview Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent c035611 commit 01ee9ec

File tree

9 files changed

+483
-6
lines changed

9 files changed

+483
-6
lines changed

‎.github/workflows/pycharm.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
name: PyCharm Plugin
1+
name: JetBrains Plugin
22

33
on:
44
push:
55
paths: ['extensions/pycharm/**']
66
pull_request:
77
paths: ['extensions/pycharm/**']
8+
workflow_dispatch:
89

910
jobs:
1011
build:
@@ -21,6 +22,6 @@ jobs:
2122
working-directory: extensions/pycharm
2223
run: ./gradlew buildPlugin
2324

24-
- name: Verify plugin
25+
- name: Verify plugin (PyCharm + Rider)
2526
working-directory: extensions/pycharm
2627
run: ./gradlew verifyPlugin

‎docs/onboarding/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Retort IDE Plugin — Onboarding Overview
2+
3+
Retort ships editor extensions for three IDEs. Each integrates with the
4+
[Retort framework](https://github.com/phoenixvc/retort) running in your terminal,
5+
surfacing commands, status, and (where supported) AI context injection directly
6+
inside your editor.
7+
8+
| IDE | Extension | Status |
9+
|-----|-----------|--------|
10+
| [VS Code](vscode.md) | VSIX via Marketplace / manual | Available |
11+
| [JetBrains](jetbrains.md) | Plugin via Marketplace / local install | Available |
12+
| [Zed](zed.md) | Extension via Zed extension registry | Available |
13+
14+
## Prerequisites
15+
16+
All extensions require Retort to be installed in your project:
17+
18+
```bash
19+
# Verify Retort is present
20+
cat .agentkit/spec/project.yaml # must exist
21+
pnpm -C .agentkit retort:sync # ensure generated files are up-to-date
22+
```
23+
24+
The extension activates automatically when `.agentkit/` is detected at the
25+
workspace root. No manual configuration is needed for basic usage.
26+
27+
## Common Features Across All IDEs
28+
29+
| Feature | VS Code | JetBrains | Zed |
30+
|---------|---------|-----------|-----|
31+
| Command palette | ✓ | ✓ | ✓ (slash commands) |
32+
| Project tool window / sidebar | ✓ | ✓ | — |
33+
| Status bar widget | ✓ | ✓ | — |
34+
| Junie / AI context injection | — | ✓ (optional) | — |
35+
36+
## Quick Links
37+
38+
- [VS Code onboarding](vscode.md)
39+
- [JetBrains onboarding](jetbrains.md) — covers PyCharm, IntelliJ IDEA, Rider
40+
- [Zed onboarding](zed.md)
41+
- [Junie integration details](jetbrains.md#junie-integration)

‎docs/onboarding/jetbrains.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Retort — JetBrains Plugin
2+
3+
The JetBrains plugin works across PyCharm, IntelliJ IDEA, Rider, and any
4+
other IDE built on the IntelliJ platform (build 233+). It provides a command
5+
palette, project tool window, and status bar widget. Optionally, when the
6+
[Junie](https://www.jetbrains.com/junie/) AI plugin is installed, Retort
7+
injects active team and task context into every Junie AI session.
8+
9+
## Requirements
10+
11+
- IntelliJ-based IDE build `233` or later (2023.3+), up to `251.*`
12+
- PyCharm 2023.3+
13+
- IntelliJ IDEA 2023.3+
14+
- Rider 2023.3+
15+
- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
16+
- Gradle / JDK 17+ (for building from source only)
17+
18+
## Installation
19+
20+
### From JetBrains Marketplace (recommended)
21+
22+
1. Open your IDE.
23+
2. Go to **Settings → Plugins → Marketplace**.
24+
3. Search for **Retort**.
25+
4. Click **Install** and restart the IDE when prompted.
26+
27+
### Manual / dev install
28+
29+
```bash
30+
cd extensions/pycharm
31+
./gradlew buildPlugin # produces build/distributions/retort-*.zip
32+
```
33+
34+
Then in the IDE: **Settings → Plugins → ⚙ → Install Plugin from Disk…** and
35+
select the generated `.zip`.
36+
37+
### Building and running in a sandbox IDE
38+
39+
```bash
40+
cd extensions/pycharm
41+
./gradlew runIde # launches a sandboxed IDE with the plugin pre-installed
42+
```
43+
44+
## Activation
45+
46+
The plugin activates for any project that contains `.agentkit/` at its root.
47+
No manual configuration is required.
48+
49+
## Available Commands
50+
51+
Access via **Tools → Retort** in the menu bar, or press
52+
`Shift+Ctrl+Alt+R` (Windows/Linux) / `Shift+Cmd+Alt+R` (macOS) to open the
53+
**Run Command...** picker.
54+
55+
| Menu Item | Description |
56+
|-----------|-------------|
57+
| Sync Configs | Regenerate all AI tool configs from spec |
58+
| Run Check | Lint + typecheck + tests |
59+
| Health Check | Full repo health check |
60+
| Orchestrate | Master coordinator — assess, plan, delegate |
61+
| Plan | Structured implementation planning |
62+
| Discover | Scan repo structure and tech stacks |
63+
| Validate | Validate spec against schema |
64+
| Show Backlog | Show consolidated backlog |
65+
| Handoff | Generate session handoff document |
66+
| Preflight | Pre-ship delivery checks |
67+
| Security Scan | Security audit |
68+
| Project Status | Unified PM dashboard |
69+
| **Run Command...** | Choose and run any Retort command |
70+
71+
## Tool Window
72+
73+
The **Retort** panel (right side bar) shows:
74+
75+
- Active orchestration phase
76+
- In-progress tasks from `.claude/state/tasks/`
77+
- Quick-launch buttons for common commands
78+
79+
## Status Bar Widget
80+
81+
A widget on the right of the status bar shows the active phase. Click it to
82+
open the command picker.
83+
84+
## Junie Integration
85+
86+
> **Status:** The Junie third-party context API is not yet public. The
87+
> integration is pre-wired and will activate automatically once JetBrains
88+
> publishes a stable extension point.
89+
90+
When both the Retort plugin and [Junie](https://plugins.jetbrains.com/plugin/24367-junie)
91+
are installed, Retort registers a workspace context provider that injects:
92+
93+
- The active orchestration **phase** (Discovery / Planning / Implementation / Validation / Ship)
94+
- **In-progress task titles** from `.claude/state/tasks/`
95+
- The path to the **teams file** (`.agentkit/spec/teams.yaml` or `AGENT_TEAMS.md`)
96+
97+
This context block is prepended to each Junie AI session so the assistant is
98+
immediately aware of what the team is working on and which slash commands are
99+
available.
100+
101+
### How the optional dependency works
102+
103+
The Junie integration is declared as an optional plugin dependency in
104+
`META-INF/plugin.xml`:
105+
106+
```xml
107+
<depends optional="true" config-file="junie.xml">com.intellij.junie</depends>
108+
```
109+
110+
- If Junie is **not** installed the `junie.xml` descriptor is never loaded and
111+
no Junie classes are referenced — the plugin works exactly as before.
112+
- If Junie **is** installed, `RetortWorkspaceContextService` is registered as a
113+
project service and wired to Junie's context provider once JetBrains publishes
114+
the stable API.
115+
116+
### Enabling context injection manually (until API is public)
117+
118+
Until the official `JunieContextProvider` extension point ships you can copy the
119+
context string into a Junie session manually:
120+
121+
1. Open the **Retort** tool window.
122+
2. Click **Copy Workspace Context** (shows active phase + tasks).
123+
3. Paste into the Junie chat as the first message.
124+
125+
## Troubleshooting
126+
127+
**Plugin not activating**
128+
: Ensure `.agentkit/spec/project.yaml` exists at the project root.
129+
Check **Help → Show Log in Explorer/Finder** for `RetortPlugin` log lines.
130+
131+
**Junie section missing in tool window**
132+
: The Junie section only renders when Junie is installed. Install it via
133+
**Settings → Plugins → Marketplace → Junie**.
134+
135+
**`gradlew buildPlugin` fails with SDK error**
136+
: Run `./gradlew wrapper` to refresh the Gradle wrapper, then check that a
137+
JDK 17+ is configured in **File → Project Structure → SDKs**.
138+
139+
**Build fails: `until-build` compatibility**
140+
: The plugin targets builds up to `251.*`. If your IDE build is newer, update
141+
`until-build` in `plugin.xml` and `intellijPlatform { ... }` in
142+
`build.gradle.kts`, then rebuild.

‎docs/onboarding/vscode.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Retort — VS Code Extension
2+
3+
The VS Code extension surfaces Retort commands in the command palette,
4+
a sidebar view, and a status bar widget. It activates automatically when
5+
a `.agentkit/` directory is present at the workspace root.
6+
7+
## Requirements
8+
9+
- VS Code `^1.85.0`
10+
- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
11+
12+
## Installation
13+
14+
### From the Marketplace (recommended)
15+
16+
1. Open VS Code.
17+
2. Press `Ctrl+Shift+X` to open the Extensions panel.
18+
3. Search for **Retort** (publisher: `phoenixvc`).
19+
4. Click **Install**.
20+
21+
### Manual / dev install
22+
23+
```bash
24+
cd extensions/vscode
25+
pnpm install
26+
pnpm run build # compiles to out/extension.js
27+
```
28+
29+
Then in VS Code: **Extensions → ⋯ → Install from VSIX...** and select
30+
`extensions/vscode/retort-*.vsix` (produced by `pnpm run package`).
31+
32+
## Activation
33+
34+
The extension activates when VS Code opens a workspace that contains `.agentkit/`
35+
at the root (`activationEvents: ["workspaceContains:.agentkit"]`). No manual
36+
enable step is required.
37+
38+
## Available Commands
39+
40+
Open the Command Palette (`Ctrl+Shift+P`) and type **Retort** to see all commands:
41+
42+
| Command | Description |
43+
|---------|-------------|
44+
| `Retort: Sync Configs` | Regenerate AI tool configs from spec |
45+
| `Retort: Run Check` | Lint + typecheck + tests |
46+
| `Retort: Health Check` | Full repo health check |
47+
| `Retort: Orchestrate` | Master coordinator — assess, plan, delegate |
48+
| `Retort: Plan` | Structured implementation planning |
49+
| `Retort: Discover` | Scan repo structure and tech stacks |
50+
| `Retort: Validate` | Validate spec against schema |
51+
| `Retort: Show Backlog` | Show consolidated backlog |
52+
| `Retort: Handoff` | Generate session handoff document |
53+
| `Retort: Preflight` | Pre-ship delivery checks |
54+
| `Retort: Security Scan` | Security audit |
55+
| `Retort: Project Status` | Unified PM dashboard |
56+
| `Retort: Run Command...` | Choose and run any Retort command |
57+
58+
## Keyboard Shortcut
59+
60+
`Shift+Ctrl+Alt+R` — opens the **Run Command...** picker.
61+
62+
## Sidebar
63+
64+
The Retort sidebar view (Activity Bar icon) shows:
65+
66+
- Active orchestration phase
67+
- In-progress tasks from `.claude/state/tasks/`
68+
- Quick-launch buttons for common commands
69+
70+
## Status Bar
71+
72+
A status bar item on the right shows the active phase (e.g. `Retort: Implementation`).
73+
Click it to open the command picker.
74+
75+
## Troubleshooting
76+
77+
**Extension not activating**
78+
: Ensure `.agentkit/spec/project.yaml` exists. The extension only activates when
79+
`.agentkit/` is present at the workspace root — not in a subdirectory.
80+
81+
**Commands not found in terminal**
82+
: The extension runs Retort in VS Code's integrated terminal. Ensure `pnpm` is
83+
on your `PATH`. Check `Extensions → Retort → Output` for error details.
84+
85+
**Sidebar is empty**
86+
: Run `Retort: Sync Configs` once to generate state files. The sidebar reads
87+
`.claude/state/` which is created on first sync.

‎docs/onboarding/zed.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Retort — Zed Extension
2+
3+
The Zed extension adds Retort slash commands to Zed's AI assistant panel.
4+
It is implemented as a Rust `slash_command` extension.
5+
6+
## Requirements
7+
8+
- [Zed](https://zed.dev) stable or nightly
9+
- Retort installed in the project (`.agentkit/spec/project.yaml` must exist)
10+
- Rust toolchain (for building from source only)
11+
12+
## Installation
13+
14+
### From the Zed Extension Registry (recommended)
15+
16+
1. Open Zed.
17+
2. Press `Cmd+Shift+X` (macOS) / `Ctrl+Shift+X` (Linux) to open extensions.
18+
3. Search for **Retort**.
19+
4. Click **Install**.
20+
21+
### Manual / dev install
22+
23+
```bash
24+
cd extensions/zed
25+
cargo build --release
26+
```
27+
28+
Then in Zed: **Extensions → Install Dev Extension** and point to the
29+
`extensions/zed` directory.
30+
31+
## Available Slash Commands
32+
33+
Type `/` in the Zed AI assistant panel to see the Retort commands:
34+
35+
| Command | Description |
36+
|---------|-------------|
37+
| `/retort-status` | Show active Retort agents and task status |
38+
| `/retort-teams` | List Retort agent teams |
39+
| `/retort-backlog` | Show open Retort backlog items |
40+
| `/retort-sync` | Instructions to run `retort sync` |
41+
42+
## Usage Example
43+
44+
```
45+
/retort-status
46+
# → Returns current phase, in-progress tasks, and team roster
47+
48+
/retort-teams
49+
# → Lists all configured agent teams with their scope
50+
51+
/retort-backlog
52+
# → Shows open items from AGENT_BACKLOG.md
53+
```
54+
55+
## Limitations
56+
57+
Compared to the VS Code and JetBrains extensions, the Zed extension is
58+
intentionally minimal — Zed's extension API currently supports slash commands
59+
only. There is no sidebar panel or status bar widget.
60+
61+
As Zed's extension API matures, additional surface areas (status bar, sidebar)
62+
will be added.
63+
64+
## Troubleshooting
65+
66+
**Commands not appearing**
67+
: Ensure the extension is installed and Zed has been restarted. Slash commands
68+
appear only when the AI assistant panel is open (`Cmd+?` or **View → AI Assistant**).
69+
70+
**`cargo build` fails**
71+
: Ensure Rust stable is installed (`rustup update stable`). The extension uses
72+
the `zed_extension_api` crate — check `Cargo.toml` for the pinned version.
73+
74+
**Output is empty**
75+
: The extension reads `.claude/state/` files. Run `retort sync` in the terminal
76+
first to generate state files, then retry the slash command.

0 commit comments

Comments
 (0)