tutorial-onboarding

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:

Phase	Quests	Deep Dive Guides
Phase 1: First Project	Q-03 First Initiative, Q-04 Execute Subtopic, Q-05 Close Initiative	01-initiative-system, 04-knowledge-loop
Phase 2: Knowledge Loop	Q-06 Promote Knowledge, Q-07 Record Pattern, Q-08 Disposition	04-knowledge-loop, 07-disposition-framework
Phase 3: Custom Domain	Q-09 Create Squad, Q-10 Define Agent	02-squad-model, 03-workflow-design
Phase 4: Ecosystem	Q-11 Act on Catalyst	05-fractal-navigation, 06-rules-and-context

Progression flow:

1. Present next quest (what/why/how + deep dive guide links)
2. Execution guide (conversational or action-based)
3. Completion verification (policies/quest-progression.md)
4. Celebrate & next step
5. 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:

1. File-based verification (same criteria as quest verification)
2. Pass → update both mission step and corresponding quest in progress.json
3. Show mission progress: Step [N]/9 complete. [impact]
4. 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:

1. Recognize completion signal
2. Enter appropriate verification node directly (quest-verify or mission-verify)
3. 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