Initialize a new project from a rough idea. Deep interrogation, optional domain research, and a roadmap if needed — writes durable context to .context/ that every future session and skill reads from. One-time, whole-project setup — not for individual features within an already-initialized project.
Initialize a new project from a rough idea. Deep interrogation, optional domain research, and a roadmap if needed — writes durable context to .context/ that every future session and skill reads from. One-time, whole-project setup — not for individual features within an already-initialized project.
disable-model-invocation
true
allowed-tools
Read, Write, Bash, Agent, AskUserQuestion
<runtime_note>
This skill is explicit-invocation only (/init-project). It never auto-triggers — disable-model-invocation: true in the frontmatter enforces that. This is deliberate: initialization is a one-time, deliberate action, not something that should fire on an ambiguous "I have an idea for..." remark.
</runtime_note>
Turn a rough, messy idea into a well-interrogated, optionally-researched, structured project foundation that any future Claude session — with zero prior context — can read and build on correctly.
Creates:
.context/OVERVIEW.md — always
.context/research/ — only if research is accepted
.context/ROADMAP.md — only if the project actually needs phases
.context/DECISIONS.md — always (may be a thin seed if nothing beyond scope was decided)
.context/STATE.md — always
After this command: the project has a durable foundation. Whatever handles individual features or phases later reads .context/ — that is a separate, recurring process, not this skill's job.
<execution_context>
This skill directory bundles:
references/questioning.md — interrogation philosophy and technique (includes the scope check)
references/spec-review.md — the fresh-context self-review step
Subagents used (defined in ~/.claude/agents/): context-researcher, context-research-synthesizer, context-roadmapper.
</execution_context>
1. Setup Check
if [ -f .context/OVERVIEW.md ]; thenecho"ALREADY_INITIALIZED"fi
If already initialized: tell the user .context/OVERVIEW.md already exists, and stop. Don't overwrite silently. If they want to start over, that's their call to make explicitly (delete the directory themselves), not this skill's to infer.
2. Deep Questioning
Follow references/questioning.md in full — the philosophy, the freeform rule, the scope check, and the decision gate. This is the highest-leverage part of the whole flow; don't rush it.
Open with, inline and freeform (NOT AskUserQuestion): "What do you want to build?"
Follow the thread from there. Loop until the reference file's decision gate is accepted.
3. Write OVERVIEW.md
Synthesize the conversation into .context/OVERVIEW.md using templates/overview.md. Do not compress — capture what was actually said, in the user's language.
mkdir -p .context
4. Offer Research
Use AskUserQuestion:
header: "Research"
question: "Research the domain before writing the roadmap?"
options:
"Yes" — Investigate stack, features, architecture, and pitfalls
"No" — Skip — I know this domain well enough
If "Yes":
Tell the user this runs in the background and takes a few minutes: "Spawning 4 researchers in parallel — no output until they return."
Spawn 4 context-researcher agents in parallel, one per dimension, each with the project domain, project context from OVERVIEW.md, and its assigned dimension + question:
Stack — "What's the standard, current stack for this kind of project?"
Features — "What do products/projects like this typically include? Table stakes vs. differentiators vs. anti-features?"
Architecture — "How are these typically structured? Major components and boundaries?"
Pitfalls — "What do people commonly get wrong building this kind of thing?"
After all 4 complete, spawn one context-research-synthesizer to read all 4 files and write .context/research/SUMMARY.md.
Present the key findings from SUMMARY.md briefly before continuing.
If "No": skip to Step 5. No .context/research/ directory is created.
5. Roadmap Decision
Spawn one context-roadmapper agent with .context/OVERVIEW.md and .context/research/SUMMARY.md (if it exists).
If it returns NO ROADMAP NEEDED: tell the user why in one line, and continue — no .context/ROADMAP.md is created. This is a valid, expected outcome for simple projects, not a fallback.
If it returns ROADMAP CREATED: continue to Step 6.
6. Present the Roadmap
Present it in sections scaled to complexity, not as one wall of text — introduce the overview, then walk through phases in digestible groups, checking in as you go rather than dumping the whole file and asking "does this look right?" once at the end.
Use AskUserQuestion after presenting:
header: "Roadmap"
question: "Does this phase structure work?"
options:
"Yes, looks right" — Continue
"Adjust" — Tell me what to change
If "Adjust": get their notes, re-spawn context-roadmapper with the revision context, present again. Loop until accepted.
7. Write DECISIONS.md and STATE.md
Using templates/decisions.md: seed with whatever decisions actually came up during questioning (technical preferences stated unprompted, explicit exclusions with reasoning). An empty or near-empty seed is fine and correct if nothing beyond scope was actually decided.
Using templates/state.md: write Current Position and Next Action. Next Action should name Phase 1 if a roadmap exists, or the core value from OVERVIEW.md if it doesn't.
8. Spec Self-Review
Follow references/spec-review.md. Dispatch the fresh-context reviewer, handle its return (fix inline if issues found — don't re-run the whole writing step for minor fixes).
9. Done
If the project is a git repository, commit the new context once before
presenting the summary: git add .context && git commit -m "chore(context): initialize project context".
