
conductor
Context-Driven Development framework for Claude Code
- version
- 1.2.0
- GitHub stars
- 15
Install
/plugin install conductor@conductorRun it inside Claude Code after adding the marketplace with /plugin marketplace add lackeyjb/claude-conductor.
Contents
Discovered from sourceSkills 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
| Language | Extensions | Styleguide File |
|---|---|---|
| TypeScript | .ts, .tsx, .mts, .cts | conductor/code_styleguides/typescript.md |
| Python | .py, .pyi | conductor/code_styleguides/python.md |
| Go | .go | conductor/code_styleguides/go.md |
| JavaScript | .js, .jsx, .mjs, .cjs | conductor/code_styleguides/javascript.md |
| HTML/CSS | .html, .css, .scss, .sass | conductor/code_styleguides/html-css.md |
When to Activate
Writing new code, reviewing code, refactoring, or setting up new files/modules.
Universal Principles
| Aspect | Guideline |
|---|---|
| Naming | Descriptive, meaningful; clarity over brevity; consistency |
| Structure | Single responsibility; max 3-4 nesting levels; group related code |
| Documentation | Document "why" not "what"; keep updated; docstrings for public APIs |
| Errors | Handle explicitly; fail fast with clear messages; never swallow |
| Testing | Write alongside code (TDD); test behavior not implementation; high coverage on critical paths |
Quick Reference
| Setting | Recommendation |
|---|---|
| Line length | 80-120 characters |
| Indentation | 2 spaces (JS/TS), 4 spaces (Python), tabs (Go) |
| Naming | Follow language conventions |
| Imports | Organized and grouped |
| Comments | Minimal, meaningful |
Setup
If styleguides missing:
- Run
/conductor:setupto initialize - Or copy from
templates/code-styleguides/toconductor/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
| File | Contains | Use For |
|---|---|---|
product.md | Vision, goals, users, features, metrics | The WHY |
tech-stack.md | Languages, frameworks, DBs, libraries, architecture | The HOW |
workflow.md | Methodology (TDD), coverage, commits, quality gates | The PROCESS |
tracks.md | All tracks (features/bugs), status, priorities | The WHAT |
code_styleguides/ | Language-specific standards, conventions, practices | The STYLE |
Workflow Reference
| Need | Read |
|---|---|
| Coverage target | workflow.md |
| Commit format | workflow.md |
| Test methodology | workflow.md |
| Technology choices | tech-stack.md |
| Coding style | code_styleguides/ |
| Current focus | tracks.md |
Loading Sequence
Before starting implementation:
- Check
tracks.mdfor current track - Read track's
spec.mdfor requirements - Read track's
plan.mdfor tasks - Follow
workflow.mdmethodology
Full context load order:
product.md(why)tech-stack.md(how)tracks.md(what)- Track's
spec.mdandplan.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)
| Phase | Purpose | Actions | Verify |
|---|---|---|---|
| RED | Define expected behavior | Write test for ONE behavior, run test | Test FAILS |
| GREEN | Make it work | Write MINIMUM code to pass | Test PASSES |
| REFACTOR | Make it clean | Improve ONE thing at a time, run tests after each change | Tests stay GREEN |
Phase 1: RED - Write Failing Test
Purpose: Define behavior before implementation.
Actions:
- Create/open test file
- Write test for ONE behavior
- Run test
- 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:
- Implement just enough to pass
- No extra features, no optimization
- 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:
- Identify improvements: duplication, naming, complex logic, long functions
- Make ONE change
- Run tests
- 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):
- Arrange: Set up test data
- Act: Execute the behavior
- Assert: Verify result
Given-When-Then (BDD): Structure nested describes for readability
Coverage Commands
| Language | Command |
|---|---|
| JS/TS (Jest) | npx jest --coverage |
| JS/TS (Vitest) | npx vitest run --coverage |
| Python | pytest --cov=src --cov-report=html |
| Go | go test -cover ./... |
Anti-Patterns to Avoid
- Test After: Writing code first defeats TDD purpose
- Testing Implementation: Test WHAT it does, not HOW (test behavior, not internal calls)
- Brittle Tests: Use resilient assertions (e.g.,
toContainEqualnot array index checks) - 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):
-
List running tasks:
# Use /tasks command to see all background agents # Parse output to identify conductor agents (implementer, planner, reviewer) -
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:
-
Retrieve output:
TaskOutput tool: - task_id: <agent_task_id> - block: false -
Display summary:
- Implementer: Tasks completed, commits made, checkpoint SHA
- Planner: Track ID, spec/plan paths created
- Reviewer: Verification status, checkpoint SHA
-
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:
-
List all worktrees:
git worktree list -
Check for running agents:
- Compare worktrees against active background tasks
- Identify orphaned worktrees (no associated running agent)
-
For each orphaned worktree, ask user:
- "Worktree
.worktrees/<agent>-<id>has no running agent. Merge and cleanup? (yes/no)"
- "Worktree
-
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> -
If no: Skip that worktree
-
Report: "Cleaned up N worktrees."
Integration with /implement
After retrieving background implementer results:
- Verify plan.md reflects completed tasks
- Check if phase is complete
- 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-ffmerge 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):
-
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:setupfirst."
- If "missing": "Conductor is not set up. Please run
-
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."
- If "not found": "No tracks found. Create one with
Argument Parsing
| Pattern | Track Selection | Phase Mode |
|---|---|---|
/implement | Auto-select first incomplete | Single-phase |
/implement user-auth | Match "user-auth" | Single-phase |
/implement --all | Auto-select first incomplete | All-phases |
/implement user-auth --all | Match "user-auth" | All-phases |
Track Selection
If track name provided ($ARGUMENTS)
- Search
conductor/tracks.mdfor matching track description - If found: "Found track ''. Is this correct?"
- If not found: Suggest closest match or next available track
If no track name provided
- Find first incomplete track (
[ ]or[~]) - Announce: "Selecting next incomplete track: ''"
- 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:
- Find resumption point: Scan plan.md for first
[~](in-progress) or first[ ](pending) task - Announce: "Resuming at Phase N: , Task: " (if continuing mid-phase)
- 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
- Find track heading in
conductor/tracks.md - Change
## [ ] Track:to## [~] Track:(if not already in progress) - 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.mdconductor/tracks/<track_id>/spec.mdconductor/workflow.mdconductor/tech-stack.md
Performance note: These files are independent and can be read simultaneously.
Phase Discovery
Parse phases from the track's plan.md:
- Find phase headings: Match
## Phase N: <Name>patterns (H2 headings) - Detect completed phases: Phases with
[checkpoint: <sha>]suffix are complete - Count tasks per phase: Count
- [ ],- [~],- [x]lines under each phase - Determine phase status:
complete: Has checkpoint SHA in headingin_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)
| Scenario | Action |
|---|---|
| No incomplete phases | Announce complete. Offer /conductor:status or /conductor:new-track. STOP |
| Exactly 1 incomplete | Auto-select. Announce "Only one phase remaining: Phase N: . Proceeding..." |
| Multiple incomplete | Use 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:
- If
run_all_phases = true: Execute all tasks from first incomplete phase through end - If
selected_phaseis 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: sequentialmode - Use
/conductor:agentsto monitor running agents and clean up orphaned worktrees
Worktree isolation (if parallel_agents: worktree in workflow.md):
-
Before spawning agent, create isolated worktree:
TASK_ID="task_$(date +%s)" git worktree add .worktrees/implementer-$TASK_ID -b conductor/implementer-$TASK_ID -
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 ... -
Announce: "Running implementer in background (worktree:
.worktrees/implementer-<task_id>). Task: ''" -
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:
- Update
tracks.md:[~]→[x] - Review if
product.mdortech-stack.mdneed updates (propose, await approval) - Use AskUserQuestion: Archive to conductor/archive / Delete / Leave as-is
- Announce: "Track complete! Run
/conductor:statusfor 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):
conductor/tech-stack.md- Verify exists, load tech contextconductor/workflow.md- Verify exists, load workflow contextconductor/product.md- Verify exists, load product contextconductor/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
| Scenario | Action |
|---|---|
| Description provided ($ARGUMENTS) | Use directly |
| No description | Ask: "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:
- Read generated files to verify structure
- Create metadata.json:
{ "id": "<track_id>", "description": "<description>", "type": "<feature|bug|chore>", "created_at": "<ISO timestamp>", "status": "pending" } - Register in tracks.md:
- If file doesn't exist, create with header
- Append:
## [ ] Track: <description> [<track_id>] - Keep tracks in chronological order
- Commit:
git add conductor/tracks.md conductor/tracks/<track_id>/ git commit -m "conductor(track): Add track '<description>'" - 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
- Verify
conductor/tracks.mdexists. If not: "Run/conductor:setupfirst." - Check
git status --porcelain. If uncommitted changes: "Commit or stash before reverting."
Phase 1: Target Selection
Parse Arguments
| Pattern | Action |
|---|---|
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
- Scan
tracks.mdandplan.mdfiles for[~](in-progress) and recent[x](completed) items - Use AskUserQuestion with numbered options for candidates + "A different item" option
- 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):
-
Extract commit SHAs from target's plan.md:
grep -o '\[[x~]\].*\[[a-f0-9]\{7\}\]' conductor/tracks/<id>/plan.md -
Find plan update commits:
git log --oneline -- conductor/tracks/<id>/plan.md -
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-editon 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:
- Read affected plan.md
- 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"
- Edit to change
Completion
Success: Announce:
- Reverted N commits
- Reset target status
- Changed files list
- Next steps: Run tests,
/conductor:status,/conductor:implementto restart
Partial: Announce:
- Successfully reverted commits
- Failed commits (conflicts)
- Manual intervention needed
- Run
git statusfor details
Conductor Setup
Initialize Conductor context-driven development environment. Follow protocol precisely.
Pre-flight Check
- 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
- Read and offer resume from
- 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):
-
Git check:
test -d .git && echo "git:yes" || echo "git:no" -
Manifest check:
ls package.json requirements.txt go.mod pom.xml Cargo.toml 2>/dev/null | head -1 || echo "manifest:none" -
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
| Type | Actions |
|---|---|
| Brownfield | Announce analysis. Check git status (warn uncommitted). Analyze README, manifest files (respect .gitignore). Infer tech stack, architecture, goals. Present findings for confirmation. |
| Greenfield | Announce 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.
| Section | File | Questions | State Step |
|---|---|---|---|
| Product Guide | product.md | Target users? Problems solved? Key features? Success metrics? | 2.1_product_guide |
| Product Guidelines | product-guidelines.md | Brand voice/tone? Design standards? Communication style? | 2.2_product_guidelines |
| Tech Stack | tech-stack.md | Brownfield: Confirm inferred stack. Greenfield: Languages, frameworks, databases? | 2.3_tech_stack |
| Code Styleguides | code_styleguides/*.md | Detect 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 |
| Workflow | workflow.md | Copy 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:
- Generate track ID:
<shortname>_YYYYMMDD - Create
tracks.mdwith first track entry - Create
tracks/<track_id>/with spec.md, plan.md, metadata.json - Update state:
"complete"
Completion
-
Commit:
git add conductor/ && git commit -m "conductor(setup): Initialize environment" -
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
- Check
conductor/tracks.mdexists. If not: "Run/conductor:setupto initialize." - 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 contextconductor/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.mdconductor/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
- TDD Execution: Red → Green → Refactor cycle mastery
- Clean Code: Maintainable, readable code
- Git Discipline: Atomic commits, clear messages
- Quality Gates: Coverage, linting, type safety
- 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 planconductor/tracks/<track_id>/spec.md- Requirementsconductor/workflow.md- Methodologyconductor/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:
-
Mark in progress: Edit plan.md, change
[ ]to[~] -
Execute TDD: Red → Green → Refactor
-
Verify coverage: Run test suite, ensure meets threshold (from workflow.md, default >80%)
-
Run quality checks: Lint, typecheck, security scans
-
Commit changes:
git add <files> git commit -m "<type>(<scope>): <description>"Types: feat, fix, refactor, test, docs, style, chore
-
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") -
Update plan.md: Change
[~]to[x], add commit SHA:- [x] Task description [abc123d] -
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: trueparameter 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:
- Document in plan.md:
- [~] Task [BLOCKED] - Reason - Propose solutions (mock dependency, alternative approach, needed info)
- 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
- Requirements Analysis: Extract clear, testable requirements
- Specification Writing: Create comprehensive spec.md
- Task Decomposition: Break features into phases/tasks
- TDD Planning: Structure tasks with test-first approach
- Risk Identification: Spot blockers and dependencies
Context Loading
Read these files in parallel (3 Read calls in one response):
conductor/product.md- Product visionconductor/tech-stack.md- Technologiesconductor/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:
- Ask 3-5 questions to clarify requirements
- Use AskUserQuestion with options + "Type your own"
- Explore edge cases, constraints, priorities
- 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
- Test Coverage Verification: Identify and fill coverage gaps
- Manual Verification Plans: Generate step-by-step verification instructions
- Checkpoint Creation: Phase completion commits with git notes
- 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- Requirementsconductor/tracks/<track_id>/plan.md- Current phase/tasksconductor/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
- Get modified files:
git diff --name-only <last-checkpoint>..HEAD - Filter to code files (exclude .json, .md, .yaml, .css)
- Verify each has test:
src/foo.ts→src/foo.test.tsortests/foo.test.ts - If missing: Create following TDD patterns
3. Execute Automated Tests
- Announce command: "Running: CI=true npm test"
- Run tests (CI env prevents watch mode)
- 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