@sous-io/sous 1.0.8 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,44 +39,44 @@
     "sous.config.schema.json"
   ],
   "dependencies": {
-    "@sous-io/plugin-api": "1.0.8"
+    "@sous-io/plugin-api": "1.0.10"
   },
   "devDependencies": {
     "esbuild": "^0.27.4",
     "jsonc-parser": "^3.3.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@sous-io/core": "1.0.8",
-    "@sous-io/plugin-authoring": "1.0.8",
-    "@sous-io/plugin-build": "1.0.8",
-    "@sous-io/documents": "1.0.8",
-    "@sous-io/plugin-claude-code": "1.0.8",
-    "@sous-io/plugin-compiler": "1.0.8",
-    "@sous-io/plugin-confd": "1.0.8",
-    "@sous-io/plugin-config-files": "1.0.8",
-    "@sous-io/plugin-cli": "1.0.8",
-    "@sous-io/plugin-expressions": "1.0.8",
-    "@sous-io/plugin-formats": "1.0.8",
-    "@sous-io/plugin-git": "1.0.8",
-    "@sous-io/plugin-github": "1.0.8",
-    "@sous-io/plugin-host": "1.0.8",
-    "@sous-io/plugin-gitlab": "1.0.8",
-    "@sous-io/plugin-harnesses": "1.0.8",
-    "@sous-io/plugin-liquid": "1.0.8",
-    "@sous-io/plugin-local": "1.0.8",
-    "@sous-io/plugin-init": "1.0.8",
-    "@sous-io/plugin-inspect": "1.0.8",
-    "@sous-io/plugin-memories": "1.0.8",
-    "@sous-io/plugin-npm": "1.0.8",
-    "@sous-io/plugin-pnpm": "1.0.8",
-    "@sous-io/plugin-recipe-answers": "1.0.8",
-    "@sous-io/plugin-recipes": "1.0.8",
-    "@sous-io/plugin-refs": "1.0.8",
-    "@sous-io/plugin-skills": "1.0.8",
-    "@sous-io/plugin-mcp": "1.0.8",
-    "@sous-io/plugin-update": "1.0.8",
-    "@sous-io/plugin-variables": "1.0.8",
-    "@sous-io/plugin-yarn": "1.0.8"
+    "@sous-io/core": "1.0.10",
+    "@sous-io/documents": "1.0.10",
+    "@sous-io/plugin-authoring": "1.0.10",
+    "@sous-io/plugin-build": "1.0.10",
+    "@sous-io/plugin-claude-code": "1.0.10",
+    "@sous-io/plugin-cli": "1.0.10",
+    "@sous-io/plugin-compiler": "1.0.10",
+    "@sous-io/plugin-confd": "1.0.10",
+    "@sous-io/plugin-config-files": "1.0.10",
+    "@sous-io/plugin-expressions": "1.0.10",
+    "@sous-io/plugin-formats": "1.0.10",
+    "@sous-io/plugin-gitlab": "1.0.10",
+    "@sous-io/plugin-git": "1.0.10",
+    "@sous-io/plugin-harnesses": "1.0.10",
+    "@sous-io/plugin-host": "1.0.10",
+    "@sous-io/plugin-inspect": "1.0.10",
+    "@sous-io/plugin-init": "1.0.10",
+    "@sous-io/plugin-mcp": "1.0.10",
+    "@sous-io/plugin-github": "1.0.10",
+    "@sous-io/plugin-local": "1.0.10",
+    "@sous-io/plugin-liquid": "1.0.10",
+    "@sous-io/plugin-memories": "1.0.10",
+    "@sous-io/plugin-npm": "1.0.10",
+    "@sous-io/plugin-recipe-answers": "1.0.10",
+    "@sous-io/plugin-pnpm": "1.0.10",
+    "@sous-io/plugin-refs": "1.0.10",
+    "@sous-io/plugin-recipes": "1.0.10",
+    "@sous-io/plugin-update": "1.0.10",
+    "@sous-io/plugin-variables": "1.0.10",
+    "@sous-io/plugin-skills": "1.0.10",
+    "@sous-io/plugin-yarn": "1.0.10"
   },
   "engines": {
     "node": ">=22"

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

@@ -168,6 +168,9 @@ The rules:
   saying what they are, and treats them as refining the goal. With none, it takes the broadest
   reasonable reading of roughly the last 10 turns, NEVER asks which of several targets was meant,
   and names what it took in the first line of its reply.
+- **Decide in the template.** When a step depends on a setting the project answers, branch on it
+  in the `.tpl.` file, so the compiled skill gives one instruction instead of asking the agent to
+  look the setting up. YOU MUST load `about-liquid-templates` for how.
 - **Tiers, never models.** Name a sub-agent's model by tier ("the next tier down from the main
   session"), never by product or provider.
 - **Public by default.** A skill published in a recipe repository is public: its examples use
@@ -206,7 +209,8 @@ A skill published in a recipe names its recipe:
 ## Source for this Skill
 
 This skill comes from the `<namespace>/<recipe>` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, run `sous repo contribute <namespace>/<recipe>`.
 
 - Source Path: <resolved source path>
 ```
@@ -222,8 +226,9 @@ never this output file.
 - Source Path: <resolved source path>
 ```
 
-The footer tells an agent reading the compiled copy where the skill came from and where to make a
-change.
+The footer tells an agent reading the compiled copy where the skill came from and how to change
+it. The Source Path of a recipe's skill points into sous's machine-wide store, which is read-only
+build input; a change to a recipe goes upstream through `sous repo contribute`.
 
 ## Examples
 
@@ -240,6 +245,7 @@ change.
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -289,6 +289,23 @@ project's variables change.
 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
    sense?" If not, parameterize the varying part.
+5. **Decide in the template, not in the agent.** When what a file tells the agent depends
+   on a project's answer, branch on the answer so the compiled file states one
+   instruction. An agent that reads a setting and then decides can get it wrong; a
+   rendered instruction cannot. Every recipe the project holds contributes its answers,
+   so a recipe may read another recipe's variable once it lists that recipe under
+   `depends`. Make the `else` branch the conservative behavior, because it is what renders
+   when nothing answered the variable:
+
+   {% raw %}
+   ```markdown
+   {% if createIssues == "always" -%}
+   File the issue without asking, and show the draft in the report.
+   {%- else -%}
+   Present the draft and wait for the user's approval.
+   {%- endif %}
+   ```
+   {% endraw %}
 
 ## Reference Files
 
@@ -304,6 +321,7 @@ The following variables are in scope at compile time in this project (secrets sh
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -2,8 +2,9 @@
 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.
+  a file keeps reverting, want to change a skill, memory or other file that came from a
+  recipe, 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
 ---
 
@@ -27,6 +28,21 @@ next time Sous runs:
 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.
 
+## Changing a File That Came From a Recipe
+
+A file whose footer names a recipe (`This skill comes from the <namespace>/<recipe> recipe`)
+is published by a recipe repository. Its Source Path points into sous's machine-wide store,
+which is read-only build input: an edit there is lost and reaches nobody. Change it upstream:
+
+1. `sous repo contribute <namespace>/<recipe>` links a working copy of the recipe's
+   repository on a new branch; the project's builds read from it until the contribution
+   is finished, so an edit shows up on the next `sous build`.
+2. Edit the recipe in that working copy, raising its version (YOU MUST load
+   `about-sous-recipes`).
+3. `sous repo contribute <namespace>/<recipe> --finish` proposes the change and unlinks.
+
+YOU MUST load `about-sous-repos` before running these commands.
+
 ## Where Your Skills Live
 
 Skills for this project live at `{{ skillsRoot }}`. That is the source directory Sous
@@ -50,9 +66,10 @@ published by the official sous recipe repository (https://github.com/sous-io/sou
 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.
+Their source is in the sous repository (https://github.com/sous-io/sous), under
+`recipes/core/sous-skills/`; the copy in the recipe repository is written by each sous
+release and takes no proposals. Never edit a compiled copy of them inside a consuming
+project; that copy is build output and is overwritten on the next sous run.
 
 ## Trust and Activation
 
@@ -89,6 +106,7 @@ far.
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -95,6 +95,7 @@ prefer the on-disk copies.
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -133,6 +133,10 @@ The fields in that example, and the ones it leaves out:
   version a definition MAY only loosen; tightening is a major bump, because an upgrade re-checks the
   answers already stored.
 
+A template may also read a variable another recipe defines. List that recipe under `depends`, so
+the variable is there wherever this recipe is, and branch on it in the template rather than telling
+the agent to look the setting up; `about-liquid-templates` shows how.
+
 ## Depends and Subscribes
 
 Both lists name other recipes, and they do different things:
@@ -232,6 +236,7 @@ example, a partial holding
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -175,6 +175,7 @@ remote before the first release, because `sous repo release` reads and writes ta
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

package/recipes/core/sous-skills/skills/create-skill/SKILL.tpl.md

@@ -110,6 +110,7 @@ load `about-liquid-templates` if any file in your skill needs `.tpl.` processing
 ## Source for this Skill
 
 This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
-repository. It was compiled from a template, so edit the source, never this output file.
+repository. It was compiled from a template, so edit the source, never this output file. To
+change it, propose the change to `sous-io/sous`, under `recipes/core/sous-skills/`.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 1.0.8
+version: 1.0.10
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous