Declarative-Workflow Walkthrough & Per-API Tutorial Skills¶

Status: Design draft — not yet implemented. ← Back to Roadmap

Motivation¶

docs/design/d-0006-protocol-native-capabilities.md's Phase 8 review closeout left two linked items unstarted: a joint declarative-workflow walkthrough (user + agent declare one api/rest, one api/events, and one api/reqreply API from scratch, end-to-end, as a genuine first-time-user simulation) and three per-API guided tutorial skills (tutorial-api-{rest,events,reqreply}) meant to teach that same workflow live, informed by whatever friction the walkthrough surfaces.

Design review alone (the review-go-codex/review-docs rounds this session ran) catches API-surface bugs and stale docs, but it does not catch workflow friction — the awkward pauses, the "which method do I call next" hesitations, the steps a static guide glosses over because its author already knows the answer. Only walking the real declare → group → capability → attach → run journey, live, surfaces that. This doc plans both the walkthrough itself (a one-time session activity, not a code change) and the tutorial skills it feeds (a durable, repeatable artifact — .github/skills/ content other sessions can load).

Updated during a later review pass: this doc originally predated both D-0008 (the declarative Router/Mount/Group/Walk feature) and D-0009 (the router/ route/middleware → internal/ relocation) — the maintainer flagged that the walkthrough's step shape was missing the routing feature entirely; this revision adds it as Step 3 and folds in D-0009's per-pattern-wrapper teaching requirement throughout.

Scope decisions¶

Toolchain / dependency decisions¶

No new dependencies. The walkthrough and resulting skills are documentation/ process artifacts only — they consume existing api/rest/api/events/ api/reqreply + adapter code as-is. .github/instructions/ agent-skills.instructions.md governs the 3 new SKILL.md files' format (frontmatter name/description, body sections) — see that file + the review-docs/review-go-codex skills in this same repo as the closest structural precedent for a multi-step, methodology-driven skill (as opposed to a tool-wrapping skill like webapp-testing).

API surface¶

No Go code changes are anticipated as part of THIS doc's own scope. If the walkthrough surfaces a genuine API gap (e.g. a missing convenience constructor), that becomes its OWN follow-on roadmap doc per the Scope Decisions table above — not an addition folded into this one.

The walkthrough: structure and what it produces¶

The walkthrough is a single combined session (not 3 separate ones) run once this doc is approved, structured as 3 back-to-back passes — one per API — each following the IDENTICAL shape so friction patterns common to all 3 (vs. API-specific ones) are easy to tell apart afterward:

