docs: ESS tutorial and onboarding for b10x; verify skills against ess 0.38.0; release 0.17.0 - #47
Merged
Merged
Conversation
- story:ess-tutorial-and-onboarding (active): a public tutorial from nothing to a conforming ESS specification with real output, held to the newest CLIs by agentplugins-check and a trial; onboarding pages that name the five shipped plugins and install them through b10x; release 0.17.0. Context cites the survey of origin/main d6c2ae1. - Scope recorded: website/docs, the checker, the Tools workflow, trials/ess-tutorial, verified.json, plugins/ess, README.md, SETUP.md, b10x.docs.yaml. aep plan artifact validate: valid.
- verified.json pins ess 0.38.0 (was 0.37.0). agentplugins-check tools:
35 spelled ess commands exist in 0.38.0; the syntax example validates
(14 scenarios, 0 refusals).
- ESS trial round on 0.38.0, all within the baseline: ess-new 16 tool
calls (38), validate valid; ess-retrofit 26 (36), 20 scenarios, 0
refusals; ess-pipeline 10 (11), 14 scenarios, 4/4 outputs;
ess-full-package 66 (53), 31 scenarios, 0 refusals, 9/9 outputs,
go test 0 failed.
- Fixes for the text the agents quoted as confusing:
- specifying: a request that names the domain and asks for a result
("make sure it validates") counts as a finished-specification
request, so it is not interviewed; the closing check allows a named
refusal where synthesis cannot arrange the model (the per-holder
limit).
- later-formats: the per-holder example's Join sets packets_out: 0 and
the at-limit refusal is expected; do not give Join a starting count
to reach it.
- testing-conformance: `--out <module root>` writes <module>/essconform,
the import path the generated README shows; ESS_REPORT_FORMAT=2 is
required from ess-conformance/8 on; a refused command sets Outcome
to the refusing outcome's name (the generated comment says empty).
- The three ess-side defects (the Outcome comment, the IR version in
synthesize --help, the report variable read as optional) are filed as
beyond10x/ess#186.
- New website/docs/tutorials/first-ess-specification.md, typed `tutorial` on the public website by its path, listed under a Tutorials sidebar category. An agent with ess@b10x interviews, writes a lending-library specification, and a Go implementation is held to the suite it synthesizes: install, interview, the files, validate and a deliberate refusal, docs/OpenAPI/graph, synthesis and go test, a planted bug turning the suite red, the toolchain pin and a Taskfile check. - Every output block is a real run on 2026-09-28 with ess 0.38.0 in an isolated sandbox (claude -p, resumed across the interview); paths are shortened to `~` and the marketplace line to beyond10x/agentplugins, which the page says. Recorded outputs: validate `library v1 — 3 file(s), valid`; synthesis `17 scenario(s) (0 authored), 0 refusal(s)`; go test 17 passed; the planted bug fails exactly Book/state/OnLoan/refuses/BorrowBook. - The committed spec/ and impl/ under website/docs/tutorials/first-ess-specification/ are the recorded files; the page quotes each whole. - Deviations from the plan: the domain has no per-member cap. The first recording asked for one: each borrow split into three commands and synthesis refused 3 scenarios (ESS-SYNTH-003), so the cap is a closing section instead. `ess verify conform mutate` runs only against ess's built-in targets, so step 7 points to ess:hardening for it. - A fresh agent given only the page (trial ess-tutorial) reached 17/17; the four places it found the page and its run disagreeing are fixed.
- install.md leads with b10x for the CLIs (`b10x init <products>`, then `b10x setup apply`); the hand install of AEP 0.55.0 and its `protocol 0.55.0` check are gone; Metaharness installs with `b10x install metaharness`; the pin examples name current releases. - plugins/b10x.md: the `init`/`upgrade` skills replace the retired `installing`; `--out` is optional; `install --dir` and `setup plan`'s `--host/--method/--json/--out` are listed (crates/b10x/src/main.rs); connectors is a routing target. - choose-a-plugin.md and trust-and-scope.md name the five plugins by id (b10x, aep, ess, worktree, connectors) instead of "Beyond10x", "AEP Plan", "AEP Drive" and "ESS Specify"; the worktree section no longer says its skill is generated by the worktree CLI (owned here since 3c7d402). - golden-path.md installs aep and ess through b10x (it sent readers to the ESS repository for the plugin) and points newcomers at the tutorial; its recorded AEP 0.44.0 / ESS 0.5.1 output stays, labelled. - intro.md, the landing page and the footer list connectors and link the tutorial; README.md and SETUP.md point newcomers at it. - b10x.docs.yaml: the reference section links plugins/b10x/ (was plugins/beyond10x/), a guide section links the tutorial, and the summary names the current plugins. - b10x:routing resources: canonical /docs/<source>/ URLs, the tutorial, one aep row instead of AEP Plan/AEP Drive, and connectors.
…play names - tools: commands spelled in website/docs/tutorials/*.md are checked against the newest releases like the skills' (ess: 42 commands, was 35). The tutorial's committed specification must validate with the newest ess, synthesize a Go suite with 0 refusals, and its committed implementation must pass it under go test. ESS_TOOLCHAIN_DELEGATED=1 keeps the page's `requires: ess` pin from handing the run to the pinned release, so the newest one is what is tested. First run: library v1 valid, 17 scenarios, 0 refusals, go test ok. - Retired names: "AEP Plan", "AEP Drive" and "ESS Specify", the display names public pages kept after the hyphenated ids were swept. New test a_retired_display_name_on_a_page_fails_the_check; with the ESS Specify entry removed it fails, restored it passes.
- trials/ess-tutorial: a fresh isolated agent with ess@b10x gets only a copy of the tutorial page (fixture/tutorial.md) and works steps 2-8. Measures tool calls, validate, synthesis, outputs and go test. - New trial kind ess-tutorial; the test the_tutorial_trial_carries_the_published_page fails when the fixture and website/docs/tutorials/first-ess-specification.md differ. - Baseline from the first accepted run: 35 tool calls, validate valid, 17 scenarios with 0 refusals, 5/5 outputs, go test 17 passed, 0 failed, 0 skipped.
- Workspace, all ten plugin manifests and the Skill version lines move to 0.17.0; CHANGELOG gains the 0.17.0 section. task check: exit 0 (141 tests, 17 eval cases, 5 plugins). agentplugins-check tools: exit 0 (aep 0.63.1, ess 0.38.0: 42 commands and the tutorial's specification, suite and go test, worktree 0.8.2). task site-build: exit 0. Trials on ess 0.38.0: ess-new, ess-retrofit, ess-pipeline, ess-full-package within the baseline; ess-tutorial 17/17 go test.
- b10x-docs-check on PR #47 refused the new summary: "/surfaces/0/summary must NOT have more than 240 characters". The shorter one names the same plugins and the tutorial.
- b10x-docs-check refused 11 ```console fences ("console is ambiguous;
use bash, shell-session, or text") in the tutorial, install.md and
golden-path.md; they are shell-session. The trial fixture copies the
page again.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A new public tutorial, Your first ESS specification, takes a developer from an empty directory to a validated specification and a Go implementation that passes its conformance suite, with an agent doing the writing. Every output block is from a real run with ess 0.38.0.
chore(plan)story:ess-tutorial-and-onboarding(active), with scopedocs(ess)verified.jsonpins ess 0.38.0; fixes for 4 passages the trial agents found confusing; ess-side defects filed as beyond10x/ess#186docs: tutorialspec/andimpl/, a Tutorials sidebar categorydocs: onboardinginstall.mdinstalls throughb10x; no AEP 0.55.0 hand install; the five plugins named by id; connectors on intro, landing page and footer;b10x.docs.yamllinks fixedfeat(check)toolschecks tutorial commands and runs the tutorial's spec, suite andgo testagainst the newest ess; retired display names refusedtest(trials)ess-tutorialtrial: a fresh agent given only the page reached 17/17chore: release 0.17.0Gates run locally:
task check: exit 0 (141 tests, 17 eval cases, 5 plugins).agentplugins-check tools: exit 0; tutoriallibrary v1 — 3 file(s), valid, 17 scenarios, 0 refusals,go testok.task site-build: exit 0.Deviations from the plan: the tutorial's domain has no per-member cap (with one, each borrow split into three commands and synthesis refused 3 scenarios,
ESS-SYNTH-003), and step 7 points toess:hardeningforconform mutate, which runs only against ess's built-in targets.The public site currently serves a bundle from before 0.14.0 (
/docs/agentplugins/plugins/aep-plan/answers 200,/plugins/b10x/404); its publisher last ran 2026-09-24. Documentation publication is pending.