Skip to content
Open
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
15 changes: 10 additions & 5 deletions .agents/skills/ask-user-authority/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ This skill is the single owner of the decision policy for no-mistakes ask-user f
`AGENTS.md` section 7 points here and does not restate this procedure.
Finding authority is determined by the criteria below, not by `yolo`.
Firstmate always applies this judgment, decides any finding that is unambiguous toward the accepted design, and escalates only genuinely ambiguous, expanding, or destructive findings.
Captain-facing escalation for findings uses the DO IT / DECIDE / REVIEW filter owned by `captain-hold-lifecycle`.
An unambiguous finding is DO IT: decide it here and do not create a live captain call.
A genuinely ambiguous, expanding, or destructive finding is DECIDE: escalate it as a live ask.
REVIEW is for finished artifacts, not ask-user findings.
A parked or standby item is not a current human decision and is not this skill's finding path.

The implementation worker never decides or answers its own ask-user finding.
It stops at the finding, routes the decision to firstmate, and applies only the decision returned through the active validation gate.
Expand Down Expand Up @@ -50,8 +55,8 @@ Do not relay reviewer labels or gate output as if they settled the decision.

## Classification examples

- Fixing a concrete defect that violates an original acceptance criterion is firstmate's to decide, regardless of implementation difficulty.
- Adding continuous frame-by-frame monitoring when the accepted criterion requested checkpoint proof expands the contract and requires the captain.
- A new finding in the same causal theme requires the captain before another fix round when prior fixes are accreting machinery around a questionable abstraction.
- A genuinely security-sensitive action requires the captain under the stronger existing boundary even if it is otherwise within scope.
- Complex architecture explicitly requested by the captain stays within scope and does not escalate merely because it is complex.
- Fixing a concrete defect that violates an original acceptance criterion is DO IT, regardless of implementation difficulty.
- Adding continuous frame-by-frame monitoring when the accepted criterion requested checkpoint proof expands the contract and is DECIDE.
- A new finding in the same causal theme is DECIDE before another fix round when prior fixes are accreting machinery around a questionable abstraction.
- A genuinely security-sensitive action is DECIDE under the stronger existing boundary even if it is otherwise within scope.
- Complex architecture explicitly requested by the captain stays DO IT and does not escalate merely because it is complex.
16 changes: 14 additions & 2 deletions .agents/skills/captain-hold-lifecycle/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,18 @@ A retirement failure makes the command fail without reversing the already-durabl
Never use `answer` for an evidence-only moot call: `answer` records what the captain said, while `reconcile close` records verified evidence.
A captain-held task closed outside this owner leaves no durable answer, so the completion gate keeps failing until `answer` records the decision the captain actually gave.
Resolved findings, recommendations that need no captain choice, and prose that merely sounds decision-like do not create held tasks.
Captain-facing escalation uses one filter, and this skill owns it:

- DO IT: no genuine human judgment remains; execute or resolve and report minimally, and do not create a live captain call.
- DECIDE: a consequential choice remains after reasonable evidence retrieval, with more than one materially defensible option or a Captain-only truth; hold that as a live ask.
- REVIEW: a finished or review-ready artifact genuinely needs Captain judgment, taste, or approval; hold that as a live ask.
- PARK/HOLD is state, not a current Captain decision.

A parked, standby, or otherwise deferred item must not appear as a current human decision merely because Captain authorization would eventually be required to resume it.
Record that state with `hold --park` (optional `--until` when the park has a date) so the structured hold kind is `parked`.
A live ask still uses `hold` without `--park`.
Unnecessary escalation is observable friction.
`ask-user-authority` maps ask-user findings onto this same filter and does not own a second procedure.
Bearings reads the resulting structured state and must never compensate by scraping historical reports, visual-review artifacts, terminal output, chat, or other prose.

A captain call can be written down twice - as the keyed status decision the fold reads, and as the backlog task held for the captain - and those two records can disagree without either surface saying so.
Expand All @@ -57,8 +69,8 @@ The absence of a routed work item is not a divergence and the guard never requir
## Operating sequence

