garagon · garagon · Apr 26, 2026 · Apr 26, 2026 · Apr 26, 2026
@@ -3014,6 +3014,77 @@ jobs:
           done
           exit $fail
 
+  custom-stack-examples-public-copy:
+    name: Public copy mentions the compliance-release stack + runtime harness
+    runs-on: ubuntu-latest
+    # PR 4 of the Custom Stack Examples v1 round. The framework
+    # spec's "do not reposition the README hero before runtime E2E
+    # lands" rule unblocks once ci/e2e-custom-stack-examples.sh is
+    # green. This lock asserts that the public docs (README.md,
+    # README.es.md, EXTENDING.md) actually describe the stack and
+    # the harness that proves it, so the public claim never drifts
+    # away from what the harness exercises.
+    steps:
+      - uses: actions/checkout@v4
+      - name: Required tokens in README.md
+        run: |
+          set -e
+          fail=0
+          for tok in 'compliance-release' 'phase_graph' 'workflow stack' \
+                     'ci/e2e-custom-stack-examples.sh' \
+                     'examples/custom-stack-template/compliance-release'; do
+            if ! grep -qF "$tok" README.md; then
+              echo "FAIL: README.md missing token '$tok'"
+              fail=1
+            fi
+          done
+          exit $fail
+      - name: Required tokens in README.es.md (Spanish first-class)
+        run: |
+          set -e
+          fail=0
+          for tok in 'compliance-release' 'phase_graph' 'workflow stack' \
+                     'ci/e2e-custom-stack-examples.sh' \
+                     'examples/custom-stack-template/compliance-release'; do
+            if ! grep -qF "$tok" README.es.md; then
+              echo "FAIL: README.es.md missing token '$tok'"
+              fail=1
+            fi
+          done
+          exit $fail
+      - name: EXTENDING.md links both starting points
+        run: |
+          set -e
+          fail=0
+          for tok in 'examples/custom-skill-template/audit-licenses' \
+                     'examples/custom-stack-template/compliance-release' \
+                     'reference/custom-stack-examples-technical-spec.md' \
+                     'ci/e2e-custom-stack-examples.sh'; do
+            if ! grep -qF "$tok" EXTENDING.md; then
+              echo "FAIL: EXTENDING.md missing token '$tok'"
+              fail=1
+            fi
+          done
+          exit $fail
+      - name: Public copy does NOT make disallowed claims
+        run: |
+          set -e
+          fail=0
+          # Spec rules: no marketplace/plugin-ecosystem framing,
+          # no compliance-certified / GDPR / SOC2 claims, no
+          # "works in every agent identically" claim.
+          for f in README.md README.es.md EXTENDING.md; do
+            for bad in 'marketplace' 'plugin ecosystem' \
+                       'GDPR ready' 'SOC2 ready' 'compliance certified' \
+                       'works in every agent identically'; do
+              if grep -qiF "$bad" "$f"; then
+                echo "FAIL: $f contains disallowed phrase '$bad'"
+                fail=1
+              fi
+            done
+          done
+          exit $fail
+
   custom-stack-examples-contract:
     name: Custom Stack Examples static contract
     runs-on: ubuntu-latest

@@ -1,19 +1,35 @@
 # Extending Nanostack
 
-Add your own skills that plug into nanostack's workflow. Your skills save artifacts, read what other skills produced, and compose with /think, /review and /ship.
+Add your own skills that plug into Nanostack's workflow. Your skills save artifacts, read what other skills produced, and compose with `/think`, `/review`, and `/ship`. Multiple skills can compose into a domain workflow stack that gates `/ship` on its own evidence.
 
-> **Quickest way to start:**
+## Two starting points
+
+| If you want | Start here |
+|---|---|
+| One skill that reuses Nanostack's artifact store + resolver + journal + analytics + conductor | `examples/custom-skill-template/audit-licenses/` (single-skill template; `bin/create-skill.sh` scaffolds from it by default) |
+| A multi-skill stack that composes into a release gate before `/ship` | `examples/custom-stack-template/compliance-release/` (license + privacy + release-readiness composer; reference shape for any new stack) |
+
+> **Quickest way to start a single skill:**
 >
 > ```bash
 > bin/create-skill.sh license-audit --concurrency read --depends-on build
 > bin/check-custom-skill.sh .nanostack/skills/license-audit
 > ```
 >
