README.md

Claude Conductor

Context-Driven Development for Claude Code

Claude Conductor transforms Claude Code into a proactive project manager, following a protocol of Context → Spec & Plan → Implement. It establishes project-level context that persists across sessions and drives every AI interaction.

Installation

Method 1: NPM Install (Easiest)

One command - works globally in all your projects:

npm install -g @vibecodingwithphill/claude-conductor

Done! The installer automatically configures everything.

Verify it works:

claude-conductor status

CLI Commands:

claude-conductor install    # Register in Claude settings
claude-conductor uninstall  # Remove from Claude settings
claude-conductor status     # Check installation
claude-conductor path       # Show install location

---

Method 2: Ask Claude to Install from GitHub

Copy this repo URL and paste it into Claude Code with a request like:

"Please install Claude Conductor from https://github.com/VibeCodingWithPhil/claude-conductor"

Claude will read the INSTALL.md and set everything up for you automatically.

---

Method 3: Manual Installation

1. Clone the repository:

   git clone https://github.com/VibeCodingWithPhil/claude-conductor.git ~/tools/claude-conductor

2. Add to Claude settings (~/.claude/settings.json):

   {
     "skills": {
       "conductor": {
         "path": "/absolute/path/to/claude-conductor"
       }
     }
   }

3. Start using - Open any project in Claude Code and run /conductor:setup

---

Package Structure

claude-conductor/
├── package.json           # NPM package definition
├── README.md              # This file
├── INSTALL.md             # Detailed installation guide (for Claude)
├── CLAUDE.md              # Development context (for contributors)
├── skills.json            # Skill definitions for Claude Code
├── bin/                   # CLI and install scripts
│   ├── cli.js             # claude-conductor command
│   └── postinstall.js     # Auto-setup after npm install
├── commands/              # Skill implementations
│   ├── setup.md           # /conductor:setup
│   ├── newTrack.md        # /conductor:newTrack
│   ├── implement.md       # /conductor:implement
│   ├── status.md          # /conductor:status
│   └── revert.md          # /conductor:revert
└── templates/             # Template files for new projects
    ├── product.md
    ├── product-guidelines.md
    ├── tech-stack.md
    ├── workflow.md
    ├── tracks.md
    └── code_styleguides/
        └── general.md

Quick Start

1. Initialize a project:

   /conductor:setup
   

2. Start a new feature/track:

   /conductor:newTrack "Add user authentication"
   

3. Begin implementation:

   /conductor:implement
   

4. Check progress:

   /conductor:status
   

Commands

Command	Description
/conductor:setup	Initialize project with context files
/conductor:newTrack	Create a new feature/bug track with spec and plan
/conductor:implement	Execute next pending task
/conductor:status	Show overall project progress
/conductor:revert	Undo changes from a track or task

Project Structure

After /conductor:setup, your project will have:

your-project/
├── conductor/
│   ├── product.md           # Project vision and goals
│   ├── product-guidelines.md # Brand and UX guidelines
│   ├── tech-stack.md        # Technology choices
│   ├── workflow.md          # Development workflow
│   ├── code_styleguides/    # Code standards
│   └── tracks.md            # Master tracking file
└── CLAUDE.md                # Updated with conductor context

Track Structure

Each track (feature/bug) creates:

conductor/tracks/<track_id>/
├── spec.md          # Detailed requirements
├── plan.md          # Actionable task breakdown
└── metadata.json    # Track metadata and status

Philosophy

Claude Conductor treats context as a managed artifact alongside code. By establishing project-level awareness, every Claude interaction benefits from:

• Product Context: Understanding the project's purpose and goals
• Technical Context: Knowing the tech stack and architecture
• Style Context: Following established patterns and guidelines
• Progress Context: Tracking what's done and what's next

Configuration

Create conductor.config.json in your project root:

{
  "project": {
    "name": "Your Project Name",
    "type": "application|library|api|cli"
  },
  "workflow": {
    "requireSpecs": true,
    "requireTests": true,
    "autoCommit": false
  },
  "tracks": {
    "prefix": "TRACK",
    "autoNumber": true
  }
}

Integration with Existing Projects

Claude Conductor works with existing projects. During setup, it will:

1. Analyze existing code structure
2. Generate context files based on findings
3. Merge with existing CLAUDE.md (if present)
4. Preserve all existing configurations

Best Practices

1. Always run setup first - Establishes context for better AI assistance
2. Create tracks for non-trivial work - Ensures planning before coding
3. Review specs before implementing - Catch issues early
4. Update context files as project evolves - Keep AI understanding current

Updates

How Updates Work

Claude Conductor separates tool logic from project data:

What	Where	Updated by
Commands & Templates	Global install location	npm update or git pull
Your project context	your-project/conductor/	You (never touched by updates)
Your tracks & specs	your-project/conductor/tracks/	You (never touched by updates)

Updating

NPM:

npm update -g @vibecodingwithphill/claude-conductor

Git:

cd ~/tools/claude-conductor && git pull

Updates take effect immediately in all projects - no per-project action needed.

Your Data is Safe

Updates never modify:

• Your conductor/ folders in projects
• Your tracks, specs, or plans
• Your customized context files
• Your CLAUDE.md files

License

Apache License 2.0

Credits

Inspired by Gemini Conductor, adapted for Claude Code.