Align Recipe pyproject.toml

Dry-run (read-only report — start here)

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python .agents/skills/align-recipe-pyproject/scripts/align_pyproject.py \
  --recipe-dir <RECIPE_DIR> --dry-run

Output: JSON on stdout. Every check produces one entry with id, status (ok / would_fix / needs_input / report_only / error), a human-readable message, and structured details. Exit code is always 0 in dry-run.

Apply (rewrite files)

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python .agents/skills/align-recipe-pyproject/scripts/align_pyproject.py \
  --recipe-dir <RECIPE_DIR>

Fixes everything the script can safely fix. Exits 0 if nothing is left unresolved, 1 otherwise (typically because description-matches-manifest needs --description-source or build-system-present needs a human).

Apply with description resolution

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python .agents/skills/align-recipe-pyproject/scripts/align_pyproject.py \
  --recipe-dir <RECIPE_DIR> --description-source={pyproject|manifest|delete}

Preview a description resolution (dry-run + --description-source)

--description-source combines with --dry-run: the script reports the would_fix outcome of the chosen resolution without writing any files. Use this to show the user exactly what a given choice will do before you apply it — the two flags are not mutually exclusive.

uv run --no-project --with tomlkit --with 'ruamel.yaml' --with packaging \
  python .agents/skills/align-recipe-pyproject/scripts/align_pyproject.py \
  --recipe-dir <RECIPE_DIR> --dry-run \
  --description-source={pyproject|manifest|delete}

Respond

Filter the report to checks with status != "ok". Never list what's fine — the user is here to see what needs doing.

If everything passed

Reply with a single line, no table, no bullets. Something like:

✓ <RECIPE_DIR>'s pyproject.toml is fully aligned with the repo standard. No changes needed.

Then stop. Do not run any further tools.

If there are things to report

Name the recipe directory once, then render a single Markdown table with these three columns:

• Rule — the check id, in backticks (e.g. `no-local-ruff-config`).
• Status — the raw status value (would_fix, fixed, needs_input, report_only, error). Do not add emoji unless the user has asked for them.
• Details — a compact summary of both what's wrong and what will happen (or what the user must do), merged into one cell so the table stays 3 columns wide. Quote from → to values from details when present.

Include exactly one row per non-ok check. Do not include ok rows.

Status-specific guidance for what to put in the Details cell:

• would_fix (dry-run) — describe the current-state problem, then say what apply would do. Include the from → to or the list of tables to be removed.
• fixed (apply) — one-liner confirming the change (new value or list of removed tables).
• needs_input (only description-matches-manifest) — the Details cell says something like "descriptions differ — needs --description-source={pyproject,manifest,delete}". Do not put the two long descriptions inside the table. See "Follow-up content" below.
• report_only (four rules can hit this: build-system-present, default-pypi-index when a non-PyPI default is declared, stale-python-version-refs, and runnability-test-in-testpaths) — the Details cell names what's missing or non-conforming (e.g. "[build-system] missing; recipe cannot be built as a package" or "default index is TestPyPI, not public PyPI"). Follow-up content goes below the table (see next section).
• error — the Details cell shows the message verbatim; if it's very long, truncate with … and put the full text below.

Follow-up content below the table

Only for statuses that need extra context. Order: table first, then this content, then closing action.

• needs_input follow-up — present pyproject_description and manifest_description from details side by side (a small nested table works well), then ask the user to pick one of pyproject, manifest, or delete. Do not re-run until they answer.

• report_only follow-up — explain the impact (recipe cannot be built as a package) and paste both templates so the user can choose:

  # Hatchling (traditional Python packaging)
  [build-system]
  requires = ["hatchling"]
  build-backend = "hatchling.build"
  
  [tool.hatch.build.targets.wheel]
  packages = ["app"]
  
  # ---- OR ----
  
  # uv_build (Astral's uv-native backend)
  [build-system]
  requires = ["uv_build>=0.8.14,<0.9.0"]
  build-backend = "uv_build"
  
  [tool.uv.build-backend]
  module-root = ""
  module-name = "app"

• error follow-up — if the message was truncated in the table, print it verbatim in full below. Do not attempt to work around it.

Closing action

• Dry-run with at least one would_fix row — offer to apply the fixes yourself. Do NOT paste the raw command as a copy-and-paste snippet for the user. Instead ask something like "Want me to apply these fixes?" (a yes/no question is fine; a question with clear options is nicer UX). If the user agrees, run apply mode yourself and render the result as another table (with fixed rows instead of would_fix). If the user declines, stop.

• Dry-run with only needs_input for description-matches-manifest — after the table, show the two descriptions side by side and ask the user to pick one of pyproject, manifest, or delete. When they choose, run apply yourself with --description-source=<their choice> and render the resulting table. Do not offer generic "apply" — the flag is required.

• Dry-run with only report_only (and no would_fix rows) — after the table, address the specific case:

  • build-system-present: show the two [build-system] template snippets and stop. This is a manual edit; the skill does not auto-fix it.
  • default-pypi-index: quote details.current_url, explain that this is not public PyPI, and ask whether it's intentional. If not, tell the user to change the URL to https://pypi.org/simple/. Do not auto-rewrite.
  • stale-python-version-refs: list details.files, executable files first, and offer to update them.
  • runnability-test-in-testpaths: quote details.testpaths and suggest adding "tests".

• Dry-run with only error rows — do not offer to apply. Errors mean the script bailed before it could compute a fix; the user has to resolve the underlying issue first.

• Dry-run with a mix (e.g. some would_fix + a needs_input) — offer to apply the fixable ones. The apply run will fix those and leave the others as-is; render the resulting table and then address the remaining statuses per the rules above.

• Apply mode with any fixed row — end with the "Next steps" reminder (see below).

Do NOT commit any changes yourself. Ever.

After apply mode

If any check has status: fixed, remind the user:

Next steps:
  cd <RECIPE_DIR> && uv sync    # if dependencies changed
  git diff                       # review the edits before committing

Then stop. Do not commit. Do not run any further tools. End your turn.