1. Read the complete investigation result and complete the visual review before declaring either complete.
2. Inventory only genuine unresolved choices that require the captain, and find the task each one gates.
3. Hold that task - or create one captain-held task for the review's open questions - with a concise reason carrying the question and options.
2. Inventory only genuine unresolved choices that require the captain now, and find the task each one gates.
3. Hold that task as a live ask - or create one captain-held task for the review's open questions - with a concise reason carrying the question and options; use `hold --park` for parked or standby state that is not a current ask.
4. Run `complete` with the full captain-held inventory for that review pass.
5. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
6. Close each call only through `answer` (or a channel that feeds `answers`), close a board-requested moot call through evidence-backed `reconcile close`, record a still-active reconciliation through `reconcile note`, use `--until` when the captain defers it, or confirm a channel already closed it.
Expand Down
24 changes: 21 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@ Hard rules, in priority order:
Those paths never authorize forcing, stashing, discarding unlanded work, or hand-writing a project's `AGENTS.md`.
Firstmate may directly edit, create, move, or delete project files or directories only when the captain clearly and concretely approves, in the moment, for a specific project, either a specific operation or a concrete scope whose authorized action needs no inference; firstmate performs exactly that approval with its own file tools, never infers or broadens it, and gains no standing authority, while the force, discard, unlanded-work, merge-authority, destructive, irreversible, and security-sensitive boundaries remain independently in force.
2. **Never merge a PR without the captain's explicit word.**
A project's captain-approved `yolo` posture is the only standing relaxation for merge authority; section 7 owns delivery and merge defaults, while the captain-instruction precedence rule below owns when a current explicit captain instruction overrides a conflicting Firstmate-written standing rule within its exact scope.
A project's captain-approved `yolo` posture is the only standing relaxation for merge authority.
An execution packet may also grant bounded packet-scoped merge authority that expires when that packet closes; that grant is a current explicit captain instruction for conforming in-scope PRs, not standing yolo.
Section 7 owns delivery and merge defaults, while the captain-instruction precedence rule below owns when a current explicit captain instruction overrides a conflicting Firstmate-written standing rule within its exact scope.
3. **Never tear down unlanded work.**
Uncommitted changes are never landed, and `bin/fm-teardown.sh` owns the complete landed-work test.
Never bypass a refusal or use `--force` unless the captain explicitly authorized discarding that work.
Expand Down Expand Up @@ -347,7 +349,7 @@ The path's worker, automated gates, and captain approval remain authoritative:
- **local-only** has the worker stop with a clean ready branch, then waits for the configured merge authority before firstmate uses the guarded fast-forward merge path.

Delivery mode and `yolo` are orthogonal.
`yolo` governs merge authority only: with it off, the captain approves every PR merge and every local-only landing; with it on, firstmate merges green, in-scope work itself.
`yolo` governs standing merge authority only: with it off, the captain approves every PR merge and every local-only landing unless a current packet-scoped grant applies; with it on, firstmate merges green, in-scope work itself.
Never merge a red PR under either setting unless a current explicit captain instruction names the single GitHub check waived through `fm-pr-merge.sh --allow-red`; that attended-only waiver still requires every other check green.
Destructive, irreversible, and security-sensitive merges still escalate.
Without a current explicit captain instruction that states the concrete merge, the green default stands, and standing `yolo` cannot authorize a red merge; section 1 owns when such an instruction overrides a Firstmate-written standing rule within its exact scope.
Expand Down Expand Up @@ -387,6 +389,11 @@ For PR-based ship tasks, the ready signal depends on mode: `no-mistakes` reports
Run `bin/fm-pr-check.sh <id> <PR url>` with the URL copied from that ready signal - it records `pr=` and the forge's `pr_head=` when available in the task's meta and arms the watcher's merge poll.
Tell the captain the PR's full `https://...` URL copied from the worker's ready line or the task's `pr=` metadata, a concise outcome summary, and the no-mistakes risk level when applicable.
A captain instruction to merge is explicit authority; `yolo` is the only standing routine merge authority.
When an execution packet explicitly grants bounded packet-scoped merge authority, firstmate may merge conforming in-scope PRs without another captain merge word while that packet remains open.
To grant it, the packet must say so explicitly, name the bound (authorized repos and objectives), and state that the grant expires when the packet closes.
Verification, review, and independent verification remain mandatory.
Scope expansion and reserved human gates still stop and escalate.
The grant expires with the packet, leaves yolo off, and is not standing global autonomous-merge authority.
For any custom `state/<id>.check.sh` you write yourself, keep it an ordinary single-link mode-`0700` file, print one line only when firstmate should wake, print nothing otherwise, finish before `FM_CHECK_TIMEOUT`, then bind its current bytes with `bin/fm-check-register.sh <id>` before the watcher may execute it.
Retire a custom check only through `bin/fm-check-unregister.sh <id>` (or `bin/fm-teardown.sh` for a spawned task); never hand-compose an `rm` with `$STATE`/`$ID`.

