initializer

name	initializer
description	Load when a project's dreamcontext brain is missing or sparse and needs to be bootstrapped from real material — or the user invokes `/initializer`. Triggers: "initialize my brain", "set up dreamcontext from my docs", "ingest my notes / wiki / Obsidian / Notion export", "there's no _dream_context yet", "bootstrap the context from this folder", or any time you detect no/empty `_dream_context/` and the user has existing project material to ingest. This is the interactive, sub-agent-driven bootstrap — it migrates whatever the user has into the proper knowledge / feature / task hierarchy. It is the single bootstrap surface for dreamcontext; it also handles codebase-only repos (a light scout + ingest pass) and scales down to a trivial scaffold when there's nothing to ingest.
user-invocable	true
alwaysApply	false
tags	["initializer","bootstrap","onboarding","ingestion","orchestration","sub-agents","dreamcontext"]

Initializer — interactive, sub-agent-driven brain bootstrap

You are the orchestrator. Like goal-skill, multi-review, and council, you do not hand-author the bulk of the corpus yourself — you dispatch sub-agents, read their results, gate the transitions, and drive convergence loops until the brain is genuinely initialized. Your value is judgment at the gates and the conversation with the user about their desired structure — not typing every knowledge file by hand.

A brain is initialized when the verifier passes against the corpus: real content across soul/user/memory + tech-stack + data-structures, the user's material ingested into the hierarchy they confirmed, candidate features and people seeded, knowledge distilled (not dumped), bookmarks laid for the first sleep — and zero template placeholders. Not when dreamcontext init finished. That's just the empty shell.

When to invoke

• /initializer (primary entry).
• You detect no _dream_context/, or a sparse one (only template stubs, empty knowledge/, zero features) — and there is material worth ingesting.
• "Initialize my brain", "set up dreamcontext from my docs/wiki/export", "ingest this folder".

The interactive trigger you must not miss: when you notice the brain is missing or sparse, do not silently scaffold and move on, and do not wait to be asked. Offer:

"I don't have a brain for this project yet — there's no/just-an-empty _dream_context/. I can initialize it properly. Point me at whatever you already have — a docs folder, an Obsidian/Notion export, ADRs, design notes, an old wiki or spec dump — and I'll ingest it into structured memory (knowledge, features, tasks) in the hierarchy you want. Or I can bootstrap from just the codebase. Which?"

