Context-Driven Development framework for Claude Code

version
1.2.0
GitHub stars
15

Install

/plugin install conductor@conductor

Run it inside Claude Code after adding the marketplace with /plugin marketplace add lackeyjb/claude-conductor.

Contents

Discovered from source

Skills 3

Code Styleguides

Language-specific coding standards and best practices.

How It Works

Reads project-level styleguides from conductor/code_styleguides/ (copied during /conductor:setup based on tech stack).

Supported Languages

LanguageExtensionsStyleguide File
TypeScript.ts, .tsx, .mts, .ctsconductor/code_styleguides/typescript.md
Python.py, .pyiconductor/code_styleguides/python.md
Go.goconductor/code_styleguides/go.md
JavaScript.js, .jsx, .mjs, .cjsconductor/code_styleguides/javascript.md
HTML/CSS.html, .css, .scss, .sassconductor/code_styleguides/html-css.md

When to Activate

Writing new code, reviewing code, refactoring, or setting up new files/modules.

Universal Principles

AspectGuideline
NamingDescriptive, meaningful; clarity over brevity; consistency
StructureSingle responsibility; max 3-4 nesting levels; group related code
DocumentationDocument "why" not "what"; keep updated; docstrings for public APIs
ErrorsHandle explicitly; fail fast with clear messages; never swallow
TestingWrite alongside code (TDD); test behavior not implementation; high coverage on critical paths

Quick Reference

SettingRecommendation
Line length80-120 characters
Indentation2 spaces (JS/TS), 4 spaces (Python), tabs (Go)
NamingFollow language conventions
ImportsOrganized and grouped
CommentsMinimal, meaningful

Setup

If styleguides missing:

  1. Run /conductor:setup to initialize
  2. Or copy from templates/code-styleguides/ to conductor/code_styleguides/

Check: ls conductor/code_styleguides/

Integration

Works with: conductor-context (project overrides), tdd-workflow (language test patterns)

Conductor Context Awareness

Automatic context loading for Conductor-managed projects.

When to Activate

When conductor/ directory exists and user is: implementing tasks, working on features/bugs, or mentions "plan"/"tracks".

Context Files

FileContainsUse For
product.mdVision, goals, users, features, metricsThe WHY
tech-stack.mdLanguages, frameworks, DBs, libraries, architectureThe HOW
workflow.mdMethodology (TDD), coverage, commits, quality gatesThe PROCESS
tracks.mdAll tracks (features/bugs), status, prioritiesThe WHAT
code_styleguides/Language-specific standards, conventions, practicesThe STYLE

Workflow Reference

NeedRead
Coverage targetworkflow.md
Commit formatworkflow.md
Test methodologyworkflow.md
Technology choicestech-stack.md
Coding stylecode_styleguides/
Current focustracks.md

Loading Sequence

Before starting implementation:

  1. Check tracks.md for current track
  2. Read track's spec.md for requirements
  3. Read track's plan.md for tasks
  4. Follow workflow.md methodology

Full context load order:

  1. product.md (why)
  2. tech-stack.md (how)
  3. tracks.md (what)
  4. Track's spec.md and plan.md

Quick Commands

