Skip to content

release(skill): harden /release against v1.2.7 failure modes #597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arul28 merged 3 commits into from
Jun 17, 2026
Merged

release(skill): harden /release against v1.2.7 failure modes #597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9868bff
docs: overhaul Mintlify site + changelog for v1.2.7
arul28 Jun 17, 2026
65e7872
release: satisfy validate-docs for v1.2.7
arul28 Jun 17, 2026
2ac18cb
release(skill): harden /release against the v1.2.7 failure modes
arul28 Jun 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 145 additions & 55 deletions .agents/skills/release/SKILL.md
View file
Open in desktop

Large diffs are not rendered by default.

6 changes: 2 additions & 4 deletions .mintignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,5 @@ docs/
packages/
.factory/

# Template files we're replacing
essentials/
ai-tools/
api-reference/
# Source-of-truth media library lives elsewhere; the docs reference the
# committed copies under /media, /logo, and /favicon.png directly.
22 changes: 21 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [1.2.7] - 2026-06-16

### Added

- ADE Code: multi-question approvals in the terminal — arrow keys choose an option and move between questions, number keys pick and submit — replacing the old single-question quick-select.
- Mobile: auto-created lanes are now named from your prompt by the host's small AI model (Chat and CLI), with a deterministic fallback if the model is offline or times out.
- iOS: the new-chat composer now matches an in-session thread (single permission dropdown when space is tight, model pill, fast-mode toggle), with fast mode honored on create.

### Changed

- ADE Code: selecting a lane no longer reflows the drawer — single-line lane cards, a shared chat row, and reserved viewport rows kill the flicker; provider glyphs and colors now match the model picker, and grid navigation escapes cleanly with Tab.
- iOS: faster Work chat scrolling, with assistant previews cached for visible rows and deferred until after the stream merges.
- Stored chat transcripts are compacted while preserving durable replay and live output.

### Removed

- macOS VM runtime, UI, and `ade vm` CLI commands.
- Mobile push notifications; the app now relies on its live sync connection, and PR actions from widgets navigate in-app.

## [1.2.6] - 2026-06-16

### Fixed
Expand Down Expand Up @@ -409,7 +428,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Initial public release.

[Unreleased]: https://github.com/arul28/ADE/compare/v1.2.5...HEAD
[Unreleased]: https://github.com/arul28/ADE/compare/v1.2.7...HEAD
[1.2.7]: https://github.com/arul28/ADE/compare/v1.2.6...v1.2.7
[1.2.6]: https://github.com/arul28/ADE/compare/v1.2.5...v1.2.6
[1.2.5]: https://github.com/arul28/ADE/compare/v1.2.4...v1.2.5
[1.2.4]: https://github.com/arul28/ADE/compare/v1.2.3...v1.2.4
Expand Down
70 changes: 49 additions & 21 deletions ai-tools/claude-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,70 @@
---
title: "Claude Code"
description: "Use Claude Code as an ADE chat and worker backend."
icon: "terminal"
description: "Claude Code runs inside ADE through the bundled Claude Agent SDK — scoped to a lane, with permission modes and transcripts handled for you."
icon: "robot"
---

Claude Code can run inside ADE as a coding agent. ADE starts sessions in the selected lane, passes the right project context, and records the transcript and tool activity.
<Frame>
<div style={{ display: "flex", alignItems: "center", justifyContent: "center", padding: "1rem 0.5rem" }}>
<img src="/media/logos/models/claude-color.svg" alt="Claude" style={{ height: "48px", background: "#fff", borderRadius: "12px", padding: "10px 16px" }} />
</div>
</Frame>

Claude Code runs inside ADE through the **bundled Claude Agent SDK** — there's no separate `claude` CLI to install. Pick a Claude model in any chat and ADE starts the session in the selected lane's worktree, applies your permission mode, streams tool calls live, and records the transcript to History.

## Setup

<Steps>
<Step title="Install or authenticate Claude Code">
Make sure the `claude` CLI works in a normal terminal.
</Step>
<Step title="Open Settings -> AI Providers">
Refresh provider detection and verify Claude Code.
<Step title="Connect Claude in Settings → AI">
Sign in with a Claude subscription or paste an Anthropic API key. A green status means Claude is ready.
</Step>
<Step title="Start a lane chat">
Choose Claude from the model/provider selector.
<Step title="Pick a Claude model in chat">
Open the model picker in the chat header and choose a Claude model. That session now runs on Claude.
</Step>
</Steps>

## What ADE adds
## What ADE handles for you

