spec-anchor

Links Java tests to OpenSpec scenarios and lets you navigate between them in IntelliJ IDEA.

Documentation: docs/: installation, the @OpenSpec annotation, the IntelliJ plugin, using with AI agents.

Modules

• spec-anchor-annotations – the @OpenSpec annotation (Java 8+, no dependencies).
• spec-anchor-intellij-plugin – IntelliJ IDEA 2025.2+ plugin: gutter navigation between spec.md scenarios and annotated tests, Ctrl+Click from the annotation to the spec, and highlighting of unknown references, invalid or duplicate slugs, and untested scenarios.

Installation

The annotation is on Maven Central. Gradle:

testImplementation("org.kleinb.openspec:spec-anchor-annotations:0.3.0")

Maven:

<dependency>
    <groupId>org.kleinb.openspec</groupId>
    <artifactId>spec-anchor-annotations</artifactId>
    <version>0.3.0</version>
    <scope>test</scope>
</dependency>

The IntelliJ plugin (IntelliJ IDEA 2025.2 or later) is not on the JetBrains Marketplace yet. Download spec-anchor-intellij-plugin-<version>.zip from the GitHub releases, then in IntelliJ go to Settings → Plugins → ⚙ → Install Plugin from Disk, pick the zip and restart the IDE if asked.

Linking a test to a scenario

Give the scenario a slug (lowercase ASCII, digits, single hyphens) as an anchor at the end of its heading:

#### Scenario: Valid credentials <a id="valid-credentials"></a>

Annotate the test with the capability path (relative to openspec/specs/) and the slug:

@OpenSpec(capability = "user-auth", scenario = "valid-credentials")
@Test
void validLogin() { }

Leave out scenario to link to the whole capability. The annotation is repeatable.

Untested scenarios

The plugin warns on every scenario heading that has a slug but no linked test. A test linked only to the whole capability does not cover its scenarios, and scenarios without a slug are not reported. Only Java tests are found. To turn the warning off or change its level, go to Settings → Editor → Inspections → OpenSpec → OpenSpec scenario without linked test.

Build

Requires JDK 21 (mise install sets up JDK and Gradle from mise.toml).

./gradlew build                                      # compile and test everything
./gradlew :spec-anchor-intellij-plugin:buildPlugin      # plugin zip in spec-anchor-intellij-plugin/build/distributions
./gradlew :spec-anchor-intellij-plugin:runIde           # try the plugin in a sandbox IDE

Release

just release publishes spec-anchor-annotations to Maven Central and creates the GitHub release with the plugin zip attached (just release-dry rehearses it). Credentials go in ~/.jreleaser/config.properties (JRELEASER_GITHUB_TOKEN, JRELEASER_MAVENCENTRAL_USERNAME, JRELEASER_MAVENCENTRAL_PASSWORD), signing keys in ~/.jreleaser/public.pgp and private.pgp; just publish --check verifies them.

License

Apache License 2.0