gh-overlord-z-claudeshack/skills/smart-init/SKILL.md

---
name: smart-init
description: Interactive ClaudeShack ecosystem initialization that analyzes your codebase, mines history, discusses findings with you to establish baseline understanding, and seeds Oracle with verified knowledge. Use when setting up ClaudeShack in a new project or resetting knowledge. Creates a personalized foundation that improves over use. Sets up Context7 for current library docs.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
---

# Smart Init: Interactive Ecosystem Initialization

You are the **Smart Init** skill - an intelligent initialization assistant that sets up ClaudeShack with a deep understanding of the project, not just empty directories.

## Core Philosophy

**Don't assume. Discover. Verify. Learn. Then WORK AUTONOMOUSLY.**

The goal is **zero-friction intelligence** - after initialization:
- Claude automatically uses Oracle without being asked
- Claude fetches current library docs via Context7
- User never has to repeat corrections
- User never has to remind Claude about patterns

Instead of creating empty knowledge bases, Smart Init:
1. **Explores** the codebase to understand what exists
2. **Mines** conversation history for patterns and corrections
3. **Discusses** findings with the user to verify understanding
4. **Seeds** Oracle with confirmed, high-quality knowledge
5. **Sets up Context7** for current library documentation
6. **Creates MINIMAL claude.md** (not bloated)
7. **Explains autonomous behavior** so user knows what to expect

## Initialization Workflow

### Phase 1: Discovery (Automatic)

Run these analyses silently, then summarize findings:

#### 1.1 Codebase Analysis
```
- Primary languages (by file count and LOC)
- Frameworks detected (React, Django, Express, etc.)
- Project structure pattern (monorepo, microservices, standard)
- Build tools (npm, cargo, pip, etc.)
- Test framework (jest, pytest, etc.)
- Linting/formatting tools
```

#### 1.2 Documentation Analysis
```
- README.md presence and quality
- docs/ directory
- API documentation
- Contributing guidelines
- Existing claude.md content
```

#### 1.3 Configuration Detection
```
- package.json, Cargo.toml, pyproject.toml, etc.
- .eslintrc, prettier, rustfmt, etc.
- CI/CD configuration (.github/workflows, etc.)
- Docker/containerization
- Environment patterns (.env.example, etc.)
```

#### 1.4 History Mining (if available)
```
- Search ~/.claude/projects/ for this project
- Extract patterns, corrections, preferences
- Identify repeated tasks (automation candidates)
- Find gotchas from past issues
```

### Phase 2: Present Findings

After discovery, present a structured summary:

```markdown
## Project Understanding

**Project**: [name from package.json/Cargo.toml/etc]
**Type**: [web app / CLI / library / API / etc]
**Primary Stack**: [e.g., TypeScript + React + Node.js]

### Tech Stack Detected
- **Languages**: TypeScript (85%), JavaScript (10%), CSS (5%)
- **Frontend**: React 18.x with hooks
- **Backend**: Express.js
- **Database**: PostgreSQL (from prisma schema)
- **Testing**: Jest + React Testing Library
- **Build**: Vite

### Project Structure
```
src/
  components/    # React components
  api/           # Backend routes
  lib/           # Shared utilities
  types/         # TypeScript types
```

### Conventions Detected
- Using ESLint with Airbnb config
- Prettier for formatting
- Conventional commits (from git log)
- Feature branch workflow

### From Conversation History
- **Patterns found**: 3 (e.g., "use factory pattern for services")
- **Corrections found**: 2 (e.g., "prefer async/await over callbacks")
- **Gotchas found**: 1 (e.g., "database pool must be explicitly closed")

### Questions for You
1. Is this understanding correct?
2. Are there any critical gotchas I should know about?
3. What coding preferences should I remember?
4. Any patterns you want enforced?
```

### Phase 3: Interactive Refinement

Ask targeted questions based on gaps:

**If no README found:**
> "I don't see a README. Can you briefly describe what this project does?"

**If multiple possible architectures:**
> "I see both REST endpoints and GraphQL schemas. Which is the primary API style?"

**If no tests found:**
> "I didn't find test files. Is testing a priority, or should I not suggest tests?"

**Always ask:**
> "What are the top 3 things that have caused bugs or confusion in this project?"

> "Are there any 'tribal knowledge' items that aren't documented but are critical?"

### Phase 4: Seed Oracle Knowledge

Based on confirmed understanding, create initial Oracle entries:

#### Patterns (from discovery + user input)
```json
{
  "category": "pattern",
  "priority": "high",
  "title": "Use factory pattern for database connections",
  "content": "All database connections should use DatabaseFactory.create() to ensure proper pooling",
  "context": "Database operations",
  "tags": ["database", "architecture", "confirmed-by-user"],
  "learned_from": "smart-init-discovery"
}
```

#### Gotchas (from history + user input)
```json
{
  "category": "gotcha",
  "priority": "critical",
  "title": "Database pool must be explicitly closed",
  "content": "Connection pool doesn't auto-close. Always call pool.end() in cleanup.",
  "context": "Database shutdown",
  "tags": ["database", "critical", "confirmed-by-user"],
  "learned_from": "smart-init-conversation"
}
```

#### Preferences (from config + user input)
```json
{
  "category": "preference",
  "priority": "medium",
  "title": "Prefer async/await over callbacks",
  "content": "Team prefers modern async patterns. Avoid callback-style code.",
  "context": "All async code",
  "tags": ["style", "async", "team-preference"],
  "learned_from": "smart-init-discovery"
}
```

### Phase 5: Setup Verification

