Skip to content

Repository navigation

Add Parameter.spec and deprecate human_readable_name - #3877

Merged
Rowlando13 merged 1 commit into
pallets:mainfrom
kdeldycke:param-naming-convention
Oct 4, 2026
Merged

Add Parameter.spec and deprecate human_readable_name#3877
Rowlando13 merged 1 commit into
pallets:mainfrom
kdeldycke:param-naming-convention

Conversation

@kdeldycke

@kdeldycke kdeldycke commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

This a follow up of #3821 , where I introduced a new Option.get_help_spec utility.

While discussing this change, I realized we had 3 aspects of a parameter for 3 different audiences:

  • decls: what the developer provide to its argument or option
  • spec: what the user see in --help and what it provide to the CLI
  • name: what is used internally in Click to identify that argument or option

And I just realize now that I can harmonize this vocabulary in the whole Click codebase with a small effort. This PR is that effort.

For illustration, here is the value of each property as taken from the documentation:

@click.argument('recipe') @click.option('-g', '--gluten-free/--no-gluten-free')
decls ('recipe',) ('-g', '--gluten-free/--no-gluten-free')
spec RECIPE --gluten-free
name recipe gluten_free
opts ['recipe'] ['-g', '--gluten-free']
secondary_opts [] ['--no-gluten-free']

The effects this PR has:

  • Rename Parameter.human_readable_name to Parameter.spec and deprecate the former
  • Make get_help_spec more generic by moving it from Option to Parameter
  • Document opts and opts

And as such targets 8.6.0.

I still did not pushed my luck too much by proposing a rename of the .name property into .id or .uid as in my original comment to keep this proposal reasonable. 😇

@kdeldycke kdeldycke added the parsing Parsing, parameters, commands, chaining, context label Sep 23, 2026
@kdeldycke kdeldycke added this to the 8.6.0 milestone Sep 23, 2026
@kdeldycke
kdeldycke force-pushed the param-naming-convention branch from 43cd853 to 9ccb32e Compare September 23, 2026 16:44
@kdeldycke
kdeldycke force-pushed the param-naming-convention branch from 9ccb32e to 9f0bcdf Compare September 23, 2026 16:52
@kdeldycke

kdeldycke commented Sep 23, 2026

Copy link
Copy Markdown
Collaborator Author

@janluke you might be interested by this change as it might help you get rid of the get_param_label you have in https://github.com/janLuke/cloup/blob/30c6ae0aca2414461e3b71096009958707b5686a/src/cloup/constraints/common.py#L57-L60

@Rowlando13
Rowlando13 merged commit 2247b35 into pallets:main Oct 4, 2026
12 checks passed
@janluke janluke mentioned this pull request Oct 4, 2026
Open
@kdeldycke
kdeldycke deleted the param-naming-convention branch October 5, 2026 05:25
johnpangalos pushed a commit to johnpangalos/skills that referenced this pull request Oct 8, 2026
@claude
feature-flow evals: harder tasks, stronger hidden checks, two judges,…
0635d78 
… lite trigger cases

Hidden checks now cover what round-3 judges found by hand: Hijack passing
through and Flush not bypassing the ETag buffer (chi); huge digit strings,
integer and negative timedelta defaults, and bounds shown in --help (click);
conflict errors naming only the flags passed (fd); and the new properties in
property-order.ts (Tailwind). Reference patches are updated to pass them.

