/ouroboros:welcome
Interactive onboarding for new Ouroboros users.
Usage
/ouroboros:welcome # First-time or update onboarding
/ouroboros:welcome --skip # Skip welcome, mark as shown
/ouroboros:welcome --force # Force re-run welcome even if shownInstructions
When this skill is invoked, follow this flow:
Pre-Check: Already Completed?
First, check ~/.ouroboros/prefs.json for welcomeCompleted:
PREFFILE="$HOME/.ouroboros/prefs.json"
if [ -f "$PREFFILE" ]; then
WELCOME_COMPLETED=$(jq -r '.welcomeCompleted // empty' "$PREFFILE" 2>/dev/null)
WELCOME_VERSION=$(jq -r '.welcomeVersion // empty' "$PREFFILE" 2>/dev/null)
if [ -n "$WELCOME_COMPLETED" ] && [ "$WELCOME_COMPLETED" != "null" ]; then
ALREADY_COMPLETED="true"
fi
fiIf ALREADY_COMPLETED is true AND no --force flag:
Use AskUserQuestion:
{
"questions": [{
"question": "Ouroboros welcome was already completed on $WELCOME_COMPLETED. What would you like to do?",
"header": "Welcome",
"options": [
{ "label": "Skip", "description": "Continue to work (recommended)" },
{ "label": "Re-run welcome", "description": "Go through the interactive onboarding again" }
],
"multiSelect": false
}]
}- Skip: Mark as complete and exit
- Re-run welcome: Continue to Step 1 below
If --skip flag present:
- Mark
welcomeShown: true(if not exists) - Show brief message:
Ouroboros welcome skipped. Run /ouroboros:welcome --force to re-run onboarding. - Exit
Step 1: Welcome Banner
Display:
Welcome to Ouroboros!
The serpent that eats itself -- better every loop.
Most AI coding fails at the input, not the output.
Ouroboros fixes this by exposing hidden assumptions
BEFORE any code is written.
Interview -> Seed -> Execute -> Evaluate
^ |
+---- Evolutionary Loop -----+Step 2: Persona Detection
AskUserQuestion:
{
"questions": [{
"question": "What brings you to Ouroboros?",
"header": "Welcome",
"options": [
{
"label": "New project idea",
"description": "I have a vague idea and want to crystallize it into a clear spec"
},
{
"label": "Tired of rewriting prompts",
"description": "AI keeps building the wrong thing because my requirements are unclear"
},
{
"label": "Just exploring",
"description": "Heard about Ouroboros and want to see what it does"
}
],
"multiSelect": false
}]
}Give brief personalized response (1-2 sentences) based on choice.
Step 3: MCP Check
cat ~/.claude/mcp.json 2>/dev/null | grep -q ouroboros && echo "MCP_OK" || echo "MCP_MISSING"If MCP_MISSING, AskUserQuestion:
{
"questions": [{
"question": "Ouroboros has a Python backend for advanced features (TUI dashboard, 3-stage evaluation, drift tracking). Set it up now?",
"header": "MCP Setup",
"options": [
{ "label": "Set up now (Recommended)", "description": "Register MCP server (requires Python >= 3.12)" },
{ "label": "Skip for now", "description": "Use basic features first (interview, seed, unstuck)" }
],
"multiSelect": false
}]
}- Set up now: Read and execute
skills/setup/SKILL.md, then return to Step 4 - Skip for now: Continue to Step 4
Step 4: Quick Reference
Available Commands:
+---------------------------------------------------+
| Command | What It Does |
|-----------------|----------------------------------|
| ooo interview | Socratic Q&A -- expose hidden |
| | assumptions in your requirements |
| ooo seed | Crystallize answers into spec |
| ooo run | Execute with visual TUI |
| ooo evaluate | 3-stage verification |
| ooo unstuck | Lateral thinking when stuck |
| ooo help | Full command reference |
+---------------------------------------------------+Step 5: First Action
AskUserQuestion:
{
"questions": [{
"question": "What would you like to do first?",
"header": "Get started",
"options": [
{ "label": "Start a project", "description": "Run a Socratic interview on your idea right now" },
{ "label": "Try the tutorial", "description": "Interactive hands-on learning with a sample project" },
{ "label": "Read the docs", "description": "Full command reference and architecture overview" }
],
"multiSelect": false
}]
}Based on choice:
- Start a project: Ask "What do you want to build?" → execute
skills/interview/SKILL.md - Try the tutorial: Execute
skills/tutorial/SKILL.md - Read the docs: Execute
skills/help/SKILL.md
Step 6: GitHub Star (Last Step)
Check gh availability first:
gh auth status &>/dev/null && echo "GH_OK" || echo "GH_MISSING"If GH_OK AND star_asked not true:
AskUserQuestion:
{
"questions": [{
"question": "If you're enjoying Ouroboros, would you like to star it on GitHub?",
"header": "Community",
"options": [
{ "label": "Star on GitHub", "description": "Takes 1 second -- helps the project grow" },
{ "label": "Maybe later", "description": "Skip for now" }
],
"multiSelect": false
}]
}- Star on GitHub:
gh api -X PUT /user/starred/Q00/ouroboros - Both: Save
{"star_asked": true, "welcomeShown": true, "welcomeCompleted": "$(date -Iseconds)", "welcomeVersion": "0.14.0"}to~/.ouroboros/prefs.json
If GH_MISSING or star_asked is true: Just save {"welcomeShown": true, "welcomeCompleted": "$(date -Iseconds)", "welcomeVersion": "0.14.0"}
Completion Message
Ouroboros Setup Complete!
MAGIC KEYWORDS (optional shortcuts):
Just include these naturally in your request:
| Keyword | Effect | Example |
|---------|--------|---------|
| interview | Socratic Q&A | "interview me about my app idea" |
| seed | Crystallize spec | "seed the requirements" |
| evaluate | 3-stage check | "evaluate this implementation" |
| stuck | Lateral thinking | "I'm stuck on the auth flow" |
REAL-TIME MONITORING (TUI):
When running ooo run or ooo evolve, open a separate terminal:
uvx --from 'ouroboros-ai[tui]' ouroboros tui monitor
Press 1-4 to switch screens (Dashboard, Execution, Logs, Debug).
READY TO BUILD:
- ooo interview "your project idea"
- ooo tutorial # Interactive learning
- ooo help # Full referencePrefs File Structure
~/.ouroboros/prefs.json:
{
"welcomeShown": true,
"welcomeCompleted": "2025-02-23T15:30:00+09:00",
"welcomeVersion": "0.14.0",
"star_asked": true
}