Specgen Sdk Java

Java SDK (Multi-Release Fat JAR) Specification Generator

This skill generates a comprehensive specification document (Markdown) that serves as a blueprint for building a distributable Java SDK library. The library is published as a Multi-Release fat JAR built with Maven, supports JDK 8 as a baseline and uses JDK 11+ overlays where modern APIs are beneficial, and wraps a remote REST API (plus any additional protocols defined in the PRD's Architecture Principle section).

The specification does NOT generate code. It produces a detailed, opinionated technical document describing every layer of the library — from the pom.xml Multi-Release configuration, to the OkHttp transport, to the model classes and high-level service facade — so that implementation becomes a mechanical exercise.

Library-First Mindset

This is NOT an application. There is no main() (only an optional minimal one for diagnostics), no Spring, no application server, no scheduler. The output is a JAR that downstream Java applications add to their classpath and call as a normal API.

Every design decision below is biased toward:

1. Minimum third-party footprint. Each transitive dependency the SDK pulls in becomes

a problem for every downstream consumer. The skill MUST resist adding libraries unless the JDK and OkHttp cannot reasonably cover the use case.

1. Long-lived JDK compatibility. Consumers may run JDK 8, 11, 17, or 21. The

Multi-Release JAR layout lets the SDK ship one artifact that runs on all of them.

1. A fat (uber) JAR as the primary artifact. Consumers either drop the fat JAR onto

the classpath or depend on it via Maven; either way they get one self-contained file.

Technology Stack

Core Stack (Always Included)

These versions are fixed unless the user explicitly overrides them.

| Component | Version | Notes | |--------------------------|----------|-----------------------------------------------| | Java baseline (release)| 8 | All sources under src/main/java target JDK 8| | Java overlay (release) | 11 | Sources under src/main/java11 target JDK 11 | | Maven | 3.9.x | Build tool | | OkHttp | 4.12.0 | The ONLY runtime third-party dependency | | Okio | 3.9.x | Transitive of OkHttp — not declared directly | | Kotlin stdlib (OkHttp) | 1.9.x | Transitive of OkHttp — not declared directly |

> Note on OkHttp 4.x vs 5.x: OkHttp 4.x runs on JDK 8 and is the safe default for an > SDK that must support legacy consumers. Move to 5.x only if the user explicitly > requires JDK 11 as the baseline AND no longer needs JDK 8 support.

Test-Only Dependencies (always included, scope = test)

| Component | Version | Purpose | |--------------------------|----------|------------------------------------------------| | JUnit Jupiter | 5.10.x | Unit + integration tests | | OkHttp MockWebServer | 4.12.0 | Stub the remote API in tests | | AssertJ | 3.26.x | Fluent assertions |

These are scoped to test and never bundled into the fat JAR.

Optional Runtime Dependencies (rare — only if PRD strictly requires)

The skill MUST default to NO additional dependencies. Add a row below ONLY when the PRD explicitly requires the protocol/format and the JDK has no reasonable equivalent.

| Component | When Selected | |--------------------------|------------------------------------------------------------| | org.java-websocket | WebSocket support AND PRD bans JDK 11 HttpClient WS API | | com.rabbitmq:amqp-client | AMQP/RabbitMQ protocol explicitly listed in Architecture Principle | | org.eclipse.paho:paho-mqtt-client | MQTT protocol explicitly listed in Architecture Principle |

> JSON is handled in-house. Do NOT add Jackson, Gson, Moshi, or org.json. The spec > describes a tiny hand-written JSON serializer/deserializer (or, if the OpenAPI spec is > trivial, simple Map round-tripping) that operates on the SDK's own > immutable model classes. This is intentional — JSON is one of the largest sources of > SDK dependency bloat and downstream version conflicts.

When the Skill Triggers

Generate the spec when the user provides an application name and version that corresponds to one of the SDK libraries defined in CLAUDE.md. The skill reads all required inputs from the project's context files — no interactive Q&A is needed for the core inputs.

The user invokes this skill by specifying the target application and version, for example:

• /specgen-sdk-java my_sdk v1.0.0
• /specgen-sdk-java my_sdk v1.0.0 module:Auth
• /specgen-sdk-java "My SDK" v1.0.0

The skill then locates the matching context folder and reads all input files automatically.

Version Gate

Before starting any work, resolve the application folder first (see Input Resolution below), then check CHANGELOG.md in the application folder (/CHANGELOG.md):

1. If /CHANGELOG.md does not exist, skip this check (first-ever execution for this application).
2. If /CHANGELOG.md exists, scan all ## vX.Y.Z headings and determine the highest version using semantic versioning comparison.
3. Compare the requested version against the highest version:

• If requested version >= highest version: proceed normally.
• If requested version **/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.

Input Resolution

This skill uses standardized input resolution. Provide:

| Argument | Required | Example | Description | |-----------------|----------|-----------------|------------------------------------------------| | ` | Yes | my_sdk | Application name to locate the context folder | | | Yes | v1.0.0 | Version to scope processing | | module: | No | module:Auth` | Limit generation to a single module |

Application Folder Resolution

The application name is matched against root-level application folders:

1. Strip any leading _ prefix from folder names (e.g., 1_my_sdk → my_sdk)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop

Auto-Resolved Paths

| File | Resolved Path | |----------------|----------------------------------------| | PRD.md | /context/PRD.md | | Module Models | /context/model/ | | Output | /context/specification/ |

Version Filtering

When a version is provided, only include user stories, NFRs, constraints, tests, and references from versions ` is provided:

• Only generate the SPEC.md for that specific module
• Other existing module spec files remain untouched
• SPECIFICATION.md (root) gets a partial update — only that module's TOC entry is

added or updated; all other entries are preserved as-is

Gathering Input

The specification is driven by six input sources that are read from the project's context files. The skill does NOT ask the user for protocol, packaging, or model choices — it determines these automatically from the context.

Input 1: Application Name (from CLAUDE.md)

From CLAUDE.md (already loaded in context), locate the target SDK under the Custom Applications section. Extract:

• Application name: The section heading (e.g., "My SDK", "Hub Client SDK")
• Application description: The description paragraph below the heading
• Target consumers: The "Used by" or "Consumers" list — informs API surface design
• Dependencies: The "Depends on" list — primary source for identifying the remote

API (its base URL, auth scheme, etc.)

The application name is used to derive:

• Artifact ID: kebab-case of the application name (e.g., my-sdk)
• Group ID: com.bestinet.urp (project-level constant unless CLAUDE.md overrides)
• Base package: com.bestinet.urp. (e.g., com.bestinet.urp.mysdk)
• Main facade class name: PascalCase of the application name with Client suffix

(e.g., MySdkClient, HubClient)

Input 2: User Stories (from PRD.md — "Library User Stories")

Read /context/PRD.md. For an SDK library, user stories describe what downstream Java applications want to do with the SDK — NOT what an end user wants to do with a UI. Phrasing examples:

• "As a consumer application, I want to fetch a paginated list of orders by status."
• "As a consumer application, I want to upload a file with progress callback."

Each story is tagged like [USSDK00101] and grouped by module. Extract:

• Modules: Each ## or ### section
• User stories per module: Tagged items defining the SDK's public methods

Items with strikethrough (~~text~~) are deprecated. List them in the "Removed / Replaced" subsection of the traceability table. Carry version tags through to the generated specification.

The user stories directly inform:

• The methods on each module's facade class (e.g., OrdersService.list(...))
• Which request/response model classes are needed
• Which HTTP endpoints the SDK calls (mapping derived together with Input 6)

Input 3: Non-Functional Requirements (from PRD.md)

Within the same PRD.md, each module has a ### Non Functional Requirement section with tagged items like [NFRSDK0120]. NFRs typical for an SDK:

• "All HTTP calls timeout after 30 seconds by default, configurable per call."
• "Connection pool reuses up to 10 keep-alive connections."
• "All retryable errors retry with exponential backoff up to 3 attempts."
• "Logging is opt-in via SLF4J — the SDK ships no SLF4J binding."

These NFRs map directly to the OkHttpClient builder configuration, the retry interceptor design, and the logging strategy in the generated spec.

Input 4: Constraints (from PRD.md)

Tagged items like [CONSSDK042]. For an SDK these usually constrain the public API surface and dependency footprint, e.g.:

• "Public API must remain backwards compatible within a major version."
• "SDK must run on JDK 8 without modification."
• "SDK must add no more than 5 transitive dependencies."

Constraints are embedded directly into the relevant module blueprint and surface as explicit rules in the spec's "Constraints" section.

Input 5: Test Instructions and References (from PRD.md)

Each module's ### Test and ### References sections feed:

• Test: The test plan section of the module SPEC.md — what scenarios MockWebServer

must cover, what fixtures are needed.

• References: The "External Documentation" subsection of the module SPEC.md — links

back to the upstream API docs, RFCs, vendor SDK comparisons, etc. Carry version tags through.

Input 6: Module Model (from model/ folder, if present)

Read /context/model/MODEL.md first as the index, then read individual module files in each module subfolder.

For an SDK, "models" are the request/response Java classes that mirror the remote API's schema — NOT database entities. Per-module model files (e.g., model/auth/model.md) define:

• The fields, types, and JSON property names for each model class
• Whether a model is a request DTO, response DTO, or both
• Validation rules to enforce client-side before sending the HTTP call
• Enum values and how they map to JSON strings

The model directly maps to:

• Immutable Java model classes (records on JDK 16+; final classes with Builder on JDK 8)
• The hand-written JSON serializer field tables
• Argument types of public facade methods

If MODEL.md is absent, derive models entirely from the OpenAPI spec (Input 7) and the user stories.

PRD.md Extended Sections

Before determining optional components, check PRD.md for the following extended sections. These are critical for SDK generation — they define the protocols the SDK must support and the design patterns it must follow.

Input 7: API Surface Source — Swagger UI URL or OpenAPI Spec (CRITICAL)

This is the highest-priority input for the SDK spec. Before any other determination, scan the entire PRD.md for one of:

| Pattern | Action | |------------------------------------------------------------------|-------------------------------------------------| | A URL ending in /swagger-ui.html, /swagger-ui/index.html, /swagger, or /api-docs | Record as swaggerUiUrl | | A URL ending in /v3/api-docs, /openapi.json, /openapi.yaml, or /swagger.json | Record as openApiSpecUrl | | A relative path to an openapi.yaml / openapi.json / swagger.yaml / swagger.json file inside the application folder | Record as openApiSpecPath | | A heading "## Swagger UI", "## OpenAPI Spec", "## API Reference" with a URL/path beneath it | Same as above based on the URL form |

Scanning order: Architecture Principle section first → "API Reference" / "External APIs" sections next → fall back to a project-wide grep for swagger / openapi / api-docs.

Resolution behaviour:

1. openApiSpecUrl or openApiSpecPath found: This is the authoritative API

surface. The spec MUST instruct the implementer to read this OpenAPI document and generate one model class per schema, one facade method per operation, and one URL constant per path. The skill should attempt to fetch the spec at generation time (if the URL is reachable) so that the generated SPEC.md can list real operation IDs, paths, and schema names — NOT placeholders.

1. Only swaggerUiUrl found: Treat the underlying /v3/api-docs (or /api-docs)

as the spec endpoint. Note in the spec that the implementer must derive the spec URL by inspecting the Swagger UI page.

1. Neither found, but PRD lists explicit endpoint tables: Use those tables as the

authoritative API surface; mark a [TODO] reminding the team to publish an OpenAPI document.

1. Nothing found: Insert a [TODO] at the top of the generated SPECIFICATION.md

reading: [TODO] No Swagger UI URL or OpenAPI spec found in PRD.md — the SDK API surface is inferred from user stories only and may drift from the real API. Then proceed using user stories alone.

The chosen API surface source MUST be summarized in the Project Overview section of SPECIFICATION.md so future readers know which document drove the SDK shape.

See references/api-extraction-patterns.md for the full procedure.

Architecture Principle Extraction

If PRD.md contains an # Architecture Principle section, extract patterns that affect SDK design. Treat this section as authoritative for protocol selection and design patterns:

| Pattern in Architecture Principle | How It Influences the SDK Spec | |------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | "REST" / "RESTful API" | Confirm OkHttp transport (default) | | "WebSocket" / "real-time" | Add WebSocket subsection. Use OkHttp's built-in WebSocket on JDK 8; document JDK 11 HttpClient WebSocket option | | "Server-Sent Events" / "SSE" | Add SSE subsection backed by OkHttp EventSource

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rashidee
• Source: rashidee/co2-skills
• License: MIT
• Homepage: https://compound-context.com/

Install and usage instructions live in the source repository linked above.