Conductor

Conductor

Primary loop: Setup -> Track -> Spec(+approval) -> Plan(+approval) -> Implement -> Review -> Reconcile

Preserved Conductor invariants:

• Durable context is on disk, not only in chat memory
• Work is represented as tracks
• Important tracks carry both spec and plan artifacts
• Review is a first-class stage before closure

OpenCode-specific adaptation:

• Use task(subagent_type="...") for delegation
• Use .omc/conductor/ paths used by OMC hooks
• Use question for gated approvals when user decisions are required

Primary directory (read-write)

.omc/conductor/
  conductor-state.json          # Index of all tracks (regenerable from track metadata)
  context/                      # Shared project context
    product.md
    tech-stack.md
    workflow.md
    styleguides/*.md
  tracks/
    <track-slug>/               # One directory per track
      metadata.json             # Track state, phase, git info, timestamps
      spec.md                   # Requirements specification
      plan.md                   # Phased implementation plan with task checkboxes
      review.md                 # Review verdict and evidence (created at review phase)
      research/                 # Optional: created when uncertainty is high
        state.json
        findings.md
  archive/                      # Completed or cancelled tracks moved here

External directory discovery (read-only import)

Conductor also scans for tracks created by other tools (e.g., Codex conductor) so that work can be continued across tools without manual copying.

Scan paths (checked in order during Setup/Resume):

1. .omc/conductor/tracks/ — primary, read-write
2. conductor/tracks/ — Codex conductor layout, read-only import

Discovery rules:

• On Setup/Resume, scan each path for subdirectories containing metadata.json or spec.md.
• Codex tracks use a slightly different metadata schema. Normalize on read:

• Codex tracks that have spec.md + plan.md but no metadata.json are also recognized — infer metadata from filenames and plan checkbox state.
• External tracks appear in status output with an [external] tag and their source path.
• External tracks are read-only by default. To work on an external track, conductor copies it into .omc/conductor/tracks/<slug>/ first (prompted via question).

Context fallback: If .omc/conductor/context/ is empty or missing during setup, also check:

• conductor/product.md → seed context/product.md
• conductor/tech-stack.md → seed context/tech-stack.md
• conductor/workflow.md → seed context/workflow.md
• conductor/code_styleguides/*.md → seed context/styleguides/*.md

conductor-state.json (index — regenerable from track metadata)

{
  "active": true,
  "activeTrack": "<track-slug>",
  "tracks": {
    "<track-slug>": {
      "slug": "<track-slug>",
      "title": "Human-readable title",
      "type": "feature",
      "status": "in_progress",
      "phase": "implementing",
      "source": "primary | external"
    }
  },
  "_meta": {
    "version": "2.0.0",
    "lastWriteAt": "ISO8601",
    "cwd": "/path/to/project"
  }
}

metadata.json (per-track — authoritative source of track state)

{
  "track_id": "<track-slug>",
  "title": "Human-readable title",
  "type": "feature | bugfix | tech-debt | hotfix",
  "status": "spec | planned | in_progress | review | done | cancelled",
  "phase": "setup | spec | planning | implementing | reviewing | complete",
  "description": "Short summary of the track goal",
  "supersedes": null,
  "blocked_by": null,
  "git_branch": "conductor/<track-slug>",
  "git_start_commit": "<sha>",
  "current_task_index": 0,
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "completed_at": null
}

State management rules

• metadata.json in each track is the authoritative source for that track's state.
• conductor-state.json is an index/cache that summarizes all tracks for quick lookup.
• If conductor-state.json is missing or stale, regenerate it from tracks/*/metadata.json.
• Track status transitions happen in metadata.json first, then sync to the index.

Conductor workflow operations (can be executed by skill protocol even if no dedicated slash command exists):

• implement <slug|active>
• refresh [scope]
• revert <slug>
• archive <slug>

2. Track Selection / Creation

   • If user provided slug/title, resolve it against tracks from all discovered paths (primary + external).
   • If the resolved track is external, ask user whether to import it into .omc/conductor/tracks/ before proceeding.
   • Else choose active track first, otherwise earliest non-complete track.
   • If no track exists, create one:
     • Generate URL-safe slug from title (e.g., payment-webhook-retry)
     • Create tracks/<slug>/metadata.json with initial phase spec
     • Create git branch conductor/<slug> from current HEAD
     • Update conductor-state.json index