- Lane-scoped working directories.
- Session transcripts in History.
- File and Git attribution.
- Provider permission controls.
- Links to PRs, Linear issues, and proof artifacts when used.
<CardGroup cols={2}>
<Card title="Lane-scoped worktree" icon="code-branch">
Every session runs in the active lane's worktree, so Claude edits and runs commands against that task's isolated checkout.
</Card>
<Card title="Live transcripts" icon="comments">
Tool calls, thinking, and diffs stream into chat and are saved to History.
</Card>
<Card title="Permission gates" icon="shield-halved">
A native permission mode decides what Claude can do without asking.
</Card>
<Card title="In-context links" icon="link">
Changes attribute to Files and Git, and link out to PRs, Linear issues, and proof when used.
</Card>
</CardGroup>

## Permission modes

Claude Code uses Claude's native permission model. Pick a stricter mode when exploring an unfamiliar repo, and a more permissive mode only when you trust the lane and task.
Claude Code uses Claude's native permission model. Pick a stricter mode when exploring an unfamiliar repo, and a more permissive one only when you trust the lane and task.

<AccordionGroup>
<Accordion title="The Claude permission modes" icon="shield-halved">
| Mode | Behavior |
|------|----------|
| `default` | Claude's built-in permission flow — asks before risky operations. |
| `plan` | Read-only. Writing and executing are blocked until you approve a plan. |
| `acceptEdits` | File writes allowed; shell commands still require approval. |
| `bypassPermissions` | Proceeds without asking. |

The mode can change mid-session from the permission picker. See [Permissions](/configuration/permissions) for how modes map across providers.
</Accordion>
<Accordion title="Where Claude runs" icon="terminal">
Claude is also one of the providers you can launch as a CLI session in the Work tab, and as a CTO worker backend. Wherever it runs, it's the same bundled Claude Agent SDK against the same lane worktree — desktop, [`ade code`](/tools/ade-code), and your phone all see the session.
</Accordion>
</AccordionGroup>

<CardGroup cols={2}>
<Card title="Agent chat" icon="comments" href="/chat/overview">
Run Claude in a lane.
</Card>
<Card title="AI providers" icon="brain" href="/configuration/ai-providers">
Configure provider defaults.
Connect each agent and set defaults.
</Card>
<Card title="Agent chat" icon="comments" href="/chat/overview">
Run Claude in a lane and watch tool calls stream.
</Card>
</CardGroup>
124 changes: 40 additions & 84 deletions ai-tools/cursor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,54 @@
---
title: "Cursor Integration"
description: "Use Cursor as an agent provider in ADE — launch sessions, route models, and track work through the Cursor SDK."
title: "Cursor"
description: "Run Cursor as an agent provider in ADE through the Cursor SDK — one of ADE's five agents, scoped to a lane."
icon: "arrow-pointer"
---

