This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 5927aeca31 Tighten the tinker-dev skill around a mandatory validation
gate
5927aeca31 is described below
commit 5927aeca319a5583041b8babbe02960aecdd719a
Author: Stephen Mallette <[email protected]>
AuthorDate: Wed Jun 17 17:43:54 2026 -0400
Tighten the tinker-dev skill around a mandatory validation gate
Establish a "Definition of Done" in SKILL.md and AGENTS.md: a change is not
done until a full Maven validation matched to the changeset has passed, run
before handing work off for review (incremental testing does not satisfy
it).
Give build/validate commands per module, with blast-radius rules for shared
modules — gremlin-server/driver/util require validating all GLVs, and
gremlin-core/gremlin-test ripple to the whole project including the OLAP
engines. Docs/comment-only changes are exempt.
Call out pitfalls that quietly invalidate a run: GLVs are skipped without
their
.glv sentinel; grammar (Gremlin.g4) and Gherkin feature changes need a
reactor
build to regenerate ANTLR parsers and per-language test code; and pass/fail
should be judged by the Maven exit code, not console text.
Reduce the skill to high-signal, non-derivable guidance:
- Remove the per-language build references and documentation.md; their
commands
now live in the Definition of Done table and the few non-obvious points
were
folded into SKILL.md.
- Collapse guardrails/conventions in SKILL.md that already live in
AGENTS.md.
- Trim gremlin-mcp.md (drop human client config) and the Repository
Structure
section to only what an agent cannot derive.
Drop the ASF license header from agent skill markdown to maximize signal and
broaden the RAT exclude to **/.skills/**/*.md.
Assisted-by: Claude Code:claude-opus-4-8
---
.skills/tinker-dev/SKILL.md | 203 +++++++++++----------
.skills/tinker-dev/references/beads-workflow.md | 19 --
.skills/tinker-dev/references/build-dotnet.md | 97 ----------
.skills/tinker-dev/references/build-go.md | 111 -----------
.skills/tinker-dev/references/build-java.md | 67 -------
.skills/tinker-dev/references/build-javascript.md | 171 -----------------
.skills/tinker-dev/references/build-python.md | 127 -------------
.../tinker-dev/references/dev-environment-setup.md | 24 +--
.skills/tinker-dev/references/documentation.md | 45 -----
.skills/tinker-dev/references/gremlin-mcp.md | 91 +--------
.skills/tinker-review/playbooks/bug-fix.md | 19 --
.skills/tinker-review/playbooks/driver-server.md | 19 --
.skills/tinker-review/playbooks/general.md | 19 --
.skills/tinker-review/playbooks/glv.md | 19 --
.skills/tinker-review/playbooks/grammar.md | 19 --
.skills/tinker-review/playbooks/new-step.md | 19 --
.skills/tinker-review/references/interfaces.md | 19 --
.skills/tinker-review/references/schema.md | 19 --
AGENTS.md | 28 ++-
pom.xml | 5 +-
20 files changed, 136 insertions(+), 1004 deletions(-)
diff --git a/.skills/tinker-dev/SKILL.md b/.skills/tinker-dev/SKILL.md
index 4336370bb2..1844425347 100644
--- a/.skills/tinker-dev/SKILL.md
+++ b/.skills/tinker-dev/SKILL.md
@@ -33,29 +33,82 @@ Canonical project documentation (prefer local files over
external URLs):
- Upgrade docs: `docs/src/upgrade/`
- Future plans: `docs/src/dev/future/`
-## Repository Structure
+## Definition of Done
+A change is **not done** until a full Maven validation has passed locally. Run
it before
+presenting work for review — even when your targeted or unit tests already
pass, and even if you
+judge a full run unnecessary. Incremental testing during development is
encouraged, but it does
+**not** satisfy this gate.
+
+Validation is two steps. First, rebuild and install the whole reactor so every
module picks up
+your changes:
+
+```bash
+mvn clean install -DskipTests
```
-tinkerpop/
-├── gremlin-core/ Core graph API and traversal engine (Java)
-├── gremlin-server/ Gremlin Server (Java)
-├── tinkergraph-gremlin/ In-memory reference graph (Java)
-├── gremlin-python/ Python GLV
-├── gremlin-js/ JavaScript/TypeScript workspace root
-│ ├── gremlin-javascript/ JS driver (npm: "gremlin")
-│ ├── gremlin-mcp/ Gremlin MCP server (npm: "gremlin-mcp")
-│ └── gremlint/ Gremlin query formatter (npm: "gremlint")
-├── gremlin-dotnet/ .NET GLV
-├── gremlin-go/ Go GLV
-├── gremlin-test/ Shared test resources and Gherkin features
-├── gremlin-tools/ Benchmarks, coverage, socket server
-├── docs/src/ AsciiDoc documentation
-├── docker/ Docker build scripts and configs
-├── bin/ Utility scripts
-└── CHANGELOG.asciidoc Changelog
-```
-Maven is the build orchestration tool for all modules, including non-JVM ones.
+Then run `verify` scoped to what you changed, using the **broadest** rule that
applies, and
+always list every module you touched.
+
+**Self-contained modules** — changing one of these only requires validating
that module:
+
+| Changed module | Validate command |
+|---|---|
+| Python GLV | `mvn verify -pl gremlin-python` |
+| JavaScript GLV | `mvn verify -pl :gremlin-javascript` |
+| .NET GLV | `mvn verify -pl
:gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests` |
+| Go GLV | `mvn verify -pl :gremlin-go` |
+| `gremlint` | `mvn verify -pl :gremlint` |
+| `gremlin-mcp` | `mvn verify -pl :gremlin-mcp` |
+| Other single JVM module (e.g. `tinkergraph-gremlin`, `gremlin-console`) |
`mvn verify -pl <module> -DskipIntegrationTests=false` |
+
+**Shared modules** — depended on by others, so changing them means validating
the consumers too.
+Use the broadest rule that matches:
+
+- **`gremlin-server`, `gremlin-driver`, or `gremlin-util`** define the wire
protocol and
+ serialization that every GLV exercises → validate the changed module(s)
**plus all GLVs**:
+ `mvn verify -pl
<changed>,gremlin-python,:gremlin-javascript,:gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests,:gremlin-go
-DskipIntegrationTests=false`
+- **`gremlin-core`, `gremlin-test`, or anything they depend on** ripple across
the whole project,
+ including the OLAP engines (`hadoop-gremlin`, `spark-gremlin`) → run
everything:
+ `mvn clean install -DskipIntegrationTests=false`
+- **Unsure?** Treat it as the `gremlin-core` case and run everything.
+
+**Docs or code comments only** — no validation gate; this gate is for changes
that affect behavior.
+
+### Things that quietly invalidate a run
+
+- **GLV tests are skipped unless activated.** A GLV is built and tested only
when its `.glv`
+ sentinel exists: `gremlin-python/.glv`, `gremlin-go/.glv`, and *both*
`gremlin-dotnet/src/.glv`
+ and `gremlin-dotnet/test/.glv` (JavaScript builds by default). Without the
sentinel the module
+ is silently skipped — a green run may have tested nothing of your change.
Create the sentinel
+ (or pass `-Pglv-python` / `-Pglv-go`) before validating a GLV change.
+- **Grammar and feature-test changes need a reactor build to take effect.**
The ANTLR grammar
+ (`gremlin-language/src/main/antlr4/Gremlin.g4`) and the Gherkin features
under `gremlin-test`
+ drive code generation during `mvn clean install` — ANTLR parsers, and
per-language test code
+ generated from the feature corpus (e.g.
`gremlin-python/build/generate.groovy`, with
+ equivalents for Go, .NET, and JavaScript). After changing either, run `mvn
clean install
+ -DskipTests` before relying on *any* test, including fast native ones, or
you will be testing
+ stale generated code.
+- **Judge pass/fail by the Maven exit code, not console text.** Do not
`grep`/`tail` the build
+ output — tests deliberately emit expected errors, so the log misleads. Exit
`0` = pass. For
+ Python, detailed per-suite results are in
`gremlin-python/target/python3/python-reports/*.xml`.
+
+If you cannot run the validation (for example, Docker is unavailable), say so
explicitly and
+report the change as **not validated** — do not present it as done.
+
+## Repository Structure
+
+Most module names map directly to their purpose (`gremlin-core`,
`gremlin-server`,
+`gremlin-go`, etc.). Two things that aren't obvious:
+
+- The **JavaScript workspace lives under `gremlin-js/`** — it contains
`gremlin-javascript/`
+ (the `gremlin` npm driver), `gremlin-mcp/`, and `gremlint/`. There is no
top-level
+ `gremlin-javascript/` directory.
+- **Maven orchestrates the build for every module, including the non-JVM
ones** (Python,
+ JavaScript, .NET, Go) — which is why the validation in the Definition of
Done runs through
+ Maven rather than each language's native test runner.
+
+Cross-language Gherkin feature tests live in `gremlin-test/`.
## Basic Build Commands
@@ -69,96 +122,46 @@ Build a specific module:
mvn clean install -pl <module-name>
```
-For GLV-specific builds, test execution, and advanced workflows, see the
appropriate
-reference file under `references/`.
-
-## Coding Conventions
-
-- All files must include the Apache Software Foundation license header.
Canonical text
- is at `bin/asf-license-header.txt`.
-- Do not use import wildcards (e.g., avoid `import
org.apache.tinkerpop.gremlin.structure.*`).
- Use explicit imports.
-- Define variables as `final` whenever possible, except for loop variables.
-- Respect existing naming patterns and package organization.
-- Use `@/` path aliases for JavaScript/TypeScript imports where the project
uses them.
-
-## Test Conventions
-
-- Prefer SLF4J `Logger` over `System.out.println` or `println` in tests.
-- Use `TestHelper` utilities for temporary directories and file structures
instead of
- hard-coding paths.
-- Always close `Graph` instances that are manually constructed in tests.
-- Tests using a `GraphProvider` with `AbstractGremlinTest` should be suffixed
`Check`,
- not `Test`.
-- Prefer Hamcrest matchers for boolean assertions (e.g., `assertThat(...,
is(true))`)
- instead of manually checking booleans.
-- Gremlin language tests use Gherkin features under:
- `gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/`
- See `docs/src/dev/developer/for-committers.asciidoc` for details.
-
-## Documentation Conventions
-
-- TinkerPop documentation is AsciiDoc-based under `docs/src/`. Do not use
Markdown in
- the main docs tree.
-- Place new content in the appropriate book (reference, dev, recipes, etc.).
-- Update the relevant `index.asciidoc` so new content is included in the build.
-- For detailed documentation generation instructions, see
`references/documentation.md`.
-
-## Changelog, License, and Checks
+For GLV-specific builds and the validation commands per module, see the
**Definition of Done**
+table above. For environment setup and GLV activation, see
`references/dev-environment-setup.md`.
-When changes affect behavior, APIs, or user-visible features:
+## Conventions
-- Add or update entries in `CHANGELOG.asciidoc` in the correct version section.
-- Do not invent new version numbers or release names; follow the existing
pattern.
-- Preserve and respect license headers and notices in all files.
-- Avoid adding third-party code or dependencies with incompatible licenses.
+The general Do/Don't rules and "when in doubt" guidance live in the root
`AGENTS.md` — the
+single source of truth, not repeated here. The conventions below are the
TinkerPop-specific
+ones that are easy to miss:
-## Agent Guardrails
-
-### Do
-
-- Make small, focused changes that are easy to review.
-- Run the relevant build and test commands before suggesting a change is
complete.
-- Update or add tests when behavior changes.
-- Update documentation and/or changelog when changing public behavior or APIs.
-- Follow existing patterns for code structure, documentation layout, and
naming.
-- Point maintainers to relevant documentation or issues when proposing
non-trivial changes.
-
-### Don't
+- **License header**: every new file needs the ASF header. Canonical text:
`bin/asf-license-header.txt`.
+- **Test naming**: a test using a `GraphProvider` with `AbstractGremlinTest`
is suffixed
+ `Check`, not `Test`.
+- **Gremlin language tests**: cross-language behavior is tested with Gherkin
features under
+ `gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/`
+ (see `docs/src/dev/developer/for-committers.asciidoc`).
+- **Docs are AsciiDoc** under `docs/src/` — never Markdown in the main docs
tree. Add new
+ content to the right book and update its `index.asciidoc`; generate with
`bin/process-docs.sh`
+ (Java 11).
+- **Changelog**: for user-visible or API changes, update `CHANGELOG.asciidoc`
in the correct
+ version section. Do not invent version numbers or release names.
-- Don't perform large, sweeping refactors unless explicitly requested.
-- Don't change public APIs, configuration formats, or network protocols
without explicit
- human approval and an associated design/issue.
-- Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main
docs tree.
-- Don't introduce new external dependencies, modules, or build plugins without
an
- associated discussion and issue.
-- Don't invent project policies, version numbers, or release names.
-- Don't remove or weaken tests to "fix" failures; adjust the implementation or
test
- data instead.
-- Don't run `bd dolt push` — pushing to DoltHub is a maintainer action
performed after
- PRs merge, not during active development.
-- Don't close a beads issue when a PR is submitted — close it only after the
PR merges
- to the target branch.
+Otherwise, match the existing code in neighboring files — explicit imports (no
wildcards),
+`final` where practical, SLF4J logging over `println`, Hamcrest matchers, and
closing any
+`Graph` you construct in a test.
-If uncertain about the impact of a change, prefer to make a minimal patch, add
comments
-for reviewers, and ask for clarification.
+## Beads Caveats
-## When In Doubt
+The general agent Do/Don't rules are in the root `AGENTS.md`. Two beads rules
are easy to get
+wrong and worth repeating here (full workflow in
`references/beads-workflow.md`):
-1. Check `CONTRIBUTING.md`, developer docs under `docs/src/dev/developer/`,
and reference docs.
-2. Prefer no change over an unsafe or speculative change.
-3. Surface the question to human maintainers.
+- Don't run `bd dolt push` — pushing to DoltHub is a maintainer action
performed after PRs
+ merge, not during active development.
+- Don't close a beads issue when a PR is submitted — close it only after the
PR merges to the
+ target branch.
## Reference Guides
-For deeper, task-specific guidance, see the reference files in this skill:
+Build and validate commands live in the **Definition of Done** table above.
For the remaining
+task-specific guidance, see:
-- [Development Environment Setup](references/dev-environment-setup.md) — fresh
clone to working environment
-- [Java / Core Builds](references/build-java.md) — Java modules,
gremlin-server, integration tests
-- [Python GLV](references/build-python.md) — build, test, result evaluation
-- [JavaScript GLV](references/build-javascript.md) — npm workspace, build,
test, evaluation
-- [.NET GLV](references/build-dotnet.md) — build, test, Docker setup
-- [Go GLV](references/build-go.md) — build, test, Docker setup
-- [Documentation](references/documentation.md) — AsciiDoc generation, website
+- [Development Environment Setup](references/dev-environment-setup.md) — fresh
clone to working environment, prerequisites, GLV activation
- [Gremlin MCP Server](references/gremlin-mcp.md) — translation, formatting,
querying via MCP
- [Beads Workflow](references/beads-workflow.md) — agent planning, persistent
memory, TinkerPop-specific conventions and DoltHub push policy
diff --git a/.skills/tinker-dev/references/beads-workflow.md
b/.skills/tinker-dev/references/beads-workflow.md
index c7e83f8982..ed03954946 100644
--- a/.skills/tinker-dev/references/beads-workflow.md
+++ b/.skills/tinker-dev/references/beads-workflow.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Beads Workflow for TinkerPop
TinkerPop uses [beads](https://github.com/steveyegge/beads) (`bd`) as the
agent planning,
diff --git a/.skills/tinker-dev/references/build-dotnet.md
b/.skills/tinker-dev/references/build-dotnet.md
deleted file mode 100644
index e7fd37a0ce..0000000000
--- a/.skills/tinker-dev/references/build-dotnet.md
+++ /dev/null
@@ -1,97 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# .NET GLV Build and Test
-
-## Requirements
-
-- **.NET SDK 8.0+** — optional; Docker handles test execution via Maven.
-- **Docker and Docker Compose** — required for running tests through Maven.
-- **Maven** — preferred build orchestration.
-- **Mono** — only needed for packing the `Gremlin.Net.Template` project.
-
-## Module Structure
-
-```
-gremlin-dotnet/
-├── pom.xml Maven parent (packaging=pom)
-├── Gremlin.Net.sln .NET solution file
-├── src/ Source code (Gremlin.Net library + template)
-│ ├── .glv Sentinel file to activate build
-│ └── Gremlin.Net/ Main library
-├── test/ Test projects
-│ ├── .glv Sentinel file to activate tests
-│ ├── Gremlin.Net.UnitTest/
-│ ├── Gremlin.Net.IntegrationTest/
-│ ├── Gremlin.Net.Benchmarks/
-│ └── Gremlin.Net.Template.IntegrationTest/
-├── Examples/ Example projects
-└── docker-compose.yml Test infrastructure
-```
-
-## Activation
-
-Both `src` and `test` directories need `.glv` sentinel files:
-```bash
-touch gremlin-dotnet/src/.glv
-touch gremlin-dotnet/test/.glv
-```
-
-Without these files, TinkerPop still builds with Maven but .NET projects are
skipped.
-
-## Maven Build Commands
-
-Run from the repository root.
-
-Build and test (requires Docker):
-```bash
-mvn clean install -pl
:gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests
-```
-
-The test execution uses Docker Compose to:
-1. Start a Gremlin Server test container (`gremlin-server-test-dotnet`)
-2. Run `dotnet test ./Gremlin.Net.sln -c Release` inside a .NET SDK 8.0
container
-3. Run example projects to verify they work
-4. Tear down containers
-
-## Docker Test Infrastructure
-
-The `docker-compose.yml` defines:
-- `gremlin-server-test-dotnet` — Gremlin Server on ports 45940-45942 and 4588
-- `gremlin-dotnet-integration-tests` — .NET SDK 8.0 container that runs
`dotnet test`
-
-The test container uses `dotnet-trx` for test result reporting.
-
-## Test Results
-
-Test results are written as `.trx` files inside the container. On failure,
check the
-Maven console output for the `dotnet test` exit code and error summary.
-
-## Template Packaging
-
-To pack the `Gremlin.Net.Template` NuGet package (requires Mono):
-```bash
-mvn clean install -Dnuget
-```
-
-## Evaluating Build Results
-
-Use the Maven exit code to determine pass/fail:
-- Exit `0` — success
-- Non-zero — failure; check the `dotnet test` output in the Maven console
diff --git a/.skills/tinker-dev/references/build-go.md
b/.skills/tinker-dev/references/build-go.md
deleted file mode 100644
index f44cc38aa7..0000000000
--- a/.skills/tinker-dev/references/build-go.md
+++ /dev/null
@@ -1,111 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Go GLV Build and Test
-
-## Requirements
-
-- **Go 1.25+** — optional for local development; Docker handles test execution
via Maven.
-- **Docker and Docker Compose** — required for running tests through Maven.
-- **Maven** — preferred build orchestration.
-
-## Module Structure
-
-```
-gremlin-go/
-├── pom.xml Maven module (no Java source; Maven wraps Go)
-├── go.mod Go module definition
-├── go.sum Go dependency checksums
-├── run.sh Convenience script for Docker-based testing
-├── driver/ Go driver source and tests
-│ ├── cucumber/ BDD feature test support
-│ ├── resources/ Test resources
-│ └── *.go / *_test.go Source and test files
-├── examples/ Example programs
-└── docker-compose.yml Test infrastructure
-```
-
-## Activation
-
-Create a `.glv` sentinel file to include Go in standard builds:
-```bash
-touch gremlin-go/.glv
-```
-
-Without this file, TinkerPop still builds with Maven but Go is skipped.
-
-## Maven Build Commands
-
-Run from the repository root.
-
-Build and test (requires Docker):
-```bash
-mvn clean install -Pglv-go -pl :gremlin-go
-```
-
-The Maven build uses Docker Compose to:
-1. Start a Gremlin Server test container
-2. Run `go test -v -json ./... -race -covermode=atomic` inside a Go container
-3. Run example programs
-4. Tear down containers and prune dangling images
-
-## Convenience Script
-
-From `gremlin-go/`:
-```bash
-./run.sh # Uses current project version
-./run.sh 4.0.0-SNAPSHOT # Specify server version
-./run.sh 3.8.0 # Use a released version
-```
-
-The default requires a SNAPSHOT server image built with:
-```bash
-mvn clean install -pl :gremlin-server -DskipTests -DskipIntegrationTests=true
-am
-mvn install -Pdocker-images -pl :gremlin-server
-```
-
-## Docker Test Infrastructure
-
-The `docker-compose.yml` defines:
-- `gremlin-server-test` — Gremlin Server on ports 45940-45942 and 4588
-- `gremlin-go-integration-tests` — Go 1.25 container that runs tests with race
- detection, coverage, and `gotestfmt` for formatted output
-
-Environment variables in the test container:
-- `CUCUMBER_FEATURE_FOLDER` — path to Gherkin feature files
-- `GREMLIN_SERVER_URL` — server endpoint for integration tests
-- `RUN_INTEGRATION_TESTS=true`
-- `RUN_BASIC_AUTH_INTEGRATION_TESTS=true`
-
-## Local Development
-
-After installing Go locally:
-```bash
-cd gremlin-go
-go build ./...
-go test ./driver/ -run TestName
-```
-
-For integration tests, a running Gremlin Server is required.
-
-## Evaluating Build Results
-
-Use the Maven exit code to determine pass/fail:
-- Exit `0` — success
-- Non-zero — failure; check the `go test` output in the Maven console
diff --git a/.skills/tinker-dev/references/build-java.md
b/.skills/tinker-dev/references/build-java.md
deleted file mode 100644
index 85c1bf9e7a..0000000000
--- a/.skills/tinker-dev/references/build-java.md
+++ /dev/null
@@ -1,67 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Java / Core Module Builds
-
-## Full Build (skip tests)
-
-When modules have unresolved dependency ordering issues (e.g., shaded jars not
yet installed, branches changed, etc.),
-build the entire project first:
-
-```bash
-mvn clean install -DskipTests
-```
-
-## Building and Test Specific Modules
-
-Build and test a single module:
-```bash
-mvn clean install -pl <module-name>
-```
-
-Examples:
-```bash
-mvn clean install -pl :tinkergraph-gremlin
-mvn clean install -pl :gremlin-core
-mvn clean install -pl :gremlin-server
-```
-
-Build and test a module and its dependencies:
-```bash
-mvn clean install -pl :gremlin-server -am
-```
-
-## Gremlin Server
-
-Build gremlin-server (commonly needed before GLV testing):
-```bash
-mvn clean install -pl :gremlin-server -am -DskipTests
-```
-
-Run gremlin-server integration tests:
-```bash
-mvn clean install -pl :gremlin-server -DskipIntegrationTests=false
-```
-
-## Integration Tests
-
-Build and test with all integration tests across the project:
-```bash
-mvn clean install -DskipIntegrationTests=false
-```
diff --git a/.skills/tinker-dev/references/build-javascript.md
b/.skills/tinker-dev/references/build-javascript.md
deleted file mode 100644
index 7ccaddea63..0000000000
--- a/.skills/tinker-dev/references/build-javascript.md
+++ /dev/null
@@ -1,171 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# JavaScript / TypeScript GLV Build and Test
-
-## Architecture
-
-`gremlin-js/` serves two roles simultaneously:
-
-- **Maven parent module** (`packaging=pom`): declares `gremlin-javascript`,
`gremlin-mcp`,
- and `gremlint` as child modules; runs `npm ci` once at the workspace root.
-- **npm workspace root**: `package.json` and `package-lock.json` live here;
all three
- packages share a single hoisted `node_modules/`.
-
-```
-gremlin-js/
-├── pom.xml Maven parent — runs npm ci
-├── package.json npm workspace root
-├── package-lock.json single lockfile for all packages
-├── node_modules/ hoisted dependencies (gitignored)
-├── node/ Node.js runtime from frontend-maven-plugin
(gitignored)
-├── gremlin-javascript/ JS driver (npm: "gremlin")
-├── gremlin-mcp/ Gremlin MCP server (npm: "gremlin-mcp")
-└── gremlint/ Gremlin query formatter (npm: "gremlint")
-```
-
-## Requirements
-
-- **Node.js 22+** / **npm 10+** — optional; Maven downloads a local copy.
-- **Docker and Docker Compose** — required for integration and feature tests.
-- **Maven** — preferred orchestration.
-
-## Maven Build Commands
-
-Run from the repository root.
-
-Build all JS packages (parent + children must be listed explicitly):
-```bash
-mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp
-DskipTests
-mvn clean install -pl :gremlin-js,:gremlin-javascript,:gremlint,:gremlin-mcp
# with tests
-```
-
-Build a single package:
-```bash
-mvn clean install -pl :gremlin-javascript -DskipTests
-mvn clean install -pl :gremlin-mcp -DskipTests
-mvn clean install -pl :gremlint -DskipTests
-```
-
-**`-DskipTests` behavior:**
-- Skips Docker-based integration, unit, and feature tests for
`gremlin-javascript`
-- Skips `npm run validate` (which includes `npm test`) for `gremlin-mcp`
-- Still runs `npm run build` and `npm run lint` for all modules
-
-Full build with tests (requires Docker):
-```bash
-mvn clean install -pl :gremlin-javascript
-```
-
-If building in isolation fails due to a missing parent:
-```bash
-mvn clean install -pl :gremlin-js -DskipTests
-```
-
-## npm Commands
-
-Run from `gremlin-js/gremlin-javascript/` after `npm ci` has been run from
`gremlin-js/`:
-
-| Command | Purpose |
-|----------------------------|--------------------------------------------|
-| `npm run unit-test` | Unit tests only — no server needed |
-| `npm run integration-test` | Integration tests — requires Gremlin Server|
-| `npm run features` | BDD feature tests — requires Gremlin Server|
-| `npm run build` | Compile TypeScript to `build/` (ESM + CJS) |
-| `npm run lint` | ESLint check |
-| `npm run generate` | Regenerate grammar from `Gremlin.g4` |
-
-**Do not run `npm test` directly** — it chains unit and integration tests and
will fail
-without a server. Use `npm run unit-test` for fast local feedback.
-
-For `gremlin-mcp`:
-
-| Command | Purpose |
-|----------------------|--------------------------------------------------|
-| `npm test` | Run unit tests |
-| `npm run test:it` | Integration tests (requires Gremlin Server) |
-| `npm run lint` | ESLint check |
-| `npm run build` | Compile TypeScript |
-| `npm run validate` | All checks (format, lint, type-check, test) |
-
-## npm Workspace Rules
-
-All npm commands that affect dependencies must be run from `gremlin-js/`, not
from
-child package directories:
-
-```bash
-cd gremlin-js/
-npm install
-```
-
-Scripts inside child packages must reference binaries by name (`mocha`, `tsc`,
`eslint`)
-rather than by relative path (`./node_modules/.bin/...`) because dependencies
are hoisted.
-
-## What Not to Change Without Care
-
-- **`package-lock.json`** — regenerated by `npm install` from `gremlin-js/`.
Do not edit
- manually. After any `package.json` change in any child, run `npm install`
from
- `gremlin-js/`.
-- **`gremlin-js/pom.xml`** — the `frontend-maven-plugin` block runs `npm ci`
with
- `<inherited>false</inherited>` so it executes only once at this level.
Removing or
- moving it will break partial `-pl` child builds.
-- **Workspace member paths in `package.json`** — must match subdirectory
names. Changing
- them requires regenerating the lockfile and updating the pom `<modules>`
list.
-
-## gremlin-javascript Directory Structure
-
-```
-gremlin-javascript/
-├── lib/ TypeScript source
-│ └── language/
-│ ├── grammar/ Generated from Gremlin.g4 — do not edit; gitignored
-│ └── translator/ Gremlin query translators (JS, Python, Go, .NET,
Java, Groovy)
-├── test/
-│ ├── unit/ Unit tests (mocha); no server needed
-│ ├── integration/ Requires running Gremlin Server
-│ └── cucumber/ BDD feature tests
-├── scripts/
-│ ├── patch-antlr4ng.js postinstall — patches antlr4ng for CJS
-│ └── groovy/
-│ └── generate.groovy Generates test/cucumber/gremlin.js from feature
corpus
-├── examples/ Standalone examples; excluded from ESLint
-└── build/ Compiled output (ESM + CJS); gitignored
-```
-
-## Docker Permissions
-
-The integration test container runs as the host user (`HOST_UID`/`HOST_GID`,
defaulting
-to `1000:1000`). If you see `EACCES` errors:
-
-```bash
-sudo chown -R $(whoami) /path/to/tinkerpop/gremlin-js/
-```
-
-If your UID is not 1000:
-```bash
-mvn clean install -Dhost.uid=$(id -u) -Dhost.gid=$(id -g) -pl
:gremlin-javascript
-```
-
-## Evaluating Build Results
-
-Do not use `grep` or `tail` on Maven output to judge pass/fail. Use the exit
code:
-- Exit `0` — success
-- Non-zero — failure; inspect Docker container logs or Maven `[ERROR]` lines
-
-Test failures surface directly in the Maven console via npm's exit code.
diff --git a/.skills/tinker-dev/references/build-python.md
b/.skills/tinker-dev/references/build-python.md
deleted file mode 100644
index 469dacc50e..0000000000
--- a/.skills/tinker-dev/references/build-python.md
+++ /dev/null
@@ -1,127 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Python GLV Build and Test
-
-## Requirements
-
-- **Python 3.9+** — optional for local development; Docker handles test
execution via Maven.
-- **Docker and Docker Compose** — required for running tests through Maven.
-- **Maven** — preferred build orchestration.
-
-## Activation
-
-Create a `.glv` sentinel file to include Python in standard builds:
-```bash
-touch gremlin-python/.glv
-```
-
-Or use the Maven profile explicitly:
-```bash
-mvn clean install -Pglv-python -pl gremlin-python
-```
-
-## Maven Build Commands
-
-Run from the repository root.
-
-Run all tests:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python
-```
-
-Run only unit tests:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit"
-```
-
-Run only integration tests:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python
-DpytestArgs="tests/integration"
-```
-
-Run only feature tests:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python -DradishArgs=" "
-```
-
-Run a specific test by name:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name"
-```
-
-Run feature tests with specific tags:
-```bash
-mvn clean install -pl gremlin-python -Pglv-python -DradishArgs="-t @some_tag"
-```
-
-## Evaluating Build Results
-
-**Do not** use `grep`, `tail`, or similar text-search tools on Maven console
output to
-determine pass/fail. Maven output can be misleading because tests validate
expected errors.
-
-Follow this hierarchy:
-
-1. **Check the exit code.** Exit `0` = success. Non-zero = failure.
-2. **Inspect XML reports** on failure. Reports are in
- `gremlin-python/target/python3/python-reports/`:
- - `TEST-native-python.xml` — unit/integration tests
- - `feature-graphbinary-result.xml` — GraphBinary feature tests
- - `feature-graphbinary-params-result.xml` — GraphBinary parameterized
- - `feature-graphbinary-bulked-result.xml` — GraphBinary bulked
- - `feature-graphson-result.xml` — GraphSON feature tests
- - `feature-graphson-params-result.xml` — GraphSON parameterized
-
-Feature test XML reports will not be present if unit/integration tests fail.
-
-**Do not** investigate a build failure beyond reporting what failed unless
asked.
-
-## Manual Test Execution
-
-If you must run tests outside Maven, work from
`gremlin-python/src/main/python/`:
-
-### Environment setup
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install --upgrade pip
-pip install .[test,kerberos]
-```
-
-### Gremlin Server management
-
-From `gremlin-python/`:
-```bash
-# Start/restart server
-docker compose down gremlin-server-test-python
-docker compose up -d gremlin-server-test-python
-
-# Check status (wait for healthy)
-docker compose ps gremlin-server-test-python
-```
-
-### Running tests manually
-- Unit tests: `pytest tests/unit/`
-- Integration tests: `pytest tests/integration/`
-- Feature tests:
- ```bash
- radish -f dots -e -t -b ./tests/radish \
-
../../../../gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features
\
- --user-data='serializer=application/vnd.gremlin-v3.0+json'
- ```
diff --git a/.skills/tinker-dev/references/dev-environment-setup.md
b/.skills/tinker-dev/references/dev-environment-setup.md
index 5ae0faa5c7..6e5ce1c880 100644
--- a/.skills/tinker-dev/references/dev-environment-setup.md
+++ b/.skills/tinker-dev/references/dev-environment-setup.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Development Environment Setup
This guide walks through setting up a TinkerPop development environment from a
fresh clone.
@@ -135,6 +116,5 @@ For AI coding agent configuration, see the "Using AI Coding
Agents" section in
## Next Steps
-- See `references/build-java.md` for Java module build details
-- See the GLV-specific reference files for language-specific workflows
-- See `references/documentation.md` for documentation instructions
+- See the **Definition of Done** table in `SKILL.md` for the build and
validate commands per
+ module / GLV.
diff --git a/.skills/tinker-dev/references/documentation.md
b/.skills/tinker-dev/references/documentation.md
deleted file mode 100644
index 9a9955e592..0000000000
--- a/.skills/tinker-dev/references/documentation.md
+++ /dev/null
@@ -1,45 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Documentation
-
-## Format and Location
-
-TinkerPop documentation is AsciiDoc-based and lives under `docs/src/`:
-
-```
-docs/src/
-├── reference/ Main reference documentation
-├── dev/
-│ ├── developer/ Developer guides (environment, contributing, releases)
-│ ├── provider/ Graph provider documentation, Gremlin semantics
-│ ├── io/ IO and serialization formats
-│ └── future/ Future plans
-├── recipes/ Gremlin recipes and patterns
-├── tutorials/ Getting started tutorials
-└── upgrade/ Version upgrade guides
-```
-
-Do not use Markdown in the main docs tree. Use AsciiDoc.
-
-## Adding or Updating Documentation
-
-1. Place new content in the appropriate book (reference, dev, recipes, etc.).
-2. Update the relevant `index.asciidoc` so the new content is included in the
build.
-3. Follow existing patterns for section structure and formatting.
diff --git a/.skills/tinker-dev/references/gremlin-mcp.md
b/.skills/tinker-dev/references/gremlin-mcp.md
index 680fc9bff5..25598f96f4 100644
--- a/.skills/tinker-dev/references/gremlin-mcp.md
+++ b/.skills/tinker-dev/references/gremlin-mcp.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Gremlin MCP Server
The Gremlin MCP server (`gremlin-mcp`) is an MCP (Model Context Protocol)
server that
@@ -49,76 +30,6 @@ When `GREMLIN_MCP_ENDPOINT` is not set, graph tools are not
registered but
`translate_gremlin_query` and `format_gremlin_query` remain fully available.
This is
useful for query translation and formatting without a running database.
-## Configuration
-
-### MCP Client Configuration (e.g., Claude Desktop, Cursor, Windsurf, Kiro)
-
-Using the published package:
-```json
-{
- "mcpServers": {
- "gremlin": {
- "command": "npx",
- "args": ["gremlin-mcp"],
- "env": {
- "GREMLIN_MCP_ENDPOINT": "localhost:8182",
- "GREMLIN_MCP_LOG_LEVEL": "info"
- }
- }
- }
-}
-```
-
-From source (after building):
-```json
-{
- "mcpServers": {
- "gremlin": {
- "command": "node",
- "args": ["gremlin-js/gremlin-mcp/dist/server.js"],
- "env": {
- "GREMLIN_MCP_ENDPOINT": "localhost:8182",
- "GREMLIN_MCP_LOG_LEVEL": "info"
- }
- }
- }
-}
-```
-
-For offline mode (translation and formatting only), omit
`GREMLIN_MCP_ENDPOINT`.
-
-### With Authentication
-```json
-{
- "mcpServers": {
- "gremlin": {
- "command": "npx",
- "args": ["gremlin-mcp"],
- "env": {
- "GREMLIN_MCP_ENDPOINT": "your-server.com:8182/g",
- "GREMLIN_MCP_USERNAME": "your-username",
- "GREMLIN_MCP_PASSWORD": "your-password",
- "GREMLIN_MCP_USE_SSL": "true"
- }
- }
- }
-}
-```
-
-### Environment Variables
-
-| Variable | Required | Default | Purpose
|
-|---------------------------------------|----------|---------|----------------------------------|
-| `GREMLIN_MCP_ENDPOINT` | No | — | Server endpoint
(host:port[/g]) |
-| `GREMLIN_MCP_USE_SSL` | No | false | Enable SSL/TLS
|
-| `GREMLIN_MCP_USERNAME` | No | — | Authentication
username |
-| `GREMLIN_MCP_PASSWORD` | No | — | Authentication
password |
-| `GREMLIN_MCP_IDLE_TIMEOUT` | No | 300 | Connection
timeout (seconds) |
-| `GREMLIN_MCP_LOG_LEVEL` | No | info | Logging: error,
warn, info, debug|
-| `GREMLIN_MCP_ENUM_DISCOVERY_ENABLED` | No | true | Smart enum
detection |
-| `GREMLIN_MCP_ENUM_CARDINALITY_THRESHOLD` | No | 10 | Max distinct
values for enum |
-| `GREMLIN_MCP_ENUM_PROPERTY_DENYLIST` | No | — | Properties to
exclude from enums |
-
## Translation
The `translate_gremlin_query` tool supports these targets:
@@ -142,7 +53,7 @@ This starts the MCP server and opens a browser-based tool
for interacting with i
## Building gremlin-mcp
-See `references/build-javascript.md` for full build instructions. Quick
reference:
+Quick reference (validate per the **Definition of Done** table in `SKILL.md`):
```bash
# Build only
diff --git a/.skills/tinker-review/playbooks/bug-fix.md
b/.skills/tinker-review/playbooks/bug-fix.md
index df634511ed..20be16eb98 100644
--- a/.skills/tinker-review/playbooks/bug-fix.md
+++ b/.skills/tinker-review/playbooks/bug-fix.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: Bug Fix
## Context
diff --git a/.skills/tinker-review/playbooks/driver-server.md
b/.skills/tinker-review/playbooks/driver-server.md
index 3a599dc23d..177fbfdf5e 100644
--- a/.skills/tinker-review/playbooks/driver-server.md
+++ b/.skills/tinker-review/playbooks/driver-server.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: Driver / Server / Serialization
## Context
diff --git a/.skills/tinker-review/playbooks/general.md
b/.skills/tinker-review/playbooks/general.md
index d8c41abf5f..91ea97253c 100644
--- a/.skills/tinker-review/playbooks/general.md
+++ b/.skills/tinker-review/playbooks/general.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: General (applies to all PRs)
## Context
diff --git a/.skills/tinker-review/playbooks/glv.md
b/.skills/tinker-review/playbooks/glv.md
index 9bac8c8ee8..8c862a7ddc 100644
--- a/.skills/tinker-review/playbooks/glv.md
+++ b/.skills/tinker-review/playbooks/glv.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: GLV Implementation
## Context
diff --git a/.skills/tinker-review/playbooks/grammar.md
b/.skills/tinker-review/playbooks/grammar.md
index 3909b26c78..dd8bb704b0 100644
--- a/.skills/tinker-review/playbooks/grammar.md
+++ b/.skills/tinker-review/playbooks/grammar.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: Grammar Change
## Context
diff --git a/.skills/tinker-review/playbooks/new-step.md
b/.skills/tinker-review/playbooks/new-step.md
index 4669bbd3f9..eb66769fb9 100644
--- a/.skills/tinker-review/playbooks/new-step.md
+++ b/.skills/tinker-review/playbooks/new-step.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Playbook: New Step
## Context
diff --git a/.skills/tinker-review/references/interfaces.md
b/.skills/tinker-review/references/interfaces.md
index f4d3031259..33df7fd202 100644
--- a/.skills/tinker-review/references/interfaces.md
+++ b/.skills/tinker-review/references/interfaces.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# Graph Review Skill — Module Interfaces
Module contracts for the Phase 1 vertical slice. Each module is independently
diff --git a/.skills/tinker-review/references/schema.md
b/.skills/tinker-review/references/schema.md
index 9cf903da55..03b833c3fb 100644
--- a/.skills/tinker-review/references/schema.md
+++ b/.skills/tinker-review/references/schema.md
@@ -1,22 +1,3 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
# PR Knowledge Graph Schema
## Vertices (9 labels)
diff --git a/AGENTS.md b/AGENTS.md
index 88e0decf99..f4952c7666 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,6 +41,31 @@ provenance tracking.
* *The contributor remains responsible for what they submit.* Review generated
output for licensing, correctness, and
style before committing.
+## Definition of Done
+
+A change is **not done** until a full Maven validation has passed locally. Run
it before
+presenting work for review — even when your targeted or unit tests already
pass, and even if you
+judge a full run unnecessary. Incremental testing during development is
encouraged, but it does
+**not** satisfy this gate.
+
+Match the validation to your changeset using a two-step pattern:
+
+1. Rebuild and install the whole reactor without tests, so every module picks
up your changes:
+ `mvn clean install -DskipTests`
+2. Run `verify` on the modules you changed, enabling integration tests where
the change warrants
+ them: `mvn verify -pl <changed-modules> [-DskipIntegrationTests=false]`
+
+Examples:
+
+- Python GLV → `mvn clean install -DskipTests` then `mvn verify -pl
gremlin-python`
+- `gremlin-server` + `gremlin-driver` → `mvn clean install -DskipTests` then
+ `mvn verify -pl gremlin-driver,gremlin-server -DskipIntegrationTests=false`
+- Broad or core changes, or when unsure → `mvn clean install
-DskipIntegrationTests=false`
+
+See the `tinker-dev` skill (and its `references/build-*.md`) for the full
changeset-to-command
+mapping and per-GLV details. If you cannot run the validation (for example,
Docker is
+unavailable), say so explicitly and report the change as **not validated**.
+
## Essential Rules
These rules apply to any AI/IDE assistant operating on this repository.
@@ -48,7 +73,8 @@ These rules apply to any AI/IDE assistant operating on this
repository.
### Do
- Make small, focused changes that are easy to review.
-- Run the relevant build and test commands before suggesting that a change is
complete.
+- Before presenting any change as complete, satisfy the **Definition of Done**
above — a full
+ Maven validation matched to your changeset, not just targeted or unit tests.
- Update or add tests when behavior changes.
- Update documentation and/or changelog when you change public behavior or
APIs.
- Follow existing patterns for code structure, documentation layout, and
naming.
diff --git a/pom.xml b/pom.xml
index 68e88295bc..e755c0a95d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -570,8 +570,9 @@ limitations under the License.
<exclude>**/go.sum</exclude>
<exclude>**/coverage.out</exclude>
<exclude>**/gremlinconsoletest.egg-info/**</exclude>
- <!-- SKILL.md requires frontmatter at very start of
file so that precludes use of the license header -->
- <exclude>**/.skills/**/SKILL.md</exclude>
+ <!-- Agent skill markdown is guidance for AI agents,
kept header-free to maximize signal;
+ SKILL.md additionally requires frontmatter at the
very start of the file -->
+ <exclude>**/.skills/**/*.md</exclude>
</excludes>
<licenses>
<license
implementation="org.apache.rat.analysis.license.ApacheSoftwareLicense20"/>