1. Struct + codec — declare a small, realistic domain struct (e.g. a sensor reading, a user-created event, a compute request/response) and its codex.Struct[T] codec from scratch, narrating each RequiredField/OptionalField choice.
2. Route/channel declaration — rest.NewRoute/events.NewChannel/ reqreply.NewRoute, including at least one path/topic variable (so PathParam/TopicParam/merge-field ergonomics get exercised, not just the flat/no-vars happy path). Declare at least 2-3 routes/channels (not just one) so Step 3 below has something real to group.
3. Router/Group declaration — group the routes/channels declared in Step 2 under a shared rest.NewRouter/events.NewRouter/ reqreply.NewRouter prefix, narrating the .Use(mw) (persistent, applies to every leaf registered afterward, including through a later .Mount()/.Group()) vs. .With(mw) (one-shot, applies ONLY to the single next .Route()/.Channel() call) distinction — this is the single most commonly mis-used pair in the whole workflow (see examples/rest-api/demo_router_groups.go's own .With()-before- .Mount()-is-discarded demonstration). Exercise at least one Mount (nesting a sub-router under a parent prefix) so the walkthrough proves prefix/middleware/tag accumulation actually composes across a nesting level, not just a flat single-level group — see D-0008 for the full Router/Mount/Group/Walk design this step exercises.
4. Capability requirement declaration — a RequireX/explicit Capability value declared on the route/channel (e.g. RequireQoS for events, a REST HeaderParam-implied Tier 2 requirement) — the step D-0006's whole capability-requirement-composition rework built (now merged into that doc as its §9), and the one most likely to surface fresh friction since it's the newest, least-polished part of the workflow.
5. Adapter attachment — Client.Attach/Server.Attach with a real adapter's New*Transport constructor (the in-process mock client/socket each flagship example already wires up — no new infrastructure).
6. Run it — dispatch one request/message/call end-to-end and observe the result.

At every step, narrate (and record) 3 things: what the next call should logically be before checking docs/source (does the obvious guess match reality?), whether any step required jumping between 2+ files/docs pages to piece together (a single-page-origin signal would be ideal), and whether an error message (if one is deliberately triggered, e.g. a missing capability) is immediately actionable without extra investigation.

Output of the walkthrough: a "Learnings" section appended to THIS doc (not a separate file) listing every friction point found, each tagged cosmetic (wording/doc-only fix), small (a guide/example improvement), or substantial (spins into its own follow-on roadmap doc) — mirroring the bug/small/trivial severity vocabulary review-docs already uses, for consistency across this session's review methodology.

Tutorial mode — the interactive step-gating mechanism¶

Raised directly by the user: a skill CAN support a genuine, user-paced, step-by-step teaching mode — a SKILL.md is instructions loaded into the agent's context, and those instructions can direct the agent to perform exactly ONE step, then stop and wait. This repo's own review-docs skill already has a lighter version of this ("Do NOT start implementing until the user confirms" — its Phase 4). The design below makes the gate TOOL- ENFORCED rather than prose-only, since a prose-only "I'll wait for you to say next" is not reliably honored under autopilot/auto-approval runtime modes — a tool call that returns a structured choice is a real, enforced stop.

Mechanism: every tutorial-mode step (the SAME 6-step shape the walkthrough validates: struct+codec → route/channel → router/group → capability requirement → adapter attach → run) ends with an ask_user call — never a plain text question. The call presents, at minimum: - continue — "Continue to next step" - redo — "Redo this step" (with a freeform field for what to change) - go_back — "Go back to an earlier step" (paired with a freeform field: which step, and what to change) - stop — "Stop here for now"

On go_back, the skill must actually RE-DO the named step with the requested change — not just acknowledge it — before presenting the NEXT ask_user gate again. The skill must never perform 2+ steps in one turn without an intervening ask_user call, even if the user's prior answer seems to imply eagerness to move fast — one step, one gate, always.

Developer mode — document-as-you-build¶

A second, user-requested operating mode living INSIDE each of the 3 tutorial skills (a mode SWITCH, not a 4^th separate skill — confirmed via explicit user direction) for a user who wants to build something REAL (not follow a script) while still getting roadmap-style documentation out of the session. Scoped to api/rest/api/events/api/reqreply work only, reached only through one of the 3 tutorial skills — not a general-purpose "document any go-codex work" capability.

Step 0 — shared mode-selection checkpoint. Every tutorial-skill invocation starts here, in BOTH modes: a short (3-5 sentence) explanation of what the skill does, followed by an ask_user 2-way choice: - "Tutorial mode — guided, step-by-step, I teach you" - "Developer mode — I document what you're building as you build it"

No auto-detection — the user was explicitly unsure an automatic "infer from context" trigger would be reliable, so Step 0 ALWAYS asks rather than guessing.

In developer mode, the skill does NOT walk the user through pre-scripted tutorial steps. Instead, the user drives their OWN real implementation (their own struct/codec, route/channel, router/group, capability requirement, adapter attachment, run) and the skill's job is to: (a) observe/assist as needed, (b) capture each step's concrete decisions as they're made (what was declared, why, any alternatives considered), and © at the end of the session (or on explicit request), draft a NEW docs/roadmap/<feature-name>.md using the EXACT plan-a-new-codex-feature Explore-mode template (Motivation / Scope decisions / API surface / Structured errors / Observer integration / Unit test plan / Files to create / Out of scope / Open design decisions) — populated from what was ACTUALLY built, written in the same forward-looking voice the template uses elsewhere (as if this had been planned this way), not as a chronological journal/changelog of events.

Developer mode's own internal pacing (does it ALSO gate per-step via ask_user the way tutorial mode does, or does it let the user drive freely and only interject to ask clarifying questions when a decision needs capturing?) is flagged as an Open design decision below — not resolved by this round's answers.

The 3 tutorial skills: shared shape¶

Each of tutorial-api-rest, tutorial-api-events, tutorial-api-reqreply is a .github/skills/tutorial-api-<name>/SKILL.md teaching ONE API's full workflow, live, to a user working in THIS repo or a project depending on go-codex. Both Tutorial mode and Developer mode above live in the SAME file, selected at Step 0. Shared structure (mirrors review-docs/ review-go-codex's own "methodology skill" shape, not a tool-wrapping skill):

Structured errors¶