Expand Down Expand Up @@ -494,6 +501,10 @@ Every escalation must stand alone and remain concise.
Lead directly with concrete evidence, then the consequence, options when applicable, and a recommendation.
Use the same evidence-first form for objections or clarifying challenges rather than unsupported deference.

Captain-facing escalation uses the DO IT / DECIDE / REVIEW filter owned by `captain-hold-lifecycle`; `ask-user-authority` maps findings onto that same filter.
A parked, held, or standby item is state, not a current human decision, unless it carries a live ask.
Do not escalate merely because resuming that item would eventually need captain authorization.

Reach the captain immediately for:

- Work ready for their review, with the PR's recorded URL.
Expand All @@ -503,6 +514,11 @@ Reach the captain immediately for:
- Anything destructive, irreversible, or security-sensitive.
- A needed credential or login.

When the primary produces a Captain-facing return that is explicitly intended to be carried back to ChatGPT, write the complete return through `bin/fm-chatgpt-return.sh` before presenting it in chat.
That script is the sole writer, refuses from a secondmate home, and verifies enumerated counts agree with listed items.
Do not write routine status updates or every internal message.
The inbox file is transient transport, not canonical storage.

In a secondmate home, reaching the captain means appending the outcome to the parent channel your charter names; a captain-facing sentence in that home's chat has not been sent, and [`docs/secondmate-parent-channel.md`](docs/secondmate-parent-channel.md) owns which outcomes the home's own scripts deliver there without you.
Do not surface automatic fixes, retries, routine progress, or internal supervision mechanics.
When a routine operational update's specific event requires no action but a response must be sent, reply exactly `Captain, shipshape.` without characterizing the visible session's unrelated decisions.
Expand All @@ -516,7 +532,7 @@ Mention cost as a courtesy when unusually much work is running, but never block
The configured `tasks-axi` backend is the durable queue; the tracked default is `data/backlog.md`.
It tracks work items only, never agents; persistent secondmates never appear as backlog items.
Work routed to a secondmate is recorded in that secondmate home's own backlog, not the main backlog.
A decision is simply a task held for the captain: create the task with `bin/fm-tasks-axi.sh add` when needed, then always hold it through `bin/fm-captain-hold.sh hold <id> --reason "<reason>"`, with `--until <date>` when the captain defers it.
A decision is simply a task held for the captain: create the task with `bin/fm-tasks-axi.sh add` when needed, then always hold it through `bin/fm-captain-hold.sh hold <id> --reason "<reason>"`, with `--until <date>` when the captain defers a live ask, and with `--park` when the item is parked or standby without a live ask.
When a main-side thread such as a pending captain decision or relay reminder is worth durable tracking, file it as its own work item and hold it through that wrapper.
Captain calls discovered by investigations or visual reviews follow `captain-hold-lifecycle`, which owns their completion gate and recorded-answer rules.
When the automatic transition gate applies, dispatch and completion move the item themselves - `bin/fm-spawn.sh` and `bin/fm-teardown.sh` own those transitions and refuse rather than report success without them - so what remains yours is filing the item before dispatch, recording decisions, and keeping notes current; `docs/configuration.md` owns gate applicability and the manual-backend exception.
Expand Down Expand Up @@ -599,6 +615,8 @@ Never infer an override, broaden its scope, apply it by analogy, carry it to ano
Ambiguous scope or conflict still requires one concise clarification before action.
Destructive, irreversible, security-sensitive, discard, and merge actions still require the captain to state that concrete action explicitly; once the captain does so and higher-priority instructions permit it, a conflicting Firstmate-written rule must not rigidly block the action.
Standing `yolo` merge authority is not a substitute for a current explicit captain instruction where an explicit action is required.
A packet-scoped merge grant is a current explicit captain instruction for that packet's conforming in-scope PRs only, and it expires when the packet closes.
It does not become standing global autonomous-merge authority, and yolo remaining off does not cancel it within that exact scope.

## Maintaining this file

Expand Down
Loading