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 <intelligence-layer path>/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:

   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 "<resolved knowledge-graph path>"
     

     This creates the nodes/<TYPE>/ 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.