@sous-io/sous 0.1.1 → 0.2.1

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/references/advanced-patterns.md

@@ -3,7 +3,7 @@
 ## Dynamic Context Injection
 
 The `` !`command` `` syntax runs a shell command before skill content is sent to Claude.
-The output replaces the placeholder — Claude receives the rendered result, not the command.
+The output replaces the placeholder; Claude receives the rendered result, not the command.
 
 ```yaml
 ---
@@ -44,16 +44,16 @@ Research $ARGUMENTS thoroughly:
 ```
 
 The `agent` field selects the subagent configuration:
-- `Explore` — read-only tools optimized for codebase exploration
-- `Plan` — planning-oriented execution
-- `general-purpose` — default; full tool access
+- `Explore`: read-only tools optimized for codebase exploration
+- `Plan`: planning-oriented execution
+- `general-purpose`: default, full tool access
 - Any custom agent defined in `.claude/agents/`
 
 Results are summarized and returned to the main conversation.
 
 > Only use `context: fork` for skills with explicit task instructions. Skills containing
 > only reference guidelines (e.g. "use these conventions") will return without meaningful
-> output — the subagent has no actionable task.
+> output; the subagent has no actionable task.
 
 ## Restricting Tool Access (`allowed-tools`)
 
@@ -76,7 +76,7 @@ and reference them from the skill body so Claude knows when to load them.
 ```
 my-skill/
 ├── SKILL.md             # Overview, navigation, fundamental instructions
-├── references/          # Deep-dive docs — loaded when needed, not always
+├── references/          # Deep-dive docs: loaded when needed, not always
 │   └── api-spec.md
 ├── examples/            # Example outputs showing expected format
 └── scripts/             # Executable scripts; referenced via $CLAUDE_SKILL_DIR

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/references/commands.md

@@ -6,13 +6,13 @@ user-initiated workflow. The user explicitly triggers it with `/skill-name`.
 ## Key Properties
 
 - Set `disable-model-invocation: true`. This removes the skill from Claude's context
-  entirely — it loads only when the user invokes it. See `frontmatter.md` for the
+  entirely; it loads only when the user invokes it. See `frontmatter.md` for the
   invocation matrix.
 - Because the model never sees the description, write it for humans, not for Claude.
-  It appears in the `/` autocomplete menu. Plain, informative language is appropriate —
+  It appears in the `/` autocomplete menu. Plain, informative language is appropriate;
   strong trigger language ("YOU MUST") is unnecessary and out of place.
 - Commands do not require an `# Abstract` section. Include one only if useful context
-  is genuinely needed. Headings are optional in general — use them only if the content
+  is genuinely needed. Headings are optional in general; use them only if the content
   is complex enough to warrant structure.
 
 ## Arguments
@@ -21,7 +21,7 @@ Commands often accept arguments (e.g. `/deploy staging`). When they do:
 
 1. Use `$ARGUMENTS` (or `$0`, `$1`, etc.) in the skill body where the arguments should
    be substituted. See `substitutions.md` for full syntax.
