# Specgen Sdk Java

> >

- **Type:** Skill
- **Install:** `agentstack add skill-rashidee-co2-skills-specgen-sdk-java`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rashidee](https://agentstack.voostack.com/s/rashidee)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rashidee](https://github.com/rashidee)
- **Source:** https://github.com/rashidee/co2-skills/tree/main/skills/specgen-sdk-java
- **Website:** https://compound-context.com/

## Install

```sh
agentstack add skill-rashidee-co2-skills-specgen-sdk-java
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. **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.
3. **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.
2. **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.
3. **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.
4. **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](https://github.com/rashidee)
- **Source:** [rashidee/co2-skills](https://github.com/rashidee/co2-skills)
- **License:** MIT
- **Homepage:** https://compound-context.com/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rashidee-co2-skills-specgen-sdk-java
- Seller: https://agentstack.voostack.com/s/rashidee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.