initial-setup

---
name: initial-setup
description: "Welcome and onboard new EvoNexus users — introduce agents, skills, routines, and the dashboard. Triggers when the user says 'get started', 'how do I use this', 'what can you do', 'help me get started', 'onboarding', 'show me around', 'what agents do I have', 'how does this work', 'first time here', or seems unfamiliar with the workspace. Also trigger when the user opens Claude Code in an EvoNexus workspace for the first time."
---

# EvoNexus — Welcome & Onboarding

The user already has EvoNexus installed and running. Your job is to welcome them, show what's available, and help them start using agents, skills, and routines right away.

## Step 0: Bootstrap Workspace Structure (dynamic)

Before welcoming, ensure the `workspace/` folder tree exists. The workspace is gitignored (personal data) so new installations start empty — you need to discover which agents are installed and create folders based on **what each agent declares in its own system prompt**, not a hardcoded list. This keeps the skill self-updating: when new agents are added (business, engineering, or custom), their folders are created automatically the next time this runs.

### Discovery phase

1. **Read `config/workspace.yaml`** to get `workspace.owner`, `workspace.company`, `workspace.language`, `workspace.timezone`, `workspace.name`. These values drive language and personalization.

2. **List all installed agents** with `Glob .claude/agents/*.md`. This captures:
   - Business layer agents (`clawdia-assistant.md`, `flux-finance.md`, etc.)
   - Engineering layer agents (`apex-architect.md`, `bolt-executor.md`, etc.) as they get imported
   - Custom agents (`custom-*.md`) the user created

3. **For each agent file**, Read it and extract:
   - **Name** from the frontmatter (`name: ...`)
   - **Color** from the frontmatter (`color: ...`) — used for future dashboard integration
   - **Domain / role** from the `description:` frontmatter field or the first prose paragraph
   - **Working folder** — look for the `## Working Folder` section and parse the first sentence for `workspace/{folder}/`. If the agent has no `## Working Folder` section (e.g., pure orchestrators like Clawdia, knowledge agents like Oracle), record it as "no dedicated folder" and skip folder creation for that agent.
   - **Subfolders** — if the Working Folder description or the agent's prose mentions specific subfolders (e.g., `strategy/analyses/`, `project/github-reviews/`), extract them too.
   - **Anti-patterns / approval rules** — scan sections like `## Anti-patterns`, `## Absolute Rules`, `## Your Level`, `### REQUIRES user approval` to extract the 1-2 most important conventions.

4. **Build an in-memory table** of `{agent, folder, subfolders, domain, conventions}`. This is the source of truth for Step 1.

### Creation phase

5. **Check if the structure already exists.** Run a quick check: if **every** folder in the discovered table already exists on disk, structure is already bootstrapped — skip creation and proceed to the "Customizations" summary below. Otherwise, continue.

