Skip to content

[Commands API interface consistency] Replace adding-a-redis-command with extend-commands-api skill - #3872

Merged
uglide merged 4 commits into
mainfrom
im/replace-adding-command-skill-with-extend-skill
Aug 6, 2026
Merged

uglide merged 4 commits into
mainfrom
im/replace-adding-command-skill-with-extend-skill

Conversation

@uglide

@uglide uglide commented Jul 30, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Reworks the agent skill for adding/extending Redis commands into extend-commands-api, aligned with the workflow of the Jedis skill of the same name. The old adding-a-redis-command skill documented the wiring mechanics; the new skill wraps those mechanics in an evidence-first workflow: gather the HLD and the redis/redis server PR, verify the command live against the Dockerized test environment with redis-cli probes and showcase scenarios, present a plan (including the sync signatures as the API contract) for explicit approval, then implement across all API flavors with tests.

Key Decisions & Assumptions

  • Rules were validated against nine historical command PRs (INCREX, HOTKEYS, CAS/CAD, XNACK, BITOP, HSCAN NOVALUES, …), which are cited as reference traces in the skill.
  • Validation surfaced conventions the old skill missed, now documented: the ReadOnlyCommands registry for read-only commands, ComplexOutput + *ReplyParser for map-shaped replies, bumping the .env.vX.XX image pin when a feature needs a newer server, and a warning not to recreate the removed generator source files old PRs touched.
  • Unlike Jedis, module areas (Search/JSON/Bloom) are documented as full citizens with all six interface flavors.
  • The old skill's ⛔ sync-interface review checkpoint is folded into plan-mode approval.

Behavioral / Conceptual Changes

  • .agents/skills/adding-a-redis-command/ is removed; AGENTS.md and .agents/docs/architecture.md now point to extend-commands-api.
  • Agents are expected to probe a running server (ports 6479 / 16379) before designing the API, and to stop for plan approval instead of a mid-implementation checkpoint.

🤖 Generated with Claude Code


Note

Low Risk
Documentation and agent-skill wiring only; no runtime or public Java API changes.

Overview
Replaces the adding-a-redis-command agent skill with extend-commands-api, aligned with the Jedis workflow of the same name. AGENTS.md, .agents/docs/architecture.md, and the .claude/skills symlink now point at the new skill; the old skill directory is removed.

The new skill keeps the full implementation matrix (types → sync contract → all flavors → builder/dispatch → tests) but wraps it in an evidence-first process: HLD, owning-repo server PR (gh), live redis-cli checks against the Docker test env (6479 / 16379), and redis-cli showcase transcripts before API design. Plan-mode approval (sync signatures as the contract) replaces the old mid-flow ⛔ sync-interface checkpoint.

It also documents gaps the prior skill skipped: decision tree for args-only vs new commands vs module areas, ReadOnlyCommands, ComplexOutput parsers, .env image bumps, docs/new-features.md, overload rules (List<K> + *Args, varargs + single-arg), a warning not to recreate removed generator test sources, and module areas as full six-flavor citizens.

Reviewed by Cursor Bugbot for commit 20c3c66. Bugbot is set up for automated code reviews on this repo. Configure here.

@uglide uglide changed the title Replace adding-a-redis-command with extend-commands-api skill [Commands API interface consistency] Replace adding-a-redis-command with extend-commands-api skill Jul 30, 2026
@uglide
uglide requested a review from a-TODO-rov July 30, 2026 14:16

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4da0c9c66

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from c4da0c9 to 460b614 Compare July 30, 2026 15:01

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 460b614c9e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +343 to +347
After mirroring, run:

