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 eb276fdbbd Added basic bootstrap for beads
eb276fdbbd is described below
commit eb276fdbbd00278a912f79fd111e771c8a1c96a8
Author: Stephen Mallette <[email protected]>
AuthorDate: Wed Apr 29 16:58:40 2026 -0400
Added basic bootstrap for beads
Uses a TinkerPop specific workflow with some workaround specific to naming
our remote database something "different", i.e. tinkerbeads :/ CTR
---
.skills/tinkerpop-dev/SKILL.md | 8 +-
.skills/tinkerpop-dev/references/beads-workflow.md | 234 +++++++++++++++++++++
bin/beads-bootstrap.sh | 92 ++++++++
docs/src/dev/developer/for-committers.asciidoc | 77 +++++++
4 files changed, 410 insertions(+), 1 deletion(-)
diff --git a/.skills/tinkerpop-dev/SKILL.md b/.skills/tinkerpop-dev/SKILL.md
index ad2b40cf30..3fc8100c2f 100644
--- a/.skills/tinkerpop-dev/SKILL.md
+++ b/.skills/tinkerpop-dev/SKILL.md
@@ -5,7 +5,8 @@ description: >
testing, or contributing to TinkerPop's graph computing framework and its
multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go).
Covers coding conventions, build recipes, test evaluation, documentation,
- development environment setup, and Gremlin MCP server usage.
+ development environment setup, Gremlin MCP server usage, and beads (bd) —
+ the agent planning and persistent memory system used by TinkerPop
maintainers.
license: Apache-2.0
compatibility: Requires Java 11+, Maven 3.5.3+, Docker. Individual GLVs may
need Python, Node.js, .NET SDK, or Go.
metadata:
@@ -134,6 +135,10 @@ When changes affect behavior, APIs, or user-visible
features:
- 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.
@@ -156,3 +161,4 @@ For deeper, task-specific guidance, see the reference files
in this skill:
- [Go GLV](references/build-go.md) — build, test, Docker setup
- [Documentation](references/documentation.md) — AsciiDoc generation, website
- [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/tinkerpop-dev/references/beads-workflow.md
b/.skills/tinkerpop-dev/references/beads-workflow.md
new file mode 100644
index 0000000000..c7e83f8982
--- /dev/null
+++ b/.skills/tinkerpop-dev/references/beads-workflow.md
@@ -0,0 +1,234 @@
+<!--
+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,
+execution, and long-term memory system, backed by a shared DoltHub database
+(`tinkerpop/tinkerbeads`). This reference covers TinkerPop-specific
conventions that differ
+from or extend the beads defaults.
+
+## Setup
+
+New contributors run the bootstrap script from the repo root:
+
+```bash
+bin/beads-bootstrap.sh
+```
+
+Prerequisites: `bd` and `dolt` installed, valid DoltHub credentials (`dolt
login`).
+
+## Core Rules
+
+- **Default**: Use beads for ALL planning and tracking (`bd create`, `bd
ready`, `bd close`)
+- **Scope**: Beads captures both concrete tasks *and* open design questions —
create a bead
+ whenever a question, decision, or trade-off needs to be preserved, not just
when there is
+ code to write
+- **Prohibited**: Do NOT use TodoWrite, TaskCreate, or markdown files for task
tracking
+- **Workflow**: Create a beads issue BEFORE writing code, mark `in_progress`
when starting
+- **Commit messages**: Every commit must include bead ID(s) as
`(tinkerpop-NNN)` on its own
+ line, placed above the `Assisted-by:` trailer. Validate this before
committing:
+ ```
+ Add vertex label support to GraphSON serializer
+
+ (tinkerpop-123)
+ Assisted-by: Claude:claude-sonnet-4-6 [Claude Code]
+ ```
+- **Bias toward persistence**: When in doubt, capture it in a bead. Lost
reasoning is harder
+ to recover than an unused issue.
+- **Session start**: Check `bd ready` for available work before beginning any
session
+
+## Essential Commands
+
+### Finding Work
+- `bd ready` - Show issues ready to work (no blockers)
+- `bd list --status=open` - All open issues
+- `bd list --status=in_progress` - Your active work
+- `bd show <id>` - Detailed issue view with dependencies
+
+### Creating & Updating
+- `bd create --title="Summary of this issue" --description="Why this issue
exists and what needs to be done" --type=task|bug|feature --priority=2` - New
issue
+ - Priority: 0-4 or P0-P4 (0=critical, 2=medium, 4=backlog). NOT
"high"/"medium"/"low"
+- `bd update <id> --claim` - Claim work
+- `bd update <id> --assignee=username` - Assign to someone
+- `bd update <id> --title/--description/--notes/--design` - Update fields
inline
+- `bd close <id>` - Mark complete
+- `bd close <id1> <id2> ...` - Close multiple issues at once (more efficient)
+- `bd close <id> --reason="explanation"` - Close with reason
+- **Tip**: When creating multiple issues/tasks/epics, use parallel subagents
for efficiency
+- **WARNING**: Do NOT use `bd edit` - it opens $EDITOR (vim/nano) which blocks
agents
+
+### Dependencies & Blocking
+- `bd dep add <issue> <depends-on>` - Add dependency (issue depends on
depends-on)
+- `bd blocked` - Show all blocked issues
+- `bd show <id>` - See what's blocking/blocked by this issue
+
+### Sync & Collaboration
+- **WARNING**: Do NOT use `bd dolt push` - that is a manual task left to human
maintainers
+- `bd dolt pull` - Pull beads from Dolt remote
+- `bd search <query>` - Search issues by keyword
+
+### Project Health
+- `bd stats` - Project statistics (open/closed/blocked counts)
+- `bd doctor` - Check for issues (sync problems, missing hooks)
+- `bd doctor --check=conventions` - Check for convention drift (lint, stale,
orphans)
+
+### Quality Tools
+- `bd create --validate` - Check description has required sections
+- `bd create --acceptance="criteria"` - Set acceptance criteria (checked by
--validate)
+- `bd create --design="decisions"` - Record design decisions
+- `bd create --notes="context"` - Add supplementary notes
+- `bd config set validation.on-create warn` - Auto-validate on every create
+- `bd lint` - Check existing issues for missing sections
+
+### Lifecycle & Hygiene
+- `bd defer <id> --until="date"` - Defer work to a future date
+- `bd supersede <id> --with=<new-id>` - Mark issue as superseded
+- `bd close <id> --suggest-next` - Show newly unblocked issues after closing
+- `bd stale` - Find issues with no recent activity
+- `bd orphans` - Find issues with broken dependencies
+- `bd preflight` - Pre-PR checks (lint, stale, orphans)
+- `bd human <id>` - Flag for human decision (list/respond/dismiss)
+
+### Structured Workflows
+- `bd formula list` - See available workflow templates
+- `bd mol pour <name>` - Start structured workflow from formula
+
+## Labels
+
+Labels provide multi-dimensional categorization orthogonal to type and
priority. An issue
+can carry multiple labels simultaneously, enabling cross-cutting views of the
issue graph.
+
+```bash
+# At creation
+bd create --title="..." --labels="gremlin-core,3.8"
+
+# After creation
+bd label add <id> <label>
+bd label remove <id> <label>
+bd label list <id> # labels on a specific issue
+bd label list-all # all labels in use across the database
+```
+
+Suggested label dimensions for TinkerPop:
+- **Module**: `gremlin-core`, `gremlin-server`, `gremlin-python`,
`gremlin-javascript`, `gremlin-dotnet`, `gremlin-go`, `tinkergraph`
+- **Cross-cutting concern**: `serialization`, `traversal`, `driver`, `docs`,
`breaking-change`, `deprecation`
+
+These are conventions, not enforced values. Use `bd label list-all` to see
what labels are
+already in use before introducing new ones.
+
+## Issue Lifecycle
+
+```
+open → in_progress → closed
+```
+
+Close a bead when its associated commit has been made and the operator has
approved the
+commit message. The bead represents completed local work; the DoltHub push
(which makes
+it visible to others) is a separate, deferred maintainer action.
+
+## Issue Content Standards
+
+Every issue must carry enough context to be understood without a side
conversation.
+Use these fields when creating:
+
+```bash
+bd create \
+ --title="Short imperative summary" \
+ --description="What the problem is and why it matters" \
+ --design="Decisions made, alternatives considered, approaches rejected" \
+ --acceptance="Testable definition of done" \
+ --labels="module,release-target" \
+ --type=bug|feature|task \
+ --priority=0-4
+```
+
+- **`--description`**: The *why*, not just the *what*. A reader should
understand the
+ motivation without prior context. For open design questions, state what is
unresolved
+ and why it matters.
+- **`--design`**: Record decisions made, alternatives considered, and
approaches rejected.
+ This is where the reasoning lives — future sessions and agents read this to
understand
+ the path that led to the current state, not just what the current state is.
+- **`--acceptance`**: What does done look like? Should be verifiable (test
passes, behavior
+ observed, doc updated). For open questions, the condition under which the
bead can close.
+
+Use `bd create --validate` to check completeness before finalizing.
+
+## JIRA Linking
+
+When a TinkerPop JIRA ticket exists for a bead, record it via
`--external-ref`. This can
+be set at creation time or added later when the operator supplies the ticket
identifier:
+
+```bash
+# At creation
+bd create --title="..." --external-ref="TINKERPOP-3456" ...
+
+# Added later
+bd update <id> --external-ref="TINKERPOP-3456"
+```
+
+## Daily Workflow
+
+**Finding and claiming work:**
+```bash
+bd ready # show unblocked issues
+bd show <id> # review details
+bd update <id> --claim # claim it
+```
+
+**Completing work:**
+```bash
+# 1. Ensure commit message includes the bead ID above the Assisted-by trailer
+# 2. Get operator approval on the commit message
+# 3. Close the bead
+bd close <id>
+```
+
+**Checking project state:**
+```bash
+bd stats # open/closed/blocked counts
+bd blocked # issues with unresolved blockers
+bd list --status=in_progress # all active work
+```
+
+**Creating dependent work:**
+```bash
+# Run bd create commands in parallel (use subagents for many items)
+bd create --title="Implement feature X" --description="Why this issue exists
and what needs to be done" --type=feature
+bd create --title="Write tests for X" --description="Why this issue exists and
what needs to be done" --type=task
+bd dep add beads-yyy beads-xxx # Tests depend on Feature (Feature blocks
tests)
+```
+
+## DoltHub Push Policy
+
+**Contributors do not push to DoltHub.** `bd dolt push` is a maintainer action
performed
+after PRs merge. Beads are closed locally as work completes; the push to
DoltHub defers
+visibility of that closed state until the work has been reviewed and merged.
+
+Maintainers run after merging a batch of PRs:
+```bash
+bd dolt pull # integrate any remote changes first
+bd dolt push # publish to tinkerpop/tinkerbeads
+```
+
+## What Not To Do
+
+- Do not run `bd dolt push` as a contributor — this is a maintainer action
post-merge
+- Do not use `bd edit` — it opens an interactive editor that blocks agents
+- Do not serialize issue creation or task execution when parallelization is
possible
diff --git a/bin/beads-bootstrap.sh b/bin/beads-bootstrap.sh
new file mode 100755
index 0000000000..ad0980a224
--- /dev/null
+++ b/bin/beads-bootstrap.sh
@@ -0,0 +1,92 @@
+#!/bin/bash
+#
+#
+# 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.
+#
+
+# This script helps automate the Beads process setup for TinkerPop.
+# It initializes Beads and clones the tinkerpop/tinkerbeads database.
+# Contributors can use this to quickly set up their local environment.
+
+set -e
+
+# Check if bd command exists
+if ! command -v bd &> /dev/null; then
+ echo "Error: 'bd' command not found. Please install Beads first:
https://github.com/steveyegge/beads";
+ exit 1
+fi
+
+# Check if dolt command exists
+if ! command -v dolt &> /dev/null; then
+ echo "Error: 'dolt' command not found. Please install Dolt first:
https://www.dolthub.com/docs/introduction/installation/";
+ exit 1
+fi
+
+# Check if dolt credentials are valid
+echo "Checking Dolt credentials..."
+if ! dolt creds check; then
+ echo "Error: Dolt credentials check failed."
+ echo "Please run 'dolt login' to authenticate with DoltHub."
+ exit 1
+fi
+
+# Ensure we are in the project root
+if [ ! -f "pom.xml" ]; then
+ echo "Error: This script must be run from the TinkerPop project root."
+ exit 1
+fi
+
+echo "Initializing Beads..."
+# Run bd init if .beads directory doesn't exist
+if [ ! -d ".beads" ]; then
+ bd init --skip-agents --skip-hooks --database tinkerbeads --prefix
tinkerpop
+else
+ echo ".beads directory already exists. Skipping 'bd init'."
+fi
+
+echo "Setting up Dolt database..."
+# Navigate to the embedded dolt directory
+mkdir -p .beads/embeddeddolt
+pushd .beads/embeddeddolt > /dev/null
+
+# Remove existing database if any, to allow cloning
+if [ -d "tinkerbeads" ]; then
+ echo "Removing existing local tinkerbeads database..."
+ rm -rf tinkerbeads
+fi
+
+echo "Cloning tinkerpop/tinkerbeads from DoltHub..."
+dolt clone tinkerpop/tinkerbeads
+
+popd > /dev/null
+
+echo "Removing project_id from metadata.json to avoid identity mismatch..."
+if [ -f ".beads/metadata.json" ]; then
+ # Use jq to safely remove the project_id field.
+ if command -v jq &> /dev/null; then
+ jq 'del(.project_id)' .beads/metadata.json > .beads/metadata.json.tmp
&& mv .beads/metadata.json.tmp .beads/metadata.json
+ else
+ # Fallback to sed if jq is not available
+ sed -i '/"project_id":/d' .beads/metadata.json
+ fi
+fi
+
+echo "Finalizing setup..."
+bd ready
+
+echo "Beads bootstrap complete for TinkerPop!"
diff --git a/docs/src/dev/developer/for-committers.asciidoc
b/docs/src/dev/developer/for-committers.asciidoc
index e88b79cc2f..1929e38476 100644
--- a/docs/src/dev/developer/for-committers.asciidoc
+++ b/docs/src/dev/developer/for-committers.asciidoc
@@ -1038,3 +1038,80 @@ resources. That file gets copied to the
`target/test-classes` on build and sure
are then configured to point at that area of the file system for those
configuration files. The XML files
can be edited to fine tune control of the log output, but generally speaking
the current configuration is likely
best for everyone's general purposes, so if changes are made please revert
them prior to commit.
+
+[[beads]]
+== Using Beads
+
+link:https://github.com/steveyegge/beads[Beads] (`bd`) is an agent planning,
execution, and
+long-term memory system that TinkerPop is trialing as part of its AI-assisted
development
+workflow. *Use of beads is optional for committers at this time.* It is
primarily intended for
+committers who work with AI coding agents such as
link:https://www.anthropic.com/claude-code[Claude Code],
+link:https://kiro.dev/[Kiro], or link:https://junie.jetbrains.com/[Junie], and
want a structured way to
+plan, track, and preserve the reasoning behind their work.
+
+=== Intent
+
+Traditional development workflows capture the final output — code, tests,
documentation — but
+discard the thinking that produced it. Beads addresses this by structuring
decisions as a
+persistent graph. Each bead represents a unit of work or an open design
question, and the
+accumulated graph of beads becomes a traversable record of what was decided,
why, and what
+alternatives were rejected. For AI agents, this means future sessions can
access the path of
+decisions that led to the current state rather than re-deriving intent from
the code alone.
+
+Beads are backed by a shared DoltHub database at
+link:https://www.dolthub.com/repositories/tinkerpop/tinkerbeads[tinkerpop/tinkerbeads],
making
+the graph of decisions visible across contributors and sessions.
+
+=== Workflow
+
+Because beads usage is optional, the agent does not load beads context
automatically. Once the
+`tinkerpop-dev` skill is active, the committer opts in by telling the agent to
use beads:
+
+----
+Use beads.
+----
+
+The agent will then read the beads workflow reference and use beads to
structure the session:
+creating issues for planned work before writing any code, capturing design
decisions and
+alternatives as the work evolves, and closing issues as commits are approved.
Sessions where
+the committer does not give this instruction will proceed without beads
involvement.
+
+From the committer's perspective this means:
+
+* *At session start* — invoke the `tinkerpop-dev` skill, then say "Use beads"
to opt in.
+ The agent will check for available work and propose a plan using beads.
+* *During work* — the agent creates and updates beads as it goes. The
committer reviews and
+ guides this, the same way they review the code changes themselves.
+* *At commit time* — the agent will include the relevant bead ID(s) in the
commit message.
+ The committer reviews and approves the commit message before it lands. The
agent then closes
+ the associated bead(s).
+* *At merge time* — the operator pushes the accumulated bead state to DoltHub
(see below).
+
+This workflow is deliberate: beads are closed locally as work commits, but the
shared DoltHub
+database only reflects that state after a PR has merged. This keeps the
canonical shared
+record aligned with accepted work rather than in-flight changes.
+
+=== Operator Responsibilities
+
+Operators (typically PMC members or active committers managing the shared
database) are
+responsible for two actions that contributors do not perform:
+
+* *Pushing to DoltHub* — after a batch of PRs has merged, the operator runs
+ `bd dolt pull && bd dolt push` to publish the closed state of beads to the
shared
+ `tinkerpop/tinkerbeads` database.
+
+* *JIRA linking* — when a JIRA ticket is associated with work tracked in
beads, the operator
+ supplies the ticket identifier to the agent, which records it against the
relevant bead.
+
+=== Setup
+
+Contributors wishing to use beads run the bootstrap script from the repository
root:
+
+[source,bash]
+----
+bin/beads-bootstrap.sh
+----
+
+This requires `bd` and `dolt` to be installed and valid DoltHub credentials
(`dolt login`).
+Full workflow guidance for AI agents is in
`.claude/skills/tinkerpop-dev/references/beads-workflow.md`.
+
