diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 06f0838..ab59af2 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -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 diff --git a/EXTENDING.md b/EXTENDING.md index e4beab4..0b0175d 100644 --- a/EXTENDING.md +++ b/EXTENDING.md @@ -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 diff --git a/README.es.md b/README.es.md index 1adf862..ac543e7 100644 --- a/README.es.md +++ b/README.es.md @@ -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 ` 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 diff --git a/README.md b/README.md index ebb1ae5..06fa5a0 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 diff --git a/examples/custom-stack-template/README.md b/examples/custom-stack-template/README.md index f9fbdea..5dd9517 100644 --- a/examples/custom-stack-template/README.md +++ b/examples/custom-stack-template/README.md @@ -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. diff --git a/examples/custom-stack-template/compliance-release/README.md b/examples/custom-stack-template/compliance-release/README.md index 4a2d262..6ca42ab 100644 --- a/examples/custom-stack-template/compliance-release/README.md +++ b/examples/custom-stack-template/compliance-release/README.md @@ -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