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
diff --git a/.skills/tinker-dev/SKILL.md b/.skills/tinker-dev/SKILL.md index 4336370..1844425 100644 --- a/.skills/tinker-dev/SKILL.md +++ b/.skills/tinker-dev/SKILL.md
@@ -33,29 +33,82 @@ - Upgrade docs: `docs/src/upgrade/` - Future plans: `docs/src/dev/future/` +## 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 +``` + +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 -``` -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 -``` +Most module names map directly to their purpose (`gremlin-core`, `gremlin-server`, +`gremlin-go`, etc.). Two things that aren't obvious: -Maven is the build orchestration tool for all modules, including non-JVM ones. +- 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 @@ mvn clean install -pl <module-name> ``` -For GLV-specific builds, test execution, and advanced workflows, see the appropriate -reference file under `references/`. +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`. -## Coding Conventions +## 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. +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: -## 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: +- **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` for details. + (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. -## Documentation Conventions +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. -- 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`. +## Beads Caveats -## Changelog, License, and Checks +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`): -When changes affect behavior, APIs, or user-visible features: - -- 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. - -## 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 - -- 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. - -If uncertain about the impact of a change, prefer to make a minimal patch, add comments -for reviewers, and ask for clarification. - -## When In Doubt - -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 c7e83f8..ed03954 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 e7fd37a..0000000 --- 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 f44cc38..0000000 --- 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 85c1bf9..0000000 --- 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 7ccadde..0000000 --- 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 469dacc..0000000 --- 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 5ae0faa..6e5ce1c 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 @@ ## 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 9a9955e..0000000 --- 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 680fc9b..25598f9 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 @@ `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 @@ ## 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 df63451..20be16e 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 3a599dc..177fbfd 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 d8c41ab..91ea972 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 9bac8c8..8c862a7 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 3909b26..dd8bb70 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 4669bbd..eb66769 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 f4d3031..33df7fd 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 9cf903d..03b833c 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 88e0dec..f4952c7 100644 --- a/AGENTS.md +++ b/AGENTS.md
@@ -41,6 +41,31 @@ * *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 @@ ### 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 68e8829..e755c0a 100644 --- a/pom.xml +++ b/pom.xml
@@ -570,8 +570,9 @@ <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"/>