Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Dev Environment Setup

Type: L2 Domain Coordinator Category: 0XX Shared

Runtime-backed coordinator for environment setup. The runtime is the execution SSOT. Worker outputs are standalone summaries, not chat prose.

MANDATORY READ

Load these before execution:

• references/coordinator_runtime_contract.md
• references/environment_setup_runtime_contract.md
• references/environment_worker_runtime_contract.md
• references/coordinator_summary_contract.md
• references/agent_skill_roots_contract.md
• references/environment_state_contract.md
• references/environment_state_schema.json

MCP servers are targets of this workflow, not a prerequisite for starting it. If a server is disconnected or unavailable, continue with file and CLI inspection and report that surface as disconnected or skipped instead of failing the coordinator.

When to Use

• First-time environment setup
• Agent/MCP drift after installs or updates
• Marketplace, plugin, MCP, or Codex execution-default drift across Claude and Codex
• Instruction file audit or repair

Inputs

Runtime

Runtime family: environment-setup-runtime

Identifier:

• targets-{normalizedTargets}

Phases:

1. PHASE_0_CONFIG
2. PHASE_1_ASSESS
3. PHASE_1B_PROVIDER_SELECTION
4. PHASE_2_DISPATCH_PLAN
5. PHASE_3_WORKER_EXECUTION
6. PHASE_4_VERIFY
7. PHASE_5_WRITE_ENV_STATE
8. PHASE_6_SELF_CHECK

Terminal phases:

• DONE
• PAUSED

Phase Map

Phase 1: Assess

Collect one environment snapshot:

• agent availability and versions
• MCP registration/connection state
• hook state
• marketplace/plugin alignment state
• Codex skill-root discovery health: active roots, cache roots, duplicate skill names, known_marketplaces.json install-location drift, whether cache is visible under ~/.codex/skills, whether ~/.codex/skills is a whole-root junction to ~/.claude/plugins, and whether approval_policy=never plus sandbox_mode=danger-full-access are already aligned
• graph provider dependency status: for each detected project language, check whether the corresponding graph provider binaries are installed (e.g. basedpyright for Python, csharp-ls for C#). Use mcp__hex-graph__install_graph_providers with mode: "check" if hex-graph MCP is connected
• graph index freshness: whether hex-graph is connected and the project has been indexed in this session (detection-only, no indexing here)
• instruction file state
• disabled flags from .hex-skills/environment_state.json if present
• task management provider availability detection (Linear MCP, gh CLI / Projects v2 readiness, file always available); explicit selection happens in Phase 1b
• research tool detection (Ref → Context7 → websearch)
• git worktree availability
• Claude Code IDE extension state: glob ~/.cursor/extensions/anthropic.claude-code-* and ~/.vscode/extensions/anthropic.claude-code-*. For each found, read claudeCode.initialPermissionMode and claudeCode.allowDangerouslySkipPermissions from the matching IDE user settings.json. Detection-only — no writes here.

Checkpoint payload:

• assess_summary

Phase 1b: Tracker Provider Selection

User selects the task tracker provider (linear, github, file). Selection is persisted in .hex-skills/environment_state.json -> task_management.provider and reused by every task-related skill (ln-200, ln-220, ln-300, ln-401, ln-130, etc.).

MANDATORY READ: Load references/tracker_provider_contract.md before this phase.

Codex exec --full-auto cannot prompt the user mid-run. Selection MUST go through runtime pause + pending_decision + record-decision (NOT AskUserQuestion).

Decision tree:

1. Load Phase 1 availability data and existing task_management from env state.
2. Compute available = filter([linear, github, file], byAvailability):
   • linear available iff Linear MCP server is connected.
   • github available iff gh auth status ok AND repository detected AND (no project_number yet, OR existing project has Status field with all 7 canonical options: Backlog, Todo, In Progress, To Review, To Rework, Done, Canceled).
   • file always available.
3. If task_management.provider is already set AND task_management.status == "active":

node references/scripts/environment-setup-runtime/cli.mjs pause \
  --identifier {identifier} \
  --reason "Confirm tracker provider" \
  --payload '{"kind":"tracker_provider_confirmation","question":"Keep current tracker {provider}?","choices":["keep","switch"],"resume_to_phase":"PHASE_1B_PROVIDER_SELECTION"}'

Resume with set-decision. On keep -> reuse existing provider. On switch -> fall through to step 4.

4. If no current provider OR user chose switch AND available.length > 1:

node references/scripts/environment-setup-runtime/cli.mjs pause \
  --identifier {identifier} \
  --reason "Select tracker provider" \
  --payload '{"kind":"tracker_provider_selection","choices":<available>,"resume_to_phase":"PHASE_1B_PROVIDER_SELECTION"}'

5. If available.length == 1, do NOT pause. Auto-select with selected_by: "single_option" and write the reason (e.g. "Only file mode available because: Linear MCP disconnected, gh CLI not authenticated").
6. Checkpoint Phase 1b:

node references/scripts/environment-setup-runtime/cli.mjs checkpoint \
  --identifier {identifier} \
  --phase PHASE_1B_PROVIDER_SELECTION \
  --payload '{"provider_selection":{"chosen":"<provider>","available":<available>,"reason":"<text>","selected_by":"user|single_option"}}'

Checkpoint payload:

• provider_selection.chosen
• provider_selection.available
• provider_selection.reason
• provider_selection.selected_by

Phase 2: Dispatch Plan

Build selective dispatch plan. Only invoke workers that have work.

Dispatch precedence:

• If marketplace/plugin drift, Codex discovery violation (including whole-root junction), or Codex execution-default drift is present, ln-013-config-syncer becomes mandatory before Codex can be reported as healthy.
• If hex-graph MCP is registered and either (a) graph provider deps are missing for detected project languages, or (b) the project has not been indexed, ln-012-mcp-configurator becomes mandatory even when MCP registration is already complete. ln-012 owns both graph provider dependency installation (PHASE_3) and graph indexing (PHASE_5).

Workers:

• ln-011-agent-installer
• ln-012-mcp-configurator
• ln-013-config-syncer
• ln-014-agent-instructions-manager

Standalone skills packaged in setup-environment but not dispatched by ln-010:

• ln-015-hex-line-uninstaller remains direct-invocation only because it removes existing Claude-side integration surfaces.

Checkpoint payload:

• dispatch_plan

Phase 3: Worker Execution

Invoke only selected workers. Do not re-probe the whole environment between worker calls.

Phase 1 assessment is the shared discovery snapshot. Materialize child manifests from that snapshot and pass them into managed worker runs.

For