docs(scope): plan onboarding-as-session feature#1431
Merged
Conversation
Adds planning docs and UI mockups for the onboarding-as-session experiment: reproducible Docker VM clones a project, Claude-Code-driven onboarding tailors `.agents/*` to it, work-source dispatch hides pipelines from the user, and pipelines self-evolve every N runs via judge signals with human-approve gates. - onboarding-as-session-plan.md: vision, ADR alignment, refactoring pre-conditions, target architecture, additive schema (5 new tables), 4-phase delivery, risks, open questions. - preview-route-plan.md: how the static dummies migrate into a build- tagged `/preview/*` namespace inside webui (no impl yet). - codecrispies-walkthrough.md: end-to-end trace of every config touchpoint using `code-crispies` on git.librete.ch as the example. - mockups/: standalone HTML dummies for index, onboarding session, work board, work item detail, evolution proposal. Planning only. No code changes. Cross-references ADR-003, 004, 006, 007, 009, 010, 011, 013, 014, 015.
…on UX Captures nine inter-locking UX decisions surfaced by the mockups in docs/scope/mockups/ and the code-crispies walkthrough: - D1 default landing is /work, not /runs or /pipelines - D2 onboarding is a streaming Claude-Code session, not a stepwise wizard - D3 pipelines hidden behind per-item Run affordance - D4 bindings glue work items to pipelines - D5 cost surfaced before dispatch - D6 evolution proposals are first-class nav with badge - D7 auto-rollback configurable, defaults off - D8 SVG icons only, no emojis - D9 multi-forge federation built into the work-board Status: Proposed. Binding on the implementation tracked in docs/scope/onboarding-as-session-plan.md and preview-route-plan.md. Updates docs/adr/README.md index.
Two new landing-page mockups, distinct surfaces for distinct audiences:
- public-landing.html: marketing-quality public page in the spirit of
ngrok.com. Mono typography (JetBrains Mono), serif gradient hero
('Newsreader'), diagram product cards with dashed connectors, trust
bar (forge + model-provider logos), copy-able docker run code chip,
code blocks, "even more ways" feature card, multi-model verification
preview block, final CTA. Pitches Wave as 'the agentic Lego kit for
software factories'.
- 00-landing.html: in-product bridge view (post-onboarding webui '/').
Fleet at a glance: in-flight runs, live activity stream, discover/
start/compare panels, in-flight list, rhythm heat-strip, judge-trend
drift indicator, recent landings, three-pillar manifesto card
(erhabenheit, kontrolle, weitsicht).
index.html updated to feature both as primary entries and surface the
new positioning vocabulary.
Static HTML only. No webui code touched.
Diagram container had min-height but no positioning context, so absolute children (dnode boxes + dline SVGs) anchored to .pcard instead of .diagram. Lines visibly escaped card boundaries on narrow viewports. Set .diagram to fixed height + overflow: hidden so SVG with viewBox-based coords renders inside the card. Tightened wide-variant to 220px.
Headless chromium captures at 1440px width, auto-trimmed: - public-landing.png (5290px) - ngrok-quality marketing landing - 00-landing.png (1620px) - in-product bridge view - 01-onboarding-session.png - streaming Claude-Code session - 02-work-board.png - unified work board - 03-work-item.png - dispatch detail + bindings - 04-evolution-proposal.png - approve/reject diff gate - index.png - mockup directory
.explore link rendered its arrow at default 300x150 because no width/height was set. Added explicit 12px sizing + white-space nowrap on label, plus a generic safety net (svg:not([width]):not([height]) defaults to 1em) so any future unsized SVG falls back gracefully.
Pure SVG diagrams replace the prior HTML-div + SVG-overlay hybrid across all 4 product cards on the public landing page. Each card now has: - Outer dashed frame with subtle dot-grid background - Hub box with concentric pulsing halo rings (hub-pulse animation) - Manhattan-routed dashed connectors with arc corners - Distributed input/output ports across hub edges (no overlap) - Breathing endpoint markers (concentric halo + core) - Color-coded line direction: blue=input, cyan=output, yellow=warn, pink=alt - Recognizable iconography per box: file/folder/document/issue/PR/check/etc Wave brand logo (two-sine-wave SVG) used at hub centers, embedded as nested SVG with original 28x28 viewBox. Lab/ contains step-by-step build (step-1 → step-6) for reference. Trademark scrub: dropped 'Lego' references in favor of 'agentic building blocks' / 'Wave building blocks' / 'Agentic Pipeline Protocol (APP)'. Section heading updated 'From issue to live PR' -> 'From issue to reviewed PR' with output relabeled 'review pass' to reflect ops-pr-review arc. Bitbucket added to trust row. Screenshots refreshed for all 7 mockup pages.
- All icon SVGs anchored at box.x + 12 (consistent left padding)
- All labels use text-anchor="start" with x = box.x + 36 (icon.right + 8 gap)
- Drop CSS .dgm .label { text-anchor: middle } so inline attribute wins
- Hub labels keep text-anchor="middle" via inline attribute
- Removed legacy duplicate icons (bare circles/polylines/lines that
predated the Python-injected icon set)
Result: every box renders with consistent left-aligned icon-text
grouping. Predictable rule, no per-box math.
Boxes for short labels (start, compare, discover, PR !58, review pass) were inheriting wider widths from their long-label siblings, leaving excess right padding. Each box now sized to fit its content (icon + gap + text + 2*padding). Icons and texts re-anchored to the new box .x values.
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
1 participant
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.
Summary
Planning docs + UI mockups for the onboarding-as-session experiment.
End goal: reproducible Docker VM clones a project, a Claude-Code session tailors
.agents/*to it, the user sees a work-board (issues / PRs / scheduled tasks) instead of pipelines, and pipelines self-evolve every N runs via judge signals with human-approve gates. CLI + webui parity throughout.No code changes. Planning + mockups only.
What's in the diff
docs/scope/onboarding-as-session-plan.md— vision, ADR alignment, refactoring pre-conditions (PRE-1..6: service layer, onboarding rewrite, Gitea adapter, asset registry, schema additions, scheduler), target architecture, additive schema (5 new tables:pipeline_eval,pipeline_version,evolution_proposal,worksource_binding,schedule), 4-phase delivery, risks, 7 open questions.docs/scope/preview-route-plan.md— how the static dummies migrate into a build-tagged/preview/*namespace inside the webui (phase A static fixtures → phase B stub services → phase C real data → phase D promote). No impl yet.docs/scope/codecrispies-walkthrough.md— end-to-end trace usingcode-crispies(Bun + TS, Gitea ongit.librete.ch) as the concrete example. Every config touchpoint: env vars, entrypoint script, auto-detected fields, generated.agents/tree, sample pipeline / prompt / contract YAML, DB rows after onboarding, dispatch flow, eval recording, evolution proposal trigger heuristics + auto-rollback config. Master config index in §9.docs/scope/mockups/— standalone HTML dummies (openindex.htmldirectly in browser, orpython3 -m http.server -d docs/scope/mockups/):Cross-references
ADRs touched / aligned with: 003 (layered), 004 (multi-adapter), 006 (cost), 007 (StateStore), 009 (ontology bounded-context pattern reused for new bounded contexts), 010 (pipeline I/O — adds
work_item_refshared schema), 011 (Wave Lego — generated pipelines must be WLP-clean from day 1), 013 (failure taxonomy — reused for eval signals), 014 (composition vs graph), 015 (persona-as-agent-md format).Test plan
docs/scope/onboarding-as-session-plan.mdand validate vision + pre-conditionsdocs/scope/codecrispies-walkthrough.md§9 master config index and confirm exhaustivedocs/scope/mockups/index.htmlin a browser; click through all 4 screensonboarding-as-session-plan.md§7preview-route-plan.md§10codecrispies-walkthrough.md§11