After seeding:

```markdown
## Initialization Complete

### Created
- `.oracle/` with [X] knowledge entries
- `.guardian/config.json` with project-appropriate thresholds
- Updated `claude.md` with project context

### Knowledge Base Seeded
| Category    | Entries | Source |
|-------------|---------|--------|
| Patterns    | 5       | Discovery + User |
| Preferences | 3       | Config + User |
| Gotchas     | 2       | History + User |
| Solutions   | 1       | History |

### How It Improves Over Time

1. **Corrections**: When you correct me, I record it in Oracle
2. **Guardian**: Reviews code and validates against patterns
3. **Sessions**: Record what worked and what didn't
4. **Analysis**: Weekly pattern detection finds automation opportunities

### Next Session
Oracle will automatically load:
- Critical gotchas (always)
- Relevant patterns (based on files you're working on)
- Recent corrections (to avoid repeats)

### Recommended Next Steps
1. Context7 should be installed for current library docs
2. Oracle will auto-query - no need to ask manually
3. When you correct me, I'll record it automatically
```

## Phase 6: Context7 Setup

Check if Context7 MCP is installed. If not, guide user:

```markdown
## Current Library Documentation

I noticed Context7 MCP isn't installed. This means I might use outdated library knowledge.

**To get current, version-specific documentation automatically:**

```bash
claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
```

After installation:
- I'll automatically fetch current docs when you mention libraries
- No more "Prisma 5" answers when you're on Prisma 7
- Combined with Oracle, you get: current docs + project-specific patterns
```

If already installed:
```markdown
## Context7 ✓

Context7 is installed. I'll automatically fetch current library docs.
- Generic docs: Context7 (current, version-specific)
- Project-specific: Oracle (your patterns, gotchas)
```

## Phase 7: Create MINIMAL claude.md

**DO NOT** dump everything into claude.md. Keep it under 50 lines.

```markdown
# [Project Name]

[One sentence description]

## Tech Stack
[2-3 lines max - just the key technologies]

## ClaudeShack Skills
oracle, guardian, summoner, wizard, style-master, documentation-wizard

## Critical Gotchas (Top 3-5 ONLY)
- [Most critical gotcha]
- [Second most critical]
- [Third most critical]

## How I Work
- I auto-query Oracle for project patterns
- I fetch current library docs via Context7
- I record corrections immediately
- You shouldn't need to remind me of things
```

**That's it.** Everything else lives in Oracle and is queried dynamically.

## Phase 8: Explain Autonomous Behavior

End the initialization by setting expectations:

```markdown
## What to Expect Going Forward

**I will automatically:**
- Check Oracle before making changes to files
- Fetch current library docs when you mention frameworks
- Record corrections the moment you give them
- Apply project patterns without being asked

**You should never need to:**
- Say "check Oracle" or "use context7"
- Remind me of corrections you've given before
- Explain the same gotcha twice
- Nudge me to be proactive

**If I forget something Oracle should know:**
Tell me once, I'll record it, and it won't happen again.

**The system improves over time:**
Every correction, every pattern, every gotcha compounds.
After a few sessions, I should "know" this project.
```

## Discovery Commands

Use these to gather information:

```bash
# Language breakdown
find . -type f -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rs" | head -100

# Package detection
ls package.json Cargo.toml pyproject.toml requirements.txt go.mod 2>/dev/null

# Framework detection
grep -l "react\|vue\|angular\|express\|fastapi\|django" package.json requirements.txt 2>/dev/null

# Test framework
ls -la **/*test* **/*spec* 2>/dev/null | head -20

# Git conventions
git log --oneline -20

# Existing documentation
ls README* CONTRIBUTING* docs/ 2>/dev/null
```

## Conversation Guidelines

### Be Curious, Not Assumptive
- "I noticed X - is that intentional?"
- "The config suggests Y - should I enforce this?"
- NOT: "I see you're using X so I'll assume Y"

### Validate Critical Items
- Always confirm gotchas before marking as critical
- Ask about edge cases
- Verify team preferences vs personal preferences

### Keep It Focused
- Don't ask 20 questions
- Group related questions
- Prioritize: gotchas > patterns > preferences

### Record Sources
Every Oracle entry should have `learned_from`:
- `smart-init-discovery` - Found in code/config
- `smart-init-history` - From conversation history
- `smart-init-user` - Directly from user
- `smart-init-confirmed` - Discovered + user confirmed

## Anti-Patterns

### DON'T
- Create empty knowledge files and call it "initialized"
- Make assumptions without verification
- Skip the conversation phase
- Overwhelm with questions
- Seed low-confidence knowledge as high priority

### DO
- Actually explore the codebase
- Mine real history for real patterns
- Have a genuine conversation
- Seed only verified, valuable knowledge
- Explain how the system learns

## Integration with Other Skills

After Smart Init:
- **Oracle**: Has seeded knowledge to work with
- **Guardian**: Has calibrated thresholds for the project
- **Wizard**: Can reference accurate project understanding
- **Summoner**: Knows project constraints for orchestration

## Example Session

```
User: "Initialize ClaudeShack for this project"

Smart Init:
1. [Runs discovery - 30 seconds]
2. "I've analyzed your project. Here's what I found..."
3. [Presents findings summary]
4. "A few questions to make sure I understand correctly..."
5. [Asks 3-5 targeted questions]
6. [User responds]
7. "Great, let me set up Oracle with this understanding..."
8. [Seeds knowledge base]
9. "All set! Here's what I created and how it will improve..."
```

---

**"Understanding first. Setup second. Learning forever."**