@sous-io/sous 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Luke Chavers
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,154 @@
+# sous
+
+sous compiles AI coding agent configuration from templates. You write skills, memories, and
+instructions once as LiquidJS templates in layered sources, then sous renders them into the
+formats agents actually read: `.claude/` plus `CLAUDE.md` for Claude Code, `.codex/` plus
+`AGENTS.md` for Codex. The CLI binary is named `xcv`.
+
+## Why
+
+- Share one set of agent configs across every project you work in, and with teammates.
+- Write a rule once as a template with variables; each project gets its own rendered copy.
+- Compile the same source to more than one agent's format.
+- Keep machine-specific values (absolute paths, tokens) in an untracked env file, out of git,
+  with shared team defaults in a committed one.
+
+## Quickstart
+
+Install the CLI:
+
+```bash
+git clone git@github.com:sous-io/sous.git
+cd sous
+npm install
+npm link
+```
+
+Then set up a project. A project needs a `.sous/` directory holding a config file, named
+`sous.config.js`, `sous.config.mjs`, or `sous.config.json`:
+
+```bash
+cd /path/to/your/project
+mkdir .sous
+$EDITOR .sous/sous.config.js
+```
+
+A config that compiles one file:
+
+```js
+export const config = {
+  projects: {
+    myproject: {
+      name: "My Project",
+      _vars: { projectRoot: "${sousDir}/.." },
+      compilation: {
+        targets: [
+          {
+            entryPoint: "${sousDir}/AGENTS.md",
+            outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
+          },
+        ],
+      },
+    },
+  },
+};
+```
+
+`${sousDir}` is the `.sous/` directory sous found, so a config can name paths relative to
+itself without hardcoding anything machine-specific. With a single project defined you do
+not need `defaultProject`; sous uses the only one. Then build:
+
+```bash
+xcv build
+```
+
+`xcv build` compiles every configured target and prunes outputs that are no longer in the
+config. Config discovery walks up from the current directory until it finds a `.sous/`
+directory holding a config, so you can run it from anywhere inside the project. Pass
+`--config <path>` to point at one explicitly instead.
+
+Values reach the config through its top-level `_env` block, which maps a config variable
+to an environment variable. Both env files use `KEY=value` lines and are loaded before
+anything resolves. There are two layers:
+
+- `.sous/.env` is committed. Put shared team defaults here, never secrets.
+- `.sous/.env.local` is gitignored. Put machine-specific values and secrets here.
+
+Precedence, highest first: your shell environment, then `.env.local`, then `.env`. So
+`FOO=bar xcv build` beats both files, and `.env.local` beats `.env` per key. This repo
+ships `.sous/.env.local.example` documenting the layer.
+
+Useful commands:
+
+| Command | What it does |
+|---|---|
+| `xcv build` | Compile, then prune stale outputs |
+| `xcv build --watch` | Rebuild on source changes |
+| `xcv compile` | Compile only |
+| `xcv prune` | Remove outputs no longer in the config |
+| `xcv clear` | Delete every file sous wrote for the project |
+| `xcv launch claude` | Build, then start the agent |
+
+## How it works
+
+Sources are markdown files. A file with `.tpl.` in its name is rendered through LiquidJS and
+the `.tpl.` is dropped from the output name (`skill.tpl.md` becomes `skill.md`). Files without
+`.tpl.` are copied verbatim. Any line of the form `@path/to/file.md` pulls in another file, so
+one instruction block can be composed into several outputs.
+
+Config lists targets. Each target names an entry point or a glob, plus one or more outputs, and
+each level can define variables:
+
+```js
+// One entry point to one file.
+{
+  entryPoint: "${sousDir}/memory/MEMORY.root.tpl.md",
+  outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
+}
+
+// One glob to a directory, mirroring the source tree under it.
+{
+  entryGlob: "${sousDir}/skills/**/*",
+  outputs: [{ destinationDir: "${projectRoot}/.claude/skills" }],
+}
+```
+
+Variables resolve later-wins across scopes: auto-injected, env, root, project, compilation,
+target, output. Templates read them as `{{ varName }}`; config files reference them as `${varName}`.
+The auto-injected ones include `${sousDir}` and `${sousConfigPath}` for the discovered
+config, and `${sousTemplatePath}` for the template being rendered.
+
+Sources come in three tiers, each able to build on the one above it:
+
+1. **Built-in** shared prompts that ship with sous, covering skill authoring, templating, and
+   the sous conventions themselves.
+2. **Team-shared**, a repo your team owns, holding the configs everyone should get.
+3. **Per-project**, the project's own `.sous/` directory, for anything specific to it.
+
+The built-in tier is reachable without knowing where sous is installed. `@include` paths
+accept aliases, and two are always defined: `~sous-shared` for the shared prompts that ship
+with sous, and `~project` for the project root. So `@~sous-shared/_partials/sub-agent-delegation.md`
+composes a built-in block into your own instruction file, and an `entryGlob` can point at a
+built-in skill bundle to compile it into your project. Define your own aliases with an
+`_aliases` block to do the same for a team-shared repo.
+
+Sous records every file and directory it writes in a state file, `.sous/sous.state.json` by
+default, which is what lets `prune` and `clear` clean up precisely instead of guessing.
+
+## Platform support
+
+- **Ubuntu** is where sous is developed and tested.
+- **macOS** should work for the core CLI, but is not tested yet. Reports welcome.
+- **Windows** is not supported.
+- The browser-automation skill bundle is **Linux only**. It depends on Linux Chrome paths and
+  the GNOME keyring.
+
+Node 22 is required; the version is pinned in `.nvmrc`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Note the licensing terms for contributions.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).

