---
slug: "pi-conductor-whamp"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Whamp/pi-conductor@master/README.md"
repo: "https://github.com/Whamp/pi-conductor"
source_file: "README.md"
branch: "master"
---
# Pi-Conductor

Converting the Gemini CLI Conductor extension to Pi skills and commands.

## Overview

**Pi-Conductor** converts the [Gemini CLI Conductor extension](https://github.com/yourusername/conductor) to work with the [Pi coding agent](https://github.com/yourusername/pi). Conductor is a context-driven development framework that follows "measure twice, code once" through spec-driven workflows.

### What is Conductor?

Conductor treats context as a managed artifact alongside code. It provides:

- **Tracks**: High-level units of work (features, bug fixes) with specs and plans
- **TDD Workflow**: Test-driven development with phase checkpointing
- **Context Management**: Product goals, tech stack, workflow, and style guides
- **Git-Aware**: Uses git notes and commits for task tracking

## Quick Start

### One-Command Installation ⭐

```bash
# Clone this repository
git clone https://github.com/yourusername/pi-conductor.git
cd pi-conductor

# Convert and install automatically
npm run update
```

That's it! The update script will:
1. Pull latest Conductor extension
2. Convert to Pi format
3. Create backup
4. Install to `~/.pi/agent/`
5. Verify installation

### Manual Installation

```bash
# Convert the extension
npm run convert

# Install to Pi
cp -r pi-output/commands/* ~/.pi/agent/commands/
cp -r pi-output/skill/conductor ~/.pi/agent/skills/
```

## Updating

### Automatic Updates ⭐

When the Conductor extension is updated, simply run:

```bash
# Check for updates
npm run update:check

# Preview what will change
npm run update:dry

# Apply updates
npm run update
```

The update script includes:
- **Automatic change detection** - Only runs if something changed
- **Changelog generation** - See exactly what changed
- **Automatic backups** - Easy rollback if something goes wrong
- **Installation verification** - Ensures everything works

### Rollback

If an update causes issues:

```bash
# List available backups
npm run rollback:list

# Rollback to previous version
npm run rollback
```

See **[HOW-TO-UPDATE.md](https://github.com/Whamp/pi-conductor/blob/HEAD/HOW-TO-UPDATE.md)** for detailed update instructions.

## Usage

Once installed, restart Pi and the following commands will be available:

### 1. Setup a Project

```bash
/conductor-setup
```

Guides you through:
- Project discovery (greenfield vs brownfield)
- Product definition (goals, users, features)
- Technology stack selection
- Code style guide selection
- Workflow customization

### 2. Create a Track

```bash
/conductor-newtrack "Add user authentication"
```

Creates:
- `conductor/tracks/<track_id>/spec.md` - Requirements
- `conductor/tracks/<track_id>/plan.md` - Implementation tasks
- `conductor/tracks/<track_id>/metadata.json` - Track status
- Updates `conductor/tracks.md` - Master track list

### 3. Implement the Track

```bash
/conductor-implement
```

Executes tasks following the TDD workflow:
1. Selects the current track
2. Executes tasks in order
3. Writes tests first, then implementation
4. Commits after each task
5. Attaches git notes for summaries

### 4. Check Status

```bash
/conductor-status
```

Displays:
- Current track and phase
- Progress percentage
- Next action needed
- Any blockers

### 5. Revert Work

```bash
/conductor-revert
```

Provides git-aware revert of:
- Entire tracks
- Specific phases
- Individual tasks

## Project Structure

After running `/conductor-setup`, your project will have:

```
conductor/
├── product.md                  # Project goals, users, features
├── product-guidelines.md       # Brand, voice, visual identity
├── tech-stack.md              # Languages, frameworks, databases
├── workflow.md                # Development methodology (TDD)
├── tracks.md                  # Master list of all tracks
├── setup_state.json           # Setup progress tracking
├── code_styleguides/          # Language-specific style guides
│   ├── python.md
│   ├── typescript.md
│   ├── javascript.md
│   └── ...
└── tracks/
    └── <track_id>/
        ├── spec.md            # Requirements
        ├── plan.md            # Implementation tasks
        └── metadata.json      # Track status
```

## NPM Scripts

### Conversion Scripts

```bash
npm run convert          # Convert TOML to Pi markdown
npm run convert:dry      # Preview conversion without writing files
```

### Update Scripts ⭐

```bash
npm run update           # Full automatic update (recommended)
npm run update:check     # Check if updates are available
npm run update:dry       # Preview what will change
npm run update:force     # Force re-conversion
```

### Rollback Scripts ⭐

```bash
npm run rollback         # Rollback to previous version
npm run rollback:list    # List available backups
```

### Changelog Scripts ⭐

```bash
npm run changelog        # View changelog
```

See **[scripts/README.md](https://github.com/Whamp/pi-conductor/blob/HEAD/scripts/README.md)** for complete script reference.

## Command Mapping

| Gemini CLI | Pi | Notes |
|------------|-----|-------|
| `/conductor:setup` | `/conductor-setup` | Colon to dash |
| `/conductor:newTrack` | `/conductor-newtrack` | Camel to lowercase |
| `/conductor:implement` | `/conductor-implement` | Direct mapping |
| `/conductor:status` | `/conductor-status` | Direct mapping |
| `/conductor:revert` | `/conductor-revert` | Direct mapping |

## Architecture

### Conversion Process

1. **Parse TOML**: Extract `description` and `prompt` fields
2. **Generate Markdown**: Create YAML frontmatter + prompt content
3. **Map Names**: Convert camelCase to lowercase (e.g., `newTrack` → `newtrack`)
4. **Copy Templates**: Bundle workflow and code style guides in skill
5. **Generate Skill**: Create SKILL.md from GEMINI.md + README.md

### Update Process

1. **Check for updates**: Compare git commits and version numbers
2. **Pull changes**: Fetch latest from conductor/ repository
3. **Analyze changes**: Generate changelog from git diff
4. **Convert**: Run conversion script
5. **Create backup**: Timestamped backup of current installation
6. **Install**: Copy commands and skill to `~/.pi/agent/`
7. **Verify**: Validate installation, rollback on failure
8. **Save state**: Record conversion metadata

### Key Insights

- **No Logic Changes**: The conversion is purely syntactic
- **Protocol Compatible**: Multi-section markdown prompts work as-is
- **State Management**: JSON files + git notes preserved
- **User Interaction**: A/B choice patterns work identically
- **Safe Updates**: Automatic backups and verification prevent broken installations

## Documentation

- **[DETAILED-USAGE.md](https://github.com/Whamp/pi-conductor/blob/HEAD/DETAILED-USAGE.md)** - Comprehensive command reference, workflows, best practices, and troubleshooting guide
- **[HOW-TO-UPDATE.md](https://github.com/Whamp/pi-conductor/blob/HEAD/HOW-TO-UPDATE.md)** - Update instructions with automated and manual workflows
- **[AGENTS.md](https://github.com/Whamp/pi-conductor/blob/HEAD/AGENTS.md)** - Agent context for maintaining and improving this project
- **[scripts/README.md](https://github.com/Whamp/pi-conductor/blob/HEAD/scripts/README.md)** - Complete scripts reference
- **[Development Archive](https://github.com/Whamp/pi-conductor/tree/HEAD/docs/development/archive/)** - Planning documents, architectural analysis, comparison notes

## Development

### Project Status

- ✅ **Phase 1**: Analysis and Script Design - Complete
- ✅ **Phase 2**: Create Conversion Script - Complete
- ✅ **Phase 3**: Generate Pi Artifacts - Complete
- ✅ **Phase 4**: Update Automation - Complete
- ✅ **Phase 5**: Documentation - Complete

### What's New

#### Update Automation (v2.0) ⭐

The project now includes automated update functionality:

- **One-command updates** - `npm run update` handles everything
- **Change detection** - Skips conversion if nothing changed
- **Automatic backups** - Every update creates a timestamped backup
- **Changelog generation** - See exactly what changed between versions
- **Installation verification** - Validates commands and skill before completion
- **Easy rollback** - Restore any previous version with one command

#### New Scripts

- `scripts/update.js` - Automated update with git integration
- `scripts/rollback.js` - Rollback to any previous backup
- `scripts/changelog.js` - View and generate changelogs
- `scripts/lib/git.js` - Git utilities
- `scripts/lib/version.js` - Version tracking
- `scripts/lib/backup.js` - Backup and restore
- `scripts/lib/changelog.js` - Changelog generation
- `scripts/lib/verify.js` - Installation verification

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with `npm run convert:dry`
5. Submit a pull request

## License

MIT License - See [LICENSE](https://github.com/Whamp/pi-conductor/tree/HEAD/LICENSE) for details.

## Acknowledgments

- Original Conductor extension for Gemini CLI
- Pi coding agent framework
- The "measure twice, code once" philosophy

## Support

For issues with:
- **Conversion**: Open an issue in this repository
- **Conductor usage**: Refer to the skill documentation in `~/.pi/agent/skills/conductor/`
- **Pi agent**: Refer to Pi documentation

## Roadmap

### Completed ✅

- [x] Automated testing of converted commands
- [x] Validation tests for conversion accuracy
- [x] Automated update workflow
- [x] Changelog generation
- [x] Backup and rollback system

### Future Ideas 📋

- [ ] Watch mode for auto-conversion on extension updates
- [ ] CLI tool for easy installation (`pi-conductor install`)
- [ ] Integration tests with Pi agent
- [ ] Custom command mappings configuration
- [ ] Version compatibility checks with semver warnings
- [ ] Selective updates (update specific commands only)