project-env-manager

Project Env Manager

Overview

Use this skill to treat project-env.yaml as the only source of truth for workstation and Codex environment requirements in the repository. Read the contract, verify the current machine, report gaps before mutation, and keep the contract synchronized when team requirements change.

Inputs

• Read project-env.yaml at the repository root first.
• Load references/schema.md when field behavior, verify modes, or authoring rules need clarification.
• Do not require, create, or update AGENTS.md as part of this skill. This skill works directly from the YAML contract.

Workflow

1. Match The Platform

• Identify the current operating system and shell.
• Prefer a platforms[] entry whose match.os and match.shell both match.
• If no exact match exists, stop and ask the user to add a new platform block instead of guessing.

2. Verify Components

• Iterate components[] in the matched platform block.
• For verify.comparison: semver, run verify.command, extract the version with verify.output_regex, and compare it against the component version.
• For verify.comparison: exists, check that verify.path exists relative to the repository root.
• For verify.manual_check: true, report the component as a manual verification item. Do not invent a CLI check.
• Treat required: true items as blocking when missing or out of policy.

3. Report Before Mutation

• Summarize the matched platform, satisfied components, missing components, version mismatches, and manual-check items.
• Show exact install.command values for components that can be installed automatically.
• If a required component is missing and install.command is absent, stop and ask the user to provide a manual install step or update the contract.
• Do not install or reconfigure anything until the user explicitly confirms the proposed actions.

4. Execute Approved Install Steps

• Run only the approved install commands for the matched platform.
• After each install batch, rerun verification for the affected components.
• If verification still fails, report the exact failing step and stop instead of adding fallback logic.

5. Maintain The Contract

• When team requirements change, update project-env.yaml first and refresh updated_at in the same task.
• Keep project-env.yaml machine-oriented and concise. Keep all environment requirements in the YAML contract itself.
• Add helper scripts only after the same verification or install step has failed, or been hand-written, at least twice.

Authoring Rules

• Keep the fixed top-level keys: schema_version, updated_at, project, policy, and platforms.
• Keep every platform dependency inside one components[] list. Do not split runtimes, skills, plugins, and MCPs into separate structures.
• Use the supported component type values: runtime, shell, tool, skill, plugin, and mcp.
• Use repo-relative verify.path values for bundled skills or other files that should exist in the repository.
• If there is no reliable CLI verification path for a plugin or MCP, mark it as a manual check instead of guessing.
• Do not add AGENTS-level process wiring for this workflow. The skill should read and maintain project-env.yaml directly.

Expected Output

• For an audit request, return:
  • the matched platform
  • satisfied components
  • blocking required gaps
  • optional gaps
  • manual-check items
  • the install commands that would run after approval
• For a maintenance request, update the contract first, then summarize what changed and what now needs verification.

Example Triggers

• "Check this project's environment before we start."
• "Set up this repo on a new Windows laptop."
• "Node drifted off the required version. Audit the environment."
• "Add a required MCP to the project contract."
• "Sync the environment contract after we upgraded Codex."

Resources

• references/schema.md: field definitions, verify modes, version rules, and authoring conventions for project-env.yaml.