Skip to content

CON-2: Finish Linear-first pre-submission compliance #186

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

Closed
swainjo wants to merge 2 commits into from
Closed

CON-2: Finish Linear-first pre-submission compliance #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6dbf804
feat: add optional Linear-first mode for Conductor tracks (#1)
swainjo Sep 16, 2026
e9f4b43
docs(install): add Cursor plugin install path (CON-2)
swainjo Sep 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
21 changes: 21 additions & 0 deletions .cursor-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"name": "conductor",
"displayName": "Conductor",
"version": "0.3.0",
"description": "Spec-Driven Development for AI coding agents: specify, plan, and implement software features.",
"author": {
"name": "Gemini CLI Extensions"
},
"homepage": "https://github.com/gemini-cli-extensions/conductor",
"repository": "https://github.com/gemini-cli-extensions/conductor",
"license": "Apache-2.0",
"keywords": [
"conductor",
"spec-driven-development",
"planning",
"sdd"
],
"category": "developer-tools",
"skills": "./skills/",
"rules": "./rules/"
}
100 changes: 92 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,40 @@ your Claude Code session:

--------------------------------------------------------------------------------

### 3. Cursor

Cursor is a first-class install target. Linear MCP is separate (see
[Optional Linear-first](#-optional-linear-first)); installing the plugin does
not authenticate Linear, and authenticating Linear does not install Conductor.

#### End-User / Developer Installation (Recommended)

There is no Cursor marketplace listing yet. Clone the repository and link it
into Cursor's local plugins directory (live-sync: edits on your branch load
without reinstalling):

1. Clone the repository:

```bash
git clone https://github.com/gemini-cli-extensions/conductor.git
cd conductor
```

2. Link into Cursor local plugins:

```bash
mkdir -p ~/.cursor/plugins/local
ln -sfn "$(pwd)" ~/.cursor/plugins/local/conductor
```

3. Reload Cursor (or restart) so it picks up `~/.cursor/plugins/local/conductor`.

*Why this method?* Cursor loads plugins from `~/.cursor/plugins/local/<name>/`.
A symlink is a live development link, the same idea as Antigravity's global
link.

--------------------------------------------------------------------------------

## 🔄 Uninstallation

To safely remove Conductor from your environment:
Expand All @@ -97,6 +131,7 @@ To safely remove Conductor from your environment:
* **Workspace Link:** Run `rm -f .agents/plugins/conductor`
* **Claude Code:** Run `/plugin remove conductor` and `/plugin marketplace
remove gemini-cli-extensions/conductor`
* **Cursor:** Run `rm -f ~/.cursor/plugins/local/conductor`

--------------------------------------------------------------------------------

Expand All @@ -114,6 +149,9 @@ To safely remove Conductor from your environment:
(Greenfield) and existing (Brownfield) projects.
- **Smart revert**: A git-aware revert command that understands logical units
of work (tracks, phases, tasks) rather than just commit hashes.
- **Optional Linear-first**: When a project has `conductor/linear.md`, tracks
use a Linear issue as the spec (pointer metadata + `plan.md`). File-based
`spec.md` / `tracks.md` remains the default when that file is absent.

--------------------------------------------------------------------------------

Expand Down Expand Up @@ -177,6 +215,8 @@ components or features by you or anyone on your team.
- `conductor/workflow.md`
- `conductor/code_styleguides/`
- `conductor/tracks.md`
- `conductor/linear.md` (only if you opt in to Linear-first)
- `scripts/linear_cli.py` and `scripts/linear_create_issue.py` (copied when Linear is enabled)

```bash
/conductor:conductor-setup
Expand All @@ -192,11 +232,20 @@ unit of work. Conductor helps you generate two critical artifacts:
building and why?
- **Plan**: An actionable to-do list containing phases, tasks, and sub-tasks.

**Generated Artifacts:**
**Generated Artifacts (file-based default):**

- `conductor/tracks/<track_id>/spec.md`
- `conductor/tracks/<track_id>/plan.md`
- `conductor/tracks/<track_id>/metadata.json`
- `conductor/tracks.md` entry

**Generated Artifacts (Linear-first, when `conductor/linear.md` exists):**

- Linear issue (created or linked) — this is the spec
- `conductor/tracks/<track_id>/metadata.json` (pointer: `track_id`, `linear`, `linear_url`)
- `conductor/tracks/<track_id>/plan.md`
- `conductor/tracks/<track_id>/index.md`
- No `spec.md`, no `tracks.md` entry

```bash
/conductor:conductor-new-track
Expand Down Expand Up @@ -247,12 +296,46 @@ following commands:

Command | Description | Generated Artifacts
:------------------------------- | :-------------------------------------------------------------------------------------- | :------------------
`/conductor:conductor-setup` | Scaffolds the project and sets up the Conductor environment. Run this once per project. | `conductor/product.md`<br>`conductor/product-guidelines.md`<br>`conductor/tech-stack.md`<br>`conductor/workflow.md`<br>`conductor/tracks.md`
`/conductor:conductor-new-track` | Starts a new feature or bug track. Generates `spec.md` and `plan.md`. | `conductor/tracks/<id>/spec.md`<br>`conductor/tracks/<id>/plan.md`<br>`conductor/tracks.md`
`/conductor:conductor-implement` | Executes the tasks defined in the current track's plan. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md`
`/conductor:conductor-status` | Displays the current progress of the tracks file and active tracks. | Reads `conductor/tracks.md`
`/conductor:conductor-revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history
`/conductor:conductor-review` | Reviews completed work against guidelines and the plan. | Reads `plan.md`, `product-guidelines.md`
`/conductor:conductor-setup` | Scaffolds the project and sets up the Conductor environment. Run this once per project. | `conductor/product.md`<br>`conductor/product-guidelines.md`<br>`conductor/tech-stack.md`<br>`conductor/workflow.md`<br>`conductor/tracks.md`<br>optional `conductor/linear.md` + CLI scripts
`/conductor:conductor-new-track` | Starts a new feature or bug track. File-based: `spec.md` + `plan.md`. Linear-first: issue as spec + pointer track. | File-based: `spec.md`, `plan.md`, `tracks.md`. Linear-first: Linear issue, pointer `metadata.json`, `plan.md`
`/conductor:conductor-implement` | Executes the tasks defined in the current track's plan. | `plan.md` (and `tracks.md` when file-based; Linear status when Linear-first)
`/conductor:conductor-status` | Displays the current progress of tracks. | Reads `tracks.md` and/or `tracks/*/metadata.json` + Linear status
`/conductor:conductor-revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history (optional Linear comment; no auto-cancel)
`/conductor:conductor-review` | Reviews completed work against guidelines and the plan (or Linear AC). | Reads `plan.md`, styleguides; Linear-first also runs label review

--------------------------------------------------------------------------------

## 🔗 Optional Linear-first

Conductor stays file-based unless the project has `conductor/linear.md`.

During setup, you can **skip** Linear (default) or **enable** it. Enabling writes
team identity and a label taxonomy into `conductor/linear.md` and copies:

- `scripts/linear_cli.py` — `get-issue`, `list-sub-issues`, `set-state`, `comment`
- `scripts/linear_create_issue.py` — create issues when MCP is unavailable

**Transport ladder:** Linear MCP (Cursor plugin / Claude Linear connector) →
CLI (`LINEAR_API_KEY`) → ask the user. Conductor does not bundle or authenticate
MCP.

When Linear-first is on:

- New tracks **create or link** a Linear issue. The issue description is the spec.
- Track folders hold pointer `metadata.json` + `plan.md` only.
- Implement/review/status use Linear acceptance criteria and Linear issue status.
- **In Review** only when work is complete; **Done** only on explicit instruction.
- Label review reads Class / Surface (and optional Domain / Platform / Quality)
from `linear.md`, not from a built-in product taxonomy.

Plugin skills `linear-issues`, `linear-review`, `linear-handoff`, and
`linear-label-review` activate only when `linear.md` exists.

CLI tests (no network):

```bash
uv run --with pytest pytest skills/conductor-setup/assets/linear/tests/
```

--------------------------------------------------------------------------------

Expand Down Expand Up @@ -298,7 +381,8 @@ corresponding Conductor protocol in the background:

## 📂 Repository Structure

- `/skills`: The protocol logic (`SKILL.md`) for each command.
- `/skills`: The protocol logic (`SKILL.md`) for each command, including optional `linear-*` skills.
- `/skills/conductor-setup/assets/linear`: `linear.md` template and CLI scripts copied into projects that opt in.
- `/rules`: Platform-specific operational rules files.

--------------------------------------------------------------------------------
Expand Down
34 changes: 27 additions & 7 deletions skills/conductor-implement/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,13 @@ You are the **Conductor Implementer**. Your goal is to execute the tasks defined

---

## Linear-first mode

**Detection:** Linear-first is **on** if and only if `conductor/linear.md` exists.
When it is on, follow **linear-issues**: the Linear issue is the spec, lifecycle
status lives on the issue, and `plan.md` markers are local execution state only.
When it is off, follow the file-based path (`spec.md`, `tracks.md`) in this skill.

## 1. Handshake & Context Initialization

Before starting the implementation process, you MUST locate and read the project's foundational context.
Expand Down Expand Up @@ -47,7 +54,10 @@ Adhere to this sequence to identify and select the track to be implemented.
2. **Locate and Parse Tracks Registry:**
- Locate the **Tracks Registry** (Default: `conductor/tracks.md`).
- Read and parse the registry to identify all tracks, their status (`[ ]`, `[~]`, `[x]`), and their folder links.
- **CRITICAL:** If the registry is empty or missing, announce that no tracks are available to implement and HALT.
- **Linear-first:** If `conductor/linear.md` exists, also discover tracks
from `conductor/tracks/*/metadata.json` (and `conductor/archive/` if
present). Do not HALT solely because `tracks.md` is missing or frozen.
- **CRITICAL:** If no tracks are found from either source, announce that no tracks are available to implement and HALT.

3. **Select Track:**
- **If a track name was provided:**
Expand All @@ -68,12 +78,18 @@ Adhere to this sequence to execute the selected track.
1. **Announce Action:** Announce which track you are beginning to implement.

2. **Update Status to 'In Progress':**
- Before beginning any work, update the status of the selected track to `[~]` in the **Tracks Registry** file.
- Stage the file and commit: `chore(conductor): Mark track '<track_description>' as in progress`.
- Before beginning any work, update the status of the selected track to `[~]` in the **Tracks Registry** file **if that file is in use**.
- **Linear-first:** set the linked Linear issue to **In Progress** (MCP or CLI) once per session. Do not require a `tracks.md` status flip.
- If you updated `tracks.md`, stage the file and commit: `chore(conductor): Mark track '<track_description>' as in progress`.

3. **Load Track Context:**
- Identify the track folder from the tracks file to get the `<track_id>`.
- Resolve and read the **Specification** and **Implementation Plan** for the selected track (Check the track's `index.md` for links, or use default paths).
- **Linear-first:** there is no `spec.md`. Fetch the Linear issue from
`metadata.json` (`linear` / `linear_url`) via MCP, else CLI, else ask
the user to paste acceptance criteria. If the issue has a parent, run
the epic track check (see **linear-issues**). Execute `plan.md` against
the issue. Comment on Linear only at phase/milestone boundaries.
- Resolve and read the **Workflow** document (Check `conductor/index.md` for the link, or use default path).
- If you fail to read any of these files, halt and inform the user.
- Check for installed skills in `.agents/skills/` and `~/.agents/extensions/conductor/skills/`.
Expand All @@ -85,8 +101,11 @@ Adhere to this sequence to execute the selected track.
- Ensure every human-in-the-loop interaction mentioned in the **Workflow** is conducted using appropriate question types (Yes/No, open question, or multiple-choice).

5. **Finalize Track:**
- After all tasks are completed, update the track status to `[x]` in the **Tracks Registry**.
- Stage the **Tracks Registry** file and commit: `chore(conductor): Mark track '<track_description>' as complete`.
- After all tasks are completed, update the track status to `[x]` in the **Tracks Registry** **if that file is in use**.
- **Linear-first:** follow **linear-issues** §3 — finish comment; **In Review**
only when work is committed, pushed, tests green, and the PR is open if
requested; **Done** only on explicit user instruction in this session.
- If you updated `tracks.md`, stage it and commit: `chore(conductor): Mark track '<track_description>' as complete`.
- Announce that the track is fully complete.

---
Expand All @@ -95,11 +114,12 @@ Adhere to this sequence to execute the selected track.

Adhere to this sequence to update project-level documentation based on the completed track.

1. **Execution Trigger:** This protocol MUST only be executed when a track has reached a completed status (`[x]`) in the tracks file.
1. **Execution Trigger:** This protocol MUST only be executed when a track has reached a completed status (`[x]`) in the tracks file, **or** (Linear-first) when `plan.md` tasks are complete and Linear close-out in §3.5 has been followed.

2. **Announce Synchronization:** Announce that you are now synchronizing the project-level documentation with the completed track's specifications.

3. **Load Track Specification:** Read the track's **Specification**.
3. **Load Track Specification:** Read the track's **Specification** (`spec.md`,
or the Linear issue description when Linear-first is on).

4. **Load Project Documents:**
- Locate and read:
Expand Down
Loading