# Find in-progress items
grep -r "\[~\]" conductor/tracks/*/plan.md

# Count by status
grep -c "\[ \]" conductor/tracks.md   # Pending
grep -c "\[~\]" conductor/tracks.md   # In progress
grep -c "\[x\]" conductor/tracks.md   # Complete

Integration

Works with: tdd-workflow (TDD guidance), code-styleguides (language conventions)

TDD Workflow Skill

Guidance for Test-Driven Development methodology.

The Core Cycle

RED → GREEN → REFACTOR (repeat)

PhasePurposeActionsVerify
REDDefine expected behaviorWrite test for ONE behavior, run testTest FAILS
GREENMake it workWrite MINIMUM code to passTest PASSES
REFACTORMake it cleanImprove ONE thing at a time, run tests after each changeTests stay GREEN

Phase 1: RED - Write Failing Test

Purpose: Define behavior before implementation.

Actions:

  1. Create/open test file
  2. Write test for ONE behavior
  3. Run test
  4. Verify FAILURE (if it passes, test is wrong)

Common mistakes: Tests pass immediately, testing implementation not behavior, writing too many tests at once

Phase 2: GREEN - Make It Pass

Purpose: Write MINIMUM code to pass test.

Actions:

  1. Implement just enough to pass
  2. No extra features, no optimization
  3. Run tests, verify PASS

Common mistakes: Over-engineering, adding untested features, "while I'm here" additions

Phase 3: REFACTOR - Improve Quality

Purpose: Clean up while keeping tests green.

Actions:

  1. Identify improvements: duplication, naming, complex logic, long functions
  2. Make ONE change
  3. Run tests
  4. If green, continue. If red, undo.

Checklist: Extract methods, rename variables, remove duplication (DRY), simplify conditionals, add type safety

Test Patterns

Arrange-Act-Assert (AAA):

  1. Arrange: Set up test data
  2. Act: Execute the behavior
  3. Assert: Verify result

Given-When-Then (BDD): Structure nested describes for readability

Coverage Commands

LanguageCommand
JS/TS (Jest)npx jest --coverage
JS/TS (Vitest)npx vitest run --coverage
Pythonpytest --cov=src --cov-report=html
Gogo test -cover ./...

Anti-Patterns to Avoid

  1. Test After: Writing code first defeats TDD purpose
  2. Testing Implementation: Test WHAT it does, not HOW (test behavior, not internal calls)
  3. Brittle Tests: Use resilient assertions (e.g., toContainEqual not array index checks)
  4. No Refactoring: Skipping refactor creates technical debt

Quick Reference

  • RED: "What should it do?" → Write failing test
  • GREEN: "Does it work?" → Write minimal code
  • REFACTOR: "Is it clean?" → Improve structure

For detailed code examples, see examples.md in this skill directory.

Integration

Works with:

  • context-awareness: Project-specific coverage targets
  • code-styleguides: Language-specific test patterns

Commands 6

Conductor Agents

Monitor and manage background Conductor agents and git worktrees.

Commands

Default (no arguments): Check Background Agent Status

Run in parallel (single response with multiple Bash calls):

  1. List running tasks:

    # Use /tasks command to see all background agents
    # Parse output to identify conductor agents (implementer, planner, reviewer)
    
  2. List worktrees:

    git worktree list
    

Status Report Format:

For each background agent, display:

  • Agent type (implementer/planner/reviewer)
  • Task ID or description
  • Status (running/completed/failed)
  • Worktree path (if using worktree isolation)

If no background agents: "No background agents currently running."

If worktrees exist but no agents: Suggest /conductor:agents cleanup to remove orphaned worktrees.


/conductor:agents results - Retrieve Results

Use TaskOutput to retrieve results from completed background agents.

For each completed agent:

  1. Retrieve output:

    TaskOutput tool:
    - task_id: <agent_task_id>
    - block: false
    
  2. Display summary:

    • Implementer: Tasks completed, commits made, checkpoint SHA
    • Planner: Track ID, spec/plan paths created
    • Reviewer: Verification status, checkpoint SHA
  3. Worktree merge (if applicable):

    • Check if agent used worktree isolation
    • Merge worktree branch back to main
    • Cleanup worktree (see cleanup section)

/conductor:agents worktrees - List Worktrees

Display detailed worktree information:

git worktree list

For each worktree:

  • Path: .worktrees/<agent>-<id>
  • Branch: conductor/<agent>-<id>
  • Status: Check if branch has uncommitted changes

Commands for manual management:

# View worktree branch commits
git log conductor/<agent>-<id>

# Manually merge worktree
git merge --no-ff conductor/<agent>-<id> -m "conductor(merge): Manual merge of <agent> worktree"

# Remove worktree
git worktree remove .worktrees/<agent>-<id>
git branch -d conductor/<agent>-<id>

/conductor:agents cleanup - Clean Orphaned Worktrees

Remove worktrees that no longer have running agents.

Safety protocol:

  1. List all worktrees:

    git worktree list
    
  2. Check for running agents:

    • Compare worktrees against active background tasks
    • Identify orphaned worktrees (no associated running agent)
  3. For each orphaned worktree, ask user:

    • "Worktree .worktrees/<agent>-<id> has no running agent. Merge and cleanup? (yes/no)"
  4. If yes:

    # Check for uncommitted changes
    cd .worktrees/<agent>-<id>
    if [ -n "$(git status --porcelain)" ]; then
      echo "WARNING: Uncommitted changes in worktree"
      # Ask user to confirm or abort
    fi
    
    # Merge branch
    git checkout main
    git merge --no-ff conductor/<agent>-<id> -m "conductor(cleanup): Merge orphaned worktree <agent>-<id>"
    
    # Remove worktree
    git worktree remove .worktrees/<agent>-<id>
    
    # Delete branch
    git branch -d conductor/<agent>-<id>
    
  5. If no: Skip that worktree

  6. Report: "Cleaned up N worktrees."


Integration with /implement

After retrieving background implementer results:

  1. Verify plan.md reflects completed tasks
  2. Check if phase is complete
  3. Suggest next action:
    • Continue implementation (more tasks)
    • Run phase verification (phase complete)
    • Check status (review progress)

Safety Notes

  • Always check for uncommitted changes before removing worktrees
  • Use --no-ff merge to preserve branch history for audit trail
  • Confirm with user before destructive operations
  • Background agents may fail - always check status before cleanup

Conductor Implement

Execute the implementation workflow for the selected track.

Pre-flight Checks

Run these checks in parallel (single response with multiple Bash calls):

  1. Verify Conductor Setup:

    test -f conductor/tech-stack.md && test -f conductor/workflow.md && test -f conductor/product.md && echo "ready" || echo "missing"
    
    • If "missing": "Conductor is not set up. Please run /conductor:setup first."
  2. Check for tracks:

    test -f conductor/tracks.md && echo "exists" || echo "not found"
    
    • If "not found": "No tracks found. Create one with /conductor:new-track."
    • If "exists", read and parse conductor/tracks.md
    • If empty or malformed: "No tracks found. Create one with /conductor:new-track."

Argument Parsing

PatternTrack SelectionPhase Mode
/implementAuto-select first incompleteSingle-phase
/implement user-authMatch "user-auth"Single-phase
/implement --allAuto-select first incompleteAll-phases
/implement user-auth --allMatch "user-auth"All-phases

Track Selection

If track name provided ($ARGUMENTS)

  1. Search conductor/tracks.md for matching track description
  2. If found: "Found track ''. Is this correct?"
  3. If not found: Suggest closest match or next available track

If no track name provided

  1. Find first incomplete track ([ ] or [~])
  2. Announce: "Selecting next incomplete track: ''"
  3. If no incomplete tracks: "All tracks complete! Create a new one with /conductor:new-track."

Begin Implementation

Session Resumption

Conductor automatically resumes from plan.md status markers:

  1. Find resumption point: Scan plan.md for first [~] (in-progress) or first [ ] (pending) task
  2. Announce: "Resuming at Phase N: , Task: " (if continuing mid-phase)
  3. Skip completed work: Tasks marked [x] are already done

No special handoff files needed - plan.md is the single source of truth.

Update Track Status

  1. Find track heading in conductor/tracks.md
  2. Change ## [ ] Track: to ## [~] Track: (if not already in progress)
  3. Commit: conductor(track): Start track '<description>' (if status changed)

Load Track Context

Read these files in parallel (use multiple Read tool calls in one response):

  • conductor/tracks/<track_id>/plan.md
  • conductor/tracks/<track_id>/spec.md
  • conductor/workflow.md
  • conductor/tech-stack.md

Performance note: These files are independent and can be read simultaneously.

Phase Discovery

Parse phases from the track's plan.md:

  1. Find phase headings: Match ## Phase N: <Name> patterns (H2 headings)
  2. Detect completed phases: Phases with [checkpoint: <sha>] suffix are complete
  3. Count tasks per phase: Count - [ ], - [~], - [x] lines under each phase
  4. Determine phase status:
    • complete: Has checkpoint SHA in heading
    • in_progress: Has any task marked [~]
    • pending: All tasks marked [ ]

Build ordered list of phases with their status and task counts.

Phase Selection

If --all flag is set

Skip selection. Announce "Running all remaining phases for track ''." Proceed to Task Execution Loop.

If --all flag is NOT set (single-phase mode)

ScenarioAction
No incomplete phasesAnnounce complete. Offer /conductor:status or /conductor:new-track. STOP
Exactly 1 incompleteAuto-select. Announce "Only one phase remaining: Phase N: . Proceeding..."
Multiple incompleteUse AskUserQuestion with options for each phase + "All remaining" option

Processing selection:

  • If phase selected: Set selected_phase = N
  • If "All remaining": Set run_all_phases = true

Task Execution Loop

Determine Execution Scope

Based on Phase Selection results:

  1. If run_all_phases = true: Execute all tasks from first incomplete phase through end
  2. If selected_phase is set: Execute only tasks within the selected phase

For each task in scope (in order):

Delegate to Implementer Agent

ALWAYS use the Task tool to delegate task execution to the implementer agent:

Task tool:
- subagent_type: 'conductor:implementer'
- prompt: |
    Execute task: <task description>

    Track ID: <track_id>
    Context files:
    - conductor/tracks/<track_id>/spec.md
    - conductor/tracks/<track_id>/plan.md
    - conductor/workflow.md
    - conductor/tech-stack.md

    Requirements:
    1. Mark task in progress in plan.md
    2. Follow TDD: Red → Green → Refactor
    3. Verify coverage meets threshold (>80%)
    4. Run quality checks (lint, typecheck)
    5. Commit with conventional message
    6. Attach git notes with summary
    7. Update plan.md with commit SHA
    8. Commit plan update

    Report back when task is complete or if blocked.

The implementer agent will:

  • Execute the full TDD cycle
  • Commit code changes with proper messages
  • Update plan.md with progress
  • Report completion or blockers

Background Execution Option

For long-running tasks or parallel workflows, run the implementer in background:

When to use:

  • User explicitly requests it ("run in background", "work on this while I...")
  • Task is estimated to take significant time
  • User wants to work on unrelated tasks in parallel

Resource Warning:

  • Each background agent runs tests independently, consuming significant CPU
  • Limit to 2-3 concurrent background agents to avoid system overload
  • On resource-constrained systems, prefer parallel_agents: sequential mode
  • Use /conductor:agents to monitor running agents and clean up orphaned worktrees

Worktree isolation (if parallel_agents: worktree in workflow.md):

  1. Before spawning agent, create isolated worktree:

    TASK_ID="task_$(date +%s)"
    git worktree add .worktrees/implementer-$TASK_ID -b conductor/implementer-$TASK_ID
    
  2. Spawn agent with worktree path:

    Task tool:
    - subagent_type: 'conductor:implementer'
    - run_in_background: true
    - prompt: |
        WORKING DIRECTORY: .worktrees/implementer-<task_id>
    
        Execute task: <task description>
    
        Track ID: <track_id>
        Context files (relative to worktree):
        - conductor/tracks/<track_id>/spec.md
        - conductor/tracks/<track_id>/plan.md
        ...
    
  3. Announce: "Running implementer in background (worktree: .worktrees/implementer-<task_id>). Task: ''"

  4. On completion (use TaskOutput to retrieve):

    # Switch to worktree to get changes
    cd .worktrees/implementer-$TASK_ID
    
    # Merge branch back
    git checkout main
    git merge --no-ff conductor/implementer-$TASK_ID -m "conductor(merge): Complete background task '<description>'"
    
    # Cleanup worktree
    git worktree remove .worktrees/implementer-$TASK_ID
    git branch -d conductor/implementer-$TASK_ID
    

Important:

  • If parallel_agents: sequential, queue background agents instead of running in parallel
  • If parallel_agents: unsafe, skip worktree creation (not recommended)
  • DO NOT use background for dependent tasks within a phase
  • Always verify background completion before phase verification

Phase Completion Check

CRITICAL: If implementer was running in background, use TaskOutput to retrieve results before phase verification.

When all tasks in a phase are complete, delegate to reviewer agent:

Task tool:
- subagent_type: 'conductor:reviewer'
- prompt: |
    Verify phase: <phase name>

    Track ID: <track_id>
    Context files:
    - conductor/tracks/<track_id>/spec.md
    - conductor/tracks/<track_id>/plan.md
    - conductor/workflow.md

    Requirements:
    1. Announce verification protocol start
    2. Verify test coverage for all changed files
    3. Run automated tests
    4. Generate manual verification plan
    5. Await user confirmation
    6. Create checkpoint commit with git notes
    7. Update plan.md with checkpoint SHA

    Do not proceed past step 5 without explicit user approval.

The reviewer agent will:

  • Verify test coverage for phase changes
  • Run full test suite
  • Generate manual verification steps
  • Await user confirmation
  • Create checkpoint commit
  • Update plan with checkpoint SHA

After Phase Verification Completes

Single-phase mode: Announce "Phase N: complete. Checkpoint: ". Use AskUserQuestion: Continue to next phase / Take a break / Check status. Act accordingly.

All-phases mode: Continue directly to next phase. Only stop at track completion.

Track Completion

When all phases complete:

  1. Update tracks.md: [~] → [x]
  2. Review if product.md or tech-stack.md need updates (propose, await approval)
  3. Use AskUserQuestion: Archive to conductor/archive / Delete / Leave as-is
  4. Announce: "Track complete! Run /conductor:status for overall progress."

Conductor New Track

Create new track (feature/bug/chore) with spec and plan.

Pre-flight Checks

Read these files in parallel (4 Read calls in one response):

  1. conductor/tech-stack.md - Verify exists, load tech context
  2. conductor/workflow.md - Verify exists, load workflow context
  3. conductor/product.md - Verify exists, load product context
  4. conductor/tracks.md - Get existing track IDs (handle if missing)

If any of the first 3 files are missing: "Run /conductor:setup first."

Performance note: Parallel reads speed up pre-flight verification.

Get Track Description

ScenarioAction
Description provided ($ARGUMENTS)Use directly
No descriptionAsk: "Provide brief track description (feature/bug/chore)"

Determine Track Type

Infer from description (don't ask):

  • Feature: "add", "create", "implement"
  • Bug: "fix", "broken", "error"
  • Chore: "update", "refactor", "clean"

Delegate to Planner Agent

ALWAYS use Task tool:

Task tool:
- subagent_type: 'conductor:planner'
- prompt: |
    Create specification and implementation plan for: <description>

    Track type: <feature|bug|chore>

    Context files:
    - conductor/product.md
    - conductor/tech-stack.md
    - conductor/workflow.md

    Generate:
    1. Specification (spec.md): Requirements, acceptance criteria, constraints
    2. Implementation plan (plan.md): Phased breakdown with TDD-oriented tasks
    3. Generate unique track_id: <sanitized_description>_<YYYYMMDD>

    Return track_id, file paths, and summary when complete.

Background Planning Option

For large features or when user wants to continue working:

Task tool:
- subagent_type: 'conductor:planner'
- run_in_background: true
- prompt: |
    Create specification and implementation plan for: <description>
    ...

When to use:

  • User explicitly requests background execution ("plan this in background")
  • Feature is complex (expected to generate large spec/plan)
  • User wants to work on other tasks while planning proceeds

Important caveats:

  • Background planning is NOT recommended for most cases because:
    • Planner uses interactive questioning (AskUserQuestion) which requires foreground
    • User feedback is valuable during spec refinement
  • Only use if user explicitly prefers to review completed artifacts without iteration

Finalize Track

After planner completes:

  1. Read generated files to verify structure
  2. Create metadata.json:
    {
      "id": "<track_id>",
      "description": "<description>",
      "type": "<feature|bug|chore>",
      "created_at": "<ISO timestamp>",
      "status": "pending"
    }
    
  3. Register in tracks.md:
    • If file doesn't exist, create with header
    • Append: ## [ ] Track: <description> [<track_id>]
    • Keep tracks in chronological order
  4. Commit:
    git add conductor/tracks.md conductor/tracks/<track_id>/
    git commit -m "conductor(track): Add track '<description>'"
    
  5. Announce: "Track '' created. Run /conductor:implement <description> to start."

Conductor Revert

Git-aware revert that understands logical units of work (tracks, phases, tasks).

Pre-flight Checks

  1. Verify conductor/tracks.md exists. If not: "Run /conductor:setup first."
  2. Check git status --porcelain. If uncommitted changes: "Commit or stash before reverting."

Phase 1: Target Selection

Parse Arguments

PatternAction
track <name>Revert entire track
phase <name>Revert specific phase
task <name>Revert specific task
(no args)Show menu of in-progress/recent items

If no target provided

  1. Scan tracks.md and plan.md files for [~] (in-progress) and recent [x] (completed) items
  2. Use AskUserQuestion with numbered options for candidates + "A different item" option
  3. If "different", ask for specific name

Confirm Target

Use AskUserQuestion: "Revert [Phase] 'Backend API' from track 'user_auth'?" Yes/No

Phase 2: Git Analysis

Run these git operations in parallel (multiple Bash calls in one response):

  1. Extract commit SHAs from target's plan.md:

    grep -o '\[[x~]\].*\[[a-f0-9]\{7\}\]' conductor/tracks/<id>/plan.md
    
  2. Find plan update commits:

    git log --oneline -- conductor/tracks/<id>/plan.md
    
  3. For track reverts - find creation commit:

    git log --oneline -- conductor/tracks.md | grep -i "add track"
    

Sequential verification:

  • After parallel reads, verify each extracted SHA exists: git cat-file -t <sha>
  • If missing, search by message: git log --oneline --all | grep "<message>"
  • Compile ordered list (newest first) of all commits to revert (implementation + plan updates)

Performance note: Parallelizing git read operations speeds up revert preparation.

Phase 3: Execution Plan

Present Summary

Display:

  • Target description
  • List of commits (newest first) with messages
  • Action: git revert --no-edit on each
  • Warnings: Merge commits need special handling, old commits may have dependents

Use AskUserQuestion: "Proceed with revert?" Yes/No

Phase 4: Execution

Execute Reverts

For each commit (newest to oldest):

git revert --no-edit <sha>

Handle Conflicts

If conflict: Use AskUserQuestion: "Show conflict for manual resolution / Abort revert"

  • If show: Display conflict, wait for resolution, run git add . && git revert --continue
  • If abort: Run git revert --abort, announce rollback

Verify Plan State

After reverts:

  1. Read affected plan.md
  2. If status doesn't match (still [x] but code reverted):
    • Edit to change [x] → [ ]
    • Remove commit SHAs
    • Commit: git commit -m "conductor(plan): Reset status after revert"

Completion

Success: Announce:

  • Reverted N commits
  • Reset target status
  • Changed files list
  • Next steps: Run tests, /conductor:status, /conductor:implement to restart

Partial: Announce:

  • Successfully reverted commits
  • Failed commits (conflicts)
  • Manual intervention needed
  • Run git status for details

Conductor Setup

Initialize Conductor context-driven development environment. Follow protocol precisely.

Pre-flight Check

  1. Check existing setup: Test conductor/setup_state.json. If exists:
    • Read and offer resume from last_successful_step
    • If step is "complete", inform setup is done
  2. Check conductor directory: If exists without state file, warn about overwrite. Confirm before proceeding.

Phase 1: Project Discovery

1.1 Detect Project Maturity

Check brownfield indicators in parallel (3 Bash calls in one response):

  1. Git check:

    test -d .git && echo "git:yes" || echo "git:no"
    
  2. Manifest check:

    ls package.json requirements.txt go.mod pom.xml Cargo.toml 2>/dev/null | head -1 || echo "manifest:none"
    
  3. Source directories check:

    ls -d src app lib 2>/dev/null | head -1 || echo "src:none"
    

Evaluation:

  • Brownfield: Any indicator returns positive result
  • Greenfield: All checks return negative/none, directory empty or only README

Performance note: Running these checks in parallel speeds up project discovery.

1.2 Execute by Maturity

TypeActions
BrownfieldAnnounce analysis. Check git status (warn uncommitted). Analyze README, manifest files (respect .gitignore). Infer tech stack, architecture, goals. Present findings for confirmation.
GreenfieldAnnounce new project. Init git if needed. Ask "What do you want to build?" Create conductor/. Write initial concept to product.md.

1.3 Initialize State

Create conductor/setup_state.json with project_type and created_at timestamp.

Phase 2: Context Generation

For each section: (1) Introduce, (2) Ask questions (AskUserQuestion with options + "Type your own" + "Auto-generate"), (3) Draft content, (4) Present for approval, (5) Write file, (6) Update state.

SectionFileQuestionsState Step
Product Guideproduct.mdTarget users? Problems solved? Key features? Success metrics?2.1_product_guide
Product Guidelinesproduct-guidelines.mdBrand voice/tone? Design standards? Communication style?2.2_product_guidelines
Tech Stacktech-stack.mdBrownfield: Confirm inferred stack. Greenfield: Languages, frameworks, databases?2.3_tech_stack
Code Styleguidescode_styleguides/*.mdDetect languages from tech-stack.md. Map to available guides (typescript, python, go, javascript, html-css). Copy templates. Ask if adding others.2.4_code_styleguides
Workflowworkflow.mdCopy template. Ask: Coverage target (default 80%)? Commit per task/phase (default task)? Use git notes (default yes)?2.5_workflow

Phase 3: Initial Track

3.1 Get Track Description

Greenfield: Ask what to build first (MVP focus) Brownfield: Ask what enhancement/improvement to start with

3.2 Delegate to Planner

ALWAYS use Task tool:

Task tool:
- subagent_type: 'conductor:planner'
- prompt: |
    Create spec and plan for initial track: <description>
    Project type: <brownfield|greenfield>

    Context files: product.md, tech-stack.md, workflow.md

    Generate spec.md and plan.md with TDD task structure.
    Return artifacts for review.

3.3 Create Track Artifacts

After planner returns:

  1. Generate track ID: <shortname>_YYYYMMDD
  2. Create tracks.md with first track entry
  3. Create tracks/<track_id>/ with spec.md, plan.md, metadata.json
  4. Update state: "complete"

Completion

  1. Commit:

    git add conductor/ && git commit -m "conductor(setup): Initialize environment"
    
  2. Announce:

    Setup complete! Project now has:
    - Product context in conductor/product.md
    - Tech stack in conductor/tech-stack.md
    - Workflow in conductor/workflow.md
    - First track in conductor/tracks/
    
    Next: /conductor:implement to start working
    

Conductor Status

Display comprehensive project status overview.

Pre-flight Check

  1. Check conductor/tracks.md exists. If not: "Run /conductor:setup to initialize."
  2. If empty: "No tracks. Create one with /conductor:new-track."

Gather Data

Step 1: Read Core Files (Parallel)

Use parallel Read tool calls for:

  • conductor/product.md - Project name and context
  • conductor/tracks.md - Track list and status

Step 2: Read All Track Plans (Parallel)

After listing track directories with ls conductor/tracks/, issue parallel Read calls for all track plan.md files:

  • conductor/tracks/<track1>/plan.md
  • conductor/tracks/<track2>/plan.md
  • (etc. for all tracks)

For each plan.md, count:

  • [ ] pending tasks
  • [~] in-progress tasks
  • [x] completed tasks
  • Identify current phase and task

Performance note: Reading all track plans in parallel significantly speeds up status reporting for projects with multiple tracks.

Generate Report

Display status with:

  • Project name and timestamp
  • Tracks overview: Completed ✅ / In Progress 🔄 / Pending ⏳ counts
  • Current focus: Track, Phase, Task (all [~] items)
  • Progress bar: [████░░░░] X% (completed/total tasks)
  • Track details: Tree view with status indicators per phase/task
  • Next actions: Upcoming 2-3 tasks
  • Call to action: "Run /conductor:implement to continue"

If Blockers

Show section with blocked tasks and reasons (from plan.md BLOCKED markers).

If All Complete

Show celebration: "🎉 ALL TRACKS COMPLETE! Create new track with /conductor:new-track"

Summary Stats

  • Total phases/tasks across all tracks
  • Overall completion percentage

Agents 3

Conductor Implementation Agent

Execute development tasks with discipline, quality, and TDD methodology adherence.

Your Expertise

  1. TDD Execution: Red → Green → Refactor cycle mastery
  2. Clean Code: Maintainable, readable code
  3. Git Discipline: Atomic commits, clear messages
  4. Quality Gates: Coverage, linting, type safety
  5. Progress Tracking: Accurate plan.md updates

Context Loading

Before implementing, read these files in parallel (4 Read calls in one response):

  • conductor/tracks/<track_id>/plan.md - Implementation plan
  • conductor/tracks/<track_id>/spec.md - Requirements
  • conductor/workflow.md - Methodology
  • conductor/tech-stack.md - Technologies

Then read applicable styleguides:

  • Relevant conductor/code_styleguides/*.md (based on languages in task)

Performance note: Parallel reads speed up context loading for each task.

TDD Cycle

Follow the Red → Green → Refactor cycle from tdd-workflow skill.

Key checkpoints:

  • Tests MUST fail before implementation (verify Red phase)
  • Write minimum code to pass (Green phase)
  • Refactor only with green tests
  • Re-run tests after each refactor

Task Execution Protocol

For each task in plan.md:

  1. Mark in progress: Edit plan.md, change [ ] to [~]

  2. Execute TDD: Red → Green → Refactor

  3. Verify coverage: Run test suite, ensure meets threshold (from workflow.md, default >80%)

  4. Run quality checks: Lint, typecheck, security scans

  5. Commit changes:

    git add <files>
    git commit -m "<type>(<scope>): <description>"
    

    Types: feat, fix, refactor, test, docs, style, chore

  6. Attach git notes:

    git notes add -m "Task: <description>
    
    Summary:
    - <key change 1>
    - <key change 2>
    
    Files:
    - <file1> (new/modified)
    - <file2>" $(git log -1 --format="%H")
    
  7. Update plan.md: Change [~] to [x], add commit SHA: - [x] Task description [abc123d]

  8. Commit plan update:

    git add conductor/tracks/<track_id>/plan.md
    git commit -m "conductor(plan): Complete '<task description>'"
    

Quality Gates

Before marking task complete, verify:

  • All tests pass
  • Coverage meets threshold
  • No linting errors
  • No type errors
  • Code follows styleguide
  • No security vulnerabilities

Performance Optimization

For long-running test suites or builds:

  • Consider running tests in background: Use run_in_background: true parameter with Bash tool
  • Can prepare next task while waiting for results
  • Always check results before marking task complete

Note: Claude Code supports background bash execution for long operations.

When Blocked

If blocked:

  1. Document in plan.md: - [~] Task [BLOCKED] - Reason
  2. Propose solutions (mock dependency, alternative approach, needed info)
  3. Ask for guidance - do NOT skip or mark incomplete work as done

Communication

  • Announce which task you're starting
  • Report test results (pass/fail)
  • Mention deviations from plan
  • Briefly celebrate task completion

Conductor Planning Agent

Translate product requirements into actionable specifications and implementation plans.

Your Expertise

  1. Requirements Analysis: Extract clear, testable requirements
  2. Specification Writing: Create comprehensive spec.md
  3. Task Decomposition: Break features into phases/tasks
  4. TDD Planning: Structure tasks with test-first approach
  5. Risk Identification: Spot blockers and dependencies

Context Loading

Read these files in parallel (3 Read calls in one response):

  • conductor/product.md - Product vision
  • conductor/tech-stack.md - Technologies
  • conductor/workflow.md - Methodology

Then read if exists: conductor/tracks.md - Existing work

Performance note: Parallel reads speed up initial context loading for planning.

Generating spec.md

Structure: Overview, Background, Functional Requirements (FR-N with description, acceptance criteria, priority), Non-Functional Requirements (NFR-N: Performance, Security), User Stories (As/Want/So format with Given/When/Then), Technical Considerations, Out of Scope, Open Questions.

Keep focused. Prioritize clarity and testability.

Generating plan.md

Structure:

# Implementation Plan: <Track Title>

## Overview
Phase breakdown and approach

## Phase 1: <Name>
Goal: <What this phase achieves>

Tasks:
- [ ] Task: <Description> (TDD: Write test, implement, refactor)
- [ ] Task: <Description>
- [ ] Verification: Manual steps [checkpoint marker]

## Phase 2: ...

Task Guidelines:

  • Each task is one TDD cycle (Red → Green → Refactor)
  • Tasks should be 30min - 2hr scope
  • End each phase with verification task
  • Verification tasks use [checkpoint marker] for reviewer agent

Interactive Questioning

Before drafting artifacts:

  1. Ask 3-5 questions to clarify requirements
  2. Use AskUserQuestion with options + "Type your own"
  3. Explore edge cases, constraints, priorities
  4. Confirm understanding before proceeding

Output

Return:

  • Track ID generated: <description_sanitized>_YYYYMMDD
  • spec.md path
  • plan.md path
  • Brief summary of what was created

Conductor Review Agent

Verify implementation quality and create phase checkpoints.

Your Expertise

  1. Test Coverage Verification: Identify and fill coverage gaps
  2. Manual Verification Plans: Generate step-by-step verification instructions
  3. Checkpoint Creation: Phase completion commits with git notes
  4. Quality Assessment: Test execution, failure diagnosis

Context Loading

Before verification, read these files in parallel (3 Read calls in one response):

  • conductor/tracks/<track_id>/spec.md - Requirements
  • conductor/tracks/<track_id>/plan.md - Current phase/tasks
  • conductor/workflow.md - Methodology requirements

Performance note: Parallel reads speed up context loading for phase verification.

Phase Verification Protocol

1. Announce Start

"Phase '' complete. Running verification protocol."

2. Ensure Test Coverage

  1. Get modified files: git diff --name-only <last-checkpoint>..HEAD
  2. Filter to code files (exclude .json, .md, .yaml, .css)
  3. Verify each has test: src/foo.ts → src/foo.test.ts or tests/foo.test.ts
  4. If missing: Create following TDD patterns

3. Execute Automated Tests

  1. Announce command: "Running: CI=true npm test"
  2. Run tests (CI env prevents watch mode)
  3. If fail: Analyze, propose fix (max 2 attempts). If still failing: Stop, request guidance.

4. Generate Manual Verification Plan

Provide specific steps based on phase type:

Frontend: Start dev server, open browser, navigate to page, confirm UI, test interactions Backend: Start server, execute curl commands, verify responses CLI: Run commands with test inputs, verify outputs

5. Await User Confirmation

Use AskUserQuestion: "Manual verification complete? Proceed with checkpoint?"

  • If No: Ask what needs fixing, loop back
  • If Yes: Continue to checkpoint

6. Create Checkpoint Commit

# Commit any remaining changes
git add .
git commit -m "conductor(checkpoint): Complete phase '<phase name>'"

# Attach git notes with summary
SHA=$(git log -1 --format="%H")
git notes add -m "Phase: <phase name>

Summary:
- <key achievement 1>
- <key achievement 2>

Tasks completed: <count>
Test coverage: <percent>%" $SHA

7. Update plan.md

Append checkpoint SHA to phase heading: ## Phase N: <name> [checkpoint: abc123d]

Commit update:

git add conductor/tracks/<track_id>/plan.md
git commit -m "conductor(plan): Mark phase '<name>' complete [<sha>]"

8. Announce Completion

Report:

  • Phase checkpoint created:
  • Tasks completed:
  • Next phase: or "Track complete!"

Sponsors

Details

Marketplace
lackeyjb/claude-conductor
Author
Bryan Lackey
Category
Workflow
License
Apache-2.0
Keywords
context-driven, development, planning, implementation