Two harder tasks pin real repos just before an upstream change and use its
tests (renamed) as hidden checks: chi-mount-routes, a bug hunt for Walk and
Routes() dropping a handler that shares a Mount() pattern (go-chi/chi#830),
and click-param-spec, a cross-module feature adding Parameter.spec and
deprecating human_readable_name (pallets/click#3877). Both fail on the pinned
commit and pass with the upstream change.

judge.workflow.js takes judges: N per challenge to measure judge noise, and
feature-flow-lite gets the eight trigger cases, graded on its own skill name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV
johnpangalos added a commit to johnpangalos/skills that referenced this pull request Oct 8, 2026
@johnpangalos @claude
Add the feature-flow-lite skill (#2)
d1d718d 
* Add feature-flow skill with trigger and behavior evals

The skill is committed as written, as the version under test.

evals/triggers: claude plugin eval cases (4 should-fire, 4 near-miss) that
check whether the Skill tool picks feature-flow, on a scaffolded fixture repo.

evals/harness: headless claude -p runs per scenario and arm (skill, Opus
baseline, Sonnet solo), graded from the stream-json trace (roster models,
stage choice, handoff/result templates, checks before review, 2-round cap,
nested-verifier timing, depth refusals) plus hidden acceptance tests run
after the agent exits, and cost split per model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: raise trigger turn cap to 8

A bug-hunt prompt investigates for several turns before it reaches for the
skill, so a 4-turn cap counted a late invocation as a miss.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow: ship the roster as named agents

Each role is now an agent in feature-flow/agents/ with model, effort and
tools pinned in frontmatter, spawned as feature-flow:<agent>. A
.claude-plugin/plugin.json makes the skill folder a skills-directory
plugin, so a user-level install (npx skills add -g) loads the agents.

No agent has the Agent tool: the main conversation spawns the verifier
after the implementor returns, which works when nesting is off and
replaces the unconfirmed per-subagent effort hedge with frontmatter pins.
Risky diffs go to risky-reviewer (opus). Handoffs drop ROLE and RETURN,
which the agents carry. Without the agents the skill falls back to
general-purpose spawns with per-call model and effort.

Harness: the skill arm loads via --plugin-dir; a skill-v0 arm runs the
first committed version from a git ref; the grader maps roles from agent
types and reads each subagent's real model from its own messages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: greenfield challenges and blind-judging prep

Three greenfield scenarios on an empty repo, one per language: a bookshop
website (plain HTML/CSS/JS), a bookmarks REST API in Go, and an expense CLI
in Rust. Each has a fixed contract and hidden black-box checks: static and
headless-render checks for the site, HTTP contract and concurrency checks
for the API, exit-code and output checks for the CLI.

prepare_blind.py copies a batch's workspaces into shuffled, anonymized
folders (plus site screenshots) and keeps the letter-to-arm mapping in the
batch directory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: count inputs wrapped in <label> as labelled

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: blind-judging workflow and greenfield scenario docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow v2, feature-flow-lite, and a Tailwind CSS challenge

Skill changes from the benchmark:
- small work takes a direct path (Opus builds, a reviewer checks) instead
  of the full pipeline; every path ends with a reviewer
- the main conversation writes acceptance criteria once, including implied
  requirements and how they combine, and every handoff carries them
- reviewers work through a per-project checklist and reproduce edge cases
- spec numbers are floors; new projects get a README
- the investigator is optional on new or small repos; the stage
  announcement rule is gone
- the description covers bug hunts

feature-flow-lite is the same flow with only the four core roles
(investigator, implementor, simplifier, reviewer).

Harness: repo fixtures via a setup script, a Tailwind CSS anchor
positioning scenario with hidden vitest checks plus the full package suite,
type, Prettier and changelog checks, and skill-v1 and lite arms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: multi-batch blind prep with diffs, library judging lens

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: retry the Tailwind package suite once

A permutation-heavy upstream test times out under parallel load; it passes
alone in every workspace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: split cost by main thread and subagents

threads.py prices each run's per-message usage by thread, with output
tokens taken from per-model totals (streamed events only snapshot output
at message start), and estimates the follow-up cost of the main thread's
final context with a warm and a cold cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: arms that pin every agent to one model and effort

skill-haiku and lite-haiku rewrite the agents' frontmatter in a temp copy
to haiku at high effort; the roster check accepts the pinned model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: report speed alongside the cost split

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: flag runs that end with subagents still running

Two headless runs exited after the main thread's turn while a background
implementor was still working; the grader now fails a setup check on that
so such runs get re-run instead of scored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: flag runs with no result event; skip them in the cost split

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: judging uses fresh scratch folders and can reuse reports

Inspectors and judges copied builds to fixed /tmp paths; a path left over
from an earlier round made cp nest the new build inside the old one. Each
copy now clears its folder first. A challenge can also carry reports from an
earlier run so only some builds are re-inspected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: brownfield feature tasks in chi, click and fd; write-once and Sonnet+planner arms

Three new scenarios clone a popular repo at a pinned commit and ask for a
feature that doesn't exist there yet: an ETag middleware in go-chi/chi, a
Duration parameter type in pallets/click, and a --count option in sharkdp/fd.
Each has hidden behavior tests that probe past the spec plus the repo's own
suite, lint, type, format and docs/changelog checks, validated against a
reference patch (fail on the untouched repo, pass on the reference).

Arms can now lay a variant's files over the skill (variants/<name>/):
write-once rewrites the lite implementor to plan first and run checks once,
and sonnet-planner runs the main session on Sonnet with an Opus planner agent
that writes the plan and acceptance criteria.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: judge feature changes in existing repos with per-challenge probes

The judge workflow takes a 'feature' kind and an optional probe text per
challenge, and words the inspection and calibration for a change a
maintainer would merge. Blind copies drop virtualenvs, whose scripts point
back at the original workspace. Setup no longer prints go's module notice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: recognize go, cargo, vitest, mypy and prettier runs as checks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: document the feature scenarios, variants and new arms

Round 3 ran four arms on the four feature tasks (tailwind, chi, click, fd);
results are in the benchmark artifact. The README now lists the feature
scenarios and how they're set up, the variant overlay and pinned-agent arm
options, and how to judge changes in existing repos.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow-lite: Haiku agents, write-once implementor, conventions as criteria, targeted tests

Ship what three benchmark rounds support. Lite with Haiku subagents beat
plain Opus on quality in every round at about the same cost, and a Haiku
implementor at medium effort that plans first and checks once was faster
with no measurable quality loss. So lite's agents move to Haiku (medium; the
investigator low), the implementor writes each file once and runs only the
tests for what it touched while it works, and the orchestrator runs the full
suite once per round. In an existing repo, the acceptance criteria now list
the repo's conventions for the change (changelog, docs, man page,
completions, README tables), which only the Opus-planner arm found before.

feature-flow's direct path, where Opus built and fixed small work itself,
cost the most of any setup. It becomes a short path: implementor, checks,
reviewer, fix loop. The README now recommends lite for most feature work.

The harness pins the round-3 arms to the commit before this change, can load
a skill folder at a ref, pin single agents (agents.only), and adds the
round-4 arms: lite-v2, lite-v2-impl-low and lite-v2-parallel (reviewer runs
alongside the checks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: harder tasks, stronger hidden checks, two judges, lite trigger cases

Hidden checks now cover what round-3 judges found by hand: Hijack passing
through and Flush not bypassing the ETag buffer (chi); huge digit strings,
integer and negative timedelta defaults, and bounds shown in --help (click);
conflict errors naming only the flags passed (fd); and the new properties in
property-order.ts (Tailwind). Reference patches are updated to pass them.

Two harder tasks pin real repos just before an upstream change and use its
tests (renamed) as hidden checks: chi-mount-routes, a bug hunt for Walk and
Routes() dropping a handler that shares a Mount() pattern (go-chi/chi#830),
and click-param-spec, a cross-module feature adding Parameter.spec and
deprecating human_readable_name (pallets/click#3877). Both fail on the pinned
commit and pass with the upstream change.

judge.workflow.js takes judges: N per challenge to measure judge noise, and
feature-flow-lite gets the eight trigger cases, graded on its own skill name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: document round-4 tasks, arms and multiple judges

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: record the first lite trigger-eval result

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* feature-flow evals: summarize the four benchmark rounds

Round 4 ran plain Opus, the shipped lite, and two speed variants on six
tasks in real repos, three builds each, with two judges per task. Lite
stayed ahead (7.9 against 7.7) at the same cost, found the repo's
unprompted conventions 5 of 6 times against 2, and now takes 5.7 minutes.
A low-effort implementor lost 0.3 points and a background reviewer saved
no time, so neither ships.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

* Ship feature-flow-lite only; move the benchmark to its own branch

This PR now carries just the feature-flow-lite skill (SKILL.md, four
agents, plugin manifest) and the README entry for it. The full
feature-flow skill is dropped: four benchmark rounds found lite matched or
beat it on quality for less money. The eval harness, hidden checks,
fixtures and trigger cases move to a separate branch so this change stays
reviewable; the full skill stays in this branch's history, where the
benchmark loads it by commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0152WPegBR4cQkwpouQxbjKV

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Rowlando13 Rowlando13 Rowlando13 approved these changes
@davidism davidism Awaiting requested review from davidism
@janluke janluke Awaiting requested review from janluke

Assignees

No one assigned

Labels

parsing Parsing, parameters, commands, chaining, context

Projects

None yet

Milestone

8.6.0

Development

Successfully merging this pull request may close these issues.

2 participants

@kdeldycke @Rowlando13