Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .agents/skills/coderabbit-pr-gate/SKILL.md
Original file line number Diff line number Diff line change
@@ -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/<id>.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.
51 changes: 51 additions & 0 deletions .agents/skills/night-ops-directive/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 <id> <human-tasks-store>`, 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.
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -498,6 +498,8 @@ These skills are not captain-invocable; load them only at their precise triggers
- `fmx-respond` - load on an `x-mention <request_id>` `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

Expand Down
8 changes: 8 additions & 0 deletions docs/documentation-audiences.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand Down
Loading