package/bin/run.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+// The CLI runs from TypeScript source; register tsx before oclif dynamically
+// imports any command module. Resolving "tsx" from this file (rather than a
+// $PKG_ROOT/node_modules path) works in every install layout: repo clone,
+// global install (nested deps), and local/npx installs (hoisted deps).
+register();
+
+const { execute, settings } = await import("@oclif/core");
+
+// tsx (above) already makes .ts imports work, so oclif's own auto-transpile
+// machinery is redundant; leaving it on makes every downstream run warn that
+// the (unshipped) typescript devDependency is missing.
+settings.enableAutoTranspile = false;
+
+await execute({ development: true, dir: import.meta.url });

package/bin/xcv

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+# Dev convenience wrapper used by the repo's npm scripts (`./bin/xcv ...`).
+# The published bin is run.js itself, which handles tsx registration.
+exec node "$(cd -P "$(dirname "${BASH_SOURCE[0]}")" > /dev/null && pwd)/run.js" "$@"

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@sous-io/sous",
+  "version": "0.1.0",
+  "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Luke Chavers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sous-io/sous.git"
+  },
+  "homepage": "https://sous-io.github.io/sous",
+  "bugs": "https://github.com/sous-io/sous/issues",
+  "keywords": [
+    "cli",
+    "ai",
+    "agents",
+    "claude",
+    "claude-code",
+    "codex",
+    "prompts",
+    "skills",
+    "templates",
+    "liquidjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "xcv": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/test",
+    "shared-prompts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "sous:build": "./bin/xcv build --rebuild",
+    "claude": "./bin/xcv launch claude",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "@oclif/color": "^1.0.13",
+    "@oclif/core": "^4",
+    "chokidar": "^5.0.0",
+    "glob": "^13.0.6",
+    "liquidjs": "^10.25.0",
+    "minimatch": "^10.2.4",
+    "tiktoken": "^1.0.22",
+    "tsx": "^4"
+  },
+  "devDependencies": {
+    "@types/glob": "^8.1.0",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.0",
+    "memfs": "^4.56.11",
+    "typescript": "^5",
+    "vitest": "^4.1.0"
+  },
+  "oclif": {
+    "bin": "xcv",
+    "dirname": "xcv",
+    "flexibleTaxonomy": true,
+    "topicSeparator": " ",
+    "commands": {
+      "strategy": "pattern",
+      "target": "./src/commands"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/shared-prompts/_partials/resume-task.md

@@ -0,0 +1,51 @@
+The agent performing this work MUST load `about-task-files`.
+
+## Delegation
+
+Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), the
+orchestrator delegates steps 1 and 2 (find and read the task file, extract status) to a background
+sub-agent, which reports back a concise summary. Step 3 is orchestrator-only.
+
+## Steps
+
+### 1. Find the Task File
+
+Run `git status` to get the current branch name. Look for the task file at:
+```
+{{ taskFileRoot }}/[branch-name].md
+```
+
+If not found, run a fresh `git status` to confirm the branch before concluding the file doesn't exist. If it truly doesn't exist, report that back; the orchestrator asks the user whether to create one (load `start-task`).
+
+### 2. Read and Analyze
+
+Read the entire task file. Identify:
+- Overall objective
+- What has been completed (checked items, status markers)
+- What remains (unchecked items, TODOs)
+- Any blockers or pending issues
+- Recent decisions and learnings
+
+### 3. Present Status and Next Steps
+
+Orchestrator-only; sub-agents cannot talk to the user. A sub-agent doing steps 1 and 2 returns its
+summary to the orchestrator, which presents:
+
+```
+Based on the task file, here's where we are:
+
+**Current Status:**
+[Brief summary of completed phases and where work stopped]
+
+**Recommended Next Steps:**
+1. [First thing to do]
+2. [Second thing]
+3. [etc.]
+
+Would you like me to:
+- A) Proceed with these next steps?
+- B) Focus on something specific?
+- C) Something else?
+```
+
+**Do not begin work until the user confirms.** If the task file has contradictions or outdated information, point them out before proceeding.

package/shared-prompts/_partials/sub-agent-delegation.md

@@ -0,0 +1,32 @@
+# Sub-Agent Delegation
+
+Several shared skills say work is "delegated" and cite the sub-agent delegation pattern. This is
+that pattern. Include this partial in a project's core memory (`@~sous-shared/_partials/sub-agent-delegation.md`)
+if the project wants the agent to follow it by default.
+
+The main chat session is an **orchestrator**: it does the reasoning, the decisions, and all
+interaction with the user, and it delegates execution to sub-agents. The orchestrator usually runs
+an expensive model, so pushing execution down to cheaper sub-agents cuts cost and, because
+sub-agents run in parallel, finishes sooner.
+
+**Orchestrator-only:** planning, decisions, anything that needs the user (questions, approvals,
+drafts), and very small actions where delegating costs more than doing it (a quick file read, a
+one-line edit).
+
+**Delegated:** anything with real work in it, including research, code changes, doc and task file
+writing, and multi-step lookups.
+
+**Rules:**
+
+- Run sub-agents in the background and in parallel by default; batch independent dispatches into one
+  message. Go synchronous only when the result blocks the very next step.
+- Prompts must be self-contained. Sub-agents start with fresh context and cannot see the
+  conversation, so state every fact, path, ID, and decision they need, and name the skills they
+  should load. Anything the sub-agent can gather itself (branch name, commits, test output) should
+  be left to it.
+- Sub-agents cannot talk to the user. Questions and user-facing messages go back to the orchestrator
+  to relay.
+- Every sub-agent reports a concise summary of what it did or found, not a file dump.
+- The orchestrator spot-checks load-bearing results (task files, code diffs, outward-facing writes)
+  in a cheap, targeted way; it does not re-read everything.
+- Never fabricate or predict a pending sub-agent's result. Wait for it.

package/shared-prompts/_partials/update-task-file.md

@@ -0,0 +1,52 @@
+The agent performing this work MUST load `about-task-files`.
+
+**CRITICAL: Do NOTHING ELSE. Update the task file IMMEDIATELY. Use as few edits as possible.**
+
+## Delegation
+
+Per the sub-agent delegation pattern (`~sous-shared/_partials/sub-agent-delegation.md`), writing the
+task file is delegated work. The orchestrator does not edit the file itself; it hands an Opus
+sub-agent everything below in one self-contained prompt:
+
+- The task file path (branch name), or instructions to derive it from `git status`.
+- The facts and decisions to record. Compiling these is orchestrator-only; sub-agents cannot see
+  this conversation, so anything known only from the conversation must be stated in the prompt.
+- Anything the sub-agent can gather itself (commit list, changed files, test/build output), which it
+  should collect rather than have the orchestrator paste in.
+
+The sub-agent loads `about-task-files`, edits the file, and reports back a concise summary of what
+it wrote. The orchestrator spot-checks with a targeted diff, not a full re-read.
+
+## What to Include
+
+Update the task file with all of the following:
+
+1. **Progress since last update** — what was completed, what is in progress, current status
+2. **Decisions made** — technical approach chosen, alternatives considered and rejected
+3. **Remaining work** — everything still needed, prioritized next steps, known dependencies
+4. **Pending issues** — unresolved problems, blockers, questions needing answers
+5. **Learnings** — insights, patterns discovered, things to remember
+6. **Commits made** — commit IDs and brief description of each
+7. **Testing URLs** — web URLs currently in use, database query results referenced
+8. **Files changed** — absolute paths with line numbers, what was done and why
+9. **Unresolved errors** — test failures, build errors, TypeScript errors — with paths and line numbers
+
+## Checklist Management
+
+- Mark completed items `[x]`
+- Add `[ ]` for newly identified tasks
+- Remove or condense sections no longer relevant
+
+## Consistency Check
+
+Scan the existing file for contradictions or outdated information. Correct before saving.
+
+## After Update
+
+**STOP immediately.** Do not:
+- Continue working on the task
+- Start new work
+- Make additional changes
+
+A sub-agent reports what it wrote and stops. The orchestrator then waits; the user will end the
+session and start a new one.

package/shared-prompts/memories/automated-browser-tasks/INDEX.tpl.md

@@ -0,0 +1,52 @@
+# Automated Browser Tasks
+
+This project can drive a real web browser to accomplish tasks — logging in as
+you (using your existing Chrome session), navigating, and extracting data —
+**headlessly**, without opening a visible browser or interrupting your work.
+
+**When a task needs a browser and no API or MCP server can do it, this is the
+default path.** Do not tell the user to click through a browser manually if it
+can be scripted.
+
+**Running a non-mutating task is normal workflow — do it without asking.** A task
+that only navigates and reads (extracts data; submits nothing, changes no state,
+sends nothing outward) is investigation, the same category as reading a file or
+running a query. Running an existing read-only task is not a "manual action" and
+not "outward-facing," so it does not need the user's permission — especially while
+investigating. Just run it and report what it found; pausing to ask first only
+wastes a round trip on a no-risk action. (Creating or modifying a task script, or
+running a task that mutates external state, is a separate case — apply normal
+judgment there.)
+
+The agent performing the work MUST load the `about-automated-browser-tasks` skill
+before writing, running, or modifying any of these tasks. It explains the `ctx`
+API, the auth model, and the scriptwriting conventions. The action skills
+`create-automated-browser-task`, `update-automated-browser-task`, and
+`running-automated-browser-tasks` cover those specific operations (including
+exact runner invocation).
+
+Browser runs are slow and multi-step, so they are delegated to a background
+sub-agent, per the sub-agent delegation pattern
+(`~sous-shared/_partials/sub-agent-delegation.md`). The sub-agent loads the skills
+itself and reports the result plus any link or actionable message.
+
+## Available Tasks
+
+{% getFiles browserTasks root=browserAutomationScriptsDir include="*.mjs" import="meta" -%}
+{% if browserTasks.size > 0 -%}
+{%- for t in browserTasks %}
+### {{ t.meta.name }}
+
+{{ t.meta.description }}
+
+- Script: `{{ t.path }}`
+{%- if t.meta.params %}
+- Parameters:
+{%- for p in t.meta.params %}
+  - `{{ p[0] }}` ({% if p[1].required %}required{% else %}optional{% if p[1].default %}, default: `{{ p[1].default }}`{% endif %}{% endif %}) — {{ p[1].description | split: ". " | first }}.
+{%- endfor %}
+{%- endif %}
+{% endfor -%}
+{% else -%}
+_No automation tasks exist yet. Load `create-automated-browser-task` to add one._
+{% endif %}