vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: use pr status's positional form in the two remaining --pr examples

Browse source 
#4184 gave 'pr status' a positional PR-number arg (--pr <n> still works, just
no longer the recommended form). docs/tools/forge.md's examples and the
prose section still showed the old --pr form in four places; same one-line
hint baked into every agent's own system prompt (hive-agent/prompts/
system.md). Neither file was touched by #4184 itself -- leftover from my own
#4182 branch that lost the collision to atlas's #4184 (docs/tools/forge.md
and hive-agent/prompts/system.md were the two genuinely non-overlapping bits
of that branch, tracked as a follow-up rather than dropped).

docs/tools/forge-cli.md is clap-generated and doesn't need regenerating --
prose-only doc changes don't touch the clap tree it's derived from.

refs #4182
This commit is contained in:
damocles 2026-09-11 10:57:47 +02:00 • committed by mara
commit 2f792a868c
2 changed files with 14 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/tools/forge.md
View file

@ -24,7 +24,7 @@ markdown-docs > docs/tools/forge-cli.md`.
**Kind-namespaced commands (preferred):** hive-forge groups issue/PR operations **Kind-namespaced commands (preferred):** hive-forge groups issue/PR operations
under `issue` and `pr` parent commands — `hive-forge pr close 42`, under `issue` and `pr` parent commands — `hive-forge pr close 42`,
`hive-forge issue create --title …`, `hive-forge pr status --pr 42`. The `hive-forge issue create --title …`, `hive-forge pr status 42`. The
`pr <verb>` / `issue <verb>` forms validate the number's kind (for example `pr close` `pr <verb>` / `issue <verb>` forms validate the number's kind (for example `pr close`
refuses an issue number, which the old generic `close` couldn't). Run refuses an issue number, which the old generic `close` couldn't). Run
`hive-forge pr --help` / `hive-forge issue --help` for the full subcommand `hive-forge pr --help` / `hive-forge issue --help` for the full subcommand
@ -49,7 +49,7 @@ hive-forge pr close 42 # close a PR (kind-validated)
hive-forge pr reopen 42 # reopen a closed PR (kind-validated) hive-forge pr reopen 42 # reopen a closed PR (kind-validated)
hive-forge issue close 42 # close an issue (kind-validated) hive-forge issue close 42 # close an issue (kind-validated)
hive-forge issue reopen 42 # reopen a closed issue (kind-validated) hive-forge issue reopen 42 # reopen a closed issue (kind-validated)
hive-forge pr status --pr 42 # PR health (mergeable / CI / reviews) hive-forge pr status 42 # PR health (mergeable / CI / reviews)
hive-forge issue create --title "..." --body "..." hive-forge issue create --title "..." --body "..."
# --- flat aliases below remain valid (hidden) --- # --- flat aliases below remain valid (hidden) ---
hive-forge view 42 # title + body + comments (marks thread read) hive-forge view 42 # title + body + comments (marks thread read)
@ -105,7 +105,7 @@ hive-forge lint no-reviewer --reviewer argus # PRs where argus specifically isn
hive-forge lint stale-branches --days 14 # branches with no recent activity, each with its merge outcome (PR #n merged / closed unmerged / no PR) hive-forge lint stale-branches --days 14 # branches with no recent activity, each with its merge outcome (PR #n merged / closed unmerged / no PR)
hive-forge lint assignments # per-assignee open item count hive-forge lint assignments # per-assignee open item count
hive-forge lint unlabeled --scope type # open issues/PRs with no exclusive type/* label (any scope works, e.g. --scope area) hive-forge lint unlabeled --scope type # open issues/PRs with no exclusive type/* label (any scope works, e.g. --scope area)
hive-forge pr status --pr 42 # PR health: mergeable, CI, reviews, last comment (exit 0 = ready) hive-forge pr status 42 # PR health: mergeable, CI, reviews, last comment (exit 0 = ready)
hive-forge pr status --sha <sha> # CI-only fast path for an explicit commit sha hive-forge pr status --sha <sha> # CI-only fast path for an explicit commit sha
hive-forge pr merge 42 # merge (refuses unless mergeable + CI not red + no changes-requested); deletes head branch hive-forge pr merge 42 # merge (refuses unless mergeable + CI not red + no changes-requested); deletes head branch
hive-forge pr merge 42 --method rebase # rebase-merge instead of a merge commit (no squash option) hive-forge pr merge 42 --method rebase # rebase-merge instead of a merge commit (no squash option)
@ -145,7 +145,7 @@ distinct output shape — pick by what you need:
| One specific comment by its id | `comment-show <id>` | single comment | | One specific comment by its id | `comment-show <id>` | single comment |
| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list |
| The code change | `pr diff <n>` | unified diff | | The code change | `pr diff <n>` | unified diff |
| Is this PR ready to merge — mergeable + CI + reviews | `pr status --pr <n>` | health view; exit code = merge-readiness | | Is this PR ready to merge — mergeable + CI + reviews | `pr status <n>` | health view; exit code = merge-readiness |
| The review verdicts + inline review comments | `pr reviews <n>` | review list | | The review verdicts + inline review comments | `pr reviews <n>` | review list |
Rule of thumb: **`view` first** when you're about to act on a thread (it Rule of thumb: **`view` first** when you're about to act on a thread (it
@ -189,19 +189,20 @@ commits straight to `main`.
### `pr status` ### `pr status`
One-stop PR health view (`--pr <n>`): mergeable state, CI checks, One-stop PR health view (`<n>`, positional — `--pr <n>` also still works):
requested reviewers + review verdicts, and the last-comment timestamp — mergeable state, CI checks, requested reviewers + review verdicts, and the
the things you need to know whether a PR is ready to merge (CI must pass last-comment timestamp — the things you need to know whether a PR is ready
before merge). `--sha <sha>` is a CI-only fast path for a raw commit. to merge (CI must pass before merge). `--sha <sha>` is a CI-only fast path
for a raw commit.
A failing/erroring CI context prints its job link. The process exit code A failing/erroring CI context prints its job link. The process exit code
is a **merge-readiness** verdict for `--pr` (0 only when CI is green AND is a **merge-readiness** verdict for a PR number (0 only when CI is green
the PR is mergeable AND no review requests changes), so it composes: AND the PR is mergeable AND no review requests changes), so it composes:
`hive-forge pr status --pr 42 && echo ready`. `--sha` mirrors the CI `hive-forge pr status 42 && echo ready`. `--sha` mirrors the CI
verdict alone. verdict alone.
``` ```
hive-forge pr status --pr 42 hive-forge pr status 42
# PR #42: feat(...): ... # lint:allow: sample CLI output, not a real tag # PR #42: feat(...): ... # lint:allow: sample CLI output, not a real tag
# state: open (mergeable: yes) # state: open (mergeable: yes)
# CI: e39a87ea3949: ✅ success (1 context(s)) # CI: e39a87ea3949: ✅ success (1 context(s))

2
hive-agent/prompts/system.md
View file

@ -35,7 +35,7 @@ Claude session (OAuth credentials) lives at `/root/.claude/` and persists across
**Code forge**: a private Forgejo (base URL in `$HIVE_FORGE_URL`) is available when `/agents/{label}/state/forge-token` exists. You have your own user account (named `{label}`). Use `hive-forge` (see below) for all forge operations — issues, PRs, comments, labels, etc. For git operations use plain `git` directly against `$HIVE_FORGE_URL/<org>/<repo>.git` (credentials are pre-configured). **Code forge**: a private Forgejo (base URL in `$HIVE_FORGE_URL`) is available when `/agents/{label}/state/forge-token` exists. You have your own user account (named `{label}`). Use `hive-forge` (see below) for all forge operations — issues, PRs, comments, labels, etc. For git operations use plain `git` directly against `$HIVE_FORGE_URL/<org>/<repo>.git` (credentials are pre-configured).
The `hive-forge` CLI is the supported interface to the Forgejo — issues, PRs, comments, labels, reviews, CI status, attachments, triage (`lint`). **Discover the verb list and each verb's full signature with `hive-forge --help` and `hive-forge <verb> --help`** rather than memorising them. The active repo is whichever git checkout you're standing in (inferred from the `origin` remote), or pass `-r <repo>` (global flag, works before or after the verb) to target a different one explicitly — there's no single hardcoded default repo, so don't assume one. A few conventions `--help` won't surface: **never `curl` the forge** — the CLI handles auth and is the only supported path; to check a PR's CI + mergeability use `hive-forge pr status --pr <n>` (or `--sha <commit>` for a CI-only fast path; exit code is a merge-readiness verdict), not curl. `--body-file -` reads the body from stdin, so a HEREDOC works for multi-line comments/issues: `hive-forge comment <num> --body-file - <<EOF ... EOF`. `hive-forge pr create --title "..." --head <branch> [--push]` opens a PR and prints its URL; `--push` `git push`es the head branch first (default remote `forge`). Forge notifications are delivered via the internal message daemon (sender `forge`), not polling. A `forge` notification stays unread **on the forge** until you actually read its thread — viewing the referenced issue/PR with `hive-forge comments <n>` or `view <n>` marks that notification read (it's the forge's own read-state, not a local mirror). So when a `forge` message points you at a thread, read the thread to clear the notification instead of letting the same one linger and re-surface. (`hive-forge comment` does the opposite — it _refuses_ to post to a thread with unread activity until you've read it, so read first, then comment.) The `hive-forge` CLI is the supported interface to the Forgejo — issues, PRs, comments, labels, reviews, CI status, attachments, triage (`lint`). **Discover the verb list and each verb's full signature with `hive-forge --help` and `hive-forge <verb> --help`** rather than memorising them. The active repo is whichever git checkout you're standing in (inferred from the `origin` remote), or pass `-r <repo>` (global flag, works before or after the verb) to target a different one explicitly — there's no single hardcoded default repo, so don't assume one. A few conventions `--help` won't surface: **never `curl` the forge** — the CLI handles auth and is the only supported path; to check a PR's CI + mergeability use `hive-forge pr status <n>` (or `--sha <commit>` for a CI-only fast path; exit code is a merge-readiness verdict), not curl. `--body-file -` reads the body from stdin, so a HEREDOC works for multi-line comments/issues: `hive-forge comment <num> --body-file - <<EOF ... EOF`. `hive-forge pr create --title "..." --head <branch> [--push]` opens a PR and prints its URL; `--push` `git push`es the head branch first (default remote `forge`). Forge notifications are delivered via the internal message daemon (sender `forge`), not polling. A `forge` notification stays unread **on the forge** until you actually read its thread — viewing the referenced issue/PR with `hive-forge comments <n>` or `view <n>` marks that notification read (it's the forge's own read-state, not a local mirror). So when a `forge` message points you at a thread, read the thread to clear the notification instead of letting the same one linger and re-surface. (`hive-forge comment` does the opposite — it _refuses_ to post to a thread with unread activity until you've read it, so read first, then comment.)
Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/agents/{label}/state/<descriptive-name>` and `send` a short pointer ("dropped the cluster audit in /agents/{label}/state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The operator can read your state from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's state directly — coordinate through shared space or a common parent. Keep messages short — a few sentences each. For anything big (file listings, long diffs, transcripts, analysis): write the payload to `/agents/{label}/state/<descriptive-name>` and `send` a short pointer ("dropped the cluster audit in /agents/{label}/state/cluster-audit-2026-05.md, headline: 3 nodes over 80% mem"). The operator can read your state from the host as `/agents/{label}/state/`. Sub-agent peers can't read each other's state directly — coordinate through shared space or a common parent.