AGENTS.md

# 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.

## This Branch: 3.7-dev

`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`.

## Primary Guidance: Agent Skills

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.

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.

## Planning and Memory: Beads

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.

**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
command -v bd >/dev/null && bd prime
```

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

These local documents are authoritative. If this file appears to contradict them, treat them as canonical.

- `README.md`
- `CONTRIBUTING.md`
- Developer documentation at `docs/src/dev/**`

## 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 
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.

## 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 **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**.

## Essential Rules

These rules apply to any AI/IDE assistant operating on this repository.

### 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.

## 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.