| name | tutorial-onboarding |
| description | Guided onboarding workflow — modn guide leads the system setup. Use when the user says "tutorial", "onboarding", or is a first-time user.
|
| spec-version | 2 |
| context | main |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash"] |
Tutorial Onboarding
Onboarding workflow led by the modn guide. SSOT for system setup.
Trigger: Auto-starts on first session when tutorial_complete is false. Manual: /tutorial:onboarding.
WHY
New users face an empty system with no clear starting point. This workflow is the sole onboarding entry point. The root README.md directs users to this workflow; the onboarding context lives here only.
This workflow is the Practice layer in the 3-layer learning model:
- Read (README → docs/{locale}/) — principles and possibilities
- Practice (this onboarding) — hands-on with real code, referencing docs/en/concepts/ for principles
Each quest references relevant concept docs so users understand the "why" while doing the "how".
Two paths:
- Path A (Free Topic): User picks a topic and progresses through quests
- Path B (Guided Mission): Choose 1 of 3 preset missions (study/work/portfolio), experience the full system
Both paths arrive at the same destination: a system with identity, initiative lifecycle, knowledge loop, squads, and disposition working together.
STEPS
Step 1: Check Progress
Read workspace/squads/tutorial/data/progress.json.
- User stage: first-time (all pending), returning (some completed), graduated (tutorial_complete = true)
- Active path: quest (default), mission (
path: mission)
- graduated → end workflow, no tutorial interaction
- returning on mission → resume from current mission step
Step 2: Welcome (first-time only)
Use the modn Welcome section from the modn guide agent (workspace/squads/tutorial/agents/guide.md).
After the easter-egg greeting, identify usage intent:
Pick what you want to do (multiple selections OK):
- Side project (personal project, hobby)
- Work (research, writing, decision-making)
- Study (lectures, deep dives)
- Creative (writing, design, music)
- Project management (tasks, goal tracking)
- Not sure yet — I want to explore
Whatever you pick, the system will adapt.
Adapt dialogue to user's language. The examples above are in English; adjust to Korean or other languages based on the user's first message.
Answers are used to tailor quest examples. They do not affect path branching.
Output: user-context
Step 3: Phase 0 — Identity (Q-01, Q-02)
Run Phase 0 quests in order. Common to both paths — start with system identity.
| Quest | Goal | Deep Dive |
|---|
| Q-01: System Identity | Set name/purpose/north star in CLAUDE.md | — |
| Q-02: Self-Introduction | Write vault/user/_meta/summary.md | — |
Step 4: Route Path
After Phase 0 completion, choose a path:
Phase 0 complete: "Identity"
The system now knows you.
Next, you'll create your first real project (Initiative).
A) I have a topic in mind → tell me your topic
B) Not yet → start with a guided mission
→ Build a squad from scratch and use it hands-on (choose from study/work/portfolio).
Experience the full cycle: initiative, subtopic, squad, and knowledge extraction.
Which one? (A or B, you can switch anytime)
Adapt dialogue to user's language based on the user's first message.
- Path A → Step 5 (Quest Flow)
- Path B → Step 7 (Mission Flow)
Save path: quest or path: mission in progress.json.
Step 5: Quest Flow (Path A)
Standard quest progression starting from Q-03:
Progression flow:
- Present next quest (what/why/how + deep dive guide links)
- Execution guide (conversational or action-based)
- Completion verification (
policies/quest-progression.md)
- Celebrate & next step
- All of Phase 0-2 complete → graduation (Step 10)
Proactive hints:
| Quest | Hint |
|---|
| Q-03 | Tailor examples to user-context from Step 2 |
| Q-04 | If spanning multiple sessions: "End with /initiative:handoff and pick up next time with /initiative:resume." |
| Q-05 | "This might feel long, but this is the moment the system learns from your work." |
| Q-06/07 | "Most of this runs automatically during the closing pipeline." |
Step 6: Quest Verify & Celebrate (Path A)
File-based verification (policies/quest-progression.md).
- Pass → update progress.json, celebrate, suggest next quest
- Fail → explain what's missing, re-execute
- Phase complete → display phase milestone
- All of Phase 0-2 complete → graduation (Step 10)
Step 7: Mission Brief (Path B)
Preset selection + mission introduction:
Mission: Build a squad from scratch and use it hands-on
What kind of squad do you want to build?
1) Study helper — organize learning materials + accumulate knowledge
2) Work workflow — automate repetitive tasks (includes mini-workflow)
3) Portfolio manager — organize career history + generate resumes
Which one appeals to you most?
Adapt dialogue to user's language based on the user's first message.
After selection:
[Selected preset] mission start.
Tasks:
1. Create an Initiative
2. Research — figure out what you need
3. Build the squad structure
4. Define an AI agent
5. First use — test with real data
6. Close Initiative + explore content opportunities
7. Promote knowledge
8. Record patterns
9. Tune disposition
Estimated time: 1-2 hours (can span multiple sessions).
Each step has a clear goal.
Let's go.
Adapt dialogue to user's language based on the user's first message.
Auto-exclude: If the target squad directory already exists, show "(already exists — customization mode)".
Save mission_preset: "study" | "work" | "portfolio" in progress.json.
Preset details: vault/knowledge/mission-presets.md
Step 8: Mission Step Execution (Path B)
Guide mission steps in order. Each step has a preset goal + auto-completes the corresponding quest:
| Mission Step | Goal | Quest Auto-completed | Deep Dive Guide |
|---|
| M-01: Create initiative | /initiative:start with preset topic | Q-03 | 01-initiative-system |
| M-02: Research & design | Complete subtopic with preset research questions | Q-04 | — |
| M-03: Build squad | workspace/squads/{name}/ + index.yml + README.md | Q-09 | 02-squad-model |
| M-04: Define agent | Define agent in workspace/squads/{name}/agents/ | Q-10 | 03-workflow-design |
| M-05: First use | Test squad with real data — preset-specific experience | — | — |
| M-06: Close + Narrative | Experience /initiative:complete + /narrative:discover | Q-05 | 04-knowledge-loop |
| M-07: Promote knowledge | CL pipeline: promote insights to vault/knowledge/ | Q-06 | — |
| M-08: Record pattern | CL pipeline: record observed patterns to vault/user/patterns/ | Q-07 | — |
| M-09: Tune disposition | Customize rules/disposition.md | Q-08 | 07-disposition-framework |
Each step provides:
- What to do (1-2 sentences)
- Why it matters (connection to the system, 1 sentence)
- Preset goal (specific deliverable)
- How to start (command or action)
Mission step details (preset goals, scaffolding): vault/knowledge/mission-presets.md
Step 9: Mission Verify & Advance (Path B)
After each mission step:
- File-based verification (same criteria as quest verification)
- Pass → update both mission step and corresponding quest in
progress.json
- Show mission progress:
Step [N]/9 complete. [impact]
- All 9 steps complete → graduation (Step 10)
Step 10: Graduation
Common to both paths:
Tutorial complete.
The system now has identity, initiative lifecycle, knowledge loop, squads, and disposition in place.
One more thing: this template keeps evolving. Run /template:sync anytime to check
for new rules, skills, and tools from upstream.
Set tutorial_complete: true in progress.json.
Path B bonus: After graduation, when Catalyst or Narrative detection activates, the squad you built starts making suggestions — the moment the system comes alive.
JUDGMENT
| Condition | Decision |
|---|
| User defers | End workflow, guide agent ambient detection only |
| Quest/mission completed during other work | Guide agent detects → verifies directly |
| Path A user requests switch to Mission | Save progress, enter mission from first incomplete step |
| Path B user requests switch to free topic | Save progress, return to quest flow |
| Quest skip request (Path A) | Phase 0-1 sequential, Phase 2 sequential, Phase 3-4 flexible |
| Mission step verification fails | Re-execute with specific guidance |
FLOW
nodes:
- id: check-progress
type: auto
summary: "Read progress.json, determine user stage/path/next step"
output: [user-stage, active-path, next-step-id]
judgment:
- condition: "tutorial_complete = true"
next: exit
type: gate
- condition: "Returning on mission path"
next: mission-step
- condition: "Returning on quest path"
next: suggest-quest
- id: welcome
type: human
summary: "First-time: modn easter-egg greeting + identify usage intent"
output: [user-context]
- id: suggest-quest
type: human
summary: "Present next quest (what/why/how + deep dive guide links)"
input: [next-step-id, user-context]
judgment:
- condition: "User defers or focuses on other work"
next: exit
type: override
- id: execute-quest
type: human
summary: "Quest execution guide — conversational or action-based"
- id: quest-verify
type: auto
summary: "File-based verification (quest-progression policy)"
judgment:
- condition: "Verification failed"
next: execute-quest
type: loop-back
- id: quest-celebrate
type: auto
summary: "Update progress.json, completion message. Phase milestone if applicable"
judgment:
- condition: "Phase 0 complete"
next: route-path
- condition: "All of Phase 0-2 complete"
next: graduate
- condition: "Quests remaining"
next: suggest-quest
- id: route-path
type: human
summary: "Phase 0 complete: free topic (Path A) vs guided mission (Path B) selection"
judgment:
- condition: "Has a topic"
next: suggest-quest
- condition: "Chooses guided mission"
next: mission-brief
- id: mission-brief
type: human
summary: "Preset selection (study/work/portfolio) + mission intro. Scope, outcome, estimated time"
- id: mission-step
type: human
summary: "Guide current mission step (M-01~M-09) with selected preset goals"
input: [next-step-id]
- id: mission-verify
type: auto
summary: "Verify mission step + auto-complete corresponding quest"
judgment:
- condition: "Verification failed"
next: mission-step
type: loop-back
- condition: "All 9 steps complete"
next: graduate
- condition: "Steps remaining"
next: mission-step
- id: graduate
type: auto
summary: "Set tutorial_complete = true, graduation message"
- id: exit
type: auto
summary: "No workflow interaction. Guide agent ambient detection remains active"
edges:
- from: check-progress → to: welcome
condition: "First-time (all pending)"
- from: welcome → to: suggest-quest
- from: suggest-quest → to: execute-quest
- from: execute-quest → to: quest-verify
- from: quest-verify → to: quest-celebrate
- from: quest-celebrate → to: route-path
condition: "Phase 0 complete"
- from: quest-celebrate → to: suggest-quest
condition: "Quests remaining"
- from: quest-celebrate → to: graduate
- from: route-path → to: suggest-quest
condition: "Path A"
- from: route-path → to: mission-brief
condition: "Path B"
- from: mission-brief → to: mission-step
- from: mission-step → to: mission-verify
- from: mission-verify → to: mission-step
- from: mission-verify → to: graduate
Agent Ambient Detection
The guide agent monitors quest/mission completion outside the workflow. When it detects a naturally completed step:
- Recognize completion signal
- Enter appropriate verification node directly (quest-verify or mission-verify)
- Verification passes → celebrate & advance
This ambient detection is the guide agent's responsibility. See workspace/squads/tutorial/agents/guide.md.
KNOWLEDGE REFS
| Type | Path | Role |
|---|
| Agent | workspace/squads/tutorial/agents/guide.md | modn guide — per-quest dialogue flow, ambient detection, persona |
| Policy | workspace/squads/tutorial/policies/quest-progression.md | Quest order, verification checks, phase rules |
| Knowledge | workspace/squads/tutorial/vault/knowledge/mission-presets.md | Mission M-01~M-09 preset goals and scaffolding (study/work/portfolio) |
| Data | workspace/squads/tutorial/data/progress.json | User progress state (path, mission step included) |
| Concepts | docs/en/concepts/ | 7 concept docs — linked per quest phase for deep dives |
