mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-18 01:51:20 -07:00
feat(cli): integrate conductor as a built-in extension
- Introduce support for bundled 'builtin' extensions in ExtensionManager - Migrate conductor extension to packages/core/src/extensions/builtin/conductor - Add automatic migration logic to cleanup manual conductor installations - Make extension versioning optional for built-ins, defaulting to CLI version - Update build and bundle scripts to include builtin extensions - Enhance documentation to highlight conductor as a core feature
This commit is contained in:
Jerop Kipruto
144
docs/cli/conductor.md
Normal file
144
docs/cli/conductor.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Conductor
|
||||
|
||||
**Measure twice, code once.**
|
||||
|
||||
Conductor is a built-in methodology for Gemini CLI that enables **Context-Driven
|
||||
Development**. It turns the Gemini CLI into a proactive project manager that
|
||||
follows a strict protocol to specify, plan, and implement software features and
|
||||
bug fixes.
|
||||
|
||||
Instead of just writing code, Conductor ensures a consistent, high-quality
|
||||
lifecycle for every task: **Context -> Spec & Plan -> Implement**.
|
||||
|
||||
The philosophy behind Conductor is simple: control your code. By treating
|
||||
context as a managed artifact alongside your code, you transform your repository
|
||||
into a single source of truth that drives every agent interaction with deep,
|
||||
persistent project awareness.
|
||||
|
||||
## Features
|
||||
|
||||
- **Plan before you build**: Create specs and plans that guide the agent for new
|
||||
and existing codebases.
|
||||
- **Maintain context**: Ensure AI follows style guides, tech stack choices, and
|
||||
product goals.
|
||||
- **Iterate safely**: Review plans before code is written, keeping you firmly in
|
||||
the loop.
|
||||
- **Work as a team**: Set project-level context for your product, tech stack,
|
||||
and workflow preferences that become a shared foundation for your team.
|
||||
- **Build on existing projects**: Intelligent initialization for both new
|
||||
(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.
|
||||
|
||||
## Usage
|
||||
|
||||
Conductor is designed to manage the entire lifecycle of your development tasks.
|
||||
It is one of the [planning workflows](./plan-mode.md#planning-workflows)
|
||||
supported by Gemini CLI.
|
||||
|
||||
**Note on Token Consumption:** Conductor's context-driven approach involves
|
||||
reading and analyzing your project's context, specifications, and plans. This
|
||||
can lead to increased token consumption, especially in larger projects or during
|
||||
extensive planning and implementation phases. You can check the token
|
||||
consumption in the current session by running `/stats model`.
|
||||
|
||||
### 1. Set Up the Project (Run Once)
|
||||
|
||||
When you run `/conductor:setup`, Conductor helps you define the core components
|
||||
of your project context. This context is then used for building new components
|
||||
or features by you or anyone on your team.
|
||||
|
||||
- **Product**: Define project context (e.g. users, product goals, high-level
|
||||
features).
|
||||
- **Product guidelines**: Define standards (e.g. prose style, brand messaging,
|
||||
visual identity).
|
||||
- **Tech stack**: Configure technical preferences (e.g. language, database,
|
||||
frameworks).
|
||||
- **Workflow**: Set team preferences (e.g. TDD, commit strategy).
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `conductor/product.md`
|
||||
- `conductor/product-guidelines.md`
|
||||
- `conductor/tech-stack.md`
|
||||
- `conductor/workflow.md`
|
||||
- `conductor/code_styleguides/`
|
||||
- `conductor/tracks.md`
|
||||
|
||||
```bash
|
||||
/conductor:setup
|
||||
```
|
||||
|
||||
### 2. Start a New Track (Feature or Bug)
|
||||
|
||||
When you’re ready to take on a new feature or bug fix, run
|
||||
`/conductor:newTrack`. This initializes a **track** — a high-level unit of work.
|
||||
Conductor helps you generate two critical artifacts:
|
||||
|
||||
- **Specs**: The detailed requirements for the specific job. What are we
|
||||
building and why?
|
||||
- **Plan**: An actionable to-do list containing phases, tasks, and sub-tasks.
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `conductor/tracks/<track_id>/spec.md`
|
||||
- `conductor/tracks/<track_id>/plan.md`
|
||||
- `conductor/tracks/<track_id>/metadata.json`
|
||||
|
||||
```bash
|
||||
/conductor:newTrack
|
||||
# OR with a description
|
||||
/conductor:newTrack "Add a dark mode toggle to the settings page"
|
||||
```
|
||||
|
||||
### 3. Implement the Track
|
||||
|
||||
Once you approve the plan, run `/conductor:implement`. Your coding agent then
|
||||
works through the `plan.md` file, checking off tasks as it completes them.
|
||||
|
||||
**Updated Artifacts:**
|
||||
|
||||
- `conductor/tracks.md` (Status updates)
|
||||
- `conductor/tracks/<track_id>/plan.md` (Status updates)
|
||||
- Project context files (Synchronized on completion)
|
||||
|
||||
```bash
|
||||
/conductor:implement
|
||||
```
|
||||
|
||||
Conductor will:
|
||||
|
||||
1. Select the next pending task.
|
||||
2. Follow the defined workflow (e.g., TDD: Write Test -> Fail -> Implement ->
|
||||
Pass).
|
||||
3. Update the status in the plan as it progresses.
|
||||
4. **Verify Progress**: Guide you through a manual verification step at the end
|
||||
of each phase to ensure everything works as expected.
|
||||
|
||||
During implementation, you can also:
|
||||
|
||||
- **Check status**: Get a high-level overview of your project's progress.
|
||||
```bash
|
||||
/conductor:status
|
||||
```
|
||||
- **Revert work**: Undo a feature or a specific task if needed.
|
||||
|
||||
```bash
|
||||
/conductor:revert
|
||||
```
|
||||
|
||||
- **Review work**: Review completed work against guidelines and the plan.
|
||||
```bash
|
||||
/conductor:review
|
||||
```
|
||||
|
||||
## Commands Reference
|
||||
|
||||
| Command | Description | Artifacts |
|
||||
| :--------------------- | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/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:newTrack` | 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:implement` | Executes the tasks defined in the current track's plan. | `conductor/tracks.md`<br>`conductor/tracks/<id>/plan.md` |
|
||||
| `/conductor:status` | Displays the current progress of the tracks file and active tracks. | Reads `conductor/tracks.md` |
|
||||
| `/conductor:revert` | Reverts a track, phase, or task by analyzing git history. | Reverts git history |
|
||||
| `/conductor:review` | Reviews completed work against guidelines and the plan. | Reads `plan.md`, `product-guidelines.md` |
|
||||
@@ -272,27 +272,24 @@ argsPattern = "\"file_path\":\"[^\"]+[\\\\/]+\\.gemini[\\\\/]+plans[\\\\/]+[\\w-
|
||||
|
||||
## Planning workflows
|
||||
|
||||
Plan Mode provides building blocks for structured research and design. These are
|
||||
implemented as [extensions](../extensions/index.md) using core planning tools
|
||||
like [`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode),
|
||||
[`exit_plan_mode`](../tools/planning.md#2-exit_plan_mode-exitplanmode), and
|
||||
[`ask_user`](../tools/ask-user.md).
|
||||
Plan Mode provides building blocks for structured research and design. Gemini
|
||||
CLI includes two built-in planning workflows to suit different project needs.
|
||||
|
||||
### Built-in planning workflow
|
||||
### Standard
|
||||
|
||||
The built-in planner uses an adaptive workflow to analyze your project, consult
|
||||
The standard planner uses an adaptive workflow to analyze your project, consult
|
||||
you on trade-offs via [`ask_user`](../tools/ask-user.md), and draft a plan for
|
||||
your approval.
|
||||
your approval. It is ideal for quick exploration and ad-hoc tasks.
|
||||
|
||||
### Custom planning workflows
|
||||
### Conductor
|
||||
|
||||
You can install or create specialized planners to suit your workflow.
|
||||
[Conductor] is a built-in methodology for spec-driven development, designed for
|
||||
managing large features and complex tasks through persistent artifacts. It
|
||||
organizes work into tracks and stores them in your project's `conductor/`
|
||||
directory.
|
||||
|
||||
#### Conductor
|
||||
|
||||
[Conductor] is designed for spec-driven development. It organizes work into
|
||||
"tracks" and stores persistent artifacts in your project's `conductor/`
|
||||
directory:
|
||||
Conductor leverages Plan Mode internally to ensure architectural safety during
|
||||
the design phase. To get started with Conductor, run `/conductor:setup`.
|
||||
|
||||
- **Automate transitions:** Switches to read-only mode via
|
||||
[`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode).
|
||||
@@ -303,10 +300,19 @@ directory:
|
||||
- **Handoff execution:** Transitions to implementation via
|
||||
[`exit_plan_mode`](../tools/planning.md#2-exit_plan_mode-exitplanmode).
|
||||
|
||||
#### Build your own
|
||||
### Comparison of planning workflows
|
||||
|
||||
| Feature | Standard | Conductor |
|
||||
| :-------------- | :--------------------------------- | :------------------------------------------------ |
|
||||
| **Persistence** | Ephemeral, session-based | Persistent, stored in your repository |
|
||||
| **Workflow** | Lightweight research & design | Structured Spec -> Plan -> Implement lifecycle |
|
||||
| **Artifacts** | `.md` files in a temp directory | `spec.md`, `plan.md`, `tracks.md` in `conductor/` |
|
||||
| **Best For** | Quick exploration and ad-hoc tasks | Major features, bug fixes, and long-running tasks |
|
||||
|
||||
### Build your own
|
||||
|
||||
Since Plan Mode is built on modular building blocks, you can develop your own
|
||||
custom planning workflow as an [extensions](../extensions/index.md). By
|
||||
custom planning workflow as an [extension](../extensions/index.md). By
|
||||
leveraging core tools and [custom policies](#custom-policies), you can define
|
||||
how Gemini CLI researches and stores plans for your specific domain.
|
||||
|
||||
@@ -376,5 +382,5 @@ those files are not automatically deleted and must be managed manually.
|
||||
|
||||
[`plan.toml`]:
|
||||
https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policies/plan.toml
|
||||
[Conductor]: https://github.com/gemini-cli-extensions/conductor
|
||||
[Conductor]: ./conductor.md
|
||||
[open an issue]: https://github.com/google-gemini/gemini-cli/issues
|
||||
|
||||
Reference in New Issue
Block a user