diff --git a/claude-plugins/.claude-plugin/marketplace.json b/claude-plugins/.claude-plugin/marketplace.json index 96cec444..24f89143 100644 --- a/claude-plugins/.claude-plugin/marketplace.json +++ b/claude-plugins/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "plugins": [ { "name": "base", - "description": "hyperhive's base plugin - skills every agent needs, regardless of role. Currently: state-hygiene (read-before-write discipline and dated-archive convention for durable agent notes/state files). Add a new skill here (not a new plugin) if it applies to all agents; give it its own specialized plugin if it doesn't.", + "description": "hyperhive's base plugin - skills every agent needs, regardless of role. Currently: state-hygiene (read-before-write discipline and dated-archive convention for durable agent notes/state files) and forge-workflow (safe forge CLI habits - never call the API directly, @-mention subscribes to a thread, ci-rerun not empty commits, verify before claiming ready, never self-merge). Add a new skill here (not a new plugin) if it applies to all agents; give it its own specialized plugin if it doesn't.", "source": "./plugins/base", "category": "productivity" }, diff --git a/claude-plugins/plugins/base/skills/forge-workflow/SKILL.md b/claude-plugins/plugins/base/skills/forge-workflow/SKILL.md new file mode 100644 index 00000000..f9ba8a93 --- /dev/null +++ b/claude-plugins/plugins/base/skills/forge-workflow/SKILL.md @@ -0,0 +1,66 @@ +--- +name: forge-workflow +description: Enforces safe, low-noise habits when working with a git forge (issues, PRs, comments, reviews) through its CLI wrapper - never call the forge API directly, understand that an @-mention subscribes someone to the whole thread, retrigger CI without empty commits, verify a PR is actually mergeable before claiming it's ready, and never merge your own PR. Use this whenever you are about to comment on, review, or merge a PR/issue, or before telling someone a PR is ready. +--- + +# Forge Workflow + +Working with a code forge (issues, PRs, reviews, CI) is mostly about not +generating noise and not skipping steps that look optional but aren't. + +## Never call the forge API directly + +If your environment provides a CLI wrapper for forge operations, use it for +every issue/PR/comment/label/review action instead of raw HTTP calls. The +wrapper is the one place auth, rate limits, and response shape are handled +correctly - going around it (e.g. hand-rolled requests) is how credentials +leak into logs and how you silently miss the wrapper's read-tracking or +retry behavior. + +## `@name` subscribes, plain name doesn't + +- Writing `@name` in a comment **notifies and subscribes that person to the + whole thread** - every future comment on it pings them too. Only do this + when you actually want them pulled in: asking them a direct question, + requesting review, handing off the next action. +- Referring to someone in the **third person** - describing what they did, + attributing work - use their plain name, no `@`. An unnecessary `@` trains + people to skim-ignore mentions, which defeats the point of the ones that + matter. + +## Retrigger CI without noise commits + +Never push an empty commit just to force a CI rerun - it pollutes history +and doesn't even help if the failure was a real code problem. Use your +forge tooling's dedicated rerun/re-dispatch verb instead. If CI is failing +for an infrastructure reason (runner down, flaky network) rather than a +code problem, say so and wait rather than spamming reruns. + +## Verify before claiming "ready" + +Before telling anyone a PR is ready to merge, actually check its +mergeability + CI state + review state through the tooling - don't infer +readiness from "I pushed and CI looked fine last I saw." State can change +after your last look (a new commit, a reviewer's request-changes, a rebase +conflict). A quick status check costs nothing and prevents a false "ready" +that wastes someone's time acting on it. + +## Never self-merge + +Merging is the reviewer's/operator's call, not the author's, regardless of +how confident you are in your own change. Push, open the PR, respond to +review - then wait. If you have merge access, using it on your own PR is +out of bounds even when it's "obviously fine." + +## Read before you comment + +If a thread has activity you haven't read yet, read it first. Commenting +over something you haven't seen risks repeating a question that was just +answered, missing new instructions, or talking past a correction. Many +forge tools enforce this by refusing to post to an unread thread - treat +that as a feature, not friction to route around. + +If your environment ships its own hive-wide/repo-wide forge conventions +doc (commit style, review checklist, etc.), treat that as the canonical +source and this skill as a reminder to follow it - don't duplicate its +rationale into your own notes either.