```bash
mvn -Dtest='*ConsistencyUnitTests,CommandBuilderCoverageUnitTests' \
-Dsurefire.failIfNoSpecifiedTests=false test

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Link to the consistency owner instead of copying it

The root guidance assigns API-consistency mechanics and tests to .agents/docs/api-consistency.md and requires skills to link to owner files rather than restating their contents, but this section copies the Maven invocation, deviation-registry ownership, and failure-handling rules. This creates a second source of truth that can drift whenever the consistency procedure changes; retain only the workflow sequencing here and link to the owner document for these mechanics.

AGENTS.md reference: AGENTS.md:L27-L35

Useful? React with 👍 / 👎.

Comment on lines +272 to +273
8. **Cluster** — pick the routing shape deliberately; there are three cases:
- A **single-key** command flows through automatically (routed by slot).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add the keyless routed cluster case

When adding a keyless RediSearch command, none of these three cases applies: existing FT.* methods override both advanced-cluster implementations and call routeKeyless so execution selects a node while honoring read/write intent and ReadFrom. Following this matrix would leave the new method on the default writer, producing different cluster routing behavior; add a fourth keyless-routed case referencing those overrides.

Useful? React with 👍 / 👎.

Comment on lines +82 to +84
redis-cli -p 6479 INFO server | grep redis_version
redis-cli -p 6479 COMMAND INFO <COMMAND> # non-empty → command exists
redis-cli -p 6479 COMMAND DOCS <COMMAND> # arity/args — compare with the server PR

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Probe module commands on the stack port

For an FT.*, JSON.*, or BF.* task, the preceding text correctly selects the stack node on port 16379, but every command in this probe block still connects to the standalone node on 6479. The probe can therefore falsely report that a module command is missing and send the workflow into the image-repin fallback; use port 16379 for module probes and showcase invocations.

Useful? React with 👍 / 👎.

Comment on lines +378 to +380
4. **Integration tests**: add methods to the sync base class
(`<Group>CommandIntegrationTests`), gated per-test with
`@EnabledOnCommand("<NAME>")`. Use assertions derived from the redis-cli

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Gate option-extension tests on the feature

When the task extends an existing command with a new option, @EnabledOnCommand("<NAME>") is true on older supported Redis versions because the base command already exists. In the inspected integration matrix (.github/workflows/integration.yml, Redis 7.2 through 8.10), the new-option test will then run against versions that reject the syntax instead of being skipped; instruct authors to gate on a newly introduced capability probe when available or use RedisConditions to assume the first supporting version.

Useful? React with 👍 / 👎.

Comment on lines +234 to +236
4. **Protocol enums** — command name in
`src/main/java/io/lettuce/core/protocol/CommandType.java` (wire bytes derive
from the enum name); subcommand tokens in `CommandKeyword`. **Never add a

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Encode dotted module command names explicitly

For a new module command such as FT.PROFILE or JSON.DEBUG, the wire bytes do not derive correctly from a Java enum constant such as FT_PROFILE: the no-argument CommandType constructor sends the literal underscore form. Existing module constants use an explicit value such as FT_CREATE("FT.CREATE"); document that dotted command families must use this constructor or the generated client will send an unknown command.

Useful? React with 👍 / 👎.

Comment on lines +302 to +304
- Create the flavor interfaces by mirroring an existing area end-to-end, register
the group in the `CommandInterfaces` enum
(`src/test/java/io/lettuce/core/api/consistency/`), and wire the group into the

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Register new area builders in the coverage mapping

When branch D creates a command area with its own builder, adding only the enum entry leaves CommandInterfaces.commandBuilderClassName() on its default RedisCommandBuilder mapping. CommandBuilderCoverageUnitTests will consequently inspect the wrong builder and report the new interface methods as missing; the new group must also add a switch case returning its Redis<Area>CommandBuilder class name.

Useful? React with 👍 / 👎.

Comment on lines +267 to +270
7. **Kotlin impl** —
`src/main/kotlin/io/lettuce/core/api/coroutines/<Group>CoroutinesCommandsImpl.kt`:
```kotlin
override suspend fun strlen(key: K): Long = ops.strlen(key).awaitSingle()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve nullable Kotlin command results

The showcased Kotlin implementation is not the repository's actual mapping for strlen: RedisStringCoroutinesCommandsImpl.strlen returns Long? and uses awaitFirstOrNull(). For commands whose reactive publisher completes empty on a nil reply, copying this awaitSingle() pattern throws instead of returning null; this is especially easy to miss because KotlinCoroutinesConsistencyUnitTests explicitly does not verify scalar nullability. Instruct authors to derive nullability from the reply contract and use awaitFirstOrNull() for nullable results.

Useful? React with 👍 / 👎.

Comment on lines +64 to +66
the reactive `Mono`/`Flux` mapping), error conditions, and the **first server
version carrying the feature** (drives `@EnabledOnCommand` gating and the test
env version). Note whether the server marks the feature *experimental/preview*.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Carry experimental status into the public API

