pi-conductor-whamp

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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)

Pi-Conductor

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

Overview

Pi-Conductor converts the Gemini CLI Conductor extension to work with the Pi coding agent. 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 ⭐

# 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:

Pull latest Conductor extension
Convert to Pi format
Create backup
Install to ~/.pi/agent/
Verify installation

Manual Installation

# 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:

# 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:

# List available backups
npm run rollback:list

# Rollback to previous version
npm run rollback

See HOW-TO-UPDATE.md for detailed update instructions.

Usage

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

1. Setup a Project

/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

/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

/conductor-implement

Executes tasks following the TDD workflow:

Selects the current track
Executes tasks in order
Writes tests first, then implementation
Commits after each task
Attaches git notes for summaries

4. Check Status

/conductor-status

Displays:

Current track and phase
Progress percentage
Next action needed
Any blockers

5. Revert Work

/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

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

Update Scripts ⭐

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 ⭐

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

Changelog Scripts ⭐

npm run changelog        # View changelog

See 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

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

Update Process

Check for updates: Compare git commits and version numbers
Pull changes: Fetch latest from conductor/ repository
Analyze changes: Generate changelog from git diff
Convert: Run conversion script
Create backup: Timestamped backup of current installation
Install: Copy commands and skill to ~/.pi/agent/
Verify: Validate installation, rollback on failure
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 - Comprehensive command reference, workflows, best practices, and troubleshooting guide
HOW-TO-UPDATE.md - Update instructions with automated and manual workflows
AGENTS.md - Agent context for maintaining and improving this project
scripts/README.md - Complete scripts reference
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

Fork the repository
Create a feature branch
Make your changes
Test with npm run convert:dry
Submit a pull request

License

MIT License - See 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 ✅

Automated testing of converted commands
Validation tests for conversion accuracy
Automated update workflow
Changelog generation
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)