## Overview
[Cursor](https://cursor.com) runs inside ADE as one of its five agent providers, alongside Claude Code, Codex, Factory Droid, and OpenCode. ADE drives Cursor's agent through the official **Cursor SDK** — ADE owns the lane scope, permissions, and system prompt; the SDK owns the model and tool execution.

ADE integrates with [Cursor](https://cursor.com) in two ways:
## Connect Cursor

1. **Launch Cursor from ADE** — open your project or a lane's worktree in Cursor from the Run tab
2. **Cursor as an agent provider** — use Cursor's AI agent as a chat provider inside ADE via the Cursor SDK
Cursor chat authenticates with an API key. Add a Cursor API key in **Settings → AI**, or set `CURSOR_API_KEY` in the environment ADE launches from — ADE accepts either.

The SDK integration means Cursor's agent capabilities are available directly in ADE's chat interface, alongside Claude, Codex, and other providers. You can switch between providers per-session.

---

## Requirements

| Requirement | Details |
|------------|---------|
| **Cursor installed** | Cursor desktop app must be installed to launch Cursor from ADE |
| **Cursor SDK auth** | Cursor chat requires `CURSOR_API_KEY` or a Cursor API key saved in ADE Settings |
| **Authentication** | ADE uses API-key authentication for Cursor chat. Cursor desktop sign-in is only needed for launching the editor. |

ADE checks Cursor API-key authentication during onboarding and in **Settings → AI**. When `CURSOR_API_KEY` is present, ADE recognizes it as a valid authentication signal. You can also save the key in ADE's encrypted provider settings.

---

## Launching Cursor from ADE

Open the **Run** tab and click the **Cursor** launcher. ADE opens the current project (or the selected lane's worktree) in Cursor as a separate application window.

The session is linked back to the active lane for tracking. File changes made in Cursor appear in the lane's diff view as soon as they are saved.

---

## Cursor as an agent provider

When Cursor API-key auth is configured, ADE can use Cursor as a chat provider through the **Cursor SDK**.

### How it works

1. ADE starts an isolated SDK worker for the active lane
2. The worker creates or resumes a Cursor SDK agent with the selected model
3. Chat messages are routed through SDK runs, and Cursor has access to the `ade` CLI for ADE workflows
4. Model discovery queries Cursor SDK metadata for available models and capabilities

### Selecting Cursor in chat

In any Agent Chat session, use the **model selector** in the chat header to choose a Cursor-provided model. Models discovered from Cursor appear alongside Claude, GPT, and other configured providers.

### Model discovery

ADE queries Cursor for its available models at startup and caches the result. The discovered models appear in:
- The chat model selector
- The worker run model configuration
- The unified model selector throughout the app

### Session behavior

| Behavior | Details |
|----------|---------|
| **Session lifecycle** | Managed by the Cursor SDK pool; sessions are reused when possible |
| **Event mapping** | SDK events are mapped to ADE's chat event model for consistent UI |
| **ADE CLI access** | The `ade` CLI is on `PATH` so Cursor agents can call ADE lane, git, PR, and action tools |
| **Interrupts** | Supported via SDK run cancel |

---

## Connection status

ADE shows Cursor's connection status in **Settings → AI**:

| Status | Meaning |
|--------|---------|
| **Connected** (green) | Cursor API key found and ready |
| **Not authenticated** (amber) | Cursor API key is missing or invalid |
| **Not found** (gray) | Cursor desktop is not detected for editor launch |

---

## Troubleshooting
Once connected, ADE discovers Cursor's available models and they appear in the model picker alongside every other provider. Pick one in any chat header to route that session through Cursor.

<AccordionGroup>
<Accordion title="Cursor not detected" icon="circle-question">
ADE checks standard installation paths for the Cursor desktop app when launching the editor. If Cursor is installed in a non-standard location, open the project directly from Cursor or add the app to the standard Applications location.
<Accordion title="How the SDK provider works" icon="gear">
When a Cursor key is configured, ADE runs the official `@cursor/sdk` in a Node worker pool. The worker creates or resumes a Cursor SDK agent with the selected model in the active lane's worktree, and routes chat turns through SDK runs. Sessions are pooled and reused, SDK events map to ADE's chat event model, and interrupts cancel the run. Because the `ade` CLI is on `PATH`, Cursor agents can call ADE's lane, git, PR, and action tools.
</Accordion>
<Accordion title="Connection status" icon="signal">
ADE shows Cursor's status in **Settings → AI**:

| Status | Meaning |
|--------|---------|
| **Connected** (green) | Cursor API key found and ready. |
| **Not authenticated** (amber) | Cursor API key is missing or invalid. |
</Accordion>
<Accordion title="Authentication failed" icon="lock">
Add a Cursor API key in **Settings → AI Providers** or set `CURSOR_API_KEY` in the environment used to launch ADE.
<Accordion title="Cursor Agent CLI in the Work tab" icon="terminal">
You can also launch the `cursor-agent` CLI as a tracked terminal session in the Work tab. ADE probes `cursor-agent` for CLI-only models and merges them into the picker, so the chat-vs-CLI distinction stays clear. This needs the `cursor-agent` binary on your `PATH`.
</Accordion>
<Accordion title="Models not appearing" icon="list">
Model discovery runs at ADE startup. If you installed Cursor after starting ADE, restart ADE or go to **Settings → AI** and click **Refresh** to re-run model discovery.
<Accordion title="Cursor Cloud agents" icon="cloud">
Kick off Cursor's hosted cloud agents from ADE and follow them in a lane:

```bash
ade cursor cloud agents list --text
ade cursor cloud agents create --repo https://github.com/owner/repo --prompt "fix flaky test" --auto-pr
```

The chat panel can open a cloud agent as an ADE chat (replies still run in the cloud) or jump to it on cursor.com.
</Accordion>
<Accordion title="Session errors" icon="circle-exclamation">
If SDK sessions fail, check that the Cursor API key is configured and that the selected model is available. Check ADE's developer logs (**Settings → Developer → Log file**) for detailed SDK worker errors.
<Accordion title="Troubleshooting" icon="circle-question">
- **Authentication failed** — add a Cursor API key in **Settings → AI**, or set `CURSOR_API_KEY` in ADE's launch environment.
- **Models not appearing** — discovery serves last-known-good rows and revalidates in the background. If Cursor was just connected, restart ADE or refresh in **Settings → AI**.
- **Session errors** — confirm the key is valid and the selected model is available; check developer logs at **Settings → Developer → Log file**.
</Accordion>
</AccordionGroup>

<CardGroup cols={2}>
<Card title="AI providers" icon="brain" href="/configuration/ai-providers">
Connect each agent and set defaults.
</Card>
<Card title="Agent chat" icon="comments" href="/chat/overview">
Run Cursor in a lane and compare it with other providers.
</Card>
</CardGroup>
Loading