You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2026/08/09 13:30:20 UTC
(tinkerpop) 03/14: Rewrite AGENTS.md on 3.7-dev around the Agent Skills
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
commit 8ea9033f322dcc804b126e5a6a3a6774eac55764
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Sun Aug 9 08:27:25 2026 -0400
Rewrite AGENTS.md on 3.7-dev around the Agent Skills
Replaces the inlined build recipes and repository tour with pointers to
the tinker-dev and tinker-doc skills, matching master. Adds what master
has no need for: the non-breaking constraint that governs a 3.7.x
change. The per-module gremlin-python/AGENTS.md goes away with it.
Assisted-by: Claude Code:claude-opus-5
---
AGENTS.md | 324 ++++++++++++++++-------------------------------
gremlin-python/AGENTS.md | 105 ---------------
2 files changed, 106 insertions(+), 323 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 04ddbad2e1..1e8286b331 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,250 +1,138 @@
# AGENTS.md
-You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement,
-maintain, and validate Apache TinkerPop’s graph computing framework and its multi-language Gremlin ecosystem.
+You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement,
+maintain, and validate Apache TinkerPop's graph computing framework and its multi-language Gremlin ecosystem.
-- `README.md`
-- `CONTRIBUTING.md`
-- Developer documentation at `docs/src/dev/**`
-
-This file must not contradict those documents. If it appears to, treat them as canonical and update this file
-accordingly.
-
-## Licensing and Provenance
-
-Apache TinkerPop is licensed under Apache License 2.0. Contributions must meet the
-[ASF's Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html). In particular:
-
-* *Do not copy verbatim from incompatibly licensed sources.* This includes GPL / AGPL / LGPL code, proprietary code,
- unlicensed snippets, and Stack Overflow / blog / forum excerpts whose licensing is unclear. Reimplement from
- specifications, standards, or Apache-compatible sources (see the ASF 3rd Party Licensing Policy).
-* *Every new source file needs the ASF license header.* See `bin/asf-license-header.txt` for the canonical form.
-* *Attribute generated work in commits.* When AI tooling authored a non-trivial portion of a change, add a trailer to
- the commit message, for example: `Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]`. This aligns with the ASF's
- recommendation on AI provenance tracking.
-* *The contributor remains responsible for what they submit.* Review generated output for licensing, correctness, and
- style before committing.
-
-## Security
-
-For Apache TinkerPop's threat model — trust boundaries, in-scope / out-of-scope, the security properties
-the project does and does not provide, and known non-findings — see [SECURITY.md](SECURITY.md), which
-points to [THREAT_MODEL.md](THREAT_MODEL.md). Consult it before triaging or reporting security issues.
-
-***
-
-## 1. Project overview
-
-Key project docs (prefer these local files over external URLs):
-
-- Reference docs: `docs/src/reference/**`
-- Recipes: `docs/src/recipes/**`
-- Upgrade docs: `docs/src/upgrade/**`
-- IO and Serialization docs: `docs/src/dev/io/**`
-- Provider docs and Gremlin Semantics: `docs/src/dev/provider/**`
-- Developer docs: `docs/src/dev/developer/**`
-- Future plans: `docs/src/dev/future/**`
-
-The project website mirrors these for released versions; use local files for branch‑accurate information.
-
-***
-
-## 2. Repository structure (high level)
-
-Use these as anchors when exploring the repo:
-
-- Core code and modules: Maven multi‑module layout under the repo root, though modules may not contain JVM-relevant code
- (i.e. Maven is simply the build orchestration tool wrapping other environments like Python or Go)
-- Docs: `docs/src/**` (AsciiDoc “books”, reference, dev docs, recipes, etc.)
-- Changelog: `CHANGELOG.asciidoc`
-- Website: `docs/site/**`
-- Scripts:
- - Docker scripts: `docker/*.sh`
- - Docs/site scripts: `bin/process-docs.sh`, `bin/generate-home.sh`
-
-When adding or modifying files, follow the existing structure and conventions in the surrounding directory.
-
-***
-
-## 3. Nested AGENTS.md files
-
-This repository uses additional `AGENTS.md` files in certain subdirectories (for example,
-`gremlin-python/AGENTS.md`, `gremlin-dotnet/AGENTS.md`, etc.) to provide stack‑specific guidance.
-
-Agents should:
-
-- Always read this root `AGENTS.md` for global rules.
-- When working in a subdirectory, also look for the closest `AGENTS.md` in the current or parent
-directories and apply its instructions for that area.
-- Treat more specific `AGENTS.md` files (deeper in the tree) as overriding or refining the generic
-guidance here when there is a conflict.
+## This Branch: 3.7-dev
-## 4. Build and test recipes
+`3.7-dev` is a maintenance branch for the 3.7.x release line. It takes non-breaking bug fixes
+and enhancements only: within the line a change must not alter existing behavior, introduce new
+APIs, change serialization formats, or modify protocols. The rule of thumb is that a client of
+one 3.7.x version must still interact correctly with a server of another. Work that fails that
+test belongs on a later branch. Changes here merge forward toward `master` — see
+`docs/src/dev/developer/for-committers.asciidoc`.
-### 4.1 Basic build and test
+## Primary Guidance: Agent Skills
-- Build everything:
+This repository provides development guidance as [Agent Skills](https://agentskills.io):
+`tinker-dev` for building, testing and coding conventions, and `tinker-doc` for authoring and
+revising documentation. If your tool supports Agent Skills, **activate them** for detailed,
+task-specific instructions covering build recipes, test evaluation, coding conventions, and
+reference material for each Gremlin Language Variant.
- ```bash
- mvn clean install
- ```
+If your tool does not discover the skill automatically, run `bin/agent-setup.sh --list` to
+see how to configure it, or `bin/agent-setup.sh <agent>` to set up the integration.
-- Build a specific module:
+## Planning and Memory: Beads
- ```bash
- mvn clean install -pl <module-name>
- ```
+TinkerPop maintainers use **beads (`bd`)** for planning and as the project's long-term
+memory — it records not just what changed, but why: decisions made, alternatives rejected,
+directions abandoned.
- Example:
-
- ```bash
- mvn clean install -pl tinkergraph-gremlin
- ```
-
-### 4.2 Integration and specialized builds
-
-- Enable integration tests:
-
- ```bash
- mvn clean install -DskipIntegrationTests=false
- ```
-
-- Include Neo4j tests:
-
- ```bash
- mvn clean install -DincludeNeo4j
- ```
-
-### 4.3 Gremlin Language Variant (GLV) builds
-
-Build Gremlin Server first:
+**If `bd` is installed, run `bd prime` at the start of a session and again after any context
+compaction.** It emits `.beads/PRIME.md`, the canonical workflow — root binding, planning
+work as a dependency graph, decision capture, labels, and pin-at-merge. Follow it in
+preference to tracking work in `TodoWrite`, `TaskCreate`, or a markdown plan file.
```bash
-mvn clean install -pl :gremlin-server -am -DskipTests
+command -v bd >/dev/null && bd prime
```
-Each GLV has its own module structure:
-
-- Python:
-
- ```bash
- mvn clean install -Pglv-python -pl gremlin-python
- ```
-
-- .NET:
-
- ```bash
- mvn clean install -pl gremlin-dotnet,gremlin-dotnet-source,gremlin-dotnet-tests
- ```
-
-- JavaScript:
-
- ```bash
- mvn clean install -Pglv-js -pl gremlin-javascript
- ```
-
-- Go:
-
- ```bash
- mvn clean install -Pglv-go -pl gremlin-go
- ```
+If `bd` is not installed, skip it — nothing else in this repository depends on beads. Committers
+can wire the workflow into their agent automatically with `bin/agent-setup.sh --contributor`.
-***
+## Canonical Documentation
-## 5. Documentation
+These local documents are authoritative. If this file appears to contradict them, treat them as canonical.
-TinkerPop’s documentation is AsciiDoc‑based and lives under `docs/src/**`.
-
-When adding or updating docs:
-
-- Use AsciiDoc (not Markdown) in the main docs tree.
-- Place new content in the appropriate book (reference, dev, recipes, etc.).
-- Update the relevant `index.asciidoc` so the new content is included in the build.
-
-***
+- `README.md`
+- `CONTRIBUTING.md`
+- Developer documentation at `docs/src/dev/**`
-## 6. Coding and testing conventions
+## Licensing and Provenance
-Agents should follow these conventions when generating or editing code and tests.
+Apache TinkerPop is licensed under Apache License 2.0. Contributions must meet the
+[ASF's Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html). In particular:
-### 6.1 Code style
+* *Do not copy verbatim from incompatibly licensed sources.* This includes GPL / AGPL / LGPL code, proprietary code,
+unlicensed snippets, and Stack Overflow / blog / forum excerpts whose licensing is unclear. Reimplement from
+specifications, standards, or Apache-compatible sources (see the ASF 3rd Party Licensing Policy).
+* *Every new source file needs the ASF license header.* See `bin/asf-license-header.txt` for the canonical form.
+* *Attribute generated work in commits.* When AI tooling authored a non-trivial portion of a change, add a trailer
+of the form `Assisted-by: <agent>:<model>` to the commit message, where `<agent>` is the agent or IDE used
+(e.g. `Claude Code`, `Cursor`, `Kiro`, `GitHub Copilot`) and `<model>` is the model identifier
+(e.g. `claude-opus-4-7`, `gpt-5`). Append a bracketed entry per additional auxiliary tool (e.g. `[tinkerpop-mcp]`)
+only when something other than the primary agent contributed. For example,
+`Assisted-by: Claude Code:claude-opus-4-7`, `Assisted-by: Cursor:gpt-5`, or
+`Assisted-by: Claude Code:claude-opus-4-7 [tinkerpop-mcp]`. This aligns with the ASF's recommendation on AI
+provenance tracking.
+* *The contributor remains responsible for what they submit.* Review generated output for licensing, correctness, and
+style before committing.
-- All files should include the Apache Software Foundation license header - canonical text for the header is at `bin/asf-license-header.txt`.
-- Do **not** use import wildcards (for example, avoid `import org.apache.tinkerpop.gremlin.structure.*`); prefer explicit imports.
-- Respect existing naming patterns and package organization.
-- Define variables as `final` whenever possible, except for loop variables.
+## Definition of Done
-### 6.2 Test guidelines
+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.
-- Prefer SLF4J `Logger` for output instead of `System.out.println` or `println` in tests.
-- Use `TestHelper` utilities to create temporary directories and file structures for file‑based tests, instead of hard‑coding paths.
-- Always close `Graph` instances that are manually constructed in tests.
-- Tests using a `GraphProvider` implementation with `AbstractGremlinTest` should be suffixed with `Check` instead of `Test`.
-- Prefer Hamcrest matchers for boolean‑style assertions (for example, `assertThat(..., is(true))`) instead of manually checking booleans.
-- For Gremlin language tests, see the "Gremlin Language Test Cases" section of `docs/src/dev/developer/for-committers.asciidoc`
-for more details and use Gherkin tests under:
+Match the validation to your changeset using a two-step pattern:
- ```text
- gremlin-tests/src/main/resources/org/apache/tinkerpop/gremlin/test/features
- ```
+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:
-## 7. Changelog, license, and checks
+- 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`
-When changes affect behavior, APIs, or user‑visible features:
+See the **Definition of Done** section of the `tinker-dev` skill 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**.
-- 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.
+## Essential Rules
-***
+These rules apply to any AI/IDE assistant operating on this repository.
-## 8. Do and don’t for agents
+### Do
+
+- Make small, focused changes that are easy to review.
+- 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 when you change public behavior or APIs, and add a changelog entry for the net user-facing
+ change — one entry per user-facing change, not one per commit (see the `tinker-doc` skill for changelog discipline).
+- Keep commit messages short and usage-focused — what changed from a reader's perspective, not an implementation
+ play-by-play. Deep rationale belongs in the PR or code comments.
+- Follow existing patterns for code structure, documentation layout, and naming.
+- If code is ready, stop and ask to commit, push or merge manually.
+
+### Don't
+
+- Don't perform large, sweeping refactors unless explicitly requested.
+- Don't change public APIs, configuration formats, serialization formats, or network protocols
+ on this branch. Those are breaking changes and belong on a later branch — see
+ **This Branch: 3.7-dev** above.
+- 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 discussion.
+- 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 push to any branch.
+- Don't merge any PR or branch.
+- Don't create tags or releases.
+- Don't add `@author` javadoc (or similar) tags for new files, but do not remove existing ones either.
+
+### When In Doubt
+
+1. Prefer no change over an unsafe or speculative change.
+2. Ask for clarification.
-These rules apply to any AI/IDE assistant operating on this repository.
+## Security
-### 8.1 Do
-
-- **Do** make small, focused changes that are easy to review.
-- **Do** run the relevant build and test commands before suggesting that a change is complete.
-- **Do** update or add tests when behavior changes.
-- **Do** update documentation and/or changelog when you change public behavior or APIs.
-- **Do** follow existing patterns for code structure, documentation layout, and naming.
-- **Do** point maintainers to relevant documentation or issues when proposing non‑trivial changes.
-- **Do** stop to ask human to commit, push or merge manually, when code is ready.
-
-### 8.2 Don’t
-
-- **Don’t** perform large, sweeping refactors (across many modules or files) unless explicitly requested.
-- **Don’t** change public APIs, configuration formats, or network protocols without explicit human approval and 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 the test data instead.
-- **Don't** push to any branch.
-- **Don't** merge any PR or branch.
-- **Don't** create tags or releases.
-
-If you are uncertain about the impact of a change, prefer to:
-
-- Make a minimal patch.
-- Add comments or notes for reviewers.
-- Ask for clarification.
-
-***
-
-## 9. When in doubt
-
-If AGENTS.md does not clearly cover a situation:
-
-1. Look for relevant information in:
- - `CONTRIBUTING.md`
- - Developer docs under `docs/src/dev/developer/**`
- - Reference docs and recipes
-2. Prefer **no change** over an unsafe or speculative change.
-3. Surface the question to human maintainers (for example, by leaving a comment, or drafting a minimal PR that asks for guidance).
-
-This file is intended to help tools act like a careful, well‑informed contributor. When in doubt, defer to human
-judgment and the canonical project documentation.
+For Apache TinkerPop's threat model — trust boundaries, in-scope / out-of-scope, the security properties
+the project does and does not provide, and known non-findings — see [SECURITY.md](SECURITY.md), which
+points to [THREAT_MODEL.md](THREAT_MODEL.md). Consult it before triaging or reporting security issues.
diff --git a/gremlin-python/AGENTS.md b/gremlin-python/AGENTS.md
deleted file mode 100644
index c86234a331..0000000000
--- a/gremlin-python/AGENTS.md
+++ /dev/null
@@ -1,105 +0,0 @@
-### gremlin-python AGENTS.md
-
-This document provides stack-specific guidance for developers and AI agents working on the `gremlin-python` module. It
-supplements the root `AGENTS.md` file.
-
----
-
-### 1. Build and Test Requirements
-
-To build and run tests for `gremlin-python`, ensure the following:
-
-* **Python Version**: A supported Python version must be installed. `gremlin-python` supports Python 3.9 through
- 3.13.
-* **Virtual Environment**: While a virtual environment is recommended for local development, the preferred way to
- run tests is via Maven and Docker, which handles environment isolation automatically.
-* **Docker**: Docker and Docker Compose must be installed and running.
-* **Maven**: Maven must be installed.
-
-### 2. Preferred Build Orchestration
-
-The preferred way to run tests is via Maven from the repository root. This ensures an OS-agnostic execution environment
-and handles all dependencies, including starting the Gremlin Server.
-
-* **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=" "
- ```
-
-### 3. Targeted Test Execution
-
-You can pass arguments to `pytest` or `radish` via Maven properties to run specific tests.
-
-* **Run a specific Unit/Integration test**:
- ```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"
- ```
-
-### 4. Evaluating Build Results
-
-**DO NOT** use `grep`, `tail` or similar text-search tools on the Maven console output (or `.output.txt`) to determine
-if the tests passed or failed. The Maven output can be misleading due to the tests validating expected errors.
-
-To accurately evaluate the results, follow this strict hierarchy:
-
-1. **Check the Command Exit Code**: A successful build **must** exit with code `0`. Any non-zero exit code is a failure.
-2. **Verify via XML Reports**: If the build fails (non-zero exit) you **must** inspect the JUnit XML reports in `gremlin-python/target/python3/python-reports/`:
- * `TEST-native-python.xml` (Unit/Integration tests)
- * `feature-graphbinary-result.xml` (Feature tests - GraphBinary)
- * `feature-graphson-result.xml` (Feature tests - GraphSON)
-
-Feature test XML reports will not be present if the unit/integration tests fail.
-
-**DO NOT** attempt to investigate a build failure beyond reporting what failed unless asked.
-
-### 5. Manual Test Execution (Advanced)
-
-If you must run tests manually outside Maven, follow these steps from the `gremlin-python/src/main/python/` directory.
-
-#### 5.1 Environment Setup
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install --upgrade pip
-pip install .[test,kerberos]
-```
-
-#### 5.2 Gremlin Server Management
-
-Manual integration and feature tests require a running Gremlin Server. Run these 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
-```
-
-#### 5.3 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'
- ```
\ No newline at end of file