Help us improve
Share bugs, ideas, or general feedback.
From ouroboros
Runs interactive onboarding for new Ouroboros users, checking ~/.ouroboros/prefs.json for completion status and supporting --skip or --force flags.
npx claudepluginhub q00/ouroboros --plugin ouroborosHow this skill is triggered — by the user, by Claude, or both
Slash command
/ouroboros:welcomeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Interactive onboarding for new Ouroboros users.
Guided 6-step onboarding wizard that configures MCP server registration and CLAUDE.md integration for Ouroboros, with community support prompts.
Provides adaptive welcome experience for new Claude Code users. Embedded in setup skill; do not invoke first-run-welcome separately—use setup instead.
Runs OrchestKit onboarding wizard: scans codebase for stack detection, configures plugins interactively, generates readiness score and improvement plan. Use for new projects, rescans, or config.
Share bugs, ideas, or general feedback.
Interactive onboarding for new Ouroboros users.
/ouroboros:welcome # First-time or update onboarding
/ouroboros:welcome --skip # Skip welcome, mark as shown
/ouroboros:welcome --force # Force re-run welcome even if shown
When this skill is invoked, follow this flow:
First, check ~/.ouroboros/prefs.json for welcomeCompleted. For upgrades from older releases, also treat legacy welcomeShown: true as completed so the welcome prompt does not reappear forever:
PREFFILE="$HOME/.ouroboros/prefs.json"
if [ -f "$PREFFILE" ]; then
WELCOME_COMPLETED=$(python3 - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
try:
prefs = json.load(open(path, encoding='utf-8'))
except Exception:
prefs = {}
if not isinstance(prefs, dict):
prefs = {}
print(prefs.get('welcomeCompleted') or ('legacy-welcomeShown' if prefs.get('welcomeShown') else ''))
PY
)
WELCOME_VERSION=$(python3 - <<'PY'
import json, os
path = os.path.expanduser('~/.ouroboros/prefs.json')
try:
prefs = json.load(open(path, encoding='utf-8'))
except Exception:
prefs = {}
if not isinstance(prefs, dict):
prefs = {}
print(prefs.get('welcomeVersion') or '')
PY
)
if [ -n "$WELCOME_COMPLETED" ] && [ "$WELCOME_COMPLETED" != "null" ]; then
ALREADY_COMPLETED="true"
fi
fi
If 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
}]
}
If --skip flag present:
welcomeShown: true, welcomeCompleted: <current timestamp>, and welcomeVersion into ~/.ouroboros/prefs.json without deleting existing keys:
python3 - <<'PY' import json, os from datetime import UTC, datetime path = os.path.expanduser('~/.ouroboros/prefs.json') os.makedirs(os.path.dirname(path), exist_ok=True) try: with open(path, encoding='utf-8') as f: prefs = json.load(f) if not isinstance(prefs, dict): prefs = {} except Exception: prefs = {} prefs.update({ 'welcomeShown': True, 'welcomeCompleted': datetime.now(UTC).isoformat(), 'welcomeVersion': '0.36.0', }) with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY
- 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**:
```json
{
"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.
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
}]
}
skills/setup/SKILL.md, then return to Step 4Available 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 |
+---------------------------------------------------+
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:
skills/interview/SKILL.mdskills/tutorial/SKILL.mdskills/help/SKILL.mdCheck 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
}]
}
gh api -X PUT /user/starred/Q00/ouroboros~/.ouroboros/prefs.json without deleting existing keys. Set star_asked: true after either star prompt choice so the star prompt is not repeated:
python3 - <<'PY' import json, os from datetime import UTC, datetime path = os.path.expanduser('~/.ouroboros/prefs.json') os.makedirs(os.path.dirname(path), exist_ok=True) try: with open(path, encoding='utf-8') as f: prefs = json.load(f) if not isinstance(prefs, dict): prefs = {} except Exception: prefs = {} prefs.update({ 'star_asked': True, 'welcomeShown': True, 'welcomeCompleted': datetime.now(UTC).isoformat(), 'welcomeVersion': '0.36.0', }) with open(path, 'w', encoding='utf-8') as f: json.dump(prefs, f, indent=2) f.write('\n') PY
**If `GH_MISSING` or `star_asked` is true:**
Merge the welcome completion fields into `~/.ouroboros/prefs.json` without deleting existing keys:
```bash
python3 - <<'PY'
import json, os
from datetime import UTC, datetime
path = os.path.expanduser('~/.ouroboros/prefs.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
try:
with open(path, encoding='utf-8') as f:
prefs = json.load(f)
if not isinstance(prefs, dict):
prefs = {}
except Exception:
prefs = {}
prefs.update({
'welcomeShown': True,
'welcomeCompleted': datetime.now(UTC).isoformat(),
'welcomeVersion': '0.36.0',
})
with open(path, 'w', encoding='utf-8') as f:
json.dump(prefs, f, indent=2)
f.write('\n')
PY
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 reference
~/.ouroboros/prefs.json:
{
"welcomeShown": true,
"welcomeCompleted": "2025-02-23T15:30:00+09:00",
"welcomeVersion": "0.36.0",
"star_asked": true
}