From 7e28523fdbeec398b3b57f622b4cb30d883f9222 Mon Sep 17 00:00:00 2001 From: Dongkeun Lee Date: Tue, 21 Jul 2026 16:43:27 -0400 Subject: [PATCH 1/5] Add operating fundamentals skill --- .../skills/operating-fundamentals/SKILL.md | 46 +++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 47 insertions(+) create mode 100644 .agents/skills/operating-fundamentals/SKILL.md diff --git a/.agents/skills/operating-fundamentals/SKILL.md b/.agents/skills/operating-fundamentals/SKILL.md new file mode 100644 index 00000000000..c8545240186 --- /dev/null +++ b/.agents/skills/operating-fundamentals/SKILL.md @@ -0,0 +1,46 @@ +--- +name: operating-fundamentals +description: Agent-only operating practice for firstmate. Use while supervising under load, deciding whether to dispatch or hold, 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. +user-invocable: false +metadata: + internal: true +--- + +# Operating fundamentals + +Apply these principles together to maximize verified fleet-wide progress. + +## 1. Saturate every available lane + +Keep a current view of usable capacity and eligible work. +Dispatch independent work into every healthy lane. +Never idle a working lane merely because another lane, resource, or dependency is blocked. + +## 2. Route around blockers + +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. + +## 3. Decouple validation from worker budgets + +Keep shared validation and other control-plane checks independent of any single exhaustible budget used by the workers they govern. +Provide a separate pool, reserved capacity, or admission policy that leaves validation available when one worker budget is depleted. +Switching every worker and validator from one shared dependency to another does not decouple them. + +## 4. Reap continuously + +On every terminal wake, verify the deliverable state, complete required landing and reporting steps, then release the lane, worktree, lease, and session as soon as their guards allow. +Fill released capacity with the next eligible work, preferring warm reusable capacity when safe. + +## 5. Obey explicit orders decisively + +Treat an explicit captain order as the governing objective within non-overridable safety and instruction constraints. +Do not let a default workflow, local guardrail, or convenience silently replace that objective. +Execute it directly or find a compliant route; if none exists, surface the exact conflict and the nearest viable alternative. + +## 6. 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. diff --git a/AGENTS.md b/AGENTS.md index 0f9d6699eda..4bf74982348 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -775,6 +775,7 @@ 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 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 while supervising under load, deciding whether to dispatch or hold, handling a blocked lane or finished crew, protecting shared validation capacity, acting on an explicit captain order, or about to assert a fleet fact. - `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, 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`. From f022a7a081d81afdd154e984590d973f24a469ab Mon Sep 17 00:00:00 2001 From: Dongkeun Lee Date: Tue, 21 Jul 2026 18:12:55 -0400 Subject: [PATCH 2/5] no-mistakes(document): Normalize operating fundamentals metadata --- .agents/skills/operating-fundamentals/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.agents/skills/operating-fundamentals/SKILL.md b/.agents/skills/operating-fundamentals/SKILL.md index c8545240186..78411f9d6bf 100644 --- a/.agents/skills/operating-fundamentals/SKILL.md +++ b/.agents/skills/operating-fundamentals/SKILL.md @@ -1,6 +1,8 @@ --- name: operating-fundamentals -description: Agent-only operating practice for firstmate. Use while supervising under load, deciding whether to dispatch or hold, 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. +description: >- + Agent-only operating practice for firstmate. + Use while supervising under load, deciding whether to dispatch or hold, 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. user-invocable: false metadata: internal: true From d85d2ca89d11eea88b5f3c5ee8b8b13bb3e49048 Mon Sep 17 00:00:00 2001 From: Dongkeun Lee Date: Tue, 21 Jul 2026 18:53:16 -0400 Subject: [PATCH 3/5] Add pure orchestrator fundamental --- .../skills/operating-fundamentals/SKILL.md | 21 ++++++++++++------- AGENTS.md | 2 +- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/.agents/skills/operating-fundamentals/SKILL.md b/.agents/skills/operating-fundamentals/SKILL.md index 78411f9d6bf..ec0f1fee114 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 while supervising under load, deciding whether to dispatch or hold, 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, or about to assert a fleet fact. user-invocable: false metadata: internal: true @@ -12,36 +12,43 @@ metadata: Apply these principles together to maximize verified fleet-wide progress. -## 1. Saturate every available lane +## 1. Orchestrate; never work inline + +Turn every captain ask into both a durable backlog item and a tracked crew assignment before project or deliverable work begins. +Keep firstmate's own thread for intake, dispatch, supervision, decisions, and outcome reporting; never perform project investigation, planning, implementation, or deliverable production inline. +Treat the backlog record and tracked owner as an atomic pair, and repair either immediately when missing so work survives context loss. +A dropped or forgotten ask is an operating failure; restore its record and owner immediately. + +## 2. Saturate every available lane Keep a current view of usable capacity and eligible work. Dispatch independent work into every healthy lane. Never idle a working lane merely because another lane, resource, or dependency is blocked. -## 2. Route around blockers +## 3. Route around blockers 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. -## 3. Decouple validation from worker budgets +## 4. Decouple validation from worker budgets Keep shared validation and other control-plane checks independent of any single exhaustible budget used by the workers they govern. Provide a separate pool, reserved capacity, or admission policy that leaves validation available when one worker budget is depleted. Switching every worker and validator from one shared dependency to another does not decouple them. -## 4. Reap continuously +## 5. Reap continuously On every terminal wake, verify the deliverable state, complete required landing and reporting steps, then release the lane, worktree, lease, and session as soon as their guards allow. Fill released capacity with the next eligible work, preferring warm reusable capacity when safe. -## 5. Obey explicit orders decisively +## 6. Obey explicit orders decisively Treat an explicit captain order as the governing objective within non-overridable safety and instruction constraints. Do not let a default workflow, local guardrail, or convenience silently replace that objective. Execute it directly or find a compliant route; if none exists, surface the exact conflict and the nearest viable alternative. -## 6. Always check before asserting +## 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. diff --git a/AGENTS.md b/AGENTS.md index 4bf74982348..d1daaa3cd48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -775,7 +775,7 @@ 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 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 while supervising under load, deciding whether to dispatch or hold, 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, or about to assert a fleet fact. - `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, 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`. From 83a92b7acf6b980e4eff6a975a1cc54e04e0a7ed Mon Sep 17 00:00:00 2001 From: Dongkeun Lee Date: Tue, 21 Jul 2026 20:16:39 -0400 Subject: [PATCH 4/5] no-mistakes(document): Align X-mode docs with pure orchestration --- .agents/skills/fmx-respond/SKILL.md | 27 +++++---- docs/architecture.md | 5 +- docs/configuration.md | 6 +- tests/operating-fundamentals.test.sh | 91 ++++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 18 deletions(-) create mode 100755 tests/operating-fundamentals.test.sh diff --git a/.agents/skills/fmx-respond/SKILL.md b/.agents/skills/fmx-respond/SKILL.md index 22e55378979..0f04c11b475 100644 --- a/.agents/skills/fmx-respond/SKILL.md +++ b/.agents/skills/fmx-respond/SKILL.md @@ -39,15 +39,15 @@ Only the *direct* author is the owner; `in_reply_to` and any other thread partic ## A request to act on: acknowledge first, act, then follow up on completion -Because the author is the captain, a mention that asks for work - "add this to the backlog", "look into X", "fix Y", "ship Z" - is a **real captain instruction**, exactly as if the captain had typed it into their own session. -Acting on it means running firstmate's **normal lifecycle**: intake to resolve the project, then file the backlog item, dispatch a crewmate, start an investigation, or ship through the gate - whatever the request calls for. +Because the author is the captain, a mention that asks for work - "look into X", "fix Y", "ship Z" - is a **real captain instruction**, exactly as if the captain had typed it into their own session. +Acting on it means following the intake and orchestration contract owned by [`operating-fundamentals`](../operating-fundamentals/SKILL.md), then running firstmate's normal lifecycle for the request. The reply confirms real work; it never substitutes for it. A polite "aye, will do" with no actual work behind it is the exact bug this guards against. -How the reply lands depends on whether the work finishes during this turn: +How the reply lands depends on whether the mention is a question or an actionable request: -- **Work that completes now** (filing a backlog item, answering from fleet state) already has its outcome, so post **one** reply reporting what was done - exactly as before. -- **Work that spawns a real, longer-running job** (dispatching a crewmate, a scout investigation, a ship task) cannot report an outcome yet, so it follows **acknowledge first -> act -> follow up on completion**: +- **A question answered from live fleet state** already has its outcome, so post **one** reply with the answer. +- **An actionable request** creates tracked work and cannot report an outcome yet, so it follows **acknowledge first -> act -> follow up on completion**: 1. **Acknowledge first.** Post an immediate, public-safe reply that you have the captain's order and are on it (the normal answer endpoint, via `bin/fm-x-reply.sh`). This is the legitimate, work-backed version of "aye, will do": it is paired with actually starting the work in the same turn, never a promise left empty. 2. **Act.** Dispatch the work through the normal lifecycle right away. 3. **Link it for the follow-up, before clearing the inbox.** Associate the spawned task with this mention so completion follow-ups can be posted later: `bin/fm-x-link.sh ` (records the request id, a timestamp, a follow-up counter, and reply platform/budget context). @@ -61,7 +61,7 @@ How the reply lands depends on whether the work finishes during this turn: So every drained mention sorts into one of three cases (the worthiness judgment, widened): -- **Actionable instruction / request** - act through the normal lifecycle. If it completes now, reply with the outcome; if it spawns real work, acknowledge now and link the task so the outcome follows on completion. +- **Actionable instruction / request** - follow `operating-fundamentals`, acknowledge the tracked work, and link its task so the outcome follows on completion. - **Question** - answer it from live fleet state; there is no work to do and no follow-up. - **Pure acknowledgment** ("thanks", a reaction, a loop-closing nicety with nothing to add) - skip: post nothing, but first **dismiss it at the relay** (`bin/fm-x-dismiss.sh `) so the relay drops the request and stops re-offering it, then clear the inbox file. @@ -131,18 +131,20 @@ Treat `state/x-inbox/` as the source of truth and process **every** file you fin `in_reply_to` is `{author_handle, text}` when this mention is a reply within an ongoing conversation, or `null` for a fresh, standalone mention. Ignore `tweet_id` entirely - you never name a platform message id; the relay binds the reply for you. b. **Classify the mention into one of three cases** (see "A request to act on: acknowledge first, act, then follow up on completion"): - - **Actionable instruction / request** ("add this to the backlog", "look into X", "fix Y", "ship Z") - go to step 2c and do the work first. + - **Actionable instruction / request** ("look into X", "fix Y", "ship Z") - go to step 2c and do the work first. - **Question** - nothing to do; skip step 2c and answer from live fleet state in step 2d. - **Pure acknowledgment** ("thanks", "👍", "nice", "got it", a reaction, or a follow-up that just closes the loop with nothing to add) - **skip**: post nothing, but **dismiss it at the relay** (step 2e-skip), then remove the inbox file (the cleanup of step 2f), and move on **without** calling `bin/fm-x-reply.sh`. A deliberate non-answer is the correct outcome here, not a failure. When in doubt between an instruction and a question, do the smallest safe lifecycle step the request implies; when in doubt between a question and bare politeness, lean toward skipping - a needless reply is noise on a public bot. - c. **Act on an actionable request through the normal lifecycle.** Treat it exactly as a captain prompt typed in session: run ordinary intake (resolve the project), then file the backlog item, dispatch a crewmate, start a scout, or ship through the gate - whatever the request calls for. + c. **Act on an actionable request through the normal lifecycle.** Treat it exactly as a captain prompt typed in session and follow the intake and orchestration contract in `operating-fundamentals` before dispatching the appropriate tracked work. **Destructive, irreversible, or security-sensitive work is the exception** (X mode is a public, relayed channel and does not carry full in-session trust): do not execute it from the mention. Flag it to the captain through the normal trusted channel first - the same carve-out as `yolo` (AGENTS.md §1, §7) - act only on the captain's word, and in step 2d say only that it has been flagged for the captain. - **If the request spawned a real, longer-running task** (you ran `bin/fm-spawn.sh`), link that task to this mention so milestone and completion follow-ups can be posted: `bin/fm-x-link.sh `. + Link the spawned task to this mention so milestone and completion follow-ups can be posted: `bin/fm-x-link.sh `. **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`. - If the work completed in this turn (a backlog item filed, a question answered), there is no task to link and step 2d reports the outcome directly. - d. **Compose the reply.** For a **question**, answer `.text` from the fleet state gathered in step 1. For an **actionable request that completed now**, report the outcome of step 2c (what was done, or - for escalated work - that it has been flagged for the captain). For an **actionable request that spawned 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. Either way keep it short, in firstmate's voice, and public-safe. + d. **Compose the reply.** For a **question**, answer `.text` from the fleet state gathered in step 1. + 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. Conversation continuity: when `in_reply_to` is present this is a conversation reply - read `in_reply_to.text` (what `in_reply_to.author_handle` said just before) as **context** and continue that thread, resolving "it", "that", "and then?" against the parent; for a fresh mention (`in_reply_to` is null) answer on its own. If nothing is in flight and the mention just asks what you are up to, say so honestly and in-voice (e.g. "Calm seas just now - nothing underway, standing by for the captain's next orders."). e. **Submit it without ever inlining the reply into a shell command.** @@ -205,7 +207,8 @@ This skill's own responsibility during the mention-handling turn is linking the ## Notes - The direct author is always your own captain (owner-only routing), and in live mode you answer and act on eligible requests **autonomously**: enabling X mode is the captain's standing authorization, so never ask the captain before posting and never hold a worthwhile reply for a chat-side OK. For reply-worthy mentions, dry-run (`FMX_DRY_RUN`) is the only non-posting path; pure acknowledgments use the relay dismiss path instead. -- An actionable mention is **acted on** through the normal lifecycle (intake, backlog, dispatch, investigate, ship), not merely replied to. Work that finishes now gets one outcome reply; work that spawns a real task gets an **acknowledgement now** plus up to three **completion follow-ups** over time, ending with a `--final` one (link the task with `bin/fm-x-link.sh` so those follow-ups can post). A reply alone, with no work behind an actionable ask, is the bug to avoid. +- An actionable mention follows the orchestration contract in `operating-fundamentals`, gets an **acknowledgement now**, and receives up to three **completion follow-ups** over time, ending with a `--final` one (link the task with `bin/fm-x-link.sh` so those follow-ups can post). + A reply alone, with no work behind an actionable ask, is the bug to avoid. - Destructive, irreversible, or security-sensitive asks are flagged to the captain through the trusted channel first and never run straight from a mention; the public reply says only that it has been flagged. - One answered mention = one reply (plus up to three completion follow-ups for a spawned task, spent only on genuine milestones); a skipped mention posts no reply but is **dismissed at the relay** (`bin/fm-x-dismiss.sh`) so the relay drops it rather than re-offering it (which would otherwise churn every poll and end in an "offline" auto-reply). A single wake may cover several pending mentions - drain them all. - Conversations: `in_reply_to` carries the parent post for continuity; a pure acknowledgment with nothing to answer is dismissed at the relay and skipped, not replied to. The relay already guards against self-replies and caps replies per conversation, so you only judge "is there something to answer here?". diff --git a/docs/architecture.md b/docs/architecture.md index 2ee1ed7a6e1..35abd51867a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -190,9 +190,8 @@ On the locked session-start bootstrap step, that token creates the local polling Without the token, the locked session-start bootstrap step removes those artifacts on opt-out and otherwise stays silent, so non-X users see no behavior change. Pending mentions are stored as `state/x-inbox/.json`; the `fmx-respond` agent-only skill drains that inbox, uses `in_reply_to` parent-post context for conversational continuity, classifies each mention as an actionable request, question, or pure acknowledgment, and submits public-safe replies through `bin/fm-x-reply.sh`. When a reply has a real visual artifact, `--image ` attaches one local PNG, JPEG, GIF, WebP, BMP, or TIFF to the relay's optional `{media_type,data_base64}` image object. -Actionable reversible requests run through firstmate's normal intake, backlog, dispatch, investigation, or ship lifecycle. -Work that completes in the answering turn gets one outcome reply. -Work that spawns a longer-running task gets an acknowledgement reply first; `bin/fm-x-link.sh` records `x_request=`, `x_request_ts=`, `x_followups=0`, and optional reply-platform context in that task's `state/.meta`, while durable per-request context preserves the original platform and budget independently of task links and inbox cleanup. +The [`operating-fundamentals`](../.agents/skills/operating-fundamentals/SKILL.md) skill owns the intake and orchestration contract for actionable requests, while fleet-state questions get one answer in the current turn. +Actionable requests get an acknowledgement reply first; `bin/fm-x-link.sh` records `x_request=`, `x_request_ts=`, `x_followups=0`, and optional reply-platform context in the tracked task's `state/.meta`, while durable per-request context preserves the original platform and budget independently of task links and inbox cleanup. Later milestone and completion wakes use `bin/fm-x-followup.sh` to post up to three public-safe follow-ups through the relay's `connector/followup` endpoint, ending with a `--final` one that always clears the link. The [X mode configuration reference](configuration.md#x-mode-env) owns the exact context retention, platform-resolution, and fail-safe posting contract. If recovery relinks the same relay request onto a successor task, `fm-x-link.sh --carry-count --carry-ts --carry-platform --carry-max ` preserves the consumed follow-up count, original 7-day window, and reply split budget instead of granting a fresh local budget or falling back to the wrong platform. diff --git a/docs/configuration.md b/docs/configuration.md index 7a0f319ae61..f35f98d1f83 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -331,9 +331,9 @@ A successful live initial answer refreshes it to the time that the relay establi Configured polls prune records beyond the local follow-up window, capped at the relay's seven-day window; legacy or malformed records fall back to their file modification time so they cannot remain indefinitely. The record is written only when a platform or explicit budget is actually known, so an unknown-platform mention leaves no useless entry. The `fmx-respond` skill decides whether the stashed mention is an actionable request, a question, or a pure acknowledgment. -Actionable reversible requests are run through intake, backlog, dispatch, investigation, or ship flow as appropriate. -If the work completes in that turn, the public reply reports the outcome. -If the request spawns a longer-running task, firstmate posts an acknowledgement through the normal answer endpoint, links the task to the mention with `bin/fm-x-link.sh`, and posts up to three completion follow-ups on genuine milestones, always finishing with a `--final` one when the task reaches a terminal state. +The [`operating-fundamentals`](../.agents/skills/operating-fundamentals/SKILL.md) skill owns the intake and orchestration contract for actionable requests; this section owns only the X-mode transport and generated-state mechanics. +Fleet-state questions are answered in that turn. +For an actionable request, firstmate posts an acknowledgement through the normal answer endpoint, links the tracked task to the mention with `bin/fm-x-link.sh`, and posts up to three completion follow-ups on genuine milestones, always finishing with a `--final` one when the task reaches a terminal state. That link stores optional reply-platform context so Discord-originated follow-ups keep Discord's larger message budget after the inbox file has been drained. Platform/budget resolution is layered and independent of the task link: a per-axis `FMX_REPLY_PLATFORM` / `FMX_REPLY_MAX_CHARS` override (how `bin/fm-x-followup.sh` passes a recorded link's context) wins. For either axis without an override, `bin/fm-x-lib.sh:fmx_resolve_reply_context` owns the source order: the durable per-request registry is consulted first, then the still-present inbox payload, then - for a follow-up posted live by request_id - an authoritative relay lookup via `POST /connector/request-context` (`{request_id}` in, `{platform, reply_max_chars}` back). diff --git a/tests/operating-fundamentals.test.sh b/tests/operating-fundamentals.test.sh new file mode 100755 index 00000000000..94f54aa5e88 --- /dev/null +++ b/tests/operating-fundamentals.test.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# Contract tests for the agent-only operating-fundamentals skill. +set -u + +# shellcheck source=tests/lib.sh +. "$(dirname "${BASH_SOURCE[0]}")/lib.sh" + +SKILL="$ROOT/.agents/skills/operating-fundamentals/SKILL.md" +AGENTS="$ROOT/AGENTS.md" + +test_agent_only_folded_frontmatter_and_size() { + local frontmatter line_count delimiter_count + + assert_present "$SKILL" "operating-fundamentals SKILL.md is missing" + frontmatter=$(awk 'NR == 1 && $0 == "---" { capture=1; next } capture && $0 == "---" { exit } capture' "$SKILL") + assert_contains "$frontmatter" "name: operating-fundamentals" "skill frontmatter is missing its canonical name" + assert_contains "$frontmatter" "description: >-" "skill description must use folded YAML metadata" + assert_contains "$frontmatter" "user-invocable: false" "skill must remain agent-only" + assert_contains "$frontmatter" "metadata:" "skill frontmatter is missing internal metadata" + assert_contains "$frontmatter" " internal: true" "skill must remain internal" + assert_contains "$frontmatter" "Use when intaking any captain ask" "folded metadata must name a concrete intake trigger" + assert_contains "$frontmatter" "supervising under load" "folded metadata must name a concrete supervision trigger" + assert_contains "$frontmatter" "about to assert a fleet fact" "folded metadata must name a concrete verification trigger" + + delimiter_count=$(grep -c '^---$' "$SKILL") + [ "$delimiter_count" -eq 2 ] || fail "skill must have one closed YAML frontmatter block" + line_count=$(wc -l < "$SKILL" | tr -d '[:space:]') + [ "$line_count" -le 90 ] || fail "skill exceeds the 90-line limit: $line_count" + pass "operating-fundamentals has folded agent-only frontmatter, concrete triggers, and stays within 90 lines" +} + +test_seven_ordered_principles() { + local headings expected + + headings=$(sed -nE 's/^## ([0-9]+\. .*)$/\1/p' "$SKILL") + expected=$(printf '%s\n' \ + "1. Orchestrate; never work inline" \ + "2. Saturate every available lane" \ + "3. Route around blockers" \ + "4. Decouple validation from worker budgets" \ + "5. Reap continuously" \ + "6. Obey explicit orders decisively" \ + "7. Always check before asserting") + [ "$headings" = "$expected" ] || fail "skill must contain exactly seven ordered operating-principle headings" + + assert_grep "every captain ask" "$SKILL" "orchestration principle must cover every captain ask" + assert_grep "durable backlog item" "$SKILL" "orchestration principle must require durable backlog tracking" + assert_grep "tracked crew assignment" "$SKILL" "orchestration principle must require a tracked owner" + assert_grep "never perform project investigation, planning, implementation, or deliverable production inline" "$SKILL" "orchestration principle must forbid inline project and deliverable work" + assert_grep "every healthy lane" "$SKILL" "lane-saturation principle is missing" + assert_grep "blocker as a routing problem" "$SKILL" "blocker-routing principle is missing" + assert_grep "shared validation" "$SKILL" "independent-validation principle is missing" + assert_grep "single exhaustible budget" "$SKILL" "independent-validation principle must cover depleted worker budgets" + assert_grep "On every terminal wake" "$SKILL" "continuous-reaping principle is missing" + 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" + pass "operating-fundamentals encodes all seven principles in the required order" +} + +test_single_conditional_agents_trigger() { + local section global_count section_count + + section=$(awk '/^## 13\. Agent-only reference skills$/ { capture=1; next } capture && /^## / { exit } capture' "$AGENTS") + global_count=$(grep -Fc '`operating-fundamentals`' "$AGENTS") + section_count=$(printf '%s\n' "$section" | grep -Fc '`operating-fundamentals`') + [ "$global_count" -eq 1 ] || fail "AGENTS.md must reference operating-fundamentals exactly once" + [ "$section_count" -eq 1 ] || fail "the sole operating-fundamentals reference must be in section 13" + assert_contains "$section" '`operating-fundamentals` - load when intaking any captain ask' "section 13 must conditionally load the skill at intake" + pass "AGENTS.md contains one conditional section-13 trigger and no every-turn duplicate" +} + +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" + fi + if grep -Eiq 'https?://|@[[:alnum:]_.-]+|[[:xdigit:]]{8}-[[:xdigit:]-]{27,}' "$SKILL"; then + fail "skill contains an incident-specific URL, address, or identifier" + fi + if grep -Eiq 'maintain|maintenance|when updating|keep this file|for maintainers' "$SKILL"; then + fail "skill contains maintenance boilerplate" + fi + pass "operating-fundamentals stays provider-neutral and omits incident and maintenance detail" +} + +test_agent_only_folded_frontmatter_and_size +test_seven_ordered_principles +test_single_conditional_agents_trigger +test_provider_neutral_and_no_maintenance_boilerplate From c4950523f2d10bc65808c01b1ef908d594280f2e Mon Sep 17 00:00:00 2001 From: Dongkeun Lee Date: Tue, 21 Jul 2026 20:38:21 -0400 Subject: [PATCH 5/5] no-mistakes(lint): Fix ShellCheck literal quoting warnings --- tests/operating-fundamentals.test.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/operating-fundamentals.test.sh b/tests/operating-fundamentals.test.sh index 94f54aa5e88..17060a81c22 100755 --- a/tests/operating-fundamentals.test.sh +++ b/tests/operating-fundamentals.test.sh @@ -64,11 +64,11 @@ test_single_conditional_agents_trigger() { local section global_count section_count section=$(awk '/^## 13\. Agent-only reference skills$/ { capture=1; next } capture && /^## / { exit } capture' "$AGENTS") - global_count=$(grep -Fc '`operating-fundamentals`' "$AGENTS") - section_count=$(printf '%s\n' "$section" | grep -Fc '`operating-fundamentals`') + global_count=$(grep -Fc "\`operating-fundamentals\`" "$AGENTS") + section_count=$(printf '%s\n' "$section" | grep -Fc "\`operating-fundamentals\`") [ "$global_count" -eq 1 ] || fail "AGENTS.md must reference operating-fundamentals exactly once" [ "$section_count" -eq 1 ] || fail "the sole operating-fundamentals reference must be in section 13" - assert_contains "$section" '`operating-fundamentals` - load when intaking any captain ask' "section 13 must conditionally load the skill at intake" + assert_contains "$section" "\`operating-fundamentals\` - load when intaking any captain ask" "section 13 must conditionally load the skill at intake" pass "AGENTS.md contains one conditional section-13 trigger and no every-turn duplicate" }