3. Preflight Context

   • read in order: context docs → active spec → active plan → relevant code/config.
   • Output compact brief: goal, accepted constraints, current phase, next task, blockers.

4. Spec Generation (phase: spec)

   • Delegate to analyst for requirements structure.
   • Delegate to architect for system boundaries, risks, and acceptance criteria.
   • Persist to tracks/<slug>/spec.md.
   • Gate: present spec to user for approval via question before proceeding.
   • Update metadata.json status to planned only after approval.

5. Plan Generation (phase: planning)

   • Delegate to planner for phased tasks.
   • Plan must follow the phased task format (see Plan Format below).
   • Require testable acceptance criteria and explicit verification commands.
   • Persist to tracks/<slug>/plan.md.
   • Gate: present plan to user for approval via question before proceeding.
   • Optionally delegate to critic for plan review before user approval.

6. Implement (phase: implementing)

   • Execute tasks sequentially per plan phase via executor.
   • Before starting each task: update its checkbox from [ ] to [~] in plan.md.
   • After completing each task: update its checkbox from [~] to [x] in plan.md.
   • Run deterministic checks per task (lint/type/test/build as applicable).
   • After completing the last task of each phase: run phase verification protocol.
   • Update metadata.json field current_task_index as tasks progress.

7. Phase Verification (within implement)

   • After completing the last task of a phase:
     1. Announce phase completion and run automated checks.
     2. Prepare a manual verification checklist for user-visible behavior.
     3. Wait for explicit user feedback via question.
     4. Create a checkpoint commit when the phase is accepted.
     5. Record the checkpoint SHA in plan.md.
   • If verification fails: reopen relevant tasks, return to implement.

8. Review (phase: reviewing)

   • Use code-reviewer and verifier as default review pair.
   • Add security-reviewer when auth, secrets, trust-boundaries, or user input changed.
   • Compute git diff from git_start_commit..HEAD for the review scope.
   • Persist verdict to tracks/<slug>/review.md.

9. Reconcile / Close

   • If review fails, reopen tasks and return to implement.
   • If review passes, mark track complete and record concise evidence.
   • Update metadata.json: status: "done", phase: "complete", completed_at: ISO8601.
   • Optionally move completed track to archive/ via archive subcommand.

# Implementation Plan

## Phase 1: <Phase Title>

- [ ] Task: <task description>
  - [ ] <sub-step 1>
  - [ ] <sub-step 2>
  - [ ] Verify relevant tests pass

- [ ] Task: <task description>
  - [ ] <sub-step 1>
  - [ ] Verify relevant tests pass

- [ ] Task: Conductor - Phase Verification '<Phase Title>'

## Phase 2: <Phase Title>
...

Rules:

• Each phase groups related tasks that can be verified together.
• Tasks use [ ] (pending), [~] (in-progress), [x] (done) checkboxes.
• Each phase ends with a verification gate task.
• Tasks should be ~1-3 hours of work each.
• Sub-steps are optional but encouraged for complex tasks.

Trigger examples:

• External dependency behavior changed recently
• Two plausible architectural options with unclear tradeoffs
• Security/compliance requirement needs primary-source confirmation

Research protocol:

1. Decompose into 3-5 research stages.
2. Parallel execute stage analysis with scientist agents (max 5 concurrent).
3. Verify contradictions; output [VERIFIED] or [CONFLICTS:<list>].
4. Synthesize into a decision note appended to spec/plan.

Persist research artifacts inside the track directory:

• tracks/<slug>/research/state.json
• tracks/<slug>/research/findings.md

[FINDING:<id>] <title>
<analysis>
[/FINDING]

[EVIDENCE:<id>]
- Source: <url or file>
- Date: <YYYY-MM-DD>
- Relevance: <why it matters>
[/EVIDENCE]

[CONFIDENCE:HIGH|MEDIUM|LOW]
<brief rationale>

Quality gates:

• Every [FINDING] must include [EVIDENCE]
• Unsupported claims must be downgraded or removed
• Unresolved contradictions must remain explicit

Example:

## Conductor Status

**Active track:** payment-webhook-retry (feature)
**Phase:** implementing (3/4 phases done)
**Tasks:** 9/13 done, 1 in-progress, 3 pending
**Next:** Complete task "Add retry backoff logic" in Phase 4
**Blockers:** None
**Review:** Not yet started