Create Implementation Plan For Redis API Change

Language and repo rules

Each rule names the file or document that proves it; the plan must respect all of them.

• JDK 8 only - no var, List.of, Optional in the API, no records; nullable numerics are boxed Long (pom.xml maven-compiler-plugin 1.8; AGENTS.md General Principles; extend-commands-api, Response mapping).
• String and byte[] parity for core commands, none for modules (extend-commands-api, Binary (byte[]) variant policy). Only keys and textual values get byte[] overloads; return types mirror the key type.
• One params class per option set, shared by both surfaces, with equals/hashCode (extend-commands-api, Params class conventions). No client-side server-version checks.
• SafeEncoder.encode() for text, Protocol.toByteArray() for numbers; token enums in args/ implement Rawable (AGENTS.md Encoding; extend-commands-api, Encoding & enum rules). No Protocol.Keyword that duplicates a token a Rawable enum carries.
• Javadoc on interface methods only, redis.io link, complexity, @since from pom.xml (extend-commands-api, Javadoc, @since, @Experimental); implementations carry none.
• @Experimental only for preview features, then on every new public element and the PR labelled experimental (same section).
• ClusterCommandObjects overrides follow the HLD's cluster constraints, not key count alone: multi-key slot checks (extend-commands-api, Decision tree B.3) and single-key or keyless commands with unsupported or special cluster semantics (the existing scan, waitReplicas, waitAOF and keyless hotkeys* overrides); plain single-key commands route through unchanged.
• Reuse generic builders; a resps/ model only for map-shaped replies (extend-commands-api, Response mapping). Multi-mode replies become distinctly named typed methods; mode by argument type becomes overloads of one name.
• Cluster tests use hash-tagged keys so multi-key commands share a slot; cluster-incompatible tests get @Test @Override @Disabled("<reason>") (extend-commands-api, Test matrix 4).
• Gate once, on the base class, with an option-aware gate: @EnabledOnCommand("<COMMAND>") only for a NEW command or subcommand (EnabledOnCommandCondition checks COMMAND INFO and cannot see a new option); a new option on an existing command gets @SinceRedisVersion("<build>"), a module option a RedisConditions#moduleVersionIsGreaterThanOrEqual assumption; @ConditionalOnEnv to exclude an environment (extend-commands-api, Test matrix).
• New integration classes are named *IT, never *IntegrationTest, never @Tag("integration") (docs/integration-testing.md §4-5; AGENTS.md Test Conventions); unit tests are *Test.
• RESP2 and RESP3 come from the parameterized base, CommandsTestsParameters#respVersions (#jedisRespVersions for legacy); no per-test work (extend-commands-api, Test matrix).
• Every new file goes into the pom.xml formatter includes (extend-commands-api, Decision tree B.7).
• Modules prefer params/builder changes over interface changes and have no binary or pipeline-binary variants (extend-commands-api, Decision tree D).
• A behaviour change gets a release-notes entry in the same PR; a breaking change a migration-guide entry; no new dependencies (AGENTS.md General Principles).

Output contract

Exactly one markdown file: ./PLAN.md, or the path the requester gives (supervised only; unattended is always ./PLAN.md). The bot stores the merged file as redis-oss/client-hld/<feature>/jedis-plan.md in the design repo and validates the frontmatter with pydantic, failing closed, so every key below is present with the stated type.