Scale the machinery to the material. A tiny repo with nothing to ingest does not need the full scout → confirm → fan-out → verify dance. Say so and run the light path: a single initializer-scout over the codebase + one initializer-ingestor to fill from it (skip the Phase 3 confirmation when there's no hierarchy to negotiate), then a quick verify. Reserve the full orchestration for real material the user wants ingested richly.

Commitment ritual (do this FIRST — non-negotiable)

1. Announce: tell the user you're running the initializer orchestration and what it does.
2. TodoWrite the phases (0–7) as items. A phase isn't done until its gate passes.
3. Track iteration counts in the todo text for each convergence loop, e.g. Phase 4: progressive ingest (batch 3/7), Phase 6: verify (iteration 2/3).

Skipping the ritual is the first step toward scaffolding an empty shell and calling it done.

Orchestration flow

flowchart TD
    P0[Phase 0 — RECOGNIZE & OFFER: detect missing/sparse brain, offer to ingest, ask where the material is + identity Qs] --> P1[Phase 1 — SCAFFOLD: dreamcontext init, detect multi-product]
    P1 --> P2[Phase 2 — SCOUT: dispatch initializer-scout over codebase + each source root -> ingestion manifest]
    P2 --> P3{Phase 3 — CONFIRM THE MAP: show proposed hierarchy, user adjusts -> agreed?}
    P3 -->|user revises| P2
    P3 -->|agreed| P4[Phase 4 — PROGRESSIVE INGEST: fan out initializer-ingestor per batch; track coverage]
    P4 --> P5[Phase 5 — CORE FILES + WARM-UP: soul/user/memory/tech-stack/data-structures, people, taxonomy, bookmarks]
    P5 --> P6{Phase 6 — VERIFY: initializer-verifier — PASS?}
    P6 -->|FAIL and iter < 3| P4
    P6 -->|cap reached| ESC[ESCALATE to user with the unresolved gaps]
    P6 -->|PASS| P7[Phase 7 — REPORT: summary + honest 'to be defined' list + offer first sleep]

Phase 0 — RECOGNIZE & OFFER (interactive — ask, then wait)

1. Confirm the brain is missing/sparse (ls _dream_context/; if present, check for empty knowledge/, zero knowledge/features/, untouched template stubs).
2. Make the offer above. Then ask only what you can't detect (3–6 questions max):
   • Where is your material? Absolute paths to folders/files to ingest (docs, exports, wiki, ADRs, specs, notes). "None — codebase only" is a valid answer.
   • What is this project, in one sentence? (skip if README is clear)
   • Who uses it? (skip if obvious)
   • What matters most right now? (current priority)
   • Any rules for how I should work / hard constraints? Wait for the answers. Capture them in TodoWrite — they feed Phases 2, 5, and the verifier.

Phase 1 — SCAFFOLD

Create the structure. Detect multi-product first (monorepo with clearly separable products → pass --multi-product "web,ios,api", lowercase kebab-case):

dreamcontext init --yes --name "<detected>" --description "<detected>" --stack "<detected>" --priority "<from Phase 0>"

If _dream_context/ already exists but is sparse, do not clobber — skip init, work with what's there, and treat the gaps as the ingestion target.

Phase 2 — SCOUT (sub-agent fan-out → ingestion manifest)

Dispatch initializer-scout (read-only). For a single source root, one scout. For several large source roots, fan out one scout per root in parallel (single message, multiple Agent calls) — each blind to the others; you merge their manifests.

Give each scout: the codebase root, the source path(s) it owns, and the Phase 0 answers. It returns a structured ingestion manifest — every source artifact categorized and mapped to a target:

Target type	What lands there
knowledge/<context>/<slug>.md	research, decisions, rationale, domain/technical deep context
knowledge/data-structures/<product>.md	real schemas (Prisma/SQL/ORM) — actual tables/fields
knowledge/features/<name>.md	product capabilities (what a feature is, typed knowledge type: feature) — candidate PRDs
state/<task>.md	open/in-flight work, TODOs, roadmap items
people roster	distinct git authors (git shortlog -sne)
taxonomy domain:<x>	recurring project nouns
bookmark	salient moments worth tagging for the first sleep

The scout also proposes a folder hierarchy for knowledge/ (context subfolders) and dedups against anything already present. A manifest that says "ingest the docs" without naming source→target per artifact is rejected — send it back.

Phase 3 — CONFIRM THE MAP (interactive gate — the user owns the shape)

Show the user the proposed hierarchy and mapping: knowledge contexts/folders, candidate features, tasks, people, taxonomy. This is where the user's desired structure wins — they rename contexts, merge/split folders, drop noise, promote/demote features. Iterate Phase 2 ↔ 3 until the user agrees. Do not start writing until the map is confirmed; a wrong hierarchy is expensive to unwind once files exist.

If running fully autonomously with no user, adopt the scout's proposal, record that you chose it, and surface it in the Phase 7 report for confirmation.

Phase 4 — PROGRESSIVE INGEST (sub-agent fan-out — the core)

Dispatch initializer-ingestor workers over the confirmed manifest, one batch per context / product / feature-cluster so each fits comfortably in one agent's context. Use parallel for independent batches, or pipeline when later batches reference earlier ones. Each ingestor:

• Distills, never dumps — summarizes durable decisions/structure; links back to the source path in the body. A few high-signal knowledge files beat copying every markdown verbatim.
• Writes into the confirmed hierarchy (knowledge/<context>/…), creates candidate features (--status planning), seeds tasks for open work, captures real schemas.
• Uses the CLI, never hand-edits JSON (knowledge create, features create, tasks create, taxonomy add).
• Bookmarks salient moments (bookmark add … -s <1|2|3>) so the first sleep has ripples to process.

Track coverage in TodoWrite (batch N/M). Loop until every manifest entry is ingested or consciously dropped. Nothing is silently skipped — if you cap out (3 passes) with entries still unprocessed, ESCALATE with the list. Re-dispatch failed batches; don't drop them.

Phase 5 — CORE FILES + WARM-UP

Populate the always-loaded core from the gathered intelligence (you or a final ingestor pass):

• 0.soul.md — identity, target user, current priority, principles (from codebase patterns
  • user), constraints, agent behaviors/rules, non-negotiables.
• 1.user.md — preferences, communication style, project details/rules, workflow notes.
• 2.memory.md — Technical Decisions + Known Issues only (no LIFO ship-narrative — that lives in CHANGELOG via dreamcontext memory remember).
• 4.tech_stack.md — detected frameworks and their conventions + infra, not a flat dep dump.
• People (dreamcontext config people "A" "B") when >1 distinct human git author.
• Taxonomy (dreamcontext taxonomy add domain:<concept>) for recurring nouns.
• Optional planning version if there's a clear near-term focus (dreamcontext core releases add …).

Phase 6 — VERIFY (the real gate)

Dispatch initializer-verifier (read-only + Bash). It returns PASS | FAIL with evidence: no template placeholders in shipped core files, dreamcontext doctor clean, dreamcontext memory recall "<seed query>" returns real hits, knowledge index built, no feature/knowledge duplication of the same topic, hierarchy sane.

• FAIL → route back to Phase 4/5, fix the specific gaps, re-verify. Cap = 3 → ESCALATE.
• PASS → the brain is initialized.

Phase 7 — REPORT

Summarize: what was created/populated and how confidently; features/people/knowledge/tasks seeded; the honest "to be defined: <what's missing and who can provide it>" list; then offer the first sleep so the fresh corpus is consolidated and the index/staleness are warm.

Convergence rules (how the loops end)

• Every loop has a hard iteration cap of 3. Hitting it means ESCALATE to the user — never "good enough, ship the shell".
• Update the TodoWrite count before each loop-back. Past the cap → stop and escalate with specifics.
• "Initialized" is defined by Phase 6 PASS — not by init finishing or the shell looking populated.

Red Flags — STOP, you're about to ship an empty shell

Thought	Reality
"No _dream_context/ — I'll just run init and continue."	init is the empty shell. The offer + ingestion is the point. Run the orchestration.
"The user didn't mention docs, so there's nothing to ingest."	You didn't ask. Phase 0's offer is mandatory — ask where their material is.
"I'll author all the knowledge files myself."	The orchestrator dispatches ingestors. Hand-authoring one or two is fine; the corpus is fan-out work.
"I'll pick the folder structure; it's obvious."	The hierarchy is the user's call (Phase 3). Propose, then let them shape it.
"I'll dump each source doc verbatim into a knowledge file."	Distill, don't dump. Verbatim dumps pollute recall.
"Some source files didn't get ingested, but most did."	Nothing is silently dropped. Track coverage; re-dispatch or escalate the remainder.
"It's a feature AND a knowledge file — I'll create both."	One home per topic. Feature OR knowledge, never both (verifier fails this).
"Looks populated, I'll report done."	Done = Phase 6 verifier PASS with evidence. Placeholders or a failing doctor = not done.

Rationalization table

If you think…	The truth is…	So…
"Asking where their material is slows things down."	Skipping it means re-deriving from the codebase what they already wrote down.	Make the offer; ingest what exists.
"The scout's hierarchy is fine, skip the user."	The user's mental model of their project beats your inference.	Confirm the map in Phase 3.
"Fan-out is overhead; one big pass is simpler."	One context can't hold a large corpus; it drops or blurs material.	Batch by context/product and fan out ingestors.
"Verifier will rubber-stamp."	A mis-prompted verifier rubber-stamps. Give it the checklist and demand evidence.	Treat FAIL as binding; loop or escalate.

Hard rules

• Orchestrator drives sub-agents. Scout (intake) → ingestor (fan-out write) → verifier (gate). You gate; you don't hand-write the whole corpus.
• Phase 0's offer is non-negotiable. When the brain is missing/sparse, proactively offer to ingest the user's material — don't wait to be asked, don't silently scaffold.
• The user owns the hierarchy (Phase 3). Propose; let them shape it before any files are written.
• Distill, don't dump. Knowledge files summarize; they link back to sources.
• One home per topic. Feature or knowledge, never both. Recall before create; update over duplicate.
• CLI, never hand-edit JSON — features/people/taxonomy/releases/tasks all via dreamcontext.
• No placeholders ship. Phase 6 verifier proves it; unreplaced {{TOKEN}} or "(add your…)" prose = FAIL.
• Nothing silently dropped. Track ingestion coverage; re-dispatch or escalate the remainder.
• Caps are hard (3 per loop). At the cap, escalate — never declare initialized.
• Use the dreamcontext skill throughout — schema, conventions, and the CLI surface come from it.

Relationship to other surfaces

Surface	Stage	Relationship
initializer (this)	First-run / re-init / enrichment	The single bootstrap surface — owns scaffold + progressive ingestion, from codebase-only to a full material import.
initializer-scout / -ingestor / -verifier	This skill's workers	Intake (manifest) → fan-out write → PASS/FAIL gate. Dispatched at Phases 2 / 4 / 6.
goal-skill	End-to-end build of a goal	The pattern this skill mirrors (plan→review→implement→validate ≈ scout→confirm→ingest→verify). Use after init for feature work.
Sleep / consolidation	Post-init	Phase 7 offers the first sleep so the new corpus is consolidated and the index warms.

Slash command wiring

/initializer invokes this skill. The natural-language triggers in When to invoke also load it. (Named initializer, not init, to avoid colliding with the built-in /init CLAUDE.md generator and the dreamcontext init CLI scaffold.)