-2. Add an `argument-hint` field to frontmatter — it appears in autocomplete next to the
+2. Add an `argument-hint` field to frontmatter; it appears in autocomplete next to the
    command name.
 
 ```yaml
@@ -42,5 +42,5 @@ appends them automatically as `ARGUMENTS: <value>`.
 
 Not every command needs `disable-model-invocation: true`. If it makes sense for Claude
 to invoke the command autonomously on the user's behalf (e.g. a lightweight helper with
-no side effects), omit the flag. Use judgement — the defining question is whether the
+no side effects), omit the flag. Use judgement; the defining question is whether the
 action should require explicit user intent.

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-agent-skills/references/frontmatter.md

@@ -8,11 +8,11 @@ All fields are optional, though `description` is strongly recommended.
 | `name`                     | Slash-command name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
 | `description`              | When to invoke this skill. Used by Claude for auto-invocation. Falls back to first paragraph of content. |
 | `argument-hint`            | Hint shown in autocomplete. Example: `[issue-number]` or `[filename] [format]`. |
-| `disable-model-invocation` | `true` — user-only invocation. Description removed from Claude's context entirely. Use for side-effect workflows. Default: `false`. |
-| `user-invocable`           | `false` — hides from `/` menu; only Claude can invoke. Use for background knowledge. Default: `true`. |
+| `disable-model-invocation` | `true`: user-only invocation. Description removed from Claude's context entirely. Use for side-effect workflows. Default: `false`. |
+| `user-invocable`           | `false`: hides from `/` menu; only Claude can invoke. Use for background knowledge. Default: `true`. |
 | `allowed-tools`            | Tools Claude may use without per-use approval when this skill is active. Example: `Read, Grep, Glob`. |
 | `model`                    | Model to use when this skill is active. |
-| `context`                  | `fork` — run the skill in an isolated subagent. Skill content becomes the subagent prompt. |
+| `context`                  | `fork`: run the skill in an isolated subagent. Skill content becomes the subagent prompt. |
 | `agent`                    | Subagent type when `context: fork` is set. Options: `Explore`, `Plan`, `general-purpose`, or any custom agent in `.claude/agents/`. Defaults to `general-purpose`. |
 | `hooks`                    | Hooks scoped to this skill's lifecycle. |
 

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/about-liquid-templates/SKILL.tpl.md

@@ -22,15 +22,15 @@ at compile time. The `.tpl.` segment is stripped from the output filename.
 | `config.tpl.sh`      | Yes        | `config.sh`       |
 | `README.md`          | No         | `README.md`       |
 
-**`SKILL.md` for any skill compiled by sous must always be `SKILL.tpl.md`** — the
+**`SKILL.md` for any skill compiled by sous must always be `SKILL.tpl.md`**; the
 required `## Source for this Skill` footer cannot be rendered without LiquidJS
 processing. See `about-agent-skills` for the full rule.
 
 For all other files, use `.tpl.` only when the file genuinely needs variable
-substitution, partials, or conditionals. Static files are copied verbatim — faster
-and safer.
+substitution, partials, or conditionals. Static files are copied verbatim (faster
+and safer).
 
-## Two Syntaxes — Do Not Mix
+## Two Syntaxes: Do Not Mix
 
 Sous uses two different variable syntaxes at two different stages. Using the wrong one in
 the wrong place silently produces the literal text instead of a value.
@@ -92,9 +92,9 @@ Include another file at render time (path **relative to the template file's dire
 {% endraw %}
 
 `render` resolves paths relative to the template file. For files outside that tree, use
-a path **alias** (`@~sous-shared/...`, `@~project/...`, or a user-defined alias) or a
-`@`-prefixed `${var}` path — the same alias resolution as `@include` (see below) works in
-`render` too.
+a recipe reference (`@~<namespace>/<recipe>/...`), a path **alias** (`@~project/...`, or a
+user-defined alias) or a `@`-prefixed `${var}` path; the same resolution as `@include`
+(see below) works in `render` too.
 
 To prevent template sequences from being processed in a code example, wrap the block in
 `raw` / `endraw` tag blocks. These blocks cannot be nested: the first `endraw`
@@ -119,7 +119,7 @@ filter name shows up only as missing or unfiltered output.
 ### Gotcha: `@include` fires inside fenced code blocks
 
 The `@include` processor runs on the raw file content *before* LiquidJS and has no
-markdown awareness whatsoever — it matches any line that is nothing but an `@`-prefixed
+markdown awareness whatsoever; it matches any line that is nothing but an `@`-prefixed
 `.md` path. A fenced code block does not protect it: an `@path.md` line inside triple
 backticks is still executed and replaced with the file's content. There is no escape
 syntax. To show an `@`-path as an example, put something else on the line (indent it,
@@ -130,20 +130,35 @@ prefix it with a word, or wrap it in backticks inline).
 A `@`-path may be any of:
 
 - **Relative** to the including file: `@sections/intro.md` (traverse up with `../`).
-- **Variable-substituted**: `@${sousRootPath}/shared-prompts/x.md` — `${var}` is
+- **Variable-substituted**: `@${projectRoot}/prompts/x.md`; `${var}` is
   substituted before resolving; if the result is absolute it is used directly.
 - **Aliased**: `@<alias>/rest.md`, where the first segment names a registered alias.
 
-### Path aliases
+### Recipe references and path aliases
 
-The first path segment, up to the first `/` or `:` (both separators work — `@a/b.md`
-≡ `@a:b.md`), is matched against the alias registry. Built-in aliases are reserved and
-always begin with `~`:
+The first path segment, up to the first `/` or `:` (both separators work, so `@a/b.md`
+is the same as `@a:b.md`), is matched first against the alias registry and then, when it begins with
+`~`, against the recipe namespaces this project or recipe can address.
+
+The normal way to reach a file that another recipe publishes is a **recipe reference**,
+written `@~<namespace>/<recipe>/<path inside that recipe>`:
+
+- `@~workflow/task-files/_partials/resume-task.md` → the file `_partials/resume-task.md`
+  inside the recipe `workflow/task-files`, at the version this project has pinned.
+
+Scoping is deliberate. A file inside a recipe may address that recipe itself plus the
+recipes it declares under `depends` or `subscribes`; a file in the project's own templates
+may address the project's subscriptions. Anything else is an error naming what was missing,
+so a reference can never quietly pick up a recipe nobody asked for.
+
+Built-in **aliases** are reserved, always begin with `~`, and are consulted before recipe
+namespaces. There is exactly one:
 
-- `@~sous-shared/...` → the Sous CLI's `shared-prompts` directory (skills, memories,
-  `_partials`, etc.). Example: `@~sous-shared/_partials/resume-task.md`.
 - `@~project/...` → the consuming project's root.
 