Not applicable — no new Go error types; this is a process/documentation deliverable.

Observer integration¶

Not applicable — no new runtime code.

Unit test plan¶

Not applicable in the usual sense (no Go code). Verification instead: - go build ./... after any example-pointing edits (confirms no code changes were accidentally introduced and no referenced file/symbol is stale). - A manual re-run of each tutorial skill's own worked-example steps against the CURRENT repo state before considering it done, confirming every referenced file/line-range/symbol still exists and the narrated commands actually produce the stated result.

Files to create¶

No docs/features//docs/guides/ page additions are anticipated — these skills are a NEW surface (live, interactive teaching) distinct from the existing static feature/guide pages, which stay as the reference material the skills link out to.

Both Tutorial mode and Developer mode live in the SAME 3 SKILL.md files above, selected at each skill's Step 0 — no separate file per mode, and no 4^th skill for developer mode (confirmed via explicit user direction; see Scope decisions above).

Out of scope (Phase 2)¶

• A 4^th tutorial skill for api/mcp — not requested; api/mcp was outside this whole roadmap's scope (it has no Capability/CapabilityRequirement mechanism to teach) and already has docs/guides/mcp.md.
• Automating the walkthrough (e.g. a script that runs all 3 passes unattended) — the whole point is a HUMAN-in-the-loop friction-finding session; automating it would defeat the purpose.
• Any fix substantial enough to need its own roadmap doc, per the Scope Decisions table above — those are tracked as separate follow-ons, not absorbed into this doc's own Files-to-create list.

Open design decisions¶

• Does the walkthrough run as part of implementing THIS doc, or as a separate, later session? Leaning toward: run it as this doc's own Implement step (walkthrough is cheap, ~1 session, and directly produces the Learnings section the tutorial skills depend on) — not pre-decided here, confirm before starting Implement.
• Should each tutorial skill generate real scratch files in the user's workspace (a true "build it with me" session), or walk through the existing examples/*-api source read-only? The shared-shape table above leans toward "point at existing examples, don't duplicate them," but a live, hands-on skill arguably teaches better by having the user type the declarations themselves in a scratch file. Resolve during the walkthrough itself — whichever felt more natural there is the answer.
• Exact severity bar for "substantial enough to spin into its own roadmap doc" — mirrors review-docs's existing bug/small/trivial distinction loosely, but that vocabulary was built for DOC bugs, not workflow-ergonomics gaps; may need its own, slightly different bar (e.g. "touches exported API surface" vs. "wording/example-only").
• Developer mode's own internal pacing — does it ALSO gate per-step via ask_user the way Tutorial mode does, or does it let the user drive freely (their own real implementation, at their own pace) and only interject with a clarifying question when a decision needs capturing for the eventual roadmap draft? Not resolved by this round's ask_user answers — the user confirmed developer mode's SHAPE (mode switch, Step-0 trigger, scope, output template) but not its internal pacing. Resolve during Refine/Implement, likely by trying both during the walkthrough itself (developer mode, if exercised there, can test which pacing feels right).
• Exact ask_user schema for the "go back to step N" case — a single freeform text field ("which step, what to change") vs. a structured {step: enum, change: string} pair. Leaning freeform for simplicity (fewer rigid enum values to keep in sync as steps evolve), but not locked in — resolve during Implement when the actual ask_user call is written.

See also¶

• Composable Capability Requirements — Phase 8's review that raised this need; the two-step declare/capability model this walkthrough exercises end-to-end.
• D-0008 — Declarative Router Groups — the Router/Mount/Group/Walk design Step 3 of the walkthrough exercises (added to this doc's step shape during a later review pass — see Motivation).
• D-0009 — Internalizing Shared Cross-Pattern Mechanics — the router/route/middleware → internal/ relocation + per-pattern public wrapper convention (rest.BearerScheme/events.SecurityMiddleware/ etc.) every tutorial skill must teach as the CURRENT way to construct a security scheme/middleware value, and the source of the pre-seeded common-pitfall note above.
• docs/concepts/declaring-apis-and-ports.md — the durable narrative home for the declare → group → capability → attach model this walkthrough and these tutorials teach live.
• .github/instructions/agent-skills.instructions.md — skill-authoring conventions the 3 new SKILL.md files must follow.
• examples/rest-api, examples/events-api, examples/reqreply-api, examples/sensor-service — the existing flagship examples the walkthrough and tutorials build on rather than duplicate.