conductor-methodology

Conductor Methodology Skill

Conductor is a context-driven development framework that structures software development through a rigorous lifecycle: Context → Spec & Plan → Implement. This skill provides guidance on Conductor's principles, file structures, and workflows.

Core Philosophy

Measure twice, code once. Conductor treats context as a managed artifact alongside code, transforming repositories into a single source of truth that drives every agent interaction with deep, persistent project awareness.

Key Principles

1. Plan before you build: Create specs and plans that guide implementation
2. Maintain context: Ensure AI follows style guides, tech stack choices, and product goals
3. Iterate safely: Review plans before code is written
4. Work as a team: Set project-level context shared across the team

Project Structure

Core Context Files (conductor/)

Located in the conductor/ directory at project root:

• product.md: Product vision, users, goals, and features
• product-guidelines.md: Prose style, brand messaging, visual identity
• tech-stack.md: Technology choices, languages, frameworks, databases
• workflow.md: Development workflow (TDD, commit strategy, coverage requirements)
• code_styleguides/: Language-specific coding standards
• tracks.md: Master list of all tracks with status and links

Track Structure (conductor/tracks/)

Each track lives in conductor/tracks/<track_id>/:

• spec.md: Detailed requirements for the track
• plan.md: Hierarchical plan with phases, tasks, and sub-tasks
• decisions.md: Architecture Decision Records for track decisions
• review.md: Auto-generated code review report on track completion
• metadata.json: Track metadata (ID, type, status, timestamps)

Track Lifecycle

Tracks represent high-level units of work (features, bugs, chores):

1. Creation (/conductor:newTrack): Generate spec and plan
2. In Progress: Mark as [~] when work begins
3. Completed: Mark as [x] when all tasks finish
4. Cleanup: Archive or delete completed tracks

Plan File Structure

Plans use hierarchical markdown with status markers:

# Phase 1: Foundation

- [ ] Task: Set up database schema
    - [ ] Create users table
    - [ ] Create posts table
    - [ ] Add indexes

- [~] Task: Implement user model
    - [x] Write failing tests
    - [~] Implement User class

# Phase 2: Features

- [ ] Task: Build authentication

Status Markers

• [ ] - Pending
• [~] - In progress
• [x] - Completed

Plan Format Rules

