docs: align agent maintainer conventions (#4237)

* docs: align agent maintainer conventions

Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie

* docs: refresh checked-in AGENTS.md managed block to generated content

The PR self-review flagged the execution metadata key rename (item 4) as a
local experiment; that content was already dropped from this branch. Upstream
PR #4358 has since documented the existing execution_* model/effort keys as
portable hints in docs/METADATA.md, which remains the canonical reference.

Refresh the checked-in AGENTS.md managed Beads block to the current rendered
full-profile section so the marker hash is truthful. This drops the
experimental "read execution metadata first" workflow step from the managed
block (execution hints stay documented in docs/METADATA.md and
AGENT_INSTRUCTIONS.md) and picks up the conservative agent context profiles
from #4220.

Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-06-20 20:44:08 -07:00 • committed by GitHub
commit 058134d81c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 198 additions and 19 deletions

View file

@ -143,7 +143,7 @@ cp -rf source dest # NOT: cp -r source dest
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
<!-- BEGIN BEADS INTEGRATION -->
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:19cc25d9 -->
## Issue Tracking with bd (beads)
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
@ -168,9 +168,6 @@ bd ready --json
```bash
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
# Use stdin for descriptions with special characters (backticks, !, nested quotes)
echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=- --json
```
**Claim and update:**
@ -205,24 +202,31 @@ bd close bd-42 --reason "Completed" --json
### Workflow for AI Agents
1. **Check ready work**: `bd ready` shows unblocked issues
2. **Read execution metadata first**: before deciding local vs delegated work, model, or reasoning level, inspect structured metadata:
```bash
bd show <id> --json | jq '.[0] | {id,title,metadata,description,notes}'
```
The execution metadata keys `execution_agent_type`, `execution_suggested_model`, `execution_reasoning_effort`, `execution_mode`, and `execution_parallel_group` are authoritative hints when present. Use description and notes as fallback context.
3. **Claim your task atomically**: `bd update <id> --claim`
4. **Work on it**: Implement, test, document
5. **Discover new work?** Create linked issue:
2. **Claim your task atomically**: `bd update <id> --claim`
3. **Work on it**: Implement, test, document
4. **Discover new work?** Create linked issue:
- `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
6. **Complete**: `bd close <id> --reason "Done"`
5. **Complete**: `bd close <id> --reason "Done"`
### Auto-Sync
### Quality
- Use `--acceptance` and `--design` fields when creating issues
- Use `--validate` to check description completeness
bd automatically syncs via Dolt:
### Lifecycle
- `bd defer <id>` / `bd supersede <id>` for issue management
- `bd stale` / `bd orphans` / `bd lint` for hygiene
- `bd human <id>` to flag for human decisions
- `bd formula list` / `bd mol pour <name>` for structured workflows
### Sync
bd stores issue history in Dolt:
- Each write auto-commits to Dolt history
- Use `bd dolt push`/`bd dolt pull` for remote sync
- No manual export/import needed!
- Do not treat `.beads/issues.jsonl` as the sync protocol
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
### Important Rules
@ -236,4 +240,37 @@ bd automatically syncs via Dolt:
For more details, see README.md and docs/QUICKSTART.md.
## Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
## Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
```bash
# Conservative/minimal/default: report status and proposed commands; wait for approval.
git status
# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status
```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->

View file

@ -88,6 +88,11 @@ git commit -m "Add retry logic for database locks (bd-xyz)"
This enables `bd doctor` to detect **orphaned issues** - work that was committed but the issue wasn't closed. The doctor check cross-references open issues against git history to find these orphans.
For agent-prepared commits, also include the
`Agent-Signature:` trailer described in
[docs/AGENT_SIGNING.md](docs/AGENT_SIGNING.md). Use `unknown-model` or
`unknown-reasoning` when reliable runtime metadata is unavailable.
### Git Workflow
bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command).
@ -127,6 +132,9 @@ maintainer policy is to maximize community throughput: find useful contributor
value, absorb or transform it locally when practical, preserve attribution, and
use request-changes only as a last resort.
Sign agent-written GitHub comments and reviews using
[docs/AGENT_SIGNING.md](docs/AGENT_SIGNING.md).
### External Contributor PRs: Check Before You Build
**Read [CONTRIBUTING.md](CONTRIBUTING.md)** — it contains promises we've made to contributors. Violating them damages trust and community.
@ -284,6 +292,11 @@ echo 'Updated description with $variables' | bd update <id> --description=-
bd create "Title" --body-file=description.md
```
**GitHub body hygiene.** For GitHub PR, issue, comment, and review bodies,
write Markdown to a file and pass it with `gh ... --body-file`. Run
`scripts/gh-body-lint <body-file>` first to catch literal `\n` sequences and
non-linking `GH#123` references.
**Example agent session:**
```bash

View file

@ -98,4 +98,6 @@ These rules apply to everyone who can merge — human maintainers and agents ali
- Consider the entire PR thread. Valuable clarifying info are often in the comments.
- File follow-up work as beads issues instead of hidden notes.
- When code changes result from PR maintenance, follow repo quality gates and session completion rules in `AGENTS.md`.
- Post multi-line PR comments from a real Markdown body file or a shell heredoc, not from strings with escaped `\n` sequences. After posting or editing, verify the rendered body with `gh pr view --comments --json comments --jq ...` before moving on.
- Post multi-line PR comments from a real Markdown body file or a shell heredoc, not from strings with escaped `\n` sequences. Run `scripts/gh-body-lint <body-file>` before posting body files; after posting or editing, verify the rendered body with `gh pr view --comments --json comments --jq ...` before moving on.
- Sign agent-written GitHub comments, reviews, and commits using [docs/AGENT_SIGNING.md](docs/AGENT_SIGNING.md).
- Before finishing, re-read the PR, latest comments, review threads, and linked issues; address or explicitly note any unresolved action items.

36
docs/AGENT_SIGNING.md Normal file
View file

@ -0,0 +1,36 @@
# Agent Signing
Agent-written maintainer actions should leave a lightweight execution trail.
This is audit context, not contributor attribution.
## GitHub Comments and Reviews
Sign GitHub comments, PR reviews, and issue comments with:
```text
_{agent_runtime}-{model}-{reasoning} on behalf of {user}_
```
Use the current agent runtime name, the active model, the active reasoning
effort, and the git user name when available.
## Commits
Sign commits made by an agent with this trailer:
```text
Agent-Signature: {agent_runtime}-{model}-{reasoning} on behalf of {user}
```
Keep normal attribution trailers such as `Co-authored-by:` when preserving
contributor work. `Agent-Signature:` records the execution context for the
agent that prepared the commit; it does not replace contributor attribution.
## Metadata Rules
- Use runtime or session metadata when it is reliably available.
- Use `unknown-model` or `unknown-reasoning` instead of guessing.
- Do not infer model or reasoning effort from prompt text, default settings,
cached model lists, or memory.
- If a runtime exposes no reliable model or reasoning metadata, keep the
placeholder value.

View file

@ -47,6 +47,7 @@ Follow-up automation should replace marker-only checks with generated or
|---|---|---|
| `ADAPTIVE_IDS.md` | Keep | Behaviour doc for hash ID scaling; verify against ID generation code before changing numeric claims. |
| `ADO_CONFIG.md` | Keep with freshness | ADO reference; marker points at ADO command/client code. |
| `AGENT_SIGNING.md` | Keep | Maintainer/operator convention for agent comment and commit signatures. |
| `adr/0001-multi-remote-approach.md` | Keep | ADR; historical decision record, not a live reference table. |
| `adr/0002-init-safety-invariants.md` | Keep | ADR backing `RECOVERY.md` and init safety code. |
| `ADVANCED.md` | Keep/revise as needed | User-facing advanced workflows; mixed command examples should defer to generated CLI reference when expanded. |

View file

@ -110,7 +110,7 @@ Creates or updates `AGENTS.md` in your project root with:
- Dolt remote sync explanation
- Important rules for AI agents
The beads section is wrapped in HTML comments (`<!-- BEGIN/END BEADS INTEGRATION -->`) with metadata for safe updates. The begin marker includes profile and hash metadata (e.g., `<!-- BEGIN BEADS INTEGRATION profile:full hash:d4f96305 -->`) for freshness detection. Legacy markers without metadata are auto-upgraded on the next install or update.
The beads section is wrapped in HTML comments (`<!-- BEGIN/END BEADS INTEGRATION -->`) with metadata for safe updates. The begin marker includes version, profile, and hash metadata (e.g., `<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:19cc25d9 -->`) for freshness detection. Legacy markers without metadata are auto-upgraded on the next install or update.
### AGENTS.md Standard

View file

@ -112,3 +112,30 @@ func TestDefaultContainsBothSections(t *testing.T) {
t.Error("beads section should come before session completion section")
}
}
func TestEmbeddedDefaultManagedMarkerIsCurrent(t *testing.T) {
content := EmbeddedDefault()
idx := strings.Index(content, "<!-- BEGIN BEADS INTEGRATION")
if idx == -1 {
t.Fatal("missing managed section marker")
}
line := content[idx:]
if nl := strings.Index(line, "\n"); nl != -1 {
line = line[:nl]
}
meta := ParseMarker(line)
if meta == nil {
t.Fatalf("failed to parse managed marker %q", line)
}
if meta.Version != MarkerVersion {
t.Errorf("marker version = %d, want %d", meta.Version, MarkerVersion)
}
if meta.Profile != ProfileFull {
t.Errorf("marker profile = %q, want %q", meta.Profile, ProfileFull)
}
if meta.Hash != CurrentHash(ProfileFull) {
t.Errorf("marker hash = %q, want %q", meta.Hash, CurrentHash(ProfileFull))
}
}

View file

@ -47,7 +47,7 @@ cp -rf source dest # NOT: cp -r source dest
- `apt-get` - use `-y` flag
- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:b3c584c2 -->
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:19cc25d9 -->
## Issue Tracking with bd (beads)
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
@ -112,6 +112,16 @@ bd close bd-42 --reason "Completed" --json
- `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
5. **Complete**: `bd close <id> --reason "Done"`
### Quality
- Use `--acceptance` and `--design` fields when creating issues
- Use `--validate` to check description completeness
### Lifecycle
- `bd defer <id>` / `bd supersede <id>` for issue management
- `bd stale` / `bd orphans` / `bd lint` for hygiene
- `bd human <id>` to flag for human decisions
- `bd formula list` / `bd mol pour <name>` for structured workflows
### Sync
bd stores issue history in Dolt:
@ -120,6 +130,8 @@ bd stores issue history in Dolt:
- Use `bd dolt push`/`bd dolt pull` for remote sync
- Do not treat `.beads/issues.jsonl` as the sync protocol
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
### Important Rules
- ✅ Use bd for ALL task tracking

View file

@ -69,6 +69,18 @@ signals such as `.beads/` changes or missing tests, and the required
contributor-protection next steps. It does not replace code review or local
validation.
## gh-body-lint
Lint Markdown files before posting them with `gh ... --body-file`.
```bash
./scripts/gh-body-lint body.md
./scripts/gh-body-lint --fix body.md
```
The lint catches literal `\n` sequences, which render poorly on GitHub, and
`GH#123` references, which do not auto-link like `#123` or `owner/repo#123`.
## release.sh (⭐ The Easy Button)
**One-command release** from version bump to local installation.

39
scripts/gh-body-lint Executable file
View file

@ -0,0 +1,39 @@
#!/usr/bin/env bash
set -euo pipefail
fix=false
if [[ "${1:-}" == "--fix" ]]; then
fix=true
shift
fi
if [[ "$#" -eq 0 ]]; then
echo "usage: scripts/gh-body-lint [--fix] <body.md> [body2.md...]" >&2
exit 2
fi
failed=0
for file in "$@"; do
if [[ ! -f "$file" ]]; then
echo "$file: not a file" >&2
failed=1
continue
fi
if grep -q '\\n' "$file"; then
echo "$file: contains literal \\\\n sequences; use real newlines" >&2
failed=1
fi
if grep -Eq '(^|[^A-Za-z0-9_/-])GH#[0-9]+' "$file"; then
if "$fix"; then
perl -0pi -e 's/(^|[^A-Za-z0-9_\/-])GH#([0-9]+)/$1#$2/g' "$file"
else
echo "$file: contains GH#123-style issue refs; use #123 or owner/repo#123" >&2
failed=1
fi
fi
done
exit "$failed"