-> The first command scaffolds a working skill from the bundled template, registers it as a custom phase, and rewrites every helper path to be self-contained. It writes to the same store path the lifecycle scripts read from (your repo root's `.nanostack/`, or `$HOME/.nanostack/` outside git), so the skill is visible whether you invoke the tool from the project root or a subdirectory. The second runs a check that covers SKILL.md frontmatter shape, the frontmatter `name:` matches the directory, `agents/openai.yaml` has the required discovery keys, the `display_name` is consistent with the skill, `bash -n` on helpers, registration in config, no leaked example paths, and a `save-artifact` + `find-artifact` round-trip. Restart your agent and `/license-audit` is live.
+> The first command scaffolds a working skill from the bundled template, registers it as a custom phase, and rewrites every helper path to be self-contained. It writes to the same store path the lifecycle scripts read from (your repo root's `.nanostack/`, or `$HOME/.nanostack/` outside git), so the skill is visible whether you invoke the tool from the project root or a subdirectory. The second runs a check that covers `SKILL.md` frontmatter shape, the frontmatter `name:` matches the directory, `agents/openai.yaml` has the required discovery keys, the `display_name` is consistent with the skill, `bash -n` on helpers, registration in config, no leaked example paths, and a `save-artifact` + `find-artifact` round-trip. Restart your agent and `/license-audit` is live.
 >
 > The contract those tools enforce lives in [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md). The 15-cell end-to-end harness that proves the journey works (including subdir-scaffold and no-git scaffold paths) is at [`ci/e2e-custom-stack-flows.sh`](ci/e2e-custom-stack-flows.sh).
+
+> **Quickest way to start a workflow stack:**
+>
+> Copy the compliance-release example, which scaffolds three skills (`license-audit` + `privacy-check` + `release-readiness`) and wires them into a `phase_graph` so the conductor schedules them between `build` and `ship`:
+>
+> ```bash
+> cp -R examples/custom-stack-template/compliance-release ~/.local/stacks/compliance-release
+> # Then follow the install commands in compliance-release/README.md.
+> ```
 >
-> Prefer copying by hand? The template still lives at `examples/custom-skill-template/audit-licenses/` and its README walks through the structure.
+> The stack manifest schema, the directory contract any new stack must satisfy, and the runtime guarantees the framework gives a stack are documented in [`reference/custom-stack-examples-technical-spec.md`](reference/custom-stack-examples-technical-spec.md). The 15-cell runtime end-to-end harness for the example stack is at [`ci/e2e-custom-stack-examples.sh`](ci/e2e-custom-stack-examples.sh) (51 assertions).
 
 ## Configure your stack
 

@@ -227,9 +227,11 @@ Si querés enforcement duro, usá Claude Code. Si aceptás disciplina a nivel ag
 
 Para la guía completa de problemas en español (slash commands, jq, phase gate, puerto en uso, Windows, sprints atascados, conflictos de nombres), ver [TROUBLESHOOTING.es.md](TROUBLESHOOTING.es.md). Para temas avanzados (proxy corporativo, doble ejecución en autopilot, telemetría) consultá la versión canónica en inglés: [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
 
-## Construí tu propio skill
+## Construí tu propio workflow stack
 
-Nanostack es un framework de workflow, no solo un set fijo de skills. Podés crear tus propios skills, registrarlos como fases, y reutilizar el mismo artifact store, resolver, sprint journal, analytics, conductor y vault local que usan los skills built-in.
+Usá Nanostack como viene, o construí tu propio workflow stack arriba. Tus skills custom pueden componerse en un workflow de dominio que controla `/ship`, y heredan el mismo artifact store, resolver, sprint journal, analytics, conductor y vault local que usan los skills built-in. Sin SaaS, sin daemon, sin build step.
+
+### Un solo skill
 
 Generá un skill desde el template, validalo, reiniciá tu agente:
 
@@ -247,9 +249,21 @@ Lo que ese skill hereda automáticamente, todo cubierto por `ci/e2e-custom-stack
 - `discard-sprint.sh --dry-run` lista los artefactos del skill junto con los core.
 - `conductor/bin/sprint.sh start --phases <json>` acepta un grafo que incluye la fase custom; `batch` lee la `concurrency:` desde el `SKILL.md` del skill.
 
-Un equipo de marketing arma `/audience` y `/campaign`. Un equipo de datos arma `/explore` y `/model`. Un equipo de compliance arma `/license-audit` y `/privacy`. Todos componen con `/think` para ideas, `/review` para calidad y `/ship` para entrega.
+### Workflow stack
+
+Un stack es varios skills custom unidos por un `phase_graph` para que el conductor sepa el orden de dependencias. El ejemplo `compliance-release` lo prueba: tres fases custom (`/license-audit` + `/privacy-check` + `/release-readiness`) componen una decisión de release antes de `/ship`. `ci/e2e-custom-stack-examples.sh` recorre el journey completo del usuario nuevo en un proyecto `/tmp` real (scaffold, validate, save, resolve, journal, analytics, discard, conductor scheduling) y corre en el workflow E2E opt-in. 15 celdas, 51 aserciones.
+
+Copiá el starting point del stack:
+
+```
+examples/custom-stack-template/compliance-release/
+```
+
+El [README del stack](examples/custom-stack-template/compliance-release/README.md) muestra la instalación. El contrato de directorio para nuevos stacks está en [`reference/custom-stack-examples-technical-spec.md`](reference/custom-stack-examples-technical-spec.md); el contrato del framework que los skills heredan está en [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md).
+
+Un equipo de marketing arma `/audience` y `/campaign`. Un equipo de datos arma `/explore` y `/model`. Un equipo de compliance arma `/license-audit`, `/privacy-check` y `/release-readiness`. Todos componen con `/think` para ideas, `/review` para calidad y `/ship` para entrega.
 
-El contrato del framework está en [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md). Walkthrough completo: [`EXTENDING.md`](EXTENDING.md).
+Walkthrough completo: [`EXTENDING.md`](EXTENDING.md).
 
 ## Privacidad
 

@@ -763,7 +763,9 @@ Open `.nanostack/know-how/` in Obsidian. Sprint journals link to conflict preced
 
 ## Build on nanostack
 
-Nanostack is a workflow framework, not just a fixed skill bundle. Create your own skills, register them as phases, and reuse the same artifact store, resolver, sprint journal, analytics, conductor, and local vault that the built-in skills run on.
+Use Nanostack as-is, or build your own workflow stack on top. Custom skills can compose into a domain workflow that gates `/ship`, and they inherit the same artifact store, resolver, sprint journal, analytics, conductor, and local vault that the built-in skills run on. No SaaS, no daemon, no build step.
+
+### Single skill
 
 Scaffold a skill from the template, validate it, restart your agent:
 
@@ -772,7 +774,7 @@ bin/create-skill.sh license-audit --concurrency read --depends-on build
 bin/check-custom-skill.sh .nanostack/skills/license-audit
 ```
 
-What that gets you, all proven by `ci/e2e-custom-stack-flows.sh`:
+The framework guarantees that one skill inherits, all proven by `ci/e2e-custom-stack-flows.sh`:
 
 - `save-artifact.sh license-audit` and `find-artifact.sh license-audit` accept the custom phase the same way they accept a core phase.
 - `resolve.sh license-audit` returns `phase_kind: "custom"` with `upstream_artifacts` driven by the skill's `depends_on` (or by `phase_graph` in `.nanostack/config.json`).
@@ -781,9 +783,21 @@ What that gets you, all proven by `ci/e2e-custom-stack-flows.sh`:
 - `discard-sprint.sh --dry-run` lists the skill's artifacts alongside the core ones.
 - `conductor/bin/sprint.sh start --phases <json>` accepts a graph that includes the custom phase; `conductor/bin/sprint.sh batch` reads its `concurrency:` from `SKILL.md`.
 
-A marketing team builds `/audience` and `/campaign`. A data team builds `/explore` and `/model`. A design team builds `/wireframe` and `/usability`. A compliance team builds `/license-audit`, `/privacy`, and `/release-readiness`. All compose with nanostack's `/think` for ideation, `/review` for quality, and `/ship` for delivery.
+### Workflow stack
+
+A stack is multiple custom skills wired together with a `phase_graph` so the conductor knows the dependency order. The compliance-release example proves the framework: three custom phases (`/license-audit` + `/privacy-check` + `/release-readiness`) compose into a release decision before `/ship`. `ci/e2e-custom-stack-examples.sh` walks the full new-user journey on a real `/tmp` project (scaffold, validate, save, resolve, journal, analytics, discard, conductor scheduling) and runs in the opt-in E2E workflow. 15 cells, 51 assertions.
+
+Copy the stack starting point:
+
+```
+examples/custom-stack-template/compliance-release/
+```
+
+The stack's [README](examples/custom-stack-template/compliance-release/README.md) walks through the install. The directory contract for any new stack is in [`reference/custom-stack-examples-technical-spec.md`](reference/custom-stack-examples-technical-spec.md); the framework contract those skills inherit is in [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md).
+
+A marketing team builds `/audience` and `/campaign`. A data team builds `/explore` and `/model`. A design team builds `/wireframe` and `/usability`. A compliance team builds `/license-audit`, `/privacy-check`, and `/release-readiness`. All compose with Nanostack's `/think` for ideation, `/review` for quality, and `/ship` for delivery.
 
-The framework contract is in [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md). Full walkthrough: [`EXTENDING.md`](EXTENDING.md). Starting point you can copy: [`examples/custom-skill-template/`](examples/custom-skill-template/).
+Full walkthrough: [`EXTENDING.md`](EXTENDING.md).
 
 ## Privacy
 

@@ -38,12 +38,12 @@ Before opening a PR with a new stack, run:
 ci/check-custom-stack-examples.sh
 ```
 
-It validates the manifest schema, the README structure, the skill folder shape, the absence of committed runtime artifacts, and `bash -n` on every helper. Once PR 3 of this round lands, `ci/e2e-custom-stack-examples.sh` will additionally exercise the runtime contract on a real `/tmp` project.
+It validates the manifest schema, the README structure, the skill folder shape, the absence of committed runtime artifacts, and `bash -n` on every helper. The runtime contract for the example stack is in `ci/e2e-custom-stack-examples.sh` (15 cells, 51 assertions on a real `/tmp` project).
 
-## What's covered today
+## What's covered
 
-- **Manifest + structural lint**: every stack file shape and skill folder layout (this PR).
-- **Skill behavior**: license audit, privacy hygiene, release-readiness composer (next PR).
-- **Runtime install + journey**: scaffold the stack, save artifacts, resolve, journal, analytics, discard, conductor scheduling (PR 3 of the round).
+- **Manifest + structural lint**: every stack file shape and skill folder layout, validated by `ci/check-custom-stack-examples.sh` (49 checks).
+- **Skill behavior**: license audit (npm/pip/go classifier), privacy hygiene (collection signals + privacy-note resolution), release-readiness composer (5-upstream rollup with TAMPERED detection). Each skill has a `bin/smoke.sh` that exercises real cases on a `/tmp` project.
+- **Runtime install + journey**: scaffold the stack from `bin/create-skill.sh --from`, save artifacts, resolve, journal, analytics, discard, conductor scheduling. All proven by `ci/e2e-custom-stack-examples.sh` (the opt-in E2E workflow).
 
-Until PR 3 ships, the stacks here are wired and lint-checked but not yet end-to-end runnable as a workflow. The status of each stack is on its own README.
+Each stack documents its own status and install path on its README.
@@ -2,7 +2,7 @@
 
 A three-skill stack that gates `/ship` on license, privacy, and release-readiness evidence. Read-only by design: no commits, no PRs, no deploys, no network calls.
 
-> Status: **PR 1 of the Custom Stack Examples v1 round.** The manifest, README, and skill folders are in place and the static contract (`ci/check-custom-stack-examples.sh`) passes. Skill behavior lands in PR 2; runtime end-to-end coverage lands in PR 3. The install commands below run once PR 3 ships; until then the skills are stubs that satisfy the structural contract.
+> Status: end-to-end working. The static contract (`ci/check-custom-stack-examples.sh`, 49 checks) runs on every PR; the runtime harness (`ci/e2e-custom-stack-examples.sh`, 15 cells / 51 assertions) runs in the opt-in E2E workflow. The install commands below are the same ones the harness exercises.
 
 ## Who this stack is for