@desplega.ai/agent-swarm 2.5.3 → 2.5.4

package/templates/skills/agent-browser/SKILL.md

@@ -70,18 +70,18 @@ Add `--contact-sheet` to the start command for a timestamped PNG summary of visu
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. Use `share-create` when a person needs to open the file. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>`. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
-agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
 ```
 
 - **GitHub PR body or comment**: upload the PNG, GIF or mp4 as a GitHub user attachment with the `github-attach` skill and embed `![caption](https://github.com/user-attachments/assets/<uuid>)`. Attachments never expire and mp4s play inline. A UI PR puts a before (main) and after pair in the `## Before / after` table. Fallback for images only, when the GitHub token is an App token (`ghu_`/`ghs_`): `agent-fs signed-url <path> --inline --json` (expires in 7 days). Never a presigned URL for an mp4 or a doc: it downloads.
-- **Linear comment or Slack message**: paste the `share-create` link.
-- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
+- **Linear comment or Slack message**: paste the live app link.
+- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the live app link for people who need to open the file.
+- Make an `agent-fs share-create <path> --json` link only when the requester asks for one or the reader has no agent-fs login (customer, public post, email, named outsider). Never make one in case the file gets forwarded.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
 The `agent-fs` skill holds the full agent-fs recipe.

package/templates/skills/agent-browser/content.md

@@ -65,18 +65,18 @@ Add `--contact-sheet` to the start command for a timestamped PNG summary of visu
 
 ## Step 3: share the screenshot through agent-fs
 
-Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. Use `share-create` when a person needs to open the file. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
+Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>`. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
 
 ```bash
 agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
   --file /tmp/<name>.png -m "<what it shows>"
 agent-fs stat thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json        # confirm size > 0
-agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --json
 ```
 
 - **GitHub PR body or comment**: upload the PNG, GIF or mp4 as a GitHub user attachment with the `github-attach` skill and embed `![caption](https://github.com/user-attachments/assets/<uuid>)`. Attachments never expire and mp4s play inline. A UI PR puts a before (main) and after pair in the `## Before / after` table. Fallback for images only, when the GitHub token is an App token (`ghu_`/`ghs_`): `agent-fs signed-url <path> --inline --json` (expires in 7 days). Never a presigned URL for an mp4 or a doc: it downloads.
-- **Linear comment or Slack message**: paste the `share-create` link.
-- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
+- **Linear comment or Slack message**: paste the live app link.
+- In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the live app link for people who need to open the file.
+- Make an `agent-fs share-create <path> --json` link only when the requester asks for one or the reader has no agent-fs login (customer, public post, email, named outsider). Never make one in case the file gets forwarded.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
 The `agent-fs` skill holds the full agent-fs recipe.

package/templates/skills/code-quality/config.json

@@ -5,7 +5,7 @@
   "slug": "code-quality",
   "title": "Code Quality",
   "description": "Push, PR, MR, merge, review, CI, gh, glab: the checks to run before you push or open a pull request, how to review one, the merge policy, and the GitHub review-reply provenance rule. Use before you push, open a PR or MR, or review one.",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "category": "skills",
   "placeholders": [],
   "runAllSeedersCandidate": true,

package/templates/skills/code-quality/content.md

@@ -51,8 +51,8 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
 
 1. CI status first, including the fork checks below before treating CI as evidence. Failing CI is blocking. Name the failing checks.
 2. Detect a GitHub fork PR with `gh pr view <number> --json isCrossRepository --jq .isCrossRepository`.
-3. For a GitHub fork PR, inspect held runs with `SHA=$(gh pr view <number> --json headRefOid --jq .headRefOid); gh api --paginate "repos/<owner>/<repo>/actions/runs?head_sha=$SHA" --jq '.workflow_runs[] | "\(.conclusion // .status)|\(.name)"'`; `gh pr checks` and `statusCheckRollup` can omit them.
-4. Treat any `action_required` run or no substantive run executed on that SHA as a CI blocker. Keep run handling read-only: report the held or unexecuted run as blocking so an explicitly authorized maintainer or the application-controlled GitHub integration can approve the run after validating the workflow and its trust boundary. Do not approve on omitted runs.
+3. For a GitHub fork PR, inspect held runs with `SHA=$(gh pr view <number> --json headRefOid --jq .headRefOid); gh api --paginate "repos/<owner>/<repo>/actions/runs?head_sha=$SHA" --jq '.workflow_runs[] | "\(.conclusion // .status)|\(.path)|\(.name)"'`; `gh pr checks` and `statusCheckRollup` can omit them.
+4. Treat no substantive run executed on that SHA, or an `action_required` run without a completed `success` run with the same workflow `path` on that SHA, as a CI blocker. A name match alone never qualifies; a different or missing `path` stays blocking. When the same `path` already succeeded on that SHA, name the held run on the `Non-blocking:` line as waiting on maintainer approval. Keep run handling read-only: report blocking held or unexecuted runs so an explicitly authorized maintainer or the application-controlled GitHub integration can approve the run after validating the workflow and its trust boundary. Do not approve on omitted runs.
 5. Tests. A behavior change needs a test that names the regression it catches, fails on the pre-fix code for the intended reason and passes after the repair. Apply the test rules in the repo's `REVIEW.md`.
 6. Apply the "Review Guidance" entries from the Repository Guidelines.
 7. Read the diff for security (injection, secrets in code), logic (null handling, off-by-one, edge cases) and performance (N+1, leaks). Run the test suite and the type check locally when you can.

package/templates/skills/delegate-work/content.md

@@ -1,6 +1,6 @@
 # delegate-work
 
-Claude (Fable 5) is the **orchestrator**: it thinks, designs, schedules, reviews, commits, and talks to the user. Everything else is delegated to the **cheapest executor that clears the quality bar**. Codex types; Claude judges.
+Claude (Opus 5.5 by default; Fable 5.1 only for hard problems) is the **orchestrator**: it thinks, designs, schedules, reviews, commits, and talks to the user. Everything else is delegated to the **cheapest executor that clears the quality bar**. Codex types; Claude judges.
 
 This skill applies in BOTH modes:
 - **Ad-hoc**: any time you'd spawn an `Agent`/Task, pick its model from the matrix below instead of the default.
@@ -12,15 +12,15 @@ Rankings 1–10, higher = better. Cost = subscription quota burned — both Clau
 
 | executor                | cost | code | taste | speed | role |
 |-------------------------|------|------|-------|-------|------|
-| fable-5                 | 2    | 9    | 9     | 4     | orchestration, deep reasoning, architecture, final judgment |
-| opus-5                  | 4    | 7    | 8     | 5     | UI implementation, complex review, browser E2E |
-| sonnet-5                | 5    | 5    | 7     | 7     | routine review, API QA agents, standard sub-agent work |
-| haiku-4.5               | 9    | 3    | 4     | 9     | search, locate, digest, mechanical sweeps — NEVER for writing code |
-| codex gpt-5.6-sol       | 8    | 10   | 6     | 6     | hard/long-horizon implementation, gnarly debugging |
-| codex gpt-5.6-terra     | 9    | 8    | 5     | 8     | everyday implementation from a frozen spec |
-| codex gpt-5.6-luna      | 10   | 6    | 4     | 10    | mechanical code: migrations, renames, test fills, dep bumps |
+| fable-5.1               | 2    | 8    | 9     | 4     | hard problems only: deep long-horizon reasoning, novel architecture, high-stakes judgment |
+| opus-5.5                | 5    | 9    | 9     | 6     | default orchestrator; UI implementation, complex review, browser E2E |
+| sonnet-5.5              | 6    | 8    | 7     | 7     | routine review, API QA agents, standard sub-agent work |
+| haiku-5.5               | 10   | 5    | 5     | 9     | search, locate, digest, sweeps, structure checks, bounded mechanical edits |
+| codex gpt-6-astra       | 5    | 10   | 6     | 4     | escalation only: hardest long-horizon or research-grade work |
+| codex gpt-6.1-sol       | 8    | 9    | 6     | 7     | default implementation, from everyday slices to gnarly debugging |
+| codex gpt-6-luna        | 10   | 4    | 3     | 10    | trivial mechanical code: renames, dep bumps, formatting sweeps |
 
-(Context for the Codex rows, from the 5.6 release: Sol-max is SOTA on the AA Coding Agent Index, ~3 pts above Fable 5 at ~⅓ the cost; Terra lands just above Fable 5; Luna outperforms Opus 5 — each in ~⅓ the time. Claude keeps the edge on taste and judgment; that's why review and UI stay Claude-side.)
+(Context, from the Sept/Oct 2026 launches. Terminal-Bench 4.0 public board: Opus 5.5 64.8%, Sonnet 5.5 61.8%, GPT-6 Astra and GPT-6.1 Sol both 58.2%, GPT-6 Sol 49.4%, GPT-6 Luna 16.4%. Haiku 5.5 launch figure: 39.2%. GPT-6.1 Sol matches Astra on DeepSWE at ⅕ the price and uses far fewer output tokens per task than Claude models. Opus 5.5 beats Fable 5.1 on most coding evals at 40% of the price, but Fable keeps the edge on long-horizon reasoning. Sonnet 5.5 sits within a few points of Opus 5.5, but at `max` effort it burns more tokens than Opus: if a Sonnet task needs `max`, use Opus instead. Haiku 5.5 beats GPT-6 Luna on every published row, at the same price. Claude keeps the edge on taste and judgment; that's why review and UI stay Claude-side.)
 
 **Defaults, not limits.** Standing permission to override: if a cheaper executor's output doesn't meet the bar, rerun or redo with a smarter one without asking. Judge the output, not the price tag. Escalating costs less than shipping mediocre work.
 
@@ -28,22 +28,26 @@ Rankings 1–10, higher = better. Cost = subscription quota burned — both Clau
 
 | work | executor | how |
 |------|----------|-----|
-| orchestration, deep reasoning, spec-writing, architecture | **Fable 5** | stay in the main session; never delegated |
-| UI implementation (pages, components, styles, UX flows) | **Opus 5** | `Agent` with `model: "opus"`, background |
-| code review — routine / per-phase | **Sonnet 5** | `Agent` with `model: "sonnet"` |
-| code review — complex, security-sensitive, cross-cutting, or reviewing Sol output | **Opus 5** (+ optional parallel Codex review, see Verify ↓) | `Agent` with `model: "opus"` |
-| API-level QA / E2E agents, plan-verification agents | **Sonnet 5** | `Agent` with `model: "sonnet"` |
-| browser E2E / driving the real UI | **Opus 5** | `Agent` with `model: "opus"`; use a browser-automation agent for local URLs unless stated differently |
-| search, locate, pattern-find, doc digests | **Haiku 4.5** | `Explore` / locator agents with `model: "haiku"` |
+| orchestration, spec-writing, architecture | **Opus 5.5** (default session model) | stay in the main session; never delegated |
+| hard problems: long-horizon reasoning, novel architecture with many unknowns, high-stakes design calls, or anything Opus 5.5 already got wrong twice | **Fable 5.1** | if the session runs on Opus, recommend the user switch with `/model`, or spawn a focused `Agent` with `model: "fable"` and judge its answer in the main session |
+| UI implementation (pages, components, styles, UX flows) | **Opus 5.5** | `Agent` with `model: "opus"`, background |
+| code review — routine / per-phase | **Sonnet 5.5** | `Agent` with `model: "sonnet"` |
+| code review — complex, security-sensitive, cross-cutting, or reviewing Sol/Astra output | **Opus 5.5** (+ optional parallel Codex review, see Verify ↓) | `Agent` with `model: "opus"` |
+| API-level QA / E2E agents, plan-verification agents | **Sonnet 5.5** | `Agent` with `model: "sonnet"` |
+| browser E2E / driving the real UI | **Opus 5.5** | `Agent` with `model: "opus"`; use a browser-automation agent for local URLs unless stated differently |
+| search, locate, pattern-find, doc digests, plan-structure validation, log/test-output triage | **Haiku 5.5** | `Explore` / locator agents with `model: "haiku"` |
+| bounded mechanical edits that need session tools (MCP, browser, secrets), so Codex can't take them | **Haiku 5.5** | `Agent` with `model: "haiku"` and an exact edit list; escalate to Sonnet on the first miss. No feature code, no design calls |
 | bulk mechanical call-sequences (~10+ similar tool/API calls, any fan-out over a list) | **a script** | `desplega:script-builder` — cheapest executor of all; one summary re-enters context, raw payloads never do |
 | raw code implementation from a frozen spec | **Codex** | variant by scope ↓, via `codex-exec.sh` |
 
 **Codex variant by scope** (effort in parentheses):
 
-- `gpt-5.6-luna` (`medium`→`high`) — mechanical & bounded: renames, mechanical migrations, test/coverage fills, CI fixes, dep bumps, single-file bug fix with known repro.
-- `gpt-5.6-terra` (`high`) — the default for a well-specified phase/step: single vertical slice, clear verification, few unknowns.
-- `gpt-5.6-sol` (`high`; `xhigh` for hard, `max` only for the gnarliest long-horizon work) — multi-file backend phases, cross-package changes, subtle debugging, anything where the spec has known-unknowns.
-- Never use Codex `ultra` (its own multi-agent mode) — parallelism is the orchestrator's job, via worktrees.
+- `gpt-6-luna` (`high`): trivial and mechanical only. Renames, dep bumps, formatting, codemod-style sweeps. It is weak at agentic terminal work, so escalate to `gpt-6.1-sol` on the first miss. Anything with judgment (test fills, CI fixes, bug fixes) starts at `gpt-6.1-sol` `medium`.
+- `gpt-6.1-sol` (`medium`): the default for a well-specified phase/step. Single vertical slice, clear verification, few unknowns. Also test/coverage fills, CI fixes, single-file bug fixes with a known repro.
+- `gpt-6.1-sol` (`high`; `xhigh` for hard): multi-file backend phases, cross-package changes, subtle debugging, anything where the spec has known-unknowns.
+- `gpt-6-astra` (`high`/`xhigh`; `max` only for the gnarliest long-horizon work): escalation rung. Use it after `gpt-6.1-sol` `xhigh` fails, or for research-grade work (hard science, theorem-style reasoning). It costs 5× Sol per token and does not beat 6.1 Sol on coding evals.
+- Older `gpt-5.6-*` and `gpt-6-sol` still appear in the model list. Don't route to them.
+- Never use Codex `ultra` (its own multi-agent mode). Parallelism is the orchestrator's job, via worktrees.
 
 **Keep in Claude regardless of matrix**: tasks where writing the spec IS the work (ambiguity = design); tiny edits (<~20 lines) where delegation overhead loses; anything needing session tools (MCP, browser, secrets); destructive/irreversible ops, pushes, GitHub mutations; judging delegated output — executors may contribute reviews, but the join and final verdict are never delegated, never skipped.
 
@@ -53,7 +57,7 @@ Heuristic: if the prompt reads as a work order → delegate; if writing it force
 
 When the harness exposes the `Workflow` tool AND the user has opted in (the desplega skills ask during setup — that answer IS the explicit opt-in the tool requires), fan-out runs as a workflow script instead of ad-hoc `Agent` calls. The matrix above still routes every executor; it just maps onto `agent()` opts:
 
-- **Model tiers** → `model: "haiku" | "sonnet" | "opus"`; omit `model` for work that must stay at orchestrator quality (it inherits the session model). `effort` follows the same logic: `low` for mechanical stages, higher tiers only for verify/judge stages.
+- **Model tiers** → `model: "haiku" | "sonnet" | "opus" | "fable"` (aliases resolve to the latest version of each family; `"fable"` only for hard-problem stages, per the routing table); omit `model` for work that must stay at orchestrator quality (it inherits the session model). `effort` follows the same logic: `low` for mechanical stages, higher tiers only for verify/judge stages.
 - **Named agents** (locators, analyzers, pattern-finders) → the `agentType` opt.
 - **Codex rows** still apply inside a workflow: an `agent()` can drive `codex-exec.sh` in its own worktree. Plan bookkeeping and commits stay orchestrator-side, as always.
 - **The join stays Claude-side**: the workflow returns data (findings, reports, file lists) — reading the diff, deduping findings, and the final verdict happen in the main session, never inside the script.
@@ -61,16 +65,16 @@ When the harness exposes the `Workflow` tool AND the user has opted in (the desp
 
 ## Codex: the one primitive
 
-> **Prerequisite**: the `codex` CLI on PATH, authenticated, with access to the gpt-5.6 models. If it's missing, the Codex rows of the matrix are unavailable — route implementation work to Claude executors instead (Opus for hard slices, Sonnet for routine ones) and tell the user why.
+> **Prerequisite**: the `codex` CLI on PATH, authenticated, with access to the gpt-6 models (check `~/.codex/models_cache.json` for the live slug list). If it's missing, the Codex rows of the matrix are unavailable. Route implementation work to Claude executors instead (Opus for hard slices, Sonnet for routine ones) and tell the user why.
 
 `bash ~/.claude/skills/delegate-work/scripts/codex-exec.sh`
 
 ```
-printf '%s' "$PROMPT" | bash ~/.claude/skills/delegate-work/scripts/codex-exec.sh -m gpt-5.6-terra -e high \
+printf '%s' "$PROMPT" | bash ~/.claude/skills/delegate-work/scripts/codex-exec.sh -m gpt-6.1-sol -e medium \
   -C <workdir> -o <report-file> -l <log-file>
 ```
 
-- `-m` model / `-e` reasoning effort — from the scope table above (script defaults: `gpt-5.6-sol` + `high`; env overrides `CODEX_MODEL`/`CODEX_EFFORT` still work).
+- `-m` model / `-e` reasoning effort — from the scope table above (script defaults: `gpt-6.1-sol` + `high`; env overrides `CODEX_MODEL`/`CODEX_EFFORT` still work).
 - `-C` working root — a **git worktree** for parallel work, repo root for sequential.
 - `-o` report file — Codex's final message; read THIS back, not the log.
 - `-l` log file — for monitoring only; keep raw logs out of the session.
@@ -101,7 +105,7 @@ Codex starts with zero session context. Every prompt: goal, exact repo/paths (ab
 - After web service-layer changes: probe the running dev server — unit tests miss RSC import crashes.
 - UI touched by anything non-Opus (or by Codex at all): hands-on polish pass — drive the real UI, screenshot, fix spacing/copy/empty-states yourself.
 - Then the per-phase review round before closing the phase: `desplega:code-reviewing` — two axes (Standards per `desplega:engineering-standards`, Spec against the phase body), parallel sub-agents Sonnet/Opus per the table, reported separately and never merged.
-- **Codex can review too**: for complex/high-stakes phases, add a Codex review (`codex exec review`, or a sol review prompt via `codex-exec.sh`) in parallel with the two Claude axes, then join — dedupe findings, discard false positives, rank the rest. The JOIN and the final verdict stay Claude-side; a review is never delegated to a single executor and never skipped.
+- **Codex can review too**: for complex/high-stakes phases, add a Codex review (`codex exec review`, or a `gpt-6.1-sol` review prompt via `codex-exec.sh`) in parallel with the two Claude axes, then join — dedupe findings, discard false positives, rank the rest. The JOIN and the final verdict stay Claude-side; a review is never delegated to a single executor and never skipped.
 
 ## Failure & mismatch handling
 

package/templates/skills/delegate-work/files/scripts/codex-exec.sh

@@ -3,9 +3,9 @@
 # codex-exec.sh — invoke `codex exec` (non-interactive) for delegated
 # implementation work. This is the SINGLE SOURCE OF TRUTH for the invocation
 # flags. The delegate-work skill calls only this script; its routing matrix
-# decides WHICH gpt-5.6 variant (-m) and effort (-e) each task gets:
-#   luna  = mechanical/bounded     terra = everyday frozen-spec slice
-#   sol   = hard/long-horizon      effort: medium|high|xhigh|max (never ultra)
+# decides WHICH gpt-6 variant (-m) and effort (-e) each task gets:
+#   gpt-6-luna  = trivial/mechanical   gpt-6.1-sol = default (medium) to hard (high/xhigh)
+#   gpt-6-astra = escalation only      effort: medium|high|xhigh|max (never ultra)
 #
 # Usage:
 #   codex-exec.sh [-m <model>] [-e <effort>] -C <workdir> -o <last-message-file> [-l <log-file>] "PROMPT"
@@ -24,7 +24,7 @@
 # parallel worktree runs from clobbering each other or the main tree.
 #
 # Env overrides (flags -m/-e take precedence):
-#   CODEX_MODEL   default: gpt-5.6-sol          gpt-5.6-sol | gpt-5.6-terra | gpt-5.6-luna
+#   CODEX_MODEL   default: gpt-6.1-sol          gpt-6.1-sol | gpt-6-astra | gpt-6-luna
 #   CODEX_EFFORT  default: high                 reasoning effort (never "fast"/low)
 #   CODEX_SANDBOX default: workspace-write (passed to codex's -s option)
 #   CODEX_BYPASS  set to 1 to use --dangerously-bypass-approvals-and-sandbox
@@ -52,7 +52,7 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-MODEL="${MODEL_FLAG:-${CODEX_MODEL:-gpt-5.6-sol}}"
+MODEL="${MODEL_FLAG:-${CODEX_MODEL:-gpt-6.1-sol}}"
 EFFORT="${EFFORT_FLAG:-${CODEX_EFFORT:-high}}"
 SANDBOX="${CODEX_SANDBOX:-workspace-write}"
 

package/templates/skills/qa/content.md

@@ -94,7 +94,7 @@ Write all test cases into the QA document's `## Test Cases` section.
 2. `agent-browser snapshot -i` to read the page state and its `@eN` refs
 3. Act on refs (`click @eN`, `fill @eN "text"`, `type`, `press`) and re-snapshot after every navigation or state change; refs are only valid for the snapshot that produced them
 4. `agent-browser screenshot /tmp/<name>.png` for evidence, then `agent-browser close`
-5. To share a screenshot outside the machine, upload it to agent-fs with `agent-fs write <path> --file /tmp/<name>.png -m "<what it shows>"` (binary-safe; `--content` mangles PNGs), keep it there as the original, and embed it in a PR or GitHub comment as a GitHub user attachment (`github-attach` skill): `![caption](https://github.com/user-attachments/assets/<uuid>)`. Use `agent-fs share-create <path>` for Slack or Linear. If agent-fs is not configured, report the local path and say the upload was skipped
+5. To share a screenshot outside the machine, upload it to agent-fs with `agent-fs write <path> --file /tmp/<name>.png -m "<what it shows>"` (binary-safe; `--content` mangles PNGs), keep it there as the original, and embed it in a PR or GitHub comment as a GitHub user attachment (`github-attach` skill): `![caption](https://github.com/user-attachments/assets/<uuid>)`. For Slack or Linear, paste the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>`; make an `agent-fs share-create <path>` link only when the requester asks for one or the reader has no agent-fs login. If agent-fs is not configured, report the local path and say the upload was skipped
 
 **For manual testing**:
 1. Present each test case's steps to the user
@@ -117,7 +117,7 @@ For each test case, record the actual result and pass/fail status.
 ### Step 4: Capture Evidence
 
 Gather evidence for the QA report:
-- **Screenshots**: Via `agent-browser screenshot` (kept on agent-fs; GitHub user attachments in a PR, `share-create` links elsewhere) or user-provided
+- **Screenshots**: Via `agent-browser screenshot` (kept on agent-fs; GitHub user attachments in a PR, live app links elsewhere) or user-provided
 - **Videos**: Session recording URLs (Loom, etc.)
 - **Logs**: Console output, error messages, relevant log lines
 - **External links**: Sentry issues, CI/CD runs, Grafana dashboards, PR URLs

package/templates/skills/researching/content.md

@@ -8,6 +8,8 @@ You are conducting comprehensive research across the codebase to answer question
 
 **All read/research work goes through sub-agents** — keep raw tool output out of the main session. Default to `run_in_background: true`.
 
+A graceful shutdown kills background sub-agents and loses every finding they have not returned. Write each sub-agent's findings (source URL or file:line plus a verbatim quote) into the research doc as they arrive, and save a v1 doc after the first round. On a long task, prefer one narrow gap-filling sub-agent at a time over an early wide fan-out. For web sources use the WebSearch and WebFetch tools: scraped search-engine result pages return captcha walls from worker containers.
+
 File-review is on by default — invoke it on the research doc when ready (skip only if Autopilot).
 
 ## When to Use

package/templates/skills/work-on-task/SKILL.md

@@ -13,7 +13,7 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
-Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it. Then list the task's local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Never re-run collection steps that already produced artifacts. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it. Then list the task's local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Never re-run collection steps that already produced artifacts. A render task (video, image, generated page) has no branch either: its live state is the local project directory plus the brief's agent-fs output. List both; timestamps are hints only. Before reusing an output, verify that it exists, is complete and valid, and corresponds to the current sources and render settings (for example, using recorded input/settings hashes). Download remote output and verify its bytes and provenance; agent-fs listing dates alone do not establish freshness. Re-render missing, invalid, incomplete or stale output. Hand over the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>` by default. Use a share link only when the requester asked for one or the reader has no agent-fs login: then reuse a usable one, and create a missing one or replace an expired, revoked or view-exhausted one without re-rendering a valid unchanged output. A task that covers several PRs re-reads every PR in scope (state, mergedAt, head SHA), not only the first: a PR that merged during the shutdown takes no more pushes. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
 
 Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.
 

package/templates/skills/work-on-task/content.md

@@ -8,7 +8,7 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
-Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it. Then list the task's local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Never re-run collection steps that already produced artifacts. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push. A document task has no branch: its live state is the brief's agent-fs output path and the task attachments. Run `agent-fs ls` on that path, download any partial and extend it. Then list the task's local work directory: a shutdown can leave the newest draft only there, or leave cache files half-written. Parse every cache file, delete the ones that fail, and re-run only the stages whose output is missing. Never re-run collection steps that already produced artifacts. A render task (video, image, generated page) has no branch either: its live state is the local project directory plus the brief's agent-fs output. List both; timestamps are hints only. Before reusing an output, verify that it exists, is complete and valid, and corresponds to the current sources and render settings (for example, using recorded input/settings hashes). Download remote output and verify its bytes and provenance; agent-fs listing dates alone do not establish freshness. Re-render missing, invalid, incomplete or stale output. Hand over the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>` by default. Use a share link only when the requester asked for one or the reader has no agent-fs login: then reuse a usable one, and create a missing one or replace an expired, revoked or view-exhausted one without re-rendering a valid unchanged output. A task that covers several PRs re-reads every PR in scope (state, mergedAt, head SHA), not only the first: a PR that merged during the shutdown takes no more pushes. If your task's `model` differs from the parent's, say so in the output, because the result's provenance changed.
 
 Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.