The evidence phase records whether the server feature is experimental or preview, but no later matrix or checklist consumes that information. Existing preview command APIs such as HOTKEYS and the Array commands apply Lettuce's @Experimental annotation across their public interface flavors; without an explicit step, a newly added preview feature can be exposed as a stable API contract even though its server syntax or semantics may still change.

Useful? React with 👍 / 👎.

[writing-javadoc](../writing-javadoc/SKILL.md) skill; `@since` mandatory):
```java
/**
* Returns the length of the string value stored at {@code key}.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Use imperative wording in the API example

The sample sync-interface Javadoc starts with “Returns,” while Lettuce's public-command Javadoc convention requires method summaries to begin with an imperative verb, here “Return.” Because this is the template agents are told to present for API approval and mirror to every flavor, correct the example rather than propagating nonconforming Javadoc across six interfaces.

AGENTS.md reference: AGENTS.md:L153-L154

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c74b28b846

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

```kotlin
override suspend fun strlen(key: K): Long = ops.strlen(key).awaitSingle()
```
8. **Cluster** — pick the routing shape deliberately; there are three cases:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Handle multi-key cluster routing explicitly

When a new command accepts multiple keys, this three-case matrix has no applicable routing path. Lettuce's decomposable cross-slot commands are not ordinary single-key routing or all-shards broadcasts: for example, RedisAdvancedClusterAsyncCommandsImpl.mget(Iterable) (lines 414–443) partitions keys with SlotHash and restores their original order, while commands such as del use different aggregation semantics. Following the current matrix can therefore leave a new decomposable command dispatched as one server command, causing cross-slot inputs to fail rather than receive Lettuce's scatter/gather behavior. Add distinct cases for atomic same-slot multi-key commands and decomposable cross-slot commands.

AGENTS.md reference: AGENTS.md:L89-L93

Useful? React with 👍 / 👎.

Comment on lines +331 to +336
- Create the flavor interfaces by mirroring an existing area end-to-end, register
the group in the `CommandInterfaces` enum
(`src/test/java/io/lettuce/core/api/consistency/`), and wire the group into the
hand-written aggregate interfaces (`RedisCommands`, `RedisAsyncCommands`,
`RedisReactiveCommands`, and the cluster variants) so they `extend` it — the
consistency tests enforce the aggregate wiring.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Wire new groups into the Kotlin aggregates

When branch D creates a command group, this aggregate list omits both RedisCoroutinesCommands and RedisClusterCoroutinesCommands, as well as the delegation from RedisCoroutinesCommandsImpl to the new group implementation. The Kotlin consistency test explicitly requires every registered group to be inherited by the applicable coroutine aggregates (KotlinCoroutinesConsistencyUnitTests, lines 68–86); merely creating the per-group coroutine interface and implementation therefore leaves the standard coroutine API incomplete and fails the consistency suite. Add the Kotlin aggregate interfaces and implementation delegate to this wiring step.

AGENTS.md reference: AGENTS.md:L89-L93

Useful? React with 👍 / 👎.

Comment on lines +255 to +259
3. **Mirror to every flavor**: async, reactive, Kotlin coroutines, and the two
cluster node-selection interfaces (`NodeSelection<Group>Commands` /
`NodeSelection<Group>AsyncCommands`), applying the per-flavor return-type
mapping rules from
[.agents/docs/api-consistency.md](../../../.agents/docs/api-consistency.md).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the Sentinel-specific command path

When the requested command belongs to Redis Sentinel, mirroring it to both node-selection interfaces and the generic dispatch classes is incorrect. CommandInterfaces.SENTINEL has no node-selection flavors, its public interfaces live under core/sentinel/api, and execution is implemented by RedisSentinelAsyncCommandsImpl and RedisSentinelReactiveCommandsImpl rather than the two generic abstract classes. Following this matrix would therefore create an unsupported node-selection surface or leave the command unavailable from StatefulRedisSentinelConnection; retain the previous no-node-selection exception and add a Sentinel-specific dispatch path.

AGENTS.md reference: AGENTS.md:L76-L77

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 766126505f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

`src/main/java/io/lettuce/core/protocol/CommandKeyword.java`.
- If the reply shape grows, extend the response model/output backward-compatibly.

**B. New command(s) in an existing group — core or module area** — the FULL

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add a Pub/Sub-specific command path

When the requested Redis command is a subscription command, such as a future SUBSCRIBE variant, neither this core/module path nor branch D applies: Pub/Sub exposes only its dedicated sync/async/reactive interfaces, uses PubSubCommandBuilder plus RedisPubSubAsyncCommandsImpl/RedisPubSubReactiveCommandsImpl, and is explicitly outside the API-consistency catalog. Following the advertised full matrix would therefore place the command in the ordinary APIs and dispatch classes instead of making it available from StatefulRedisPubSubConnection (and potentially its cluster counterpart); add a separate Pub/Sub decision-tree path.

AGENTS.md reference: AGENTS.md:L74-L80

Useful? React with 👍 / 👎.

---
name: extend-commands-api
description: Add or extend Redis commands in the Lettuce client API end-to-end — a new core command, a family of new commands, an extension to an existing command's options, or a module/area command (Search/JSON/Bloom/VectorSet). Gathers evidence first (HLD document, the server-side PR in the repo owning the command family, live verification against the Dockerized test environment with redis-cli), plans the full implementation matrix in plan mode, then implements across all API flavors with unit and integration tests. Trigger on "add support for the <X> command", "implement <REDIS COMMAND> in Lettuce", "extend <command> with <option>", or adding a new argument/overload to an existing command.
allowed-tools: Bash(mvn *), Bash(make *), Bash(redis-cli *), Bash(gh *)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Restrict the gh grant to read-only commands

When this skill is active, Bash(gh *) preauthorizes every GitHub CLI operation, including gh pr create, gh pr merge, gh pr comment, and issue-writing commands that the repository explicitly reserves for maintainers. The evidence phase only needs gh auth status, gh search prs, gh pr view, and gh pr diff, so grant those command patterns individually rather than exposing the prohibited write operations.

AGENTS.md reference: AGENTS.md:L52-L57

Useful? React with 👍 / 👎.

@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from 7661265 to c448378 Compare August 3, 2026 12:25

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4483785c8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +269 to +271
3. **Mirror to every flavor**: async, reactive, Kotlin coroutines, and the two
cluster node-selection interfaces (`NodeSelection<Group>Commands` /
`NodeSelection<Group>AsyncCommands`), applying the per-flavor return-type

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Exempt transactional commands from node-selection mirroring

When extending a transaction-control command such as WATCH, this instruction sends the change through both node-selection interfaces, but CommandInterfaces.TRANSACTIONAL explicitly registers null for those flavors and the cluster aggregates exclude the transactional group. Preserve the previous “unless the group has no node-selection flavor” exception so these commands are mirrored only to sync, async, reactive, and coroutine APIs.

Useful? React with 👍 / 👎.

Comment on lines +355 to +357
- Module commands still gate on server capability, not version:
`@EnabledOnCommand("FT.CREATE")`-style probes; integration tests target the
stack node.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Gate module tests against the stack connection

For a module test that connects to the stack node on port 16379, @EnabledOnCommand still resolves a separate default LettuceExtension connection through DefaultRedisClient, which uses TestSettings.port() (6479). In the inspected 7.2/7.4 integration environments, the core and stack images are distinct, so a command present on the stack node can be reported absent on the core node and the test is silently skipped; instruct module tests to evaluate RedisConditions against their stack connection or provide a stack-aware condition.

Useful? React with 👍 / 👎.

Comment on lines +458 to +459
TEST_WORK_FOLDER=./work/docker mvn -DskipITs=false -DskipUnitTests=true \
-Dit.test=FooIntegrationTests verify -Pci

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Match the integration test work directory to make start

With the default Makefile environment, make start exports REDIS_ENV_WORK_DIR=$(ROOT_DIR)/work, but this command forces TEST_WORK_FOLDER to ./work/docker. Tests that resolve TLS certificates or sockets through TlsSettings will therefore look in a different directory from the topology that was just started; use the work directory printed by make start (normally $PWD/work) as required by the linked integration-testing guide.

Useful? React with 👍 / 👎.

Comment on lines +208 to +213
**A. Extension of an existing command that fits an existing `*Args` class**
(new option token / new field):
- Touch ONLY the `*Args` class (+ `CommandKeyword` for new tokens) + tests. Do NOT
touch the command interfaces, builder signatures, or dispatch layers — the
existing `args.build(commandArgs)` delegation carries the new option through
automatically (cf. the `XAddArgs` part of the stream-idempotency PR).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Route output-changing options through the full API matrix

When an option fits an existing *Args class but changes the command's Java reply type, this branch still says to touch only the args plumbing. Extending the response model/output is safe only when the existing public return type can represent both shapes; otherwise callers need a separately typed overload mirrored through the interfaces and dispatch layers. Make unchanged public reply shape a condition of branch A and route incompatible reply changes through branch C.

Useful? React with 👍 / 👎.

Comment on lines +498 to +501
- [ ] PR description states: server PR link, HLD link, gating choice and why,
behavior against older servers, and includes a showcase transcript. (Draft
with the [draft-pr-description](../draft-pr-description/SKILL.md) skill;
remember the guardrail — the agent never creates the PR itself.)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve evidence when drafting the PR description

The referenced draft-pr-description skill derives its output only from git diff and git log and explicitly omits information not evidenced there, while the server PR, HLD, gating rationale, and redis-cli transcript gathered in Phase 0 normally are not part of the source diff. Invoking it as written can therefore produce a description missing every evidence item this checklist requires; instruct the agent to augment the generated file from its Phase 0 notes or extend the drafting skill to accept that evidence.

Useful? React with 👍 / 👎.

a-TODO-rov
a-TODO-rov previously approved these changes Aug 3, 2026
@a-TODO-rov
a-TODO-rov dismissed their stale review August 3, 2026 12:40

Accidentally approved

@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from c448378 to 8df816d Compare August 3, 2026 12:56
@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from 8df816d to 7371e1e Compare August 6, 2026 13:40

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7371e1e0d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +229 to +230
2. **Sync interface** `src/main/java/io/lettuce/core/api/sync/<Group>Commands.java`
— pick the group by command family (STRING → `RedisStringCommands`, HASH →

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add a path for cluster-administration commands

When extending the CLUSTER command with a new subcommand, this path points to the ordinary core/api/sync/<Group> surface and then requires coroutine and node-selection mirrors. Existing cluster-management methods instead live directly in core/cluster/api/{sync,async,reactive}/RedisCluster*Commands, have no corresponding coroutine or node-selection group, and are tested in ClusterCommandIntegrationTests. Add a dedicated cluster-administration case so the method is exposed through cluster connections rather than placed in the regular six-flavor matrix.

AGENTS.md reference: AGENTS.md:L74-L80

Useful? React with 👍 / 👎.

Comment on lines +229 to +230
2. **Sync interface** `src/main/java/io/lettuce/core/api/sync/<Group>Commands.java`
— pick the group by command family (STRING → `RedisStringCommands`, HASH →

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Handle commands declared directly on aggregate interfaces

When extending an aggregate-only connection command such as AUTH, SELECT, or SWAPDB, there is no per-group sync interface at this path: these methods are declared directly on the standalone aggregate interfaces and coroutine aggregate, while AUTH is additionally declared on the cluster aggregates and their coroutine implementation. Sending such a change through branch B can create an artificial command group and unsupported node-selection methods while leaving the actual aggregate APIs unchanged; add a distinct aggregate-only path that enumerates the applicable declarations and implementations.

AGENTS.md reference: AGENTS.md:L89-L93

Useful? React with 👍 / 👎.

Comment on lines +68 to +72
3. **Verify the command exists on the "next" Redis OSS version.** Start the
integration environment using the **highest** version the Makefile supports
(check `SUPPORTED_TEST_ENV_VERSIONS` in the `Makefile`, or the
`src/test/resources/docker-env/.env.vX.XX` files — pick numerically, `8.10` >
`8.8`):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Probe the first supported Redis line as well

When a feature first ships on an older supported line, such as Redis 8.8.x, checking only the highest 8.10 environment cannot reveal that .env.v8.8 is still pinned to a build from before the feature. In the inspected .github/workflows/integration.yml, the nightly matrix runs each supported line, but a new-command test guarded by @EnabledOnCommand silently skips when that line's image lacks the command, so the first claimed supporting line receives no coverage. Probe the first server version identified in step 2 as well and update its environment pin, rather than checking and potentially bumping only the newest line.

Useful? React with 👍 / 👎.

@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from 7371e1e to ae63108 Compare August 6, 2026 13:52

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ae63108da2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

---
name: extend-commands-api
description: Add or extend Redis commands in the Lettuce client API end-to-end — a new core command, a family of new commands, an extension to an existing command's options, or a module/area command (Search/JSON/Bloom/VectorSet). Gathers evidence first (HLD document, the server-side PR in the repo owning the command family, live verification against the Dockerized test environment with redis-cli), plans the full implementation matrix in plan mode, then implements across all API flavors with unit and integration tests. Trigger on "add support for the <X> command", "implement <REDIS COMMAND> in Lettuce", "extend <command> with <option>", or adding a new argument/overload to an existing command.
allowed-tools: Bash(mvn *), Bash(make *), Bash(redis-cli *), Bash(gh *)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Restrict build-tool grants to non-release goals

When this skill is active, Bash(make *) and Bash(mvn *) also preauthorize make release and mvn release:prepare; the inspected Makefile:59-62 release target runs Maven's release preparation and performance goals, which can create release commits/tags and push them despite automated agents being prohibited from committing or pushing. Whitelist only the start/test/stop and Maven build, formatting, and version-query invocations required by this workflow.

AGENTS.md reference: AGENTS.md:L52-L53

Useful? React with 👍 / 👎.

existing `args.build(commandArgs)` delegation carries the new option through
automatically (cf. the `XAddArgs` part of the stream-idempotency PR).
- Add a fluent setter returning `this`; register new tokens in
`src/main/java/io/lettuce/core/protocol/CommandKeyword.java`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Encode punctuation-bearing keywords explicitly

When a new option contains punctuation, such as IDMP-DURATION or FILTER-EF, merely registering the corresponding Java identifier in CommandKeyword uses the no-argument constructor and sends the underscore form (IDMP_DURATION or FILTER_EF). Existing constants use an explicit string constructor for this case, so document that requirement here; otherwise an implementation following this option-extension path compiles but sends an unknown token to Redis.

Useful? React with 👍 / 👎.

Comment on lines +331 to +334
9. **Read-only command?** Register it in
`src/main/java/io/lettuce/core/protocol/ReadOnlyCommands.java` (`CommandName`
enum) so replica-read routing knows, and bump the size assertion in
`ClusterReadOnlyCommandsUnitTests`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid marking mixed command types as read-only

When a read-only subcommand or overload shares its top-level protocol type with write-capable variants, following this blanket registration step marks every variant as read-only: ReadOnlyCommands stores only a Set<CommandType> and its predicate ignores command arguments. Existing write forms of that type then become eligible for replica routing under ReadFrom, causing incorrect routing or READONLY failures. Limit registration to protocol types whose variants are all read-only; mixed types must remain master-routed or use argument-aware classification.

Useful? React with 👍 / 👎.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 6 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit ae63108. Configure here.

9. **Read-only command?** Register it in
`src/main/java/io/lettuce/core/protocol/ReadOnlyCommands.java` (`CommandName`
enum) so replica-read routing knows, and bump the size assertion in
`ClusterReadOnlyCommandsUnitTests`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read-only names must match CommandType

High Severity

Read-only registration is described as adding a ReadOnlyCommands.CommandName entry, but the skill does not state that each name must match an existing CommandType enum constant (e.g. JSON.GET → JSON_GET). ReadOnlyCommands initializes with CommandType.valueOf(commandNames.name()); a mismatch fails class initialization.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit ae63108. Configure here.

Base automatically changed from im/remove-api-generators to main August 6, 2026 14:09
@uglide
uglide force-pushed the im/replace-adding-command-skill-with-extend-skill branch from ae63108 to 20c3c66 Compare August 6, 2026 14:09

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 20c3c6642a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +351 to +354
- Areas get their **own builder** (`Redis<Area>CommandBuilder`, cf.
`RediSearchCommandBuilder`) with a matching
`Redis<Area>CommandBuilderUnitTests`, and keep their argument types and reply
parsers in an area package (e.g. `core/search/arguments/`).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Wire new area builders into both dispatch classes

When branch D creates a command area with a dedicated builder, creating the builder and its tests is insufficient: existing area builders are stored in fields and initialized in the constructors of both AbstractRedisAsyncCommands and AbstractRedisReactiveCommands. Without adding that wiring, the dispatch methods prescribed by step B have no builder instance to invoke, so the new area cannot compile or execute. Add both dispatch-class fields and constructor initialization to this branch.

AGENTS.md reference: AGENTS.md:L89-L93

Useful? React with 👍 / 👎.

@uglide
uglide merged commit 47d48b1 into main Aug 6, 2026
10 checks passed
@uglide
uglide deleted the im/replace-adding-command-skill-with-extend-skill branch August 6, 2026 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址