6. **Create folders.** For each entry in the table that declares a Working Folder:
   - Create `workspace/{folder}/` if missing
   - Create any declared subfolders
   - Create `.gitkeep` in the top-level folder (subfolders don't need it — the wildcard in `.gitignore` handles them)
   - **Never overwrite** existing folders or files

7. **Create the shared read-only folder** `workspace/projects/` (plural) if missing — this is where the user uploads git repositories that every agent can read. Also add a `.gitkeep`.

8. **Create operational folders** that are not owned by any single agent but are referenced by routines:
   - `workspace/daily-logs/` — written by clawdia and by the morning/eod routines
   - `workspace/meetings/` — managed by `int-sync-meetings` routine (Fathom)

   Only create these if they're referenced by at least one installed routine or agent; skip if the underlying agent/routine is not installed.

### Overview files phase

9. **Read `workspace.language`** from `config/workspace.yaml`. All overview files respect this value:
   - Filename and content are translated to `workspace.language` (e.g., `pt-BR` → `[C] Visão Geral — Financeiro.md`; `en` → `[C] Overview — Finance.md`; `es` → `[C] Visión General — Finanzas.md`)
   - If `workspace.language` is not set, default to `en`
   - This is the only place where the codebase writes localized filenames, because these files land in `workspace/` (gitignored, personal)

10. **For each folder** you created in Step 6, write an overview file using this canonical template (translate title, headings, and bullets to the target language before writing):

    ```markdown
    # Overview — {Sector}

    Working folder for agent **@{agent-name}** ({agent domain extracted from the agent file}).

    ## What goes here

    {Extract 3-6 bullets from the agent's Working Folder description and Responsibilities section}

    ## Conventions

    - Files created by the agent are prefixed with `[C]`
    - {1-2 agent-specific rules extracted from Anti-patterns / Absolute Rules / Your Level}
    ```

    **Never overwrite** an existing overview — if one already exists in any language, skip it (the user may have customized it).

### Customizations summary phase

11. **Scan agent improvement notes.** For each agent, check if `.claude/agent-memory/{agent-name}/_improvements.md` exists. If yes, read the first few lines and remember them for the summary.

12. **Scan agent memory folders** for customizations the user has saved (e.g., feedback memories, project memories). Count how many entries each agent has in its `MEMORY.md` index.

13. **Report customizations to the user.** After the welcome, include a "Your workspace customizations" section that surfaces:
    - Which agents have pending `_improvements.md` notes (and the first line of each)
    - Which agents have non-empty `MEMORY.md` indexes (count of entries) — this tells the user where they've already built up context
    - Any `custom-*` agents the user has created
    - Any new folders the user added to `workspace/` that don't match an installed agent

    This makes onboarding dynamic: instead of a generic tour, the user sees **their** workspace state and what's already been tailored.

### Important rules

- **Never overwrite** existing files or folders — the user may already have content
- **Discovery drives creation** — never hardcode folder names; always parse from the agent files. If a new agent is added, it will be picked up automatically.
- **`projects/` (plural)** is shared read-access for all agents; the user uploads git repos there
- **Engineering agents** (dev layer from oh-my-claudecode) typically don't declare a `## Working Folder` because they work across the codebase itself — skip folder creation for them
- **`personal/`** may contain a health dashboard setup (`docker-compose.yml`, `health-data.js`) — don't touch if it exists
- **`meetings/`** is managed by the sync-meetings routine — no overview file (has its own `README.md`)
- **Speed:** the discovery phase reads ~30 small markdown files; keep it fast by only reading the top ~40 lines of each agent unless you need deeper inspection

After bootstrap is done (or confirmed already existing), proceed to Welcome.

## Welcome

Start with a warm, **dynamic** welcome that uses the counts you discovered in Step 0. Do not hardcode agent or skill numbers — read them from the filesystem so the message stays accurate as the workspace grows.

Counts to compute at runtime:
- **Agents:** `Glob .claude/agents/*.md` and count entries (exclude `custom-*.md` or report them separately)
- **Skills:** `Glob .claude/skills/*/SKILL.md` and count entries
- **Routines:** count entries in `config/routines.yaml` (or `ROUTINES.md` if yaml doesn't exist)
- **Custom extensions:** count `.claude/agents/custom-*.md`, `.claude/skills/custom-*/SKILL.md`, `.claude/commands/custom-*.md`

Welcome text (template, translate to `workspace.language`):

> Welcome to **{workspace.name}** — your AI-powered operating system, {workspace.owner}. You have **{N} agents**, **{N} skills**, and **{N} automated routines** ready to go. Let me show you what you can do.

## Your Agents

Present the agents in a **dynamic table** built from Step 0's discovery table. Group them by layer:

1. **Business layer** — agents whose file name matches the canonical business names (clawdia, flux, atlas, pulse, pixel, sage, nex, mentor, kai, oracle, mako, aria, zara, lex, nova, dex) or whose description mentions a business domain
2. **Engineering layer** — agents whose file name starts with a known dev role (apex, bolt, compass, echo, flow, grid, hawk, lens, oath, prism, probe, quill, raven, scout, scroll, trail, vault, zen, canvas) — these come from oh-my-claudecode
3. **Custom layer** — any agent whose filename starts with `custom-`

For each layer, build a table dynamically by reading each agent file and extracting command, name, and one-line role:

| Command | Agent | Role | Try saying... |
|---------|-------|------|---------------|
| `/{command}` | **{Name}** | {role from description frontmatter} | {first example from description} |

**Do not hardcode the table.** Build it from the files on disk so new agents (including engineering imports and custom ones) appear automatically.

After the agents table, add:

> You don't have to use slash commands — just describe what you need and I'll route to the right agent automatically.

## Quick Wins to Try Right Now

Suggest 3 things the user can try immediately based on what's most useful:

### 1. Morning Briefing
"Say **'good morning'** and the Ops agent will check your calendar, emails, tasks, and give you a prioritized plan for the day."

### 2. Dashboard Overview
"Open **http://localhost:8080** to see the web dashboard — overview metrics, reports, services, and even a Claude Code terminal in the browser."

### 3. Run a Routine
"Try running a routine manually:
- `make morning` — morning briefing
- `make community` — community pulse report
- `make fin-pulse` — financial snapshot

Each routine generates an HTML report you can view in the dashboard under Reports."

## Skills by Domain

Compute skill categories **dynamically** from the filesystem:

1. `Glob .claude/skills/*/SKILL.md` → list of installed skills
2. Group by prefix (the part before the first `-`): `fin-`, `social-`, `dev-`, `int-`, `mkt-`, etc.
3. Count entries per prefix
4. For each prefix, pull 2-3 representative examples by reading the `name:` frontmatter of the first few skills in that group

Present as a table:

> You have **{total}** skills organized by prefix. Here are the categories installed in your workspace:

| Prefix | Count | Examples |
|--------|-------|----------|
| `{prefix}-` | {N} | {skill1, skill2, skill3} |
| ... | ... | ... |

**Do not hardcode the prefix list.** Different installations may have different layers enabled — the business layer (`fin-`, `social-`, `mkt-`, `hr-`, `legal-`, etc.), the engineering layer (`dev-`), and any custom prefixes the user introduced. Build the table from what's actually installed.

After the table:

> Browse all skills in the dashboard under **Skills**, or just ask me to do something and I'll use the right skill.

## Automated Routines

Read `config/routines.yaml` at runtime to list the actual routines installed in this workspace. Group them by frequency (daily / weekly / monthly) based on the cron schedule or `frequency:` field, and list the first handful per group.

Present as:

> EvoNexus can run routines automatically on a schedule. You have **{N} routines** installed:
>
> **Daily:** {list top 5-6 by name}
> **Weekly:** {list}
> **Monthly:** {list}
>
> Start the scheduler with `make scheduler` and routines run at their configured times. See the full list with `make help`.

If `config/routines.yaml` is missing or empty, say so and point the user to `create-routine` skill to set up their first one.

## The Web Dashboard

"Your dashboard at **http://localhost:8080** has:

- **Overview** — all metrics at a glance
- **Chat** — Claude Code terminal in the browser
- **Reports** — HTML reports from routines
- **Systems** — register and manage your apps
- **Services** — start/stop scheduler, see live logs
- **Routines** — metrics per routine + manual run button
- **Integrations** — connect YouTube, Instagram, LinkedIn via OAuth
- **Users & Roles** — manage access with custom permissions"

## Your Workspace Customizations

After the welcome tour, surface what's already been tailored in this specific workspace — this turns a generic onboarding into a personalized status check. Gather:

1. **Agent improvement notes** — for each agent folder in `.claude/agent-memory/`, check if `_improvements.md` exists. If yes, read the first line and list it. Example output:
   > - **@flux** has 2 pending improvement ideas: "Add cash flow forecast chart…"
   > - **@sage** has 1 pending improvement idea: "Link OKR review to Linear cycles…"

2. **Agent memory depth** — for each `.claude/agent-memory/{agent}/MEMORY.md`, count the index entries. Report agents with accumulated context:
   > - **@clawdia** has built up 14 memories (feedback, project context, references)
   > - **@aria** has 3 memories

3. **Shared knowledge base** — check `memory/index.md`. Report how many people profiles, projects, glossary entries, and trends are populated:
   > - **Shared memory:** 6 people profiles, 2 project histories, 42 glossary terms, 15 weekly trend snapshots

4. **Custom agents, skills, and commands** — list anything under `.claude/agents/custom-*`, `.claude/skills/custom-*`, `.claude/commands/custom-*`. These are workspace-specific extensions the user created.

5. **Orphaned folders** — list any directories in `workspace/` that do **not** match a declared agent working folder. These may be legacy or manual organization and deserve a heads-up:
   > - `workspace/meetings/` — managed by the sync-meetings routine (not owned by any agent, this is expected)
   > - `workspace/{unknown}/` — not matched to any agent, you may want to review

6. **Config status** — check `config/workspace.yaml` values. If `owner`, `company`, `language`, or `timezone` are missing/default, flag them as "needs configuration".

Present all of this as a concise summary under a heading like:

> ## Your workspace so far
>
> Here's what's already been customized in **{workspace.name}**:
> - {bulleted list from items 1-6 above}
>
> This tells you where you've invested setup time. Agents with pending `_improvements.md` notes are great targets for your next session — open the file with your agent and clear the backlog.

## What to Do Next

Based on what you discovered in the customizations phase, suggest **personalized** next steps — don't hardcode suggestions:

- If the user has populated `memory/people/` but not `memory/projects/` → suggest updating project context
- If any agent has `_improvements.md` → suggest tackling it
- If no routines are scheduled → suggest running a morning briefing manually
- If the user has `custom-*` agents → suggest trying one of them
- Default: suggest "good morning" to `@clawdia` (if installed) for the daily briefing

End with:

> Just tell me what you're working on and I'll route you to the right agent.

## Tone

- Enthusiastic but not overwhelming — show value quickly
- Let the user explore at their own pace
- Suggest concrete actions, not abstract descriptions
- If they seem experienced, be concise; if new, be more detailed
- Always end with an invitation to try something: "Want to try one of these now?"