opencode-skills-collection 4.0.45 → 4.0.46

package/bundled-skills/pi-delegate/references/dispatch-and-poll.md

@@ -0,0 +1,146 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` wraps pi's non-interactive JSON mode, captures its event stream, and writes a
+`result.json`. Run one command, then read one file.
+
+## Before the first run
+
+```bash
+command -v pi
+pi --version
+pi --list-models   # optional: pick a model id for --model
+```
+
+Install with `npm install -g @earendil-works/pi-coding-agent`. Authenticate with `/login` inside
+pi (subscription providers) or an API-key environment variable; pi stores credentials in
+`~/.pi/agent/`.
+
+## Dispatching
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+```
+
+`<skill-dir>` is the installed folder containing this skill's `SKILL.md`.
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | Brief path. Omit it to read the brief from stdin. |
+| `--cd <dir>` | Working root and child process cwd (default: current directory). |
+| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. |
+| `--provider <name>` | pi provider name (default: pi's own default). Token-validated. |
+| `--model <pattern>` | pi model id or pattern (default: pi's own default). Token-validated: letters, digits, `. _ : / -`. |
+| `--session <id>` | Resume a specific pi session; send only the delta brief. |
+| `--resume-last` | Continue the most recent pi session for this cwd (`pi --continue`); send only the delta brief. |
+| `--read-only` | Restrict pi's callable tools to `--tools read,grep,find,ls`. |
+| `--approve` | Trust project-local `.pi` resources for this run. The default passes `--no-approve`. |
+| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Pi has no timeout flag. |
+| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
+| `-h`, `--help` | Print the relay's header help. |
+
+`--session` and `--resume-last` are mutually exclusive. The child cwd pins the workspace; pi has
+no add-dir flag and no sandbox, so reachability is simply the filesystem.
+
+Remember: pi has no permission modes. A run without `--read-only` can write and execute anything
+the user account can. `--read-only` removes write/edit/bash from Pi's callable tool surface, but
+installed extension code still runs with the user's host permissions.
+
+## Artifacts and result fields
+
+Artifacts live outside the repo by default, so they do not appear in `touchedFiles`; an
+`--out-dir` inside the worktree can make the artifacts appear there:
+
+- `brief.txt` - the exact brief.
+- `events.jsonl` - raw pi stdout events (the session header, then every agent event).
+- `final.txt` - assistant text joined with a blank line between chunks; absent if none was emitted.
+- `stderr.txt` - complete stderr.
+- `result.json` - the stable `delegate-relay.result.v1` contract.
+
+`result.json` fields:
+
+- `schema`, `tool` (`"pi"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `pi_unavailable`), `exitCode`, and
+  `signal` (`null` unless the child died on a signal).
+- `workdir`, requested `provider`/`model`, `projectTrusted`, `readOnly`, `resumed`, `piVersion`,
+  `sessionId`, `startedAt`, and `finishedAt`.
+- `actualProvider`, `actualModel`, `usage`, and `stopReason` from Pi's final assistant event.
+- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
+- `sessionId` - parsed from the JSON stream's `session` header. Resume with `--session <id>`.
+  Note: `--continue` may mint a new session id for the continued run; the result always reports
+  the id of the run that just happened.
+- `finalMessage` - assistant text parts joined with `"\n\n"`; tool calls and tool results are
+  excluded.
+- `touchedFiles` - `git status --porcelain` lines for the **final working tree under `--cd` only**,
+  not an attribution of pi's edits: anything already dirty before dispatch shows up too. Dispatch
+  from a clean tree when you want the list to read as "what pi changed". `null` means git could
+  not report; `[]` means git ran and the tree is clean.
+- `stderrTail` - the last 20 non-empty stderr lines on any run that did not complete (`failed`,
+  `timeout`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`.
+- `error` - present for launch failures, preflight failures, when the relay watchdog fires
+  (`timeout`), and on an `aborted` run.
+
+Pi's stream carries thinking and message-update events the relay archives but does not parse.
+
+## Waiting for completion
+
+The relay blocks. Use the orchestrator's background-command facility, or background it in a
+shell and poll for `result.json`. The run is done only when the process exits and the file
+contains a `status`. The result file is written atomically, so a partial read is impossible.
+
+A pre-run usage error exits 2 and writes no result. A missing `pi` exits 127 and writes
+`status: "pi_unavailable"`.
+
+## When a run misbehaves
+
+- **`status: "pi_unavailable"` (exit 127):** install pi (`npm install -g @earendil-works/pi-coding-agent`),
+  authenticate, and re-dispatch.
+- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
+  causes: an unknown `--model` (`Model "<x>" not found`), an expired login, or a provider error.
+  A final assistant event with `stopReason: "error"` or `"aborted"` is failed even if Pi exits zero.
+- **`status: "failed"` with an `error` mentioning `version preflight`:** the bounded `pi --version`
+  probe failed or hung, so pi was never dispatched. Check the install (`pi --version` yourself).
+- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
+  closed terminal) and forwarded the kill to pi. The result is written before the relay exits;
+  inspect the working tree before re-dispatching. On native Windows a hard kill of the relay is
+  uncatchable (Node supports no `SIGTERM` handler there), so this status may never get written -
+  a relay process that is gone without a `result.json` is an aborted run; inspect the working
+  tree and `events.jsonl` directly.
+- **`status: "failed"` with `signal: "SIGKILL"`:** the host killed the process, commonly through
+  the OOM killer or a supervisor timeout. This is not a pi error; check host memory and
+  re-dispatch, or split the task into smaller briefs.
+- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
+  `pi did not finish within --timeout <dur>; killed by the relay watchdog`. Increase `--timeout`
+  or split the task. On POSIX the relay sends SIGTERM to the process group, waits 10 seconds,
+  then sends SIGKILL if needed; on Windows there is no escalation phase — the whole process tree
+  is felled immediately with `taskkill /pid <pid> /t /f`.
+- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
+  `<structured_output_contract>` to the next brief to require a closing report.
+
+## Recovering lost work
+
+`events.jsonl` in the run directory records every event the implementer streamed. If finished
+work is lost — the run killed late, or the working tree damaged afterward — read the event log
+before re-dispatching: it identifies which files and tool commands were involved, which scopes
+what needs redoing. Tool execution events carry the write/edit arguments, but treat any
+reconstruction as unverified until it matches a working-tree diff — when the tree still holds the
+work, preserve the tree rather than replaying the log.
+
+## What the relay runs
+
+The launch is equivalent to:
+
+```bash
+cat brief.txt | pi --mode json [--provider <name>] [--model <pattern>] \
+  [--session <id> | --continue] [--approve | --no-approve] [--tools read,grep,find,ls]
+```
+
+The brief rides stdin, so it is not visible in the host process list and no argv size cap
+applies. On native Windows `pi` is a `.cmd` shim, so the relay launches it with `shell:true`;
+only the token-validated `--provider`/`--model`/`--session` values ever ride argv. Before dispatch the relay
+runs a bounded `pi --version` preflight (10s cap) so a hung or crashing CLI fails fast and
+explicitly instead of hanging the run. The relay passes `--no-approve` by default, so project
+`.pi` settings, extensions, and skills stay untrusted; `--approve` opts in for a trusted repository.
+
+## The commit boundary
+
+The relay never commits. Pi edits the working tree; the orchestrator reviews, re-runs the gates,
+and commits. See [review-and-land.md](review-and-land.md).

package/bundled-skills/pi-delegate/references/multi-task-queues.md

@@ -0,0 +1,59 @@
+# Multi-task queues
+
+The single-task loop scales to a queue: a removal across layers, a migration across files, or a
+refactor sweep. Sequencing and bookkeeping make it trustworthy.
+
+## Run sequentially, one commit per task
+
+Run tasks **one at a time, in dependency order**, landing each after review and gates before
+dispatching the next:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief task-01.txt --cd /path/to/repo
+```
+
+- Later briefs can rely on earlier work only after it lands.
+- One commit per task keeps history reviewable and each step revertible.
+- A clean tree before each dispatch keeps `touchedFiles` honest.
+
+Use parallel runs only for genuinely independent tasks in separate working trees. Sequential is
+the default because it preserves clean task boundaries.
+
+## Carry decided constraints forward
+
+Fresh pi sessions do not remember earlier tasks. If task 2 chooses a helper name, fixture
+location, or interface that task 5 needs, write that fact into task 5's brief.
+
+Use a resumed pi session only for rework on the same task. Send a delta brief with
+`--resume-last`, or with `--session <id>` from that task's `result.json`. Start unrelated queue
+items in fresh sessions.
+
+## Keep a progress file
+
+For more than two or three tasks, maintain one progress file beside the work:
+
+- **Status table** - queued / at-implementer / reviewed+committed, with the commit hash.
+- **Per-task review notes** - what landed, what you verified, and gate outcomes.
+- **Needs your eyes** - design decisions, non-blocking nitpicks, and questions for the human.
+- **End-of-run checklist** - the final cross-task verification.
+
+Update it when each task lands, not in one batch at the end.
+
+## Close with a coherence check
+
+After the last task:
+
+- Run the full test/build once more.
+- Search repo-wide for the thing the queue changed.
+- Replay migrations from a clean state and check drift when applicable.
+- Push and open or update the PR only after the final tree is coherent.
+
+## When to stop and ask
+
+Proceed on work that follows from the agreed plan. Stop and surface when:
+
+- A task cannot be completed correctly within its brief.
+- Review calls the plan itself into question.
+- Gates reveal a problem affecting already-landed tasks.
+
+Report the landed state, commit hashes, and open question, then wait.

package/bundled-skills/pi-delegate/references/review-and-land.md

@@ -0,0 +1,95 @@
+# Review and land
+
+The implementer made the changes; you own the judgment. Verify against reality, never the self-report, and read
+the diff as generated code because a green gate cannot catch every failure mode.
+
+## Check tests before trusting gates
+
+If the diff touches existing tests, review those edits first:
+
+- Treat unbriefed test edits as a contract change, not part of the fix.
+- Treat newly skipped, disabled, or commented-out tests as failing until proven otherwise.
+- Treat loosened assertions the same way: contains/truthy replacing exact matches, broadened error
+  types, and widened tolerances all weaken the gate.
+
+## Re-run the gates yourself
+
+`result.json` carries pi's claims, not evidence. Re-run the project's actual test, lint, and build
+commands in the working tree and read their output. Passing is necessary, not sufficient.
+
+For changes with a specialized verification shape:
+
+- **Migrations or schema:** round-trip them and check for drift.
+- **Removals or renames:** grep for dangling references.
+- **Stateful behavior:** exercise the behavior, not just compilation.
+
+## Read the diff against the brief
+
+Start with `touchedFiles`, open the diff, and compare it to the brief:
+
+- **Scope creep** - changes the brief excluded.
+- **Scope shortfall** - missed behavior, edges, or cleanup.
+- **Quiet judgment calls** - defensible but unasked decisions that need review.
+
+## The implementer sweep
+
+Check every diff for patterns gates often miss:
+
+- Hardcoded success or fixture data on a real-work path.
+- Catch-all error handling that returns a default instead of propagating or recovering.
+- Imports, dependencies, methods, and signatures not present in the installed version.
+- Unused imports, uncalled helpers, unreachable branches, and scaffolding comments.
+- A second client, error idiom, or logging style beside the repo's existing one.
+- Tests that assert internals instead of behavior, or near-duplicate test bodies.
+- Optional parameters, config flags, and abstractions with no caller.
+- Guards for impossible cases that hide trust-boundary validation.
+
+Send anything blocking back to pi as a delta brief, or fix it in the tree, and report either
+choice to the human. Run relevant guard skills if installed.
+
+## The commit boundary
+
+When the gates pass and the diff holds, **the orchestrator commits**, never the implementer.
+Write a clear message describing what landed.
+
+From dispatch until that commit, the uncommitted working tree is the authoritative copy of the
+implementer's work — the only one you can commit from, and often the only copy at all. Never run
+`git checkout`, `reset`, `clean`, or a branch switch in the workspace between those two points —
+however messy an interrupted run looks, inspect it first: `git status`, `git diff`,
+`git diff --cached` for anything the implementer staged (plain `git diff` is blind to the index),
+and open any untracked files (`??` in `git status`) directly — they are the implementer's new
+files, and no diff shows their contents. The tree is evidence, not clutter. After that inspection
+the verdict can legitimately be to discard — work built on a premise you have since corrected,
+for example — and then `git checkout`/`clean` is the right tool. The ban is on reflexive cleanup
+before anyone has looked.
+
+## Rework: send the delta
+
+Continue the same session with only the correction:
+
+```bash
+echo "The fix is right, but the test mocks the DB session. Use the real migrated fixture and remove the
+unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
+```
+
+Use `--session <id>` instead when resuming the specific id recorded in `result.json` - the stable
+handle, since `--continue` may mint a new id for each continued run. The relay rejects
+`--resume-last` plus `--session` before launch. Rework gets the same gate rerun, test review,
+diff review, and implementer sweep.
+
+Pi has no permission modes, so a write-capable rework run executes with no prompts - keep rework
+briefs as narrow as the original. A `--read-only` run removes write/edit/bash from Pi's callable
+tool surface, including extension/custom tools; installed extension code still runs with the
+user's host permissions, so inspect `touchedFiles` and the tree after every run.
+
+## Surface, do not absorb
+
+The human opted into delegation, so committing verified, gate-passing work is the contract. Keep
+them in the loop when the work changes shape:
+
+- Report design decisions and defensible-but-unrequested turns.
+- Note non-blocking nitpicks you did not block on.
+- Stop and ask if correct completion requires going beyond the brief.
+
+For a queue, keep these notes in the progress file described in
+[multi-task-queues.md](multi-task-queues.md).

package/bundled-skills/pi-delegate/references/writing-the-brief.md

@@ -0,0 +1,132 @@
+# Writing the brief
+
+A brief is the entire task as pi will see it. It runs in a separate session with **no memory of
+your conversation, no access to prior notes, and no shared context** - only the text you send and
+whatever it can inspect in the workspace. If a constraint is not in the brief or discoverable in
+the repo, it does not exist for pi.
+
+One shortcut: pi auto-loads `AGENTS.md` and `CLAUDE.md` context files from the workspace and its
+parent directories, so conventions written there reach pi without inlining. Restate the
+load-bearing rules in the brief anyway - the brief is the contract.
+
+## Model choice and resumed sessions
+
+Pi uses its configured default model when `--model` is omitted, so a fresh dispatch does not
+require it. Pass `--model <id>` only when the human asked for a specific model, choosing from
+`pi --list-models`. The relay forwards explicit ids and patterns (letters, digits, `. _ : / -`);
+glob patterns with `*` are rejected because the value reaches a shell on Windows.
+
+A resumed run keeps the session context. Send only the delta brief with `--resume-last` or
+`--session <id>`.
+
+## The shape that works
+
+Use a compact, block-structured brief. State the task, what done means, the few constraints that
+matter, and the report pi must return.
+
+```xml
+<task>
+One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to
+change, and explicitly what to leave untouched. The leave-untouched list prevents unrelated refactors.
+</task>
+
+<verification_loop>
+Run these before finishing and fix anything they surface, do not just report it:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+Confirm the working tree shows only the intended changes afterward.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the
+work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes (include test/lint counts)
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+Add extra blocks only when the task needs them:
+
+- **Debugging or open-ended fixes** - add `<completeness_contract>` (resolve fully, not just the
+  first plausible cause) and `<missing_context_gating>` (find missing repo facts or state what is
+  unknown).
+- **Research or recommendations** - add `<research_mode>` (separate observed facts, inferences,
+  and open questions), and dispatch with `--read-only` so Pi cannot invoke write/edit/bash tools.
+
+## Always ask for the report explicitly
+
+The relay builds `finalMessage` from assistant text in pi's JSON event stream. Without a closing
+summary, the edits may exist but the result is hard to review. The `<structured_output_contract>`
+block makes the expected report explicit.
+
+## Discover the real gates
+
+Read the repo's `AGENTS.md`, `CLAUDE.md`, `Makefile`, `package.json`, or equivalent first and copy
+the actual commands into `<verification_loop>`. A brief that says only "run the tests" makes the
+implementer guess or skip them.
+
+## Honor repo conventions
+
+Restate the load-bearing house rules in the brief. Pi can inspect the workspace (and auto-loads
+context files), but the important constraints should be directly in front of it.
+
+## One task per brief
+
+Keep each brief bounded. One brief -> one pi run -> one reviewed commit keeps the diff and
+rollback clean. Split mixed implementation, review, documentation, and roadmap requests into
+separate dispatches.
+
+## Premises freeze at dispatch
+
+The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
+fact block before sending — ownership, target branch, constraints, anything a judgment call rests
+on. If a premise turns out wrong while the run is live, stop the run and re-dispatch a corrected
+brief rather than discounting the output afterward; for a write-capable run, inspect the working
+tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
+re-dispatch.
+
+## A worked example
+
+```xml
+<task>
+In the payments service at services/billing/, the refund path double-charges when a refund is retried
+after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency
+key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge
+path, API routes, and data models untouched.
+</task>
+
+<verification_loop>
+Run and make green before finishing:
+  pytest tests/billing/ -q
+  ruff check services/billing/
+Confirm git status shows only refund.py and its test file changed.
+</verification_loop>
+
+<action_safety>
+Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
+changes in the working tree for review.
+</action_safety>
+
+<structured_output_contract>
+Report: (1) the root cause and fix, (2) files touched, (3) pytest and ruff outcomes with counts,
+(4) anything left open or needing a decision.
+</structured_output_contract>
+```
+
+## Stdin delivery
+
+The relay pipes the brief to pi on stdin. Unlike CLIs that take the brief as an argument, there
+is no OS argv size cap and the brief never appears in the host process list. Large context can be
+inlined, but prefer pointing pi at workspace files it can read itself. Keep secrets out of the
+brief anyway on shared machines - reference environment variables or files with tight permissions.
+
+Dispatch with [dispatch-and-poll.md](dispatch-and-poll.md), then review and commit with
+[review-and-land.md](review-and-land.md).

package/bundled-skills/qoder-delegate/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: qoder-delegate
+description: Delegate coding tasks to the Qoder CLI (`qodercli`) only when the user
+  explicitly requests it, while the orchestrator retains review and landing responsibility.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+metadata:
+  version: 0.5.0
+---
+# Qoder Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `qoder` implementer (`Qoder`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. Delegate one bounded coding task to a separate **implementer** - Qoder CLI -
+then review what it produced and land it yourself. You write the brief and own the judgment; Qoder
+edits the working tree in its session; you verify and commit.
+
+The loop needs only shell and file access, so any comparable orchestrator can drive it.
+
+## When NOT to use this
+
+- The task is small enough to do inline; delegation overhead is not worth it.
+- `qodercli` is not installed or authenticated.
+- You want to write the code yourself or need only an interactive Qoder session.
+
+## Prerequisites (check once)
+
+```bash
+command -v qodercli
+qodercli --version
+qodercli --list-models
+```
+
+If the binary is missing, install it from Qoder's
+[official Quick Start](https://docs.qoder.com/en/cli/quick-start). Authenticate with `qodercli login`,
+or set `QODER_PERSONAL_ACCESS_TOKEN` for automation. A successful `--list-models` confirms the current
+account can return its live model catalog.
+
+## Choose model and context window
+
+Qoder's available models can change. If the human requests a model, use its exact current value from
+`qodercli --list-models`; never invent or pin a catalog entry. Otherwise omit `--model` and let Qoder
+use its current default.
+
+`--context-window <n>` is optional. Pass a positive integer only when the human requests a size or the
+task needs an explicit budget. Qoder applies it only to supported models; surface an unsupported
+model/size error instead of silently choosing another value.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Qoder sees the brief plus what it can inspect in the workspace, not this chat. Include the goal,
+current state, what to change, what to leave untouched, the project's **actual** gates, and a closing
+report contract. Tell Qoder not to commit. Keep one task per brief. See
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Use the bundled relay. It wraps Qoder's non-interactive `stream-json` mode and writes `result.json`.
+`<skill-dir>` is the installed folder containing this `SKILL.md`.
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# choose a live model:                 add --model "<value from qodercli --list-models>"
+# request a supported context window: add --context-window 32768
+# resume the latest session:          add --resume-last  # delta brief only
+# resume a specific session:          add --resume <id>  # delta brief only
+# see every option:                   node .../relay.mjs --help
+```
+
+Implementation runs default to Qoder's `auto` permission mode. The relay never bypasses permissions
+unless the caller explicitly requests it, and it never commits. See
+[references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The relay blocks until Qoder exits. Run it with the orchestrator's background-command facility, or
+background it in the shell and wait for `result.json`. Completion means the process exited and the
+file contains a `status`; do not trust a progress display.
+
+A pre-run usage error exits 2 and writes no result. Missing `qodercli` exits 127 and writes
+`status: "qoder_unavailable"` with installation guidance.
+
+Native Windows relay launch is not yet verified; do not claim it until a native Windows smoke passes.
+
+### 4. Review - do not trust the self-report
+
+Treat Qoder's final message and gate outcomes as claims:
+
+- Re-run the project's gates yourself.
+- Read the diff against the brief, starting with `touchedFiles`.
+- Check any `--add-dir` workspaces separately; their changes are not in the primary tree report.
+- Run relevant guard skills if installed.
+- Round-trip migrations and grep for dangling references after removals or renames.
+
+See [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The implementer edits; **the orchestrator commits**. Commit only after the gates pass and the diff
+holds. If rework is needed, send a delta brief with `--resume-last` or `--resume <id>`, then review
+again.
+
+## Permission model
+
+Qoder print mode cannot show approval prompts. The relay defaults to `auto`, which makes
+non-interactive allow/deny decisions. `default` can deny actions that would require a prompt;
+`accept_edits` permits workspace edits but may deny shell actions; `dont_ask` fails closed; `plan`
+maps to `default` plus Qoder's Plan work state; and `bypass_permissions` is for explicitly trusted
+runs only.
+
+Qoder falls back to `default` when a non-default mode is requested outside a trusted directory. Check
+`actualPermissionMode` in `result.json`; no requested mode replaces diff review.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they ask for it, landing verified, gate-passing work
+is the contract. Two limits remain: **surface, do not absorb** (report Qoder's design decisions and
+non-blocking deviations) and **stop for scope changes** (ask before expanding beyond the brief). See
+[references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) - brief structure, real gates,
+  report contract, secrets, and delta briefs.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) - flags, model/context controls,
+  artifacts, result fields, sessions, and failure recovery.
+- [references/review-and-land.md](references/review-and-land.md) - independent review, commit boundary,
+  and rework.
+- [references/multi-task-queues.md](references/multi-task-queues.md) - sequential queues, constraint
+  carry-forward, progress tracking, and final coherence.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `qoder` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.