Initial commit with translated description

2026-03-29 09:45:56 +08:00
commit 663b3cd80d
14 changed files with 2671 additions and 0 deletions
--- a/references/onboarding-flow.md
+++ b/references/onboarding-flow.md
@@ -0,0 +1,158 @@
+# Onboarding Flow Reference
+
+How to handle onboarding as a proactive agent.
+
+## Detection
+
+At session start, check for `ONBOARDING.md`:
+
+```
+if ONBOARDING.md exists:
+    if status == "not_started":
+        offer to begin onboarding
+    elif status == "in_progress":
+        offer to resume or continue drip
+    elif status == "complete":
+        normal operation
+else:
+    # No onboarding file = skip onboarding
+    normal operation
+```
+
+## Modes
+
+### Interactive Mode
+User wants to answer questions now.
+
+```
+1. "Great! I have 12 questions. Should take ~10 minutes."
+2. Ask questions conversationally, not robotically
+3. After each answer:
+   - Update ONBOARDING.md (mark answered, save response)
+   - Update USER.md or SOUL.md with the info
+4. If interrupted mid-session:
+   - Progress is already saved
+   - Next session: "We got through X questions. Continue?"
+5. When complete:
+   - Set status to "complete"
+   - Summarize what you learned
+   - "I'm ready to start being proactive!"
+```
+
+### Drip Mode
+User is busy or prefers gradual.
+
+```
+1. "No problem! I'll learn about you over time."
+2. Set mode to "drip" in ONBOARDING.md
+3. Each session, if unanswered questions remain:
+   - Ask ONE question naturally
+   - Weave it into conversation, don't interrogate
+   - Example: "By the way, I realized I don't know your timezone..."
+4. Learn opportunistically from conversation too
+5. Mark complete when enough context gathered
+```
+
+### Skip Mode
+User doesn't want formal onboarding.
+
+```
+1. "Got it. I'll learn as we go."
+2. Agent works immediately with defaults
+3. Fills in USER.md from natural conversation
+4. May never formally "complete" onboarding — that's fine
+```
+
+## Question Flow
+
+Don't ask robotically. Weave into conversation:
+
+❌ Bad: "Question 1: What should I call you?"
+✅ Good: "Before we dive in — what would you like me to call you?"
+
+❌ Bad: "Question 5: What is your primary goal?"
+✅ Good: "I'd love to understand what you're working toward. What's the main thing you're trying to accomplish right now?"
+
+## Opportunistic Learning
+
+Even outside formal onboarding, notice and capture:
+
+| User Says | Learn |
+|-----------|-------|
+| "I'm in New York" | Timezone: America/New_York |
+| "I hate long emails" | Communication: brief |
+| "My cofounder Sarah..." | Key person: Sarah (cofounder) |
+| "I'm building an app for..." | Current project |
+
+Update USER.md and mark corresponding onboarding question as answered.
+
+## Handling Interruption
+
+### Mid-Question Interruption
+```
+User: "Actually, hold on — need to take this call"
+Agent: "No problem! We can pick this up anytime."
+[Save progress, don't ask again this session]
+```
+
+### Multi-Day Gap
+```
+Session 1: Answered 4 questions, got interrupted
+[3 days pass]
+Session 2: "Hey! Last time we were getting to know each other. 
+           Want to continue, or should I just ask occasionally?"
+```
+
+### User Seems Annoyed
+```
+If user seems impatient with questions:
+- Stop asking
+- Switch to opportunistic learning only
+- Note in ONBOARDING.md: "User prefers organic learning"
+```
+
+## Completion Criteria
+
+Onboarding is "complete enough" when you have:
+
+**Minimum viable:**
+- Name
+- Primary goal or current project
+- Communication preference (even if inferred)
+
+**Ideal:**
+- All 12 questions answered
+- USER.md fully populated
+- SOUL.md personality configured
+
+**Reality:**
+- Many users will never formally complete
+- That's okay — agent adapts
+- Keep learning from every interaction
+
+## Post-Onboarding
+
+When status changes to "complete":
+
+1. Summarize what you learned:
+   ```
+   "Okay, here's what I've got:
+   - You're [Name], based in [Timezone]
+   - You're working on [Project] toward [Goal]
+   - You prefer [communication style]
+   - Key people: [list]
+   
+   Anything I got wrong or missed?"
+   ```
+
+2. Explain what's next:
+   ```
+   "I'm now in proactive mode. I'll:
+   - Check in during heartbeats
+   - Look for ways to help without being asked
+   - Build things I think you'll find useful
+   
+   I'll always check before doing anything external."
+   ```
+
+3. Transition to normal operation