Conductor Compatibility Skill

Purpose: create and maintain Conductor artifacts so they remain fully compatible with the Gemini Conductor extension and its workflow (Context -> Spec & Plan -> Implement).

Use this skill when the user asks to set up a new project context, start a new track, implement or resume a track, check progress, or revert work.

Required File Structure (Do Not Deviate)

conductor/
  product.md
  product-guidelines.md
  tech-stack.md
  workflow.md
  setup_state.json
  code_styleguides/
    *.md
  tracks.md
  tracks/
    <track_id>/
      spec.md
      plan.md
      metadata.json
  archive/                 (optional)
    <track_id>/            (optional)

Required Formats

Track ID

• Format: shortname_YYYYMMDD (lowercase ASCII, underscores only).
• Example: auth_20251219.

conductor/tracks.md

• Must use --- separators between track sections.
• Each track section must use the exact heading format below.

---

## [ ] Track: <Track Description>
*Link: [./conductor/tracks/<track_id>/](./conductor/tracks/<track_id>/)*

conductor/tracks/<track_id>/metadata.json

• Required keys: track_id, type, status, created_at, updated_at, description.
• Timestamps are ISO 8601 UTC, e.g., 2025-12-19T23:59:59Z.
• status values: new, in_progress, completed, cancelled.

conductor/tracks/<track_id>/plan.md

• Use checklist markers: [ ] (pending), [~] (in progress), [x] (done).
• When completing a task, append the first 7 chars of the commit SHA to the task line.
• If the workflow defines the Phase Completion Verification protocol, append a meta-task to each phase: - [ ] Task: Conductor - User Manual Verification '<Phase Name>' (Protocol in workflow.md)
• When a phase is checkpointed, append [checkpoint: <sha>] to the phase heading.

Setup Workflow (Greenfield or Brownfield)

1. Detect project maturity (greenfield vs brownfield) based on repo and code presence.
2. Create conductor/ and conductor/setup_state.json if missing. Start with: { "last_successful_step": "" }
3. Generate or update the core documents with user input:
   • product.md
   • product-guidelines.md
   • tech-stack.md
4. Copy the workflow template from assets/templates/workflow.md into conductor/workflow.md unless the user provides a custom workflow.
5. Copy code style guides from assets/templates/code_styleguides/ into conductor/code_styleguides/.
6. Initialize conductor/tracks.md using the format in assets/templates/tracks.md.
7. Create the initial track folder and artifacts (spec.md, plan.md, metadata.json).
8. Update conductor/setup_state.json as steps complete using these values:
   • 2.1_product_guide
   • 2.2_product_guidelines
   • 2.3_tech_stack
   • 2.4_code_styleguides
   • 2.5_workflow
   • 3.3_initial_track_generated

New Track Workflow

1. Confirm Conductor is set up (product.md, tech-stack.md, workflow.md exist).
2. Collect or confirm a track description.
3. Draft and confirm spec.md (requirements, acceptance criteria, out of scope).
4. Draft and confirm plan.md based on workflow.md (TDD steps if required).
5. Create conductor/tracks/<track_id>/ with spec.md, plan.md, metadata.json.
6. Append the track section to conductor/tracks.md using the required format.

Implement Workflow

1. Parse conductor/tracks.md by --- separators and select the target track.
2. Mark the selected track as [~] in conductor/tracks.md before work starts.
3. Read conductor/tracks/<track_id>/spec.md, plan.md, and conductor/workflow.md.
4. Execute tasks strictly following the Task Workflow in workflow.md (including tests, commits, git notes, and plan updates).
5. When the track is complete, mark the track as [x] in conductor/tracks.md.
6. Synchronize product.md, tech-stack.md, and product-guidelines.md when the spec warrants it, with explicit user approval.
7. Offer to archive or delete the completed track. If archiving, move it to conductor/archive/<track_id> and remove its section from tracks.md.

Status Workflow

• Verify Conductor setup and conductor/tracks.md exists.
• Summarize counts of tracks and tasks (done/in progress/pending).
• Report current phase/task and next action.

Revert Workflow

• Confirm the target track/phase/task from tracks.md and plan.md.
• Use git history to identify associated commits.
• Present a clear revert plan and wait for explicit user confirmation before executing any destructive action.

Templates Available

• assets/templates/workflow.md
• assets/templates/code_styleguides/*.md
• assets/templates/tracks.md
• assets/templates/product.md
• assets/templates/product-guidelines.md
• assets/templates/tech-stack.md
• assets/templates/spec.md
• assets/templates/plan.md
• assets/templates/metadata.json