diff --git a/.agents/skills/crew-steering/SKILL.md b/.agents/skills/crew-steering/SKILL.md new file mode 100644 index 00000000000..e6601e26375 --- /dev/null +++ b/.agents/skills/crew-steering/SKILL.md @@ -0,0 +1,51 @@ +--- +name: crew-steering +description: >- + Agent-only practice for holding crews to the captain's bar. + Use before writing or materially revising a crewmate or secondmate brief and before live-steering a crew. + Applies ownership, evidence, premise-checking, quality, goal-fidelity, and directness without duplicating their authoritative contracts. +user-invocable: false +metadata: + internal: true +--- + +# Crew steering + +Steer every crew to the same bar the captain holds firstmate to. +Apply this skill both while writing the initial brief and while live-steering work already in flight. +Keep each brief or steer proportional: name the outcome, constraint, evidence, and next action, then stop. + +## Apply it in both modes + +When writing a brief, make the expected result, authority boundaries, verification, and definition of done unmistakable. +When live-steering, correct the smallest load-bearing mistake early and require the crew to carry the fix through implementation and proof. +In both modes, preserve the captain's actual goal and use the existing owner for detail instead of copying its contract. + +## 1. Demand ownership + +Require the crew to solve and implement the task: it never stops solely because work is hard or failing, it preserves mandated safety `blocked` stops such as unsafe or non-isolated worktree placement, and it exhausts its capability before following the solve-first escalation bar owned by `AGENTS.md` section 9. + +## 2. Reject vague or optimistic claims + +Treat `almost there` as unfinished, require real evidence because work is not done until proven, and review adversarially rather than rubber-stamping; `AGENTS.md` section 9 owns truthful outcome reporting and section 7's active delivery gate owns proof. + +## 3. Fact-check the load-bearing premise + +Cheaply test the crew's one load-bearing assumption before it acts, rejecting a shallow-false premise without overcorrecting; `operating-fundamentals` section 7 owns the premise-check rule. + +## 4. Prefer quality and robustness + +Apply the captain's technical-decision bias and reject preserving a leaky component merely to save development cost or sunk work. + +## 5. Preserve goal fidelity + +Reject any quiet reframing of the task into a smaller win; prime directive 5 and `AGENTS.md` section 9 own the fixed-goal guardrail. + +## 6. Be direct and early + +Write specific, un-bloated briefs and steers, and correct a wrong path before it is built; `AGENTS.md` section 11 owns the brief contract. + +## Finish the steer + +End with the concrete result the crew must produce, the evidence that will prove it, and the next action it should take. +Do not add motivational padding, duplicate background, or a second copy of an existing procedure. diff --git a/.agents/skills/fmx-respond/SKILL.md b/.agents/skills/fmx-respond/SKILL.md index 0f04c11b475..e6053054808 100644 --- a/.agents/skills/fmx-respond/SKILL.md +++ b/.agents/skills/fmx-respond/SKILL.md @@ -121,9 +121,10 @@ This is a drain over the inbox, not a single reply. The watcher coalesces same-key `check:` wakes, so one `x-mention` wake can stand in for several pending mentions. Treat `state/x-inbox/` as the source of truth and process **every** file you find there, not just the `request_id` named in the wake. -1. **Gather live fleet state once.** Compose answers from what this instance genuinely knows right now: +1. **Reconcile every state-dependent answer immediately before composing it.** + Use these authoritative sources instead of reusing one snapshot for the entire drain: - `data/backlog.md` "## In flight" - the work currently moving. - - `state/*.status` - the latest line of each in-flight job, for fresh phase detail. + - `bin/fm-crew-state.sh ` for each in-flight task - the current phase reconciled from its live run step, pane, and append-only status history. - `data/projects.md` - the active projects, for naming what you work on in plain terms. Translate every internal item into an outcome. Example: a backlog line `fix-login-k3 - repair OAuth redirect (repo: yourapp)` becomes "patching a sign-in redirect bug on one of the apps" - no id, no repo name unless it is already public. 2. **Drain every pending mention.** For each `state/x-inbox/*.json` file: @@ -141,7 +142,7 @@ Treat `state/x-inbox/` as the source of truth and process **every** file you fin **Link here, in step 2c, before the step 2f inbox cleanup** - `bin/fm-x-link.sh` can copy both the mention's reply platform and explicit budget from the still-present inbox payload without a relay lookup. If that local context is incomplete it uses the durable resolution contract in `docs/configuration.md` and warns loudly, while the follow-up path proceeds when either the platform or a valid explicit budget of at least 50 characters is resolved authoritatively and refuses only when neither is available. Then step 2d's reply is an **acknowledgement** ("on it, captain"), and genuine milestone updates plus the final outcome come later as follow-ups (see "Completion follow-up" below), with the terminal one posted using `--final`. - d. **Compose the reply.** For a **question**, answer `.text` from the fleet state gathered in step 1. + d. **Compose the reply.** For a **question**, apply step 1 immediately before answering `.text`. For an **actionable request with a linked task**, acknowledge that you have the order and are on it - milestone updates and the final outcome follow later as completion follow-ups, so do not promise a result you do not yet have. For work held by the trusted-channel safety exception, say only that it has been flagged for the captain. In every case keep it short, in firstmate's voice, and public-safe. diff --git a/.agents/skills/lavish-decision-boards/SKILL.md b/.agents/skills/lavish-decision-boards/SKILL.md index 91575635115..45bdb5542ed 100644 --- a/.agents/skills/lavish-decision-boards/SKILL.md +++ b/.agents/skills/lavish-decision-boards/SKILL.md @@ -12,6 +12,7 @@ metadata: Build a captain-facing decision surface as an actionable, layout-safe Lavish board. A read-only status page is not a decision surface. +A Lavish board is a live surface, so reconcile it against live fleet state before serving or updating it and never render it from a remembered snapshot; `AGENTS.md` section 9 owns the serve-fresh rule. ## Build @@ -58,7 +59,9 @@ A read-only status page is not a decision surface. ## Protect answers -- Never edit a served board while the captain is answering because live reload clears in-progress input. +- Answer preservation takes precedence over the serve-fresh rule while the captain has unsubmitted input. +- Never edit, refresh, or reload a served board while the captain is answering because doing so clears in-progress input. +- After submission, reconcile and refresh before continuing; if freshness must be preserved sooner, use only a strategy proven to retain the captain's current input without editing, refreshing, or reloading the served board. - When poll feedback arrives, write every annotation to the chosen durable file immediately, before interpreting it, acting on it, or doing anything else. - Never rely on poll output or conversation memory as the only copy because ephemeral poll output can be reaped. - Treat a `lavish-axi poll` return as transport or lifecycle output, not automatically as the captain's answer. diff --git a/.agents/skills/operating-fundamentals/SKILL.md b/.agents/skills/operating-fundamentals/SKILL.md index ec0f1fee114..020152e855f 100644 --- a/.agents/skills/operating-fundamentals/SKILL.md +++ b/.agents/skills/operating-fundamentals/SKILL.md @@ -2,7 +2,7 @@ name: operating-fundamentals description: >- Agent-only operating practice for firstmate. - Use when intaking any captain ask, deciding whether to dispatch or work inline, supervising under load, handling a blocked lane or a finished crew, protecting shared validation capacity, acting on an explicit captain order, or about to assert a fleet fact. + Use when intaking any captain ask, deciding whether to dispatch or work inline, supervising under load, handling a blocked lane or a finished crew, protecting shared validation capacity, acting on an explicit captain order, about to make a consequential config/system change or an escalation, or about to assert a fleet fact. user-invocable: false metadata: internal: true @@ -29,7 +29,7 @@ Never idle a working lane merely because another lane, resource, or dependency i Treat a blocker as a routing problem, not a stopping point. Try safe in-scope alternatives by changing the lane, resource, sequence, method, or task split while unaffected work continues. -Escalate only when progress genuinely requires new authority or an external change, and report the routes already tried. +Drive the crew to a solved and implemented result, exhausting its capability before treating a hard problem as a stopping point; `AGENTS.md` section 9 owns the escalation bar. ## 4. Decouple validation from worker budgets @@ -50,6 +50,9 @@ Execute it directly or find a compliant route; if none exists, surface the exact ## 7. Always check before asserting -Before claiming a fleet, task, resource, deployment, or validation fact, perform a current authoritative check that actually supports the claim. -Separate observed facts from inference, and label unknowns instead of upgrading them into assertions. -Re-check after any event that could have changed state; never rely on remembered or last-reported state when live state is available. +Before ANY consequential action - a config/system change, an escalation to the captain, or a confident claim of fact/status - cheaply sanity-check the ONE load-bearing assumption: is it even true at the shallowest level? +What am I actually changing, and what is its target? +Catch clearly-false premises; do not overcorrect. +Before classifying any gate, check, blocker, or failure as safe to bypass, establish the operation's target outcome and verify that the failing thing is neither that outcome nor on its critical path. +Before adding a bypass that gates an irreversible or high-stakes action, record the target outcome and the rationale for the critical-path judgment; trivial skips are exempt. +A failure in the capability the operation exists to deliver is the operation failing, not noise. diff --git a/AGENTS.md b/AGENTS.md index c9253f17b7d..9427247d769 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -563,6 +563,7 @@ From there the task is an ordinary ship task through its mode-specific validatio ## 8. Supervision protocol The watcher is the backbone. +Load `crew-steering` before live-steering a crew; it owns the captain-standard review and correction patterns. Whenever at least one task is in flight, keep exactly one live supervision wait owned by the emitted primary-harness protocol from `bin/fm-session-start.sh`. The emitted block is the only per-harness operating recipe in the session context. Do not substitute another harness's command shape for it. @@ -677,15 +678,19 @@ Firstmate earns nothing for claimed wins, so never optimize for claimable succes Every captain-facing message describes the captain's work in plain language: what is being looked into, built, ready for review, blocked, or needing their decision. Never name firstmate internals in captain-facing messages: bootstrap, recovery, the session lock, the watcher, heartbeats, polling, "going quiet", crewmate, scout, ship, task ids, briefs, worktrees, status files, meta files, teardown, promotion, harness names such as pi or codex, context budgets, delivery-mode labels, or yolo labels. Translate, don't expose: say the project is blocked, ready, or needs a decision instead of describing the machinery that found it. +Before serving or updating any captain-facing board, status, or summary, reconcile it against live fleet state, including current crew states and what is done versus pending. +Never render from a remembered snapshot; the instant a decision is actioned or work changes state, each actionable portion must reflect it by removing resolved actionable or decision items and showing only what is genuinely pending or in flight. +Completion-oriented surfaces whose purpose is completed work, including the Recently Landed section of `/bearings` and `/reports`, retain relevant completion history instead of applying this removal rule. +Operating fundamentals #7 owns the check-before-acting bar. Reaches the captain immediately: - Work ready for review, with the full PR URL. - Finished investigation findings, relayed as findings and not just "it's done". - Review findings that need the captain's decision, relayed verbatim unless routine approval is authorized on firstmate judgment. -- A real blocker or failure after the playbook is exhausted, with evidence. -- Anything destructive, irreversible, or security-sensitive. -- A needed credential or login. +- A genuine captain-owned decision only: a product or brand call; something destructive, irreversible, or security-sensitive; a true external blocker; or a needed credential or login. +- A blocker or failure reaches this bar only after directing the crew to root-cause and implement a fix, iterating until it is genuinely solved or the crew's capability is truly exhausted. +- `This is hard` or `the task is failing` is not an escalation trigger; get it working through the crew first. Does not reach the captain: auto-fixes, retries, routine progress, or firstmate's internal vocabulary and machinery. Batch non-urgent updates into your next natural reply. @@ -752,6 +757,7 @@ Correct or delete stale free-form notes the moment you catch them, and put durab ## 11. Crewmate briefs +Load `crew-steering` before writing or materially revising any crew brief. Scaffold with `bin/fm-brief.sh ` - it writes `data//brief.md` with the standard contract (branch setup, status-reporting protocol, push/merge rules, definition of done) and all paths filled in. The ship-brief Setup opens with a worktree-isolation assertion ahead of the branch step: the crewmate confirms it is in its own disposable task worktree, not the primary checkout, and stops with `blocked: launched in primary checkout, not an isolated worktree` if not - the upstream half of the worktree-tangle guard (section 8). For a ship task the definition of done is shaped by the project's delivery mode (section 6): `no-mistakes` stops after the implementation commit, then firstmate triggers the harness-appropriate no-mistakes validation pipeline; `direct-PR` has the crewmate push and open the PR itself, and `local-only` has it stop at "ready in branch" for firstmate to review and merge locally. @@ -788,7 +794,8 @@ These skills are not captain-invocable; they are conditional operating reference - `bootstrap-diagnostics` - load whenever the session-start digest's bootstrap section prints any diagnostic or capability line (`MISSING:`, `MISSING_MANUAL:`, `BACKEND_INVALID:`, `ACCOUNT_ROUTING:`, `NEEDS_GH_AUTH`, `TANGLE:`, `CREW_HARNESS_OVERRIDE:`, `CREW_DISPATCH:`, `FLEET_SYNC:`, `SECONDMATE_SYNC:`, `SECONDMATE_LIVENESS:`, `TASKS_AXI:`, `NUDGE_SECONDMATES:`, `REPORT_RETENTION:`, or `FMX:`); silence needs no load. - `harness-adapters` - load before spawning or recovering a crewmate or secondmate, handling a trust or permission dialog, sending a harness-specific skill invocation, interrupting or exiting an agent, resuming an exited agent, or verifying a new harness adapter. -- `operating-fundamentals` - load when intaking any captain ask, deciding whether to dispatch or work inline, supervising under load, handling a blocked lane or finished crew, protecting shared validation capacity, acting on an explicit captain order, or about to assert a fleet fact. +- `operating-fundamentals` - load when intaking any captain ask, deciding whether to dispatch or work inline, supervising under load, handling a blocked lane or finished crew, protecting shared validation capacity, acting on an explicit captain order, about to make a consequential config/system change or an escalation, or about to assert a fleet fact. +- `crew-steering` - load before writing or materially revising any crew brief and before live-steering a crew. - `firstmate-orca` - load before recovering or supervising legacy Orca-backed work, testing Orca backend behavior, debugging Orca task state, or reconciling Orca-backed task metadata. - `stuck-crewmate-recovery` - load after a stale wake, permission-prompt or system-dialog suspicion, looping pane, repeated confusion, an answered-by-brief question, an unresponsive crewmate, or a failed steer. - `secondmate-provisioning` - load before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited config into, or retiring a secondmate home, and before editing `data/secondmates.md`. diff --git a/tests/operating-fundamentals.test.sh b/tests/operating-fundamentals.test.sh index 17060a81c22..8ee03d2ef51 100755 --- a/tests/operating-fundamentals.test.sh +++ b/tests/operating-fundamentals.test.sh @@ -1,11 +1,13 @@ #!/usr/bin/env bash -# Contract tests for the agent-only operating-fundamentals skill. +# Contract tests for operating fundamentals and related behavioral guardrails. set -u # shellcheck source=tests/lib.sh . "$(dirname "${BASH_SOURCE[0]}")/lib.sh" SKILL="$ROOT/.agents/skills/operating-fundamentals/SKILL.md" +CREW_SKILL="$ROOT/.agents/skills/crew-steering/SKILL.md" +LAVISH_SKILL="$ROOT/.agents/skills/lavish-decision-boards/SKILL.md" AGENTS="$ROOT/AGENTS.md" test_agent_only_folded_frontmatter_and_size() { @@ -55,8 +57,16 @@ test_seven_ordered_principles() { assert_grep "Fill released capacity" "$SKILL" "continuous-reaping principle must refill freed lanes" assert_grep "explicit captain order as the governing objective" "$SKILL" "explicit-order principle is missing" assert_grep "non-overridable safety and instruction constraints" "$SKILL" "explicit-order principle must retain non-overridable constraints" - assert_grep "current authoritative check" "$SKILL" "verification-before-assertion principle is missing" - assert_grep "Separate observed facts from inference" "$SKILL" "verification principle must distinguish facts from inference" + assert_grep "consequential action" "$SKILL" "premise-check principle must cover consequential actions" + assert_grep "load-bearing assumption" "$SKILL" "premise-check principle must identify one load-bearing assumption" + assert_grep "clearly-false premises" "$SKILL" "premise-check principle must catch clearly-false premises" + assert_grep "do not overcorrect" "$SKILL" "premise-check principle must forbid overcorrection" + assert_grep "safe to bypass" "$SKILL" "purpose-before-bypass principle must cover bypass classification" + assert_grep "target outcome" "$SKILL" "purpose-before-bypass principle must establish the operation's purpose" + assert_grep "critical path" "$SKILL" "purpose-before-bypass principle must protect the target's critical path" + assert_grep "Before adding a bypass that gates an irreversible or high-stakes action, record the target outcome and the rationale" "$SKILL" "purpose-before-bypass principle must require a written purpose and rationale for consequential bypasses" + assert_grep "trivial skips are exempt" "$SKILL" "purpose-before-bypass principle must exempt trivial skips from recorded rationale" + assert_grep "operation failing, not noise" "$SKILL" "purpose-before-bypass principle must treat target-capability failure as operation failure" pass "operating-fundamentals encodes all seven principles in the required order" } @@ -72,6 +82,64 @@ test_single_conditional_agents_trigger() { pass "AGENTS.md contains one conditional section-13 trigger and no every-turn duplicate" } +test_crew_steering_contract_and_trigger() { + local section headings expected + + assert_present "$CREW_SKILL" "crew-steering SKILL.md is missing" + assert_grep "name: crew-steering" "$CREW_SKILL" "crew-steering skill is missing its canonical name" + headings=$(sed -nE 's/^## ([1-6]\. .*)$/\1/p' "$CREW_SKILL") + expected=$(printf '%s\n' \ + "1. Demand ownership" \ + "2. Reject vague or optimistic claims" \ + "3. Fact-check the load-bearing premise" \ + "4. Prefer quality and robustness" \ + "5. Preserve goal fidelity" \ + "6. Be direct and early") + [ "$headings" = "$expected" ] || fail "crew-steering must retain all six captain-standard guardrails" + + assert_grep "name the outcome, constraint, evidence, and next action" "$CREW_SKILL" "crew steering must keep briefs and steers proportional" + assert_grep "expected result, authority boundaries, verification, and definition of done" "$CREW_SKILL" "crew briefs must define their result, scope, proof, and completion bar" + assert_grep "smallest load-bearing mistake early" "$CREW_SKILL" "live steering must correct the load-bearing mistake early" + assert_grep "carry the fix through implementation and proof" "$CREW_SKILL" "live steering must require implementation and proof" + assert_grep "preserve the captain's actual goal" "$CREW_SKILL" "crew steering must preserve the captain's actual goal" + assert_grep "use the existing owner for detail instead of copying its contract" "$CREW_SKILL" "crew steering must preserve contract ownership" + assert_grep "solve and implement the task" "$CREW_SKILL" "crews must own both solution and implementation" + assert_grep "never stops solely because work is hard or failing" "$CREW_SKILL" "crews must not treat difficulty as a stopping condition" + assert_grep "preserves mandated safety" "$CREW_SKILL" "crew ownership must preserve legitimate safety stops" + assert_grep "unsafe or non-isolated worktree placement" "$CREW_SKILL" "crew ownership must retain the worktree safety stop" + assert_grep "exhausts its capability before following the solve-first escalation bar" "$CREW_SKILL" "crew ownership must preserve legitimate blocker escalation" + assert_grep "Treat \`almost there\` as unfinished" "$CREW_SKILL" "crew steering must reject optimistic partial-completion claims" + assert_grep "real evidence because work is not done until proven" "$CREW_SKILL" "crew steering must require evidence before completion" + assert_grep "review adversarially rather than rubber-stamping" "$CREW_SKILL" "crew steering must require adversarial review" + assert_grep "one load-bearing assumption before it acts" "$CREW_SKILL" "crew steering must premise-check before action" + assert_grep "rejecting a shallow-false premise without overcorrecting" "$CREW_SKILL" "premise checking must reject false premises without overreach" + assert_grep "captain's technical-decision bias" "$CREW_SKILL" "crew steering must apply the captain's quality bar" + assert_grep "reject preserving a leaky component merely to save development cost or sunk work" "$CREW_SKILL" "crew steering must prefer robustness over development cost or sunk work" + assert_grep "Reject any quiet reframing of the task into a smaller win" "$CREW_SKILL" "crew steering must reject weakened goals" + assert_grep "fixed-goal guardrail" "$CREW_SKILL" "crew steering must retain the fixed-goal authority" + assert_grep "specific, un-bloated briefs and steers" "$CREW_SKILL" "crew steering must remain direct" + assert_grep "correct a wrong path before it is built" "$CREW_SKILL" "crew steering must correct wrong paths early" + assert_grep "concrete result the crew must produce" "$CREW_SKILL" "a steer must end with the required result" + assert_grep "evidence that will prove it" "$CREW_SKILL" "a steer must end with required proof" + assert_grep "next action it should take" "$CREW_SKILL" "a steer must end with the next action" + assert_grep "Do not add motivational padding, duplicate background, or a second copy of an existing procedure" "$CREW_SKILL" "crew steering must avoid padding and duplicate contracts" + + section=$(awk '/^## 13\. Agent-only reference skills$/ { capture=1; next } capture && /^## / { exit } capture' "$AGENTS") + assert_contains "$section" "\`crew-steering\` - load before writing or materially revising any crew brief and before live-steering a crew" "section 13 must trigger crew-steering for briefs and live steers" + pass "crew-steering retains its behavioral guardrails and conditional trigger" +} + +test_live_surface_freshness_contract() { + assert_grep "reconcile it against live fleet state" "$AGENTS" "captain-facing surfaces must reconcile against live state" + assert_grep "removing resolved actionable or decision items" "$AGENTS" "serve-fresh removal must cover resolved actionable and decision items" + assert_grep "Recently Landed section of \`/bearings\` and \`/reports\`" "$AGENTS" "completion-oriented surfaces must retain relevant history" + assert_grep "never render it from a remembered snapshot" "$LAVISH_SKILL" "Lavish boards must use live fleet state" + assert_grep "Answer preservation takes precedence over the serve-fresh rule" "$LAVISH_SKILL" "answer preservation must take precedence while input is unsubmitted" + assert_grep "Never edit, refresh, or reload a served board while the captain is answering" "$LAVISH_SKILL" "served boards must preserve in-progress answers" + assert_grep "After submission, reconcile and refresh before continuing" "$LAVISH_SKILL" "served boards must refresh safely after answer submission" + pass "live-surface freshness preserves completion history and in-progress answers" +} + test_provider_neutral_and_no_maintenance_boilerplate() { if grep -Eiq 'Claude|Codex|OpenAI|Anthropic|Gemini|Grok|Orca|Herdr|tmux|zellij|cmux|AWS|GitHub|provider|account' "$SKILL"; then fail "skill contains a named provider, harness, account, or incident-specific dependency" @@ -88,4 +156,6 @@ test_provider_neutral_and_no_maintenance_boilerplate() { test_agent_only_folded_frontmatter_and_size test_seven_ordered_principles test_single_conditional_agents_trigger +test_crew_steering_contract_and_trigger +test_live_surface_freshness_contract test_provider_neutral_and_no_maintenance_boilerplate