+Everything else sous once shipped inside its own package is published as a recipe now, so
+a recipe reference is what reaches it.
+
 Projects register their own aliases in settings via an `_aliases` block (root and/or
 project level); names may **not** start with `~` (reserved). An alias value is a string
 or an array of strings (each may use `${var}`):
@@ -159,23 +174,23 @@ wins**; if none exist, the build errors listing every path tried:
 
 1. Each base of the matched alias, in order (project `_aliases` are tried before root,
    before built-in bases of the same name).
-2. The path resolved **relative to the including file** — using the *full* path
+2. The path resolved **relative to the including file**, using the *full* path
    including the alias segment. So an alias miss can fall through to a real relative
    directory of the same name, letting an alias **augment** a local directory.
 
 ## Custom Tags
 
-**`showVars`** — dumps all variables currently in scope as a fenced JSON block.
+**`showVars`**: dumps all variables currently in scope as a fenced JSON block.
 Useful during development to see exactly what variables are available at a given point
 in a template. Remove before finalizing.
 
-**`getFiles`** — globs files under a root directory and assigns the resulting array to a
+**`getFiles`**: globs files under a root directory and assigns the resulting array to a
 template variable. It renders nothing; present the results yourself with a `for` loop.
 Each entry has `path`, `dir`, `relPath`, and `name`. `include`/`exclude` take
 comma-separated glob patterns matched relative to `root`, and attribute values may be
 quoted strings or scope variables. The optional `import="<exportName>"` dynamically
 imports each file and attaches that export to the entry (files that fail to import, or
-that lack the export, are dropped) — this is how a manifest of scripts reads its own
+that lack the export, are dropped); this is how a manifest of scripts reads its own
 metadata:
 
 {% raw %}
@@ -188,7 +203,7 @@ metadata:
 ```
 {% endraw %}
 
-**`listFiles`** — the convenience counterpart to `getFiles`: it globs and renders a
+**`listFiles`**: the convenience counterpart to `getFiles`: it globs and renders a
 markdown bullet list of file names inline, with no loop needed. Add `relative="true"` to
 render paths relative to the root instead of bare file names:
 
@@ -198,7 +213,7 @@ render paths relative to the root instead of bare file names:
 ```
 {% endraw %}
 
