@elevasis/sdk 1.15.1 → 1.17.0

package/reference/claude-config/skills/tutorial/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: tutorial
+description: |
+  Persona-aware onboarding tutorial that forks into a vibe-coder track (zero technical
+  vocabulary, agent does all the work) or a technical track (full SDK depth, code-first).
+  On first invocation, asks one gate question to determine the user's track and persists the
+  choice to .claude/memory/profile.md. Subsequent invocations skip the question and display
+  the track menu with current progress markers. Supports /tutorial switch (flip track) and
+  /tutorial status (display-only).
+argument-hint: "[switch | status]"
+context: fork
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Tutorial
+
+Persona-aware onboarding. Forks at first invocation into a **vibe-coder track** (non-technical,
+agent handles everything silently) or a **technical track** (developer-focused, full SDK depth).
+
+**Usage:** `/tutorial` | `/tutorial switch` | `/tutorial status`
+
+---
+
+## Architecture Note
+
+`profile.md` is read at session start alongside `.claude/rules/agent-start-here.md`. The rules
+layer uses the track choice to adjust tone, vocabulary, and tool-call visibility project-wide.
+This router does not enforce that tone -- it only writes profile.md and loads the right track
+file. The project-wide tone effect is handled by the rules layer reading profile.md on each
+session start.
+
+---
+
+## Step 1: Parse the Argument
+
+Check whether the invocation included an argument:
+
+- `/tutorial switch` -- go to [Switch Track](#switch-track)
+- `/tutorial status` -- go to [Status Display](#status-display) (no prompt afterward)
+- `/tutorial` (no argument) -- continue to Step 2
+
+---
+
+## Step 2: Check for Existing Profile
+
+Read `.claude/memory/profile.md`.
+
+- **File does not exist (first invocation):** go to [First Invocation](#first-invocation)
+- **File exists:** go to [Returning Invocation](#returning-invocation)
+
+---
+
+## First Invocation
+
+### Ask the Gate Question
+
+Print verbatim:
+
+> "Are you here to **build automations by describing what you want** (and I handle the technical
+> side), or are you a **developer** who'll edit code directly?"
+
+Wait for the user's answer. Accept natural-language replies -- map to one of two tracks:
+
+| User says (examples)                                             | Track        |
+| ---------------------------------------------------------------- | ------------ |
+| "describe what I want", "non-technical", "you handle it", "vibe" | `vibe-coder` |
+| "developer", "edit code", "technical", "build myself", "code"    | `technical`  |
+
+If the answer is ambiguous, ask once: "Just to confirm -- do you want me to handle the technical
+side, or will you be editing code directly?"
+
+### Persist the Profile
+
+Write `.claude/memory/profile.md` using the template below. Select the tone-implications block
+that matches the chosen track.
+
+**For vibe-coder track:**
+
+```markdown
+# Project Profile
+
+**Track:** vibe-coder
+**Selected at:** YYYY-MM-DD
+**Switch tracks:** Run `/tutorial switch` to change.
+
+## Tone Implications
+
+In this project, always:
+- Say "automation" instead of workflow / agent / resource
+- Say "the information your automation needs" instead of schema / Zod / type
+- Say "make it live" or "publish" instead of deploy
+- Say "your business profile" instead of organization model / config
+- Say "account connection" instead of credential
+- Say "your dashboard" or "your map" instead of Operations / Command Center / Command View
+- Say "your approval queue" instead of HITL / approval gate
+- Never mention repo / monorepo / git
+- Never mention TypeScript / pnpm / CLI
+- Say "the tool the automation uses" instead of adapter / platform tool
+- Say "updating your profile together" instead of /knowledge ceremony
+- Run slash commands silently on the user's behalf -- never expose command names or code
+```
+
+**For technical track:**
+
+```markdown
+# Project Profile
+
+**Track:** technical
+**Selected at:** YYYY-MM-DD
+**Switch tracks:** Run `/tutorial switch` to change.
+
+## Tone Implications
+
+Code-first communication. Use current command names and SDK terminology without hand-holding.
+No vocabulary substitutions. Slash commands may be surfaced directly. Full technical depth.
+```
+
+### Initialize Progress File
+
+Read `.claude/memory/tutorial-progress.md`.
+
+- If the file does not exist, read `.claude/skills/tutorial/progress-template.md` and write its
+  contents verbatim to `.claude/memory/tutorial-progress.md`. If `progress-template.md` is also
+  missing (sibling agent has not yet created it), write a minimal stub:
+
+```markdown
+# Tutorial Progress
+
+**Vibe-coder track**
+
+- [ ] 1 Welcome
+- [ ] 2 How to talk to me
+- [ ] 3 Your business profile
+- [ ] 4 Your first automation
+- [ ] 5 Your dashboard
+- [ ] 6 Your approval queue
+- [ ] 7 Changing things later
+- [ ] 8 When things go wrong
+
+**Technical track**
+
+- [ ] 1 What is this workspace
+- [ ] 2 The skill layer
+- [ ] 3 The vibe layer
+- [ ] 4 Echo workflow tour
+- [ ] 5 Custom workflow with schemas
+- [ ] 6 Platform tools and credentials
+- [ ] 7 Multi-step and conditionals
+- [ ] 8 Going to production
+- [ ] 9 /knowledge ceremony
+- [ ] 10 Features and labels
+- [ ] 11 Entity extensions
+- [ ] 12 HITL
+- [ ] 13 Schedules
+- [ ] 14 Notifications + integrations
+- [ ] 15 Error handling
+- [ ] 16 LLM and agents
+- [ ] 17 Composition
+- [ ] 18 Rules, memory, scaffold registry
+- [ ] 19 Template lifecycle and /git-sync
+```
+
+- If the file already exists, leave it unchanged.
+
+### Load Track and Show Menu
+
+Read the matching track file:
+
+- `vibe-coder` track: `.claude/skills/tutorial/vibe-coder.md`
+- `technical` track: `.claude/skills/tutorial/technical.md`
+
+Read `.claude/memory/tutorial-progress.md` and apply progress markers to the menu (see
+[Progress Markers](#progress-markers)). Display the menu. Prompt: "Pick a number to start."
+
+---
+
+## Returning Invocation
+
+Read `.claude/memory/profile.md` and extract the **Track** field.
+
+Read `.claude/memory/tutorial-progress.md`.
+
+Load the matching track file:
+
+- `vibe-coder` track: `.claude/skills/tutorial/vibe-coder.md`
+- `technical` track: `.claude/skills/tutorial/technical.md`
+
+Apply progress markers to the menu (see [Progress Markers](#progress-markers)). Display the
+menu. Prompt: "Pick a number to continue, or type a number to jump to any lesson."
+
+Wait for the user to pick a number, then follow that lesson's instructions from the track file.
+
+---
+
+## Progress Markers
+
+When rendering any menu, annotate each item using the markers from `tutorial-progress.md`:
+
+| Marker in progress file | Menu display |
+| ----------------------- | ------------ |
+| `[ ]`                   | `[ ]`        |
+| `[>]`                   | `[>]`        |
+| `[x] YYYY-MM-DD`        | `[x]`        |
+
+Read the progress file, match items by lesson number and track section, and substitute the
+marker inline. Items with no matching entry display `[ ]`.
+
+---
+
+## Switch Track
+
+Print:
+
+> "You're currently on the **{current-track}** track. Switching will show you the
+> **{other-track}** menu. Your progress for each track is saved separately and will not be lost.
+> Switch?"
+
+Wait for confirmation. On yes:
+
+1. Read `.claude/memory/profile.md`.
+2. Update the **Track** field to the other track name.
+3. Update the **Selected at** date to today.
+4. Replace the Tone Implications block with the block for the new track (see [First Invocation](#first-invocation) for both blocks).
+5. Write the updated profile.md.
+6. Load the new track file and display the menu with current progress markers.
+7. Prompt: "Pick a number to start, or press Enter to begin at lesson 1."
+
+On no: print "No change made." and stop.
+
+Do not modify `tutorial-progress.md` -- it tracks per-track progress independently.
+
+---
+
+## Status Display
+
+Same as [Returning Invocation](#returning-invocation) but do not show a number-prompt afterward.
+If no profile exists yet, print:
+
+> "No track selected yet. Run `/tutorial` to get started."
+
+---
+
+## Error States
+
+- **Track file missing** (`vibe-coder.md` or `technical.md` not found): print "Track content
+  file is not yet available. It may still be generating -- try again in a moment." Do not
+  attempt to generate the content; it belongs to the sibling track files.
+- **progress-template.md missing**: write the minimal stub documented in [First Invocation](#first-invocation). Do not fail.
+- **profile.md malformed**: treat as missing and run the gate question again.

package/reference/claude-config/skills/tutorial/progress-template.md

@@ -0,0 +1,74 @@
+# Tutorial Progress
+
+This file lives at `.claude/memory/tutorial-progress.md` once `/tutorial` runs for the first time.
+It tracks per-track progress separately so users can switch tracks without losing state.
+
+**Started:** {YYYY-MM-DD}
+**Last session:** {YYYY-MM-DD}
+
+---
+
+## Vibe-Coder Track
+
+```
+Your Tutorial
+==============
+1  Welcome -- what this place does for you             [ ]
+2  How to talk to me                                   [ ]
+3  Your business profile                               [ ]
+4  Your first automation                               [ ]
+5  Your dashboard -- where everything lives            [ ]
+6  Your approval queue -- signing off on things        [ ]
+7  Changing things later                               [ ]
+8  When things go wrong                                [ ]
+```
+
+---
+
+## Technical Track
+
+```
+SECTION A -- The workspace                              (3 items)
+  1  What is this workspace                              [ ]
+  2  The skill layer -- slash commands you'll use        [ ]
+  3  The vibe layer -- ambient intent classification     [ ]
+
+SECTION B -- Build your first thing                     (5 items)
+  4  Echo workflow tour                                  [ ]
+  5  Custom workflow with schemas                        [ ]
+  6  Platform tools and credentials                      [ ]
+  7  Multi-step and conditionals                         [ ]
+  8  Going to production                                 [ ]
+
+SECTION C -- The Organization Model                     (3 items)
+  9  /knowledge ceremony -- identity, customers,         [ ]
+     offerings via the layered flow
+ 10  Features and labels                                 [ ]
+ 11  Entity extensions -- BaseProject, BaseDeal          [ ]
+
+SECTION D -- Modules (load on demand)                   (6 items)
+ 12  HITL                                                [ ]
+ 13  Schedules                                           [ ]
+ 14  Notifications + integrations                        [ ]
+ 15  Error handling                                      [ ]
+ 16  LLM and agents                                      [ ]
+ 17  Composition (execution.trigger)                     [ ]
+
+SECTION E -- Power user                                 (2 items)
+ 18  Rules, memory, scaffold registry                    [ ]
+ 19  Template lifecycle and /git-sync                    [ ]
+```
+
+---
+
+## Completed Lessons
+
+| Track      | Item | Title | Completed | Duration |
+| ---------- | ---- | ----- | --------- | -------- |
+| _none yet_ |      |       |           |          |
+
+---
+
+## Capability Observations
+
+(The teaching agent jots brief notes here, e.g. "user navigated Command Center confidently" or "user wanted code shown in lesson 4 -- flagged as candidate for /tutorial switch")