# Init Workspace > Use when a project has no recorded intelligence-layer location yet and the user wants to get started, set up the knowledge graph, bootstrap this plugin, or begin planning/design/implementation work for the first time in this project. Also use when asked to "initialize the workspace," "set up the knowledge graph," or when a SessionStart nudge reports that no intelligence-layer location is recorded for this project. - Skill: `bhangeef16/init-workspace` (Agent Skill) - Install (CLI): `npx skillmds@latest add bhangeef16/init-workspace` - Raw SKILL.md: https://api.skillmd.com/api/skills/bhangeef16/init-workspace/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: BhangeeF16 (https://skillmd.com/u/bhangeef16) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bhangeef16/init-workspace --- # Init Workspace This skill runs the one-time setup that lets every other skill in this plugin know where this project's run workspaces and its graph-native knowledge layer live. It is topology-agnostic: it makes no assumption about any particular repository layout, alias set, or folder name beyond `.kaizen` itself. ## When this skill has already run Before doing anything else, check whether `.kaizen/workspace.map.yaml` exists in the current project (relative to the project root — the directory Claude Code was started in, or the nearest parent that looks like the project root if unclear). If it already exists, read it and report the recorded `intelligence-layer` and `knowledge-graph` paths back to the user in one line — do not ask the onboarding questions again or recreate anything. If `.kaizen/workspace.map.yaml` does not exist, but `.agent/workspace.map.yaml` does, go to Migration below instead of the first-run flow. ## Migration from `.agent/` If this project already ran the old, pre-`.kaizen` version of this skill, `.agent/workspace.map.yaml` will exist. Never migrate silently and never delete `.agent/`. Instead: 1. Tell the user plainly that this project has an existing `.agent/` intelligence layer, and offer to migrate it to `.kaizen/` — do not perform the copy until they say yes. 2. If they decline, stop here and continue using `.agent/workspace.map.yaml` as-is for this session (report its recorded `product-knowledge` path); do not proceed to the first-run flow. 3. If they accept, copy the full contents of `.agent/` into `.kaizen/`, leaving the original `.agent/` directory untouched on disk. Do not overwrite anything that already exists at the `.kaizen/` destination. 4. Ask the knowledge-graph question (step 2 of the first-run flow below) fresh — the old `.agent/workspace.map.yaml` only ever recorded a single `product-knowledge` path in the old six-folder, non-graph format, which is not itself a graph and is not converted automatically. Note this plainly to the user: the old `product-knowledge` content still exists at its old path, untouched, and moving its contents into graph nodes (via `kaizen graph new`) is a separate, later exercise, not something this migration step does for them. 5. Write `.kaizen/workspace.map.yaml` per step 5 of the first-run flow below, then continue at step 6 (graph scaffold) of that flow. 6. Report back: what was copied, the old `.agent/` path (still present, untouched), and the new `.kaizen/workspace.map.yaml` location. ## First-run flow If neither `.kaizen/workspace.map.yaml` nor `.agent/workspace.map.yaml` exists: 1. Ask the user directly, as a required question (do not guess or default silently): "Where would you like the intelligence layer (run workspaces) to live?" Accept a relative or absolute path. Offer `./.kaizen` as the default, but let the user override it. 2. Ask a second, independent required question: "Where would you like the knowledge graph to live?" Offer `/graph` as the default, but let the user override it — including pointing it at a path outside the intelligence-layer directory entirely, or in a separate git repository. This is deliberately a second question, not derived silently from the first: a deploying project's own durable knowledge often already lives in its own separate repository, independent of where run-workspace scratch state lives. 3. Resolve both answers to absolute paths. 4. Create the intelligence-layer directory if it does not already exist. Never overwrite anything already present in it. 5. Write (or create, if the directory does not yet exist) `.kaizen/workspace.map.yaml` in the project root with both resolved paths, for example: ```yaml intelligence-layer: /absolute/path/to/.kaizen knowledge-graph: /absolute/path/to/.kaizen/graph ``` `.kaizen/workspace.map.yaml` is always the fixed, discoverable anchor for this project — even when the resolved `knowledge-graph` path (or the resolved `intelligence-layer` path itself) points somewhere else entirely, this map file itself always lives at that one project-root-relative location so other skills never have to guess where to look first. 6. Scaffold the knowledge graph at the resolved `knowledge-graph` path: - If Bash is available in the current session, run it from the project root: ``` python3 "${CLAUDE_PLUGIN_ROOT}/bin/kaizen.py" graph init --path "" ``` This creates the `nodes//` folder for each of the fifteen node types plus an empty `index.json`/`edges.jsonl`, and is safe to run again over an existing graph — it never truncates existing content. - If Bash is not available, do not attempt to shell out. Instead, carry the exact command above into the step-7 summary so a human or a Bash-capable session can run it, and state plainly that the graph has not been scaffolded yet. 7. Report back a short, concrete summary: both resolved paths, whether the graph was scaffolded (or, if Bash was unavailable, the exact command to run), and that `.kaizen/workspace.map.yaml` now records these locations so these questions will not be asked again in this project. ## Notes - This skill only manages the `intelligence-layer` and `knowledge-graph` locations. It does not scaffold or ask about backend/frontend source code locations — those are out of scope for this milestone's onboarding flow. - `${CLAUDE_SKILL_DIR}` always resolves to this skill's own folder (`skills/init-workspace/`) regardless of how the plugin was installed. - If the user's answer to either question is ambiguous or missing required information (for example, they say "somewhere sensible" with no path), ask a clarifying follow-up rather than picking a path yourself — this mirrors the plugin's broader "ask a required question rather than hide an unknown behind an assumption" convention.