-**`exportScalarVarsJs`** — emits every in-scope scalar variable (string, finite number,
+**`exportScalarVarsJs`**: emits every in-scope scalar variable (string, finite number,
 boolean) as an ES module default export, keys sorted. Objects, arrays, `null` and
 non-finite numbers are skipped. Use it to compile a settings module that runtime code
 imports, rather than re-deriving project configuration:
@@ -211,7 +226,7 @@ imports, rather than re-deriving project configuration:
 
 ## Custom Filters
 
-**`bulletList`** — converts an array variable to a markdown bullet list:
+**`bulletList`**: converts an array variable to a markdown bullet list:
 
 {% raw %}
 ```
@@ -231,7 +246,7 @@ Given a non-array value, `bulletList` returns it as a plain string with no bulle
 ## Authoring Guidelines
 
 Templates (`.tpl.*` files) must be **maximally reusable**. A well-written template
-can be copied between projects or shared across teams without edits — only the
+can be copied between projects or shared across teams without edits; only the
 project's variables change.
 
 **Rules:**
@@ -244,7 +259,7 @@ project's variables change.
    a variable is set, wrap it in {% raw %}`{% if varName %} ... {% endif %}`{% endraw %} so the
    block disappears cleanly for projects that don't define it.
 3. **Prefer derived variables over raw values.** Example: `ticketPrefix` is derived
-   from `jiraProjectKey` — templates use `ticketPrefix` so they stay correct if the
+   from `jiraProjectKey`; templates use `ticketPrefix` so they stay correct if the
    key changes.
 4. **Test portability mentally.** Before finalizing a template, ask: "If I compiled
    this for a different project with different settings, would the output still make
@@ -252,7 +267,7 @@ project's variables change.
 
 ## Reference Files
 
-- [liquid-filters.md](references/liquid-filters.md) — complete standard LiquidJS filter catalogue (string, array, number, date, default)
+- [liquid-filters.md](references/liquid-filters.md): complete standard LiquidJS filter catalogue (string, array, number, date, default)
 
 ## Available Variables
 

package/recipes/core/sous-skills/skills/about-sous/SKILL.tpl.md

@@ -0,0 +1,70 @@
+---
+name: about-sous
+description: >
+  YOU MUST load this skill when you cannot edit a file in this project, are asked why
+  a file keeps reverting, need to know where the source of truth for any managed file
+  lives, or need to understand what this project's configuration system is.
+user-invocable: false
+---
+
+# About Sous
+
+Sous (`sous`) is a CLI tool that compiles markdown templates and manages output files
+for AI coding agents. It reads a central configuration, resolves variables, and
+copies or renders files to their destinations in this project.
+
+## Files You Must Never Edit
+
+Sous manages certain files in this project by compiling them from a central source.
+**You must never edit these directly.** Your changes will be silently overwritten the
+next time Sous runs:
+
+- `.claude/`: Claude Code configuration, skills, and instructions
+- `.codex/`: Codex configuration and skills
+- `AGENTS.md` and `CLAUDE.md`: agent instruction files
+- Any file you did not create yourself in a designated source directory
+
+If you need to change something in one of these files, the change must be made at the
+source, in the central configuration this project uses with Sous.
+
+## Where Your Skills Live
+
+Skills for this project live at `{{ skillsRoot }}`. That is the source directory Sous
+compiles from. Create and edit skills there, never in `.claude/skills/` or
+`.codex/skills/` directly.
+
+YOU MUST load `create-skill` when creating a new skill for this project.
+
+YOU MUST load `about-sous-configuration` when creating or editing the project's sous
+config (`sous.config.*`, `conf.d/` layers), defining or debugging config variables, or
+diagnosing a ConfigError.
+
+## Sous's Shared Recipes
+
+The `about-sous`, `about-sous-configuration`, `about-agent-skills` and
+`about-liquid-templates` skills you are reading come from the `core/sous-skills` recipe,
+published by the official sous recipe repository (https://github.com/sous-io/sous-recipes).
+A copy of that recipe also ships inside the installed sous package, where it seeds the
+machine-wide store so a fresh, offline install still has these skills.
+
+Edit them only in the recipe repository, where they are the sources. Never edit a compiled
+copy of them inside a consuming project; that copy is build output and is overwritten on
+the next sous run.
+
+## Sous's Own Documentation
+
+Sous's full documentation ships inside the installed package as plain markdown
+at `{{ sousRootPath }}/docs/markdown/`. Read `_sidebar.md` there first; it is
+the index of what exists. When you need to understand a sous feature beyond
+what the skills cover, read these files before guessing or searching the web:
+they match the INSTALLED version of sous, unlike the online copy
+(https://sous-io.github.io/sous/markdown/#/), which tracks the latest release.
+The reference content is still being written; the index shows what exists so
+far.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/recipes/core/sous-skills/skills/about-sous-configuration/SKILL.tpl.md

@@ -0,0 +1,75 @@
+---
+name: about-sous-configuration
+description: >
+  YOU MUST load this skill when creating or editing a sous config file (sous.config.* or a
+  conf.d layer), defining or debugging ${var} config variables, deciding where a setting
+  belongs, using SOUS_* env vars or --sous-* flags, or when sous fails to load with a
+  ConfigError.
+user-invocable: false
+license: Apache-2.0
+compatibility:
+  - claude
+  - codex
+metadata:
+  version: 2.0.0
+  tags: [sous, configuration]
+---
+
+# About Sous Configuration
+
+Sous reads one configuration per project from the project's `.sous/` directory: exactly ONE
+primary config (`sous.config.js|mjs|json|yaml`), optionally extended by `conf.d/` drop-in
+layers that deep-merge over it. One config describes one project; every setting lives at the
+top level of a single flat object. There is no user-level config and no multi-project map.
+Configs use `${var}` syntax, resolved by a fixpoint loop (declaration order never matters);
+`sous*`-prefixed variable names are reserved auto-vars.
+
+## This Project's Configuration
+
+Resolved at compile time for the project this skill was compiled into:
+
+- Primary config: `{{ sousConfigPath }}`
+- Discovered `.sous/` directory: `{{ sousDir }}`
+- Drop-in layer directory: `{{ sousConfDir }}`
+
+## The Documentation Is the Reference
+
+The full configuration reference ships inside the installed sous package as plain markdown.
+Read these files for anything beyond this page; do not guess and do not search the web:
+
+- `{{ sousRootPath }}/docs/markdown/configuration.md`: the config file, its shape, composition
+- `{{ sousRootPath }}/docs/markdown/config-discovery.md`: how sous finds the config; flag/env
+  precedence; env-file layering; discovery errors
+- `{{ sousRootPath }}/docs/markdown/config-layers.md`: merge semantics; the JS `configure()`
+  contract; the builder API; the managed 5xx layer band
+- `{{ sousRootPath }}/docs/markdown/config-variables.md`: the scope chain; auto-vars; fixpoint
+  resolution; error anatomy; `stateFilePath`/`pidFilePath`
+- `{{ sousRootPath }}/docs/markdown/config-inspection.md`: the validation pipeline; the JSON
+  Schema artifact; the `sous config` commands
+
+These files match the INSTALLED sous version. The same content is published at
+https://sous-io.github.io/sous/markdown/#/configuration, which tracks the latest release;
+prefer the on-disk copies.
+
+## Rules
+
+- After editing any config file, run `sous config validate`: it runs schema validation plus
+  full variable resolution, surfacing cycles and undefined `${refs}`. Use
+  `sous config get <path> --layers` to see which file set a value.
+- Hand-written config belongs in the primary file or your own `conf.d/` layers. Never
+  hand-edit `conf.d/500-*` through `conf.d/599-*`; that band is reserved for layers the sous
+  CLI writes.
+- Any config problem halts sous with a ConfigError naming the offending file; fix the named
+  file rather than working around it.
+- Configs use `${var}`; template files use LiquidJS double-brace syntax. The two resolve at
+  different stages and must not be mixed. YOU MUST load `about-liquid-templates` when writing
+  or editing `.tpl.` files.
+- YOU MUST load `about-sous` for which files in the project are compiled outputs that must
+  never be edited directly.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/{shared-prompts/skills/sous-skills → recipes/core/sous-skills/skills}/create-skill/SKILL.tpl.md

@@ -9,7 +9,7 @@ description: >
 The agent performing this work MUST load `about-agent-skills` for skill structure,
 frontmatter, and architecture principles.
 
-Skills for this project live at `{{ skillsRoot }}`. Create new skills there — not in
+Skills for this project live at `{{ skillsRoot }}`. Create new skills there, not in
 `.claude/skills/` or `.codex/skills/` directly (those are managed automatically and
 must not be edited).
 
@@ -30,7 +30,7 @@ what is already there before creating anything: a directory holding `SKILL.md` /
 subdirectories that each contain a skill means you are looking at bundles, so add the skill
 to the bundle it belongs to. When a new skill genuinely needs a new bundle, create the
 bundle directory and add a matching `entryGlob` target in the config of every project that
-should receive it — a bundle with no `entryGlob` is never compiled anywhere.
+should receive it; a bundle with no `entryGlob` is never compiled anywhere.
 
 ### 2. Write `SKILL.tpl.md`
 
@@ -54,16 +54,16 @@ metadata:
 
 ### 3. Add supporting files (if needed)
 
-- `references/` — supplementary documentation loaded on demand
-- `scripts/` — executable scripts the skill uses
-- `examples/` — example outputs
+- `references/`: supplementary documentation loaded on demand
+- `scripts/`: executable scripts the skill uses
+- `examples/`: example outputs
 
-Reference all supporting files from `SKILL.md` — the agent will not discover them
+Reference all supporting files from `SKILL.md`; the agent will not discover them
 otherwise.
 
 ### 4. Name the main file `SKILL.tpl.md` and add the source footer
 
-Skills in `{{ skillsRoot }}` are compiled and distributed — the main skill file must
+Skills in `{{ skillsRoot }}` are compiled and distributed; the main skill file must
 always be named `SKILL.tpl.md`, not `SKILL.md`. No exceptions, and specifically **not even
 when the skill body contains no variables at all**: the mandatory `## Source for this Skill`
 footer itself contains a template variable, so every skill needs a LiquidJS render pass by
@@ -93,8 +93,7 @@ Once the files exist in `{{ skillsRoot }}`, distribution is handled automaticall
 
 ### 6. Write the body for whoever executes it
 
-Per the sub-agent delegation pattern
-(`~sous-shared/_partials/sub-agent-delegation.md`), a skill's steps may run in a delegated
+Per the sub-agent delegation pattern, a skill's steps may run in a delegated
 sub-agent with fresh context. Mark which steps are delegated and which are
 orchestrator-only (anything needing the user or this conversation's contents), and
 phrase skill-loading requirements as "The agent performing this work MUST load `x`".

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -0,0 +1,45 @@
+# core/sous-skills
+#
+# SPECIAL: this recipe's source of truth stays inside the sous npm package, where
+# it seeds the machine-wide store on first run so a fresh, offline setup works.
+# The release pipeline pushes a copy here, versioned to match the sous
+# application version. That copy is machine-written distribution output.
+#
+# Because it is the offline seed, this recipe declares NO dependencies. Nothing
+# it ships may point at a recipe that has to be fetched.
+formatVersion: 1
+
+namespace: core
+name: sous-skills
+version: 0.2.1
+
+description: >-
+  The skills that teach an agent what sous is and how it works: which files sous
+  owns and must never be hand-edited, how a sous configuration is written and
+  debugged, the .tpl. template convention and LiquidJS syntax, what an agent
+  skill is, and how to create one.
+
+contents:
+  - kind: skills
+    include:
+      - skills/**/*
+
+variables:
+  - name: skillsRoot
+    env: SKILLS_ROOT
+    type: path
+    prompt: Where should this project's own skills be kept?
+    description: >-
+      This recipe teaches agents to write skills of their own, and a skill's
+      source is not the compiled copy sous builds into the agent directories.
+      This setting says where those sources are kept: the create-skill skill
+      writes new skills there, and the about-sous and about-agent-skills skills
+      point agents at it when they go looking. The default keeps them in a
+      prompts directory at the project root, but any path works, either relative
+      to the project root or absolute.
+    example: prompts/skills
+    default: prompts/skills
+    required: true
+    scope: shared
+    validate:
+      minLength: 1