easy-cheese: Instructions file for Codex

Agent Instructions for easy-cheese

This document is for LLMs, agents, and automation tools working in this repository.

Tenets

The easy-cheese tenets and the owner's rulings live in one page: the easy-cheese manifesto. Read it before you change a workflow, the role of a skill, or a contract between skills.

Single Quality Gate: just check

Always run just check before declaring work done — before any commit, push, PR open, or hand-off. Treat green from just check as the only signal that a change is shippable.

just check autofixes lint (markdown, yaml, python via ruff) and runs the full local build: skill frontmatter validation (validate_skills.py), the Wedge archive build, python + bash test suites, and mkdocs build --strict. CI runs just ci (same checks, no autofixes).

just check

Do NOT commit or push when just check fails. If CI fails, pull the branch locally, run just check, commit the autofixes, and push.

Prerequisites

• just — recipe runner
• uv — lint-py-fix invokes uvx ruff (no global ruff install needed)
• yamllint, yamlfmt, markdownlint-cli2, bats — see README for install hints

Skills in this repo

This is a skills-only collection following the Agent Skills spec. Every change either adds, edits, or supports a skill under skills/<name>/.

Skill Python bundle doctrine

This is the target contract. Existing violations are migration work; do not expand them while enforcement is implemented separately.

• A skill that executes Python ships exactly one executable archive at skills/<skill>/scripts/<skill>.pyz, built by Wedge from skills/<skill>/wedge.toml over the shared skills/wedge.toml; a skill with no Python ships no archive. Skill prose invokes only its own archive.
• Runtime Python lives under src/. Tests remain under tests/; repository build, release, generation, and maintenance programs may live under scripts/.
• Published schemas live in src/easy_cheese_schemas/. All non-published runtime code lives under src/easy_cheese/, split between skills/<python_skill_name>/, shared/, and cli/. Skill slugs remain kebab-case; Python package segments use underscores.
• cli/ holds command surfaces only; it may import shared/ and schemas. shared/ code must not import cli/.
• Archives may contain Python modules, bytecode, and immutable package resources. Dependencies must be pure Python and zip-importable. Native extensions, platform-specific libraries, required external executables, runtime package installation, and caller-managed extraction are prohibited.
• Each archive contains its own skill package and immutable resources, the shared and CLI support it uses, published schemas, and the pure-Python dependency closure pinned by uv.lock. It dispatches only its own skill's COMMANDS. Runtime use performs no archive download, loader lookup, or sidecar-lock verification. Shiv's transparent cache extraction remains part of the archive runtime; caller-managed extraction is prohibited.
• Wedge is a build-time dependency only. main tracks no archive: just wedge-build writes them as ignored build output, and just test builds them before any suite executes one. Hand-written Python never lives under skills/; archive metadata remains in wedge.toml.
• dist is the default branch and the published tree. Each publish dist run (push to main, hourly schedule, or manual dispatch) builds the archives from the main tip and appends one commit that holds the full main tree plus those archives. scripts/publish_dist.py only fast-forwards dist. A source older than the last published one is a no-op (superseded). A source that diverges from it is refused. A dist tip without a Source-Commit trailer is published over with a warning. Branch from main and target main; never push to or branch from dist.