diff --git a/.agents/skills/coderabbit-pr-gate/SKILL.md b/.agents/skills/coderabbit-pr-gate/SKILL.md new file mode 100644 index 0000000000..4276293c4c --- /dev/null +++ b/.agents/skills/coderabbit-pr-gate/SKILL.md @@ -0,0 +1,46 @@ +--- +name: coderabbit-pr-gate +description: >- + Agent-only policy for reacting to CodeRabbit's PR review advice, beyond a bare pass/fail check, + and for handling CodeRabbit's rate-limiting without treating it as review failure. + Load before treating a public registered repo's PR as ready to merge or teardown when + CodeRabbit is enabled on it, and whenever a CodeRabbit review comment or rate-limit response + needs a reaction. +user-invocable: false +metadata: + internal: true +--- + +# CodeRabbit review-gate routine + +This skill applies to every public registered repo with CodeRabbit enabled. +It covers reacting to CodeRabbit's actual review content, not just whether its check reports pass or fail. +The watcher's PR poll already wakes firstmate on a new bot review comment (see `state/.pr-review-seen` in `AGENTS.md` section 2); this skill is the reaction policy layered on top of that wake, not a second wake mechanism. + +## Policy + +A green CodeRabbit check is necessary but not sufficient. +CodeRabbit can pass a PR while still leaving actionable suggestion comments (bugs, security notes, missed edge cases) that a bare status check does not surface. +Before treating a PR as merge-ready on a CodeRabbit-enabled repo: + +1. Read CodeRabbit's review comments on the PR (via `gh-axi`), not just its check conclusion. +2. Classify each comment: a genuine actionable finding (correctness, security, a real bug) versus style-only or already-addressed noise. +3. Route actionable findings the same way any other review finding is routed under `AGENTS.md` section 7 and `ask-user-authority`. + A routine, reversible fix within accepted task criteria is autonomous under `yolo`; anything that would expand scope, or is destructive, irreversible, or security-sensitive, escalates to the captain as a decision rather than being silently applied or silently ignored. +4. Do not merge past an unresolved actionable CodeRabbit finding without either fixing it or getting an explicit captain or `yolo`-authorized decision to proceed anyway. + +## Rate-limit handling + +CodeRabbit rate-limits review requests on busy repos or accounts. +A rate-limited or not-yet-reviewed state is not a failure and not silence to route around: + +- Treat a CodeRabbit rate-limit or pending-review response as a `paused:`-class external wait (`AGENTS.md` section 8's distinction between `paused:` and `blocked:`), not a `blocked:` or `failed:` one. +- Re-check on a bounded backoff rather than polling tightly or repeatedly re-requesting a review, which extends the rate limit; let the watcher's own wake cadence carry the recheck instead of arming a dedicated poll loop for it. +- If CodeRabbit still has not produced a review after a reasonable number of backoff cycles, do not block merge readiness on it indefinitely. + Report the stalled review to the captain as evidence rather than silently merging without it or silently waiting forever. +- Never spam re-requests at CodeRabbit to work around a rate limit; that worsens the limit for every repo sharing the account. + +## Scope + +Applies to every public registered repo, including non-owned repos dispatched to via a fork (see `AGENTS.md` section 7 and `night-ops-directive`). +A private or `local-only` project without CodeRabbit enabled is unaffected; this routine only activates where CodeRabbit review is live. diff --git a/.agents/skills/night-ops-directive/SKILL.md b/.agents/skills/night-ops-directive/SKILL.md new file mode 100644 index 0000000000..46184ea8e6 --- /dev/null +++ b/.agents/skills/night-ops-directive/SKILL.md @@ -0,0 +1,51 @@ +--- +name: night-ops-directive +description: >- + Agent-only policy for a captain-authorized autonomous work session across a federated task + store or backlog with no captain present to answer routine questions. + Load when the captain authorizes autonomous, unattended, or overnight work across a backlog + or federated task store, or when reconciling that a standing autonomous-dispatch directive is + still active. +user-invocable: false +metadata: + internal: true +--- + +# Autonomous overnight dispatch + +This skill is the standing policy for a captain-authorized stretch of unattended work. +Work through a federated task store or backlog without pausing for questions that `AGENTS.md` section 7's `yolo` authority already answers, and without collapsing into hands-on implementation. + +## Standing directive + +- Firstmate stays a delegator for the whole session, including overnight: read state, decide routing, write briefs, spawn crewmates, supervise, and report. + Do not personally hand-edit project files, grind through binary or database debugging, or `git diff` a project clone to do a crewmate's job. + If a bounded, low-risk edit to firstmate's own shared tracked material is genuinely faster to author directly than to brief, treat that as the exception, not the norm. +- Prefer stacked PRs for multi-step work over delaying a wave of dispatch. + Do not hold otherwise ready work waiting for an unrelated PR to land unless section 7's serialization test is met. +- Firstmate owns its own wake cadence for this directive. + `ScheduleWakeup` and `CronCreate` are blocked for the primary session by `bin/fm-subagent-pretool-check.sh`; do not attempt either. + The watcher heartbeat (`bin/fm-watch.sh`, `FM_HEARTBEAT` default 600s, doubling per idle heartbeat up to `FM_HEARTBEAT_MAX` default 7200s, resetting on any actionable wake) is the durable wake mechanism and needs no separate timer. +- Infra and migration work discovered in the task store is in scope for this directive; do not gate it away as out-of-scope by default. +- Fork-first pushes for non-captain-writable default branches are already enforced automatically by the ship brief scaffold (`AGENTS.md` section 11); no separate action is needed here beyond trusting that mechanism. +- Pace dispatch waves against CI and review-bot rate limits (see `coderabbit-pr-gate` for the CodeRabbit-specific reaction routine) rather than firing every ready item at once. + +## Yolo scope for this directive + +`AGENTS.md` section 7's `yolo` reversibility test applies: the qualifying test for a routine `yolo`-covered gate, including a PR merge, is reversibility, meaning whether it can be undone if it turns out wrong. +This directive does not expand `yolo` past section 7's boundaries: destructive, irreversible, and security-sensitive choices remain captain-only regardless of how autonomous the session is. + +## Human-only task triage and the promotion path + +A federated task-store item that names a physical, financial, credential, interpersonal, or otherwise non-code action is not crewmate work. +Route it to a dedicated human-tasks-only federated store rather than leaving it mixed into the code-mappable backlog or attempting to work it. +Move a qualifying item with `bd transfer `, not `bd promote`, which only promotes a wisp to a permanent bead within the same store. +`bd transfer` closes the source row with a pointer to the destination, creates the new row in the destination store, and links the two with a `supersedes` edge so the move stays queryable from either side. + +If the destination human-tasks store is not yet functional, do not hand-debug its provisioning personally beyond one bounded verification attempt. +File the blocker as a backlog item and keep triaging code-mappable work through the normal task lifecycle instead. + +## Session-boundary notes + +This directive persists across restarts because it lives in tracked `AGENTS.md` and this skill, not in conversation memory. +A restart mid-directive is a non-event: reconcile fleet state per section 5 and resume dispatch, it does not require the captain to re-issue the directive. diff --git a/AGENTS.md b/AGENTS.md index 378cda3dad..11c113800b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -290,7 +290,7 @@ The path's worker, automated gates, and captain approval remain authoritative: Delivery mode and `yolo` are orthogonal. With `yolo` off, the captain owns ask-user findings, PR merges, and local-only merge approval. -With `yolo` on, firstmate decides routine gates only within the captain's original request and accepted task criteria, and merges only green or otherwise approved work. +With `yolo` on, firstmate decides routine gates only within the captain's original request and accepted task criteria, and merges only green or otherwise approved work; the qualifying test for a routine gate, including a PR merge, is reversibility, meaning whether it can be undone if it turns out wrong. Standing `yolo` authority never approves an ask-user Fix that would materially expand that product or engineering contract; destructive, irreversible, and security-sensitive choices remain stronger captain boundaries. Complexity alone is not expansion: a difficult correction genuinely required by accepted intent, including explicitly requested complex architecture, remains autonomous. Before deciding any ask-user finding, load `ask-user-authority`; the implementation worker never answers its own finding. @@ -498,6 +498,8 @@ These skills are not captain-invocable; load them only at their precise triggers - `fmx-respond` - load on an `x-mention ` `check:` wake to handle the mention, on an `x-mode-error ...` `check:` wake to report the X-mode configuration blocker, on a `public-followup ...` `check:` wake or a startup-surfaced public commitment, and on any milestone or terminal wake for an X-mode-linked task before posting its completion follow-up; relevant only when X mode is on. - `firstmate-codexapp` - load before coordinating a visible Codex Desktop thread, evaluating a Codex App backend request, or reconciling Codex Desktop host-tool smoke evidence for Firstmate work. - `firstmate-coding-guidelines` - load before changing firstmate's shared, tracked material, as defined by section 1's list, whether editing directly or briefing a crewmate for a firstmate-repo task. +- `night-ops-directive` - load when the captain authorizes autonomous, unattended, or overnight work across a backlog or federated task store, or when reconciling that a standing autonomous-dispatch directive is still active. +- `coderabbit-pr-gate` - load before treating a public registered repo's PR as ready to merge or teardown when CodeRabbit is enabled on it, and whenever a CodeRabbit review comment or rate-limit response needs a reaction. ## 14. X mode diff --git a/docs/documentation-audiences.json b/docs/documentation-audiences.json index 3440e755f4..3f5476f618 100644 --- a/docs/documentation-audiences.json +++ b/docs/documentation-audiences.json @@ -123,6 +123,10 @@ "path": ".agents/skills/bootstrap-diagnostics/SKILL.md", "audience": "agent-runtime" }, + { + "path": ".agents/skills/coderabbit-pr-gate/SKILL.md", + "audience": "agent-runtime" + }, { "path": ".agents/skills/decision-hold-lifecycle/SKILL.md", "audience": "agent-runtime" @@ -151,6 +155,10 @@ "path": ".agents/skills/harness-adapters/SKILL.md", "audience": "agent-runtime" }, + { + "path": ".agents/skills/night-ops-directive/SKILL.md", + "audience": "agent-runtime" + }, { "path": ".agents/skills/project-management/SKILL.md", "audience": "agent-runtime"