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:
parent
0268ba894c
commit
058134d81c
10 changed files with 198 additions and 19 deletions
69
AGENTS.md
69
AGENTS.md
|
|
@ -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 -->
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
36
docs/AGENT_SIGNING.md
Normal 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.
|
||||
|
|
@ -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. |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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))
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
39
scripts/gh-body-lint
Executable 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"
|
||||
Loading…
Add table
Add a link
Reference in a new issue