---
feature: bless
client: jedis
hld: {path: redis-oss/client-hld/bless/README.md, sha: <approved_sha>}
tracks: [redis/redis#15649]
target_version: "8.12"
decision_class: B                    # the convention skill's decision-tree letter; none when estimated_size is none
conventions:                         # headings the coder reads, as "path#Heading" - block form, every entry quoted
  - ".agents/skills/extend-commands-api/SKILL.md#Decision tree"
  - ".agents/skills/extend-commands-api/SKILL.md#Binary (byte[]) variant policy"
  - ".agents/skills/extend-commands-api/SKILL.md#Test matrix"
estimated_size: medium               # none | small | medium | large
integration_targets: [RedisClientBlessCommandsIT, ClusterBlessCommandsIT]   # ^[A-Za-z0-9_.*$#-]+$
unit_targets: [BlessParamsTest, UnifiedJedisBlessCommandsTest, PipeliningBaseBlessCommandsTest]
open_questions: 2
---

integration_targets names the Failsafe classes the harness runs on standalone and cluster: for an existing group the existing runners RedisClient<Group>CommandsTest and Cluster<Group>CommandsTest; for a new family the new *IT runners (standalone and cluster); for a module the <Feature>RedisClientCommandsIT / <Feature>ClusterCommandsIT pair; and, for every core change, the affected legacy commands/jedis/<Group>CommandsTest class, since the Test matrix requires legacy Jedis coverage for every core command (binary variants only add tests to it). Every entry must match ^[A-Za-z0-9_.*$#-]+$ (a class name, optionally Class#method). Keep conventions in block form with every entry quoted: headings carry [, ], ( and & (Binary (byte[]) variant policy), which break a YAML flow sequence, and the bot rejects a plan whose frontmatter does not parse. estimated_size: none (with decision_class: none) means Jedis is not impacted: the body then has section 1 explaining why from this repo's code, every other section reads "none", and section 5 has no steps.

Then these sections, in this order, all present (write "none" rather than omitting one):

1. Summary - what the change gives a Jedis user, the decision class, the analogue traced, and the size estimate with its reason.
2. HLD requirement coverage - R.x | where (file, symbol) | proving test | note, one row per R.x and NF.x.
3. Public API to add/change - the String-interface signatures in full with their Javadoc (@since, @Experimental when preview), then a table of the binary, pipeline and pipeline-binary mirrors, the params and args types with their setters, and a back-compat note (additive / deprecates X / breaking).
4. Files to change - path | add/edit | what, covering tokens, args, params, resps, interfaces, CommandObjects, ClusterCommandObjects, UnifiedJedis, PipeliningBase, Jedis, every test class, the pom.xml formatter includes and the release-notes file.
5. Ordered implementation steps - each with the files, the check to run after it (for example mvn -q -Dtest=<Name>ParamsTest test), and a "done when".
6. Test plan - unit (params, mocked delegation), integration per topology (standalone, cluster; RESP2/RESP3 through the parameterized base), the gating annotation and value, the written-not-run list (what the sandbox cannot execute), and the exact harness commands: mvn -q test (or mvn -q -Dtest=<unit_targets> test) and mvn -B -DskipUnitTests=true -Dit.failIfNoSpecifiedTests=false -Dit.test=<integration_targets> verify under a JDK 8 JAVA_HOME, with REDIS_ENDPOINTS_CONFIG_PATH pointing at an endpoints file that defines standalone0, modules-docker and cluster-stable.
7. Docs / changelog / public-API files - the release-notes entry, any module page, the formatter-includes lines, and the statement that Jedis has no API-tracking file.
8. Behaviour against older servers - what a user gets on a server without the command or option (the server error; gated tests skipped).
9. Risks & open questions - each with the planner's default; includes every unverified item and every HLD-versus-convention conflict.
10. Out of scope - what the HLD mentions that this plan deliberately leaves out, and why.

Running it locally

From this repo, in Claude Code / Codex / Cursor, with an HLD at hand:

Use the create-implementation-plan-for-redis-api-change skill to plan the Jedis implementation of $TMPDIR/bless/README.md into $TMPDIR/bless/jedis-plan.md.

The agent reads the HLD and this checkout, traces the analogue, and presents the plan for review; it edits nothing else. Inside the bot the same text is the system prompt of the planning task (plan_skill_path in the roster): the sandbox clones redis/jedis at master, writes ./HLD.md, runs this skill with Mode: unattended, and opens the resulting ./PLAN.md as one PR in the design repo. Reviewers revise it with /revise <text>, /redo, or a "Request changes" review; merging it is the go for the coding task, which follows the plan rather than this repo's extension skill.

Testing the skill

Three canonical inputs, each with a pass condition:

A plan that cites as existing a file this repo does not have (rows marked add in section 4 may name new files), or a signature with no sibling and no R.x behind it, has failed. A plan whose section 9 is empty while the HLD's section 8 scenarios are all expected has failed too: the unverified replies belong there.