1. Phases: Top-level markdown headers (# Phase Name)
2. Parent Tasks: Bullet points with - [ ] Task: Description
3. Sub-tasks: Indented bullet points with - [ ] Description
4. Commit SHAs: Appended after completion (e.g., - [x] Task: Description [abc1234])
5. Phase Checkpoints: Appended to phase headers (e.g., # Phase 1 [checkpoint: def5678])

Workflow Patterns

Test-Driven Development (TDD)

Standard workflow from workflow.md:

1. Select Task: Choose next pending task from plan
2. Mark In Progress: Change [ ] to [~] in plan
3. Write Failing Tests (Red): Create tests that define expected behavior
4. Implement to Pass (Green): Write minimal code to pass tests
5. Refactor: Improve code while keeping tests passing
6. Verify Coverage: Ensure >80% coverage (or configured percentage)
7. Document Deviations: Update tech-stack.md if needed
8. Update Plan Status: Mark task as [x] in plan.md (pre-commit)
9. Confirm Commit: Ask user to commit or skip
10. Commit Code + Plan: Stage code changes and plan.md together, commit with descriptive message
11. Attach Task Summary: Use git notes for detailed summary (optional)
12. Record SHA in Plan: Append commit SHA to task line on disk (included in next commit)

Phase Completion Protocol

When a phase completes:

1. Ensure Test Coverage: Verify all changed files have tests
2. Execute Automated Tests: Run full test suite with CI=true
3. Propose Manual Verification Plan: Provide step-by-step verification steps
4. Await User Feedback: Get explicit confirmation
5. Record Phase Reference: Get last task commit SHA, append [checkpoint: <sha>] to phase header in plan (on disk only)
6. Announce Completion: Inform user the phase is complete and verified

Commit Message Patterns

• Implementation: feat(module): Add feature description
• Bug Fix: fix(module): Fix issue description
• Tests: test(module): Add tests for feature
• Refactoring: refactor(module): Refactor description
• Documentation: docs(module): Update documentation
• Chores: chore: Maintenance task description

Note: Plan.md updates are bundled into code commits — no separate conductor-specific commits are created. Track creation uses standard commit types (e.g., chore: Create track 'description').

Git Notes Usage

Conductor uses git notes for auditable tracking:

Task Notes

Attached to implementation commits with format:

Task: <Task Name>
Summary: <Brief description of changes>
Files Changed:
  - path/to/file1.ts
  - path/to/file2.ts
Why: <Rationale for changes>

Phase Verification Notes

Optionally attached to the last task commit of a phase:

Phase: <Phase Name>
Automated Tests: <Command run and result>
Manual Verification:
  - Step 1: <Action and expected result>
  - Step 2: <Action and expected result>
User Confirmation: <User's confirmation statement>

Question Types for Interactive Workflows

When gathering requirements or context:

Additive Questions

For brainstorming and scope (users, goals, features):

• Allow multiple answers
• Add "(Select all that apply)"
• Present as options A, B, C, D, E

Exclusive Choice Questions

For singular commitments (technology selection, workflow rules):

• Require single answer
• Do NOT add "(Select all that apply)"
• Present as options A, B, C, D, E

Option Format

Always include:

• A, B, C: Suggested answers
• D: "Type your own answer"
• E: "Autogenerate and review "

Track ID Format

Track IDs follow the pattern: shortname_YYYYMMDD

Examples:

• darkmode_20260113 - Add dark mode feature
• bugfix_20260113 - Fix login issue
• refactor_20260113 - Refactor database layer

State Management

Setup State (conductor/setup_state.json)

Tracks setup progress for resumability:

{
  "last_successful_step": "2.3_tech_stack"
}

Possible values:

• "" - Initial state
• "2.1_product_guide" - Product guide complete
• "2.2_product_guidelines" - Guidelines complete
• "2.3_tech_stack" - Tech stack complete
• "2.4_code_styleguides" - Style guides copied
• "2.5_workflow" - Workflow configured
• "3.3_initial_track_generated" - Setup fully complete

Track Metadata (metadata.json)

{
  "track_id": "feature_20260113",
  "type": "feature",
  "status": "in_progress",
  "created_at": "2026-01-13T10:30:00Z",
  "updated_at": "2026-01-13T15:45:00Z",
  "description": "Add user authentication"
}

Best Practices

When Creating Specs

1. Ask context-aware questions based on product.md and tech-stack.md
2. Provide 2-3 plausible options for each question
3. Ask questions sequentially (one at a time)
4. Include acceptance criteria and out-of-scope items
5. Get user confirmation before proceeding

When Creating Plans

1. Read and follow the workflow.md methodology
2. Break features into testable tasks
3. Include phase completion verification tasks
4. Use hierarchical structure (phases > tasks > sub-tasks)
5. Add status markers to EVERY item
6. Get user confirmation before starting work

When Implementing

1. Follow the workflow.md task lifecycle precisely
2. Never skip test-writing step in TDD
3. Verify tool call success before proceeding
4. Update plan.md status in real-time
5. Use git notes for audit trails
6. Get user confirmation for phase completions

When Syncing Documentation

1. Only update docs when track completes ([x])
2. Analyze spec.md for significant changes
3. Propose changes with diff format
4. Get explicit user approval before editing
5. Be very conservative with product-guidelines.md
6. Commit all doc changes together

Reverting Work

Conductor provides git-aware revert for logical units:

1. Identify Target: Track, phase, or task
2. Find Commits: Implementation + plan updates + track creation (if applicable)
3. Handle Rewritten History: Search for similar commit messages if SHA missing
4. Present Plan: Show all commits to be reverted
5. Get Confirmation: Explicit user approval required
6. Execute: Revert in reverse chronological order

Integration with Claude Code

All commands are invoked with /conductor:<command>:

• /conductor:setup - Initialize project
• /conductor:newTrack [description] - Create new track
• /conductor:implement [track] - Execute track plan
• /conductor:status - Show progress overview
• /conductor:revert [target] - Revert work

Commands use Claude Code tools (Read, Write, Edit, Bash, Glob, Grep) and follow plugin best practices.