levnikolaevich/ln-011-agent-installer

Paths: File paths (shared/, references/) are relative to skills repo root. Locate this SKILL.md directory and go up one level for repo root.

Agent Installer

Type: L3 Worker Category: 0XX Shared

Installs or updates the two supported CLI agents: Codex CLI and Claude Code. Single pass per agent: install then immediately verify.

MANDATORY READ: Load shared/references/coordinator_summary_contract.md, shared/references/environment_worker_runtime_contract.md, and shared/references/worker_runtime_contract.md

---

Input / Output

| Direction | Content | |-----------|----------| | Input | OS info, disabled flags per agent, dry_run flag, optional runId, optional summaryArtifactPath | | Output | Structured summary envelope with payload.status = completed / skipped / error, plus per-agent install outcomes in changes / detail |

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and remain fully standalone. If runId is not provided, generate a standalone run_id before emitting the summary envelope.

Runtime

Runtime family: environment-worker-runtime

Phase profile:

1. PHASE_0_CONFIG
2. PHASE_1_INSTALL_VERIFY
3. PHASE_2_POST_CODEX_SANITY_CHECK
4. PHASE_3_WRITE_SUMMARY
5. PHASE_4_SELF_CHECK

Runtime rules:

• emit summary_kind=env-agent-install
• standalone runs generate their own run_id and write the default worker-family artifact path
• managed runs require both runId and summaryArtifactPath and must write the summary to the exact provided path
• always write the validated summary artifact before terminal outcome

Output Contract

Always build a structured env-agent-install summary envelope per:

• shared/references/coordinator_summary_contract.md
• shared/references/environment_worker_runtime_contract.md

Payload fields:

• targets
• agents_processed
• agents_skipped
• versions
• codex_drift_detected
• status

---

Agent Registry

| Agent | Install Command | Health Check | Interactive | |-------|----------------|--------------|-------------| | Codex | npm i -g @openai/codex | codex --version | codex or codex "prompt" | | Claude | npm i -g @anthropic-ai/claude-code or claude update | claude --version | claude or claude "prompt" |

Automation uses:

• Codex: codex exec ...
• Claude: claude -p ...

Note: codex / codex "prompt" are interactive TTY entrypoints. Non-interactive validation and review automation must use codex exec ..., because Codex rejects direct interactive mode when stdin is not a terminal.

---

Workflow

For each enabled agent: Install or Update -> Verify -> Record

Phase 1: Install & Verify

For each agent in registry, apply first matching rule:

| Condition | Action | Report | |-----------|--------|--------| | disabled: true | SKIP | disabled by user | | dry_run: true | Show planned command | dry run | | Codex | npm install -g @openai/codex then codex --version | version or error | | Claude installed | claude update then claude --version | version or error | | Claude missing | npm install -g @anthropic-ai/claude-code then claude --version | version or error |

Single pass: install and verify happen atomically per agent. No separate scan phase; the install result is the state.

Error handling:

| Error | Detection | Response | |-------|-----------|----------| | npm not in PATH | npm --version fails | FAIL gracefully, report npm not found in PATH | | Permission denied | stderr contains EACCES | FAIL, suggest npm install -g --prefix ~/.local {pkg} | | Network error | stderr contains ETIMEDOUT or ENETUNREACH | FAIL, report network error | | Unknown error | Any other non-zero exit | FAIL, include stderr |

Output table:

Agent Installation:
| Agent  | Action    | Version  | Status |
|--------|-----------|----------|--------|
| Codex  | installed | 0.124.0  | ok     |
| Claude | updated   | 2.1.119  | ok     |

Phase 2: Post-Install Codex Sanity Check

After successful Codex install/update:

1. Check ~/.codex/config.toml top-level approval_policy and sandbox_mode.
2. Check configured Codex marketplaces for duplicate active paths to this repo.
3. If drift is found, report a WARN and defer remediation to ln-013-config-syncer.

This installer does not install marketplace plugins, rewrite Codex marketplace layout, or manage Codex execution defaults. It only reports drift so install success is not mistaken for a healthy two-agent environment.

---

Critical Rules

1. Never modify disabled flags. Respect them, never change them.
2. Fail gracefully. One agent failure does not block the other.
3. Global install only. CLI tools must be in PATH.
4. Report all changes. Include config observations in the final summary table.
5. Idempotent. Safe to run multiple times.
6. Claude and Codex only. Do not add unrelated agent branches.
7. Codex marketplace/plugin and execution-default remediation belongs to ln-013. This skill may detect drift, but must not rewrite marketplace/cache layout or Codex top-level permission defaults itself.

Anti-Patterns

| DON'T | DO | |-------|-----| | Separate check/install/verify phases | Single pass: install then verify | | Retry failed installs automatically | One attempt, report failure | | Use sudo npm install | Suggest --prefix for permission issues | | Install agents marked disabled | Skip with clear report | | Configure MCP settings or marketplace plugins here | Route environment alignment to ln-013-config-syncer |

---

Definition of Done

• [ ] Codex and Claude processed in single pass (install + verify)
• [ ] Disabled agents skipped with report
• [ ] Version verified immediately after each install
• [ ] Codex marketplace/plugin and execution-default sanity checked or explicitly reported for ln-013 follow-up
• [ ] Status table displayed
• [ ] Structured summary returned
• [ ] Summary artifact written to the managed or standalone runtime path

---

Version: 1.1.0 Last Updated: 2026-03-23