init-kumiki-project

name	init-kumiki-project
description	Check whether the current workspace is a kumiki project, initialize it if not, and confirm the setup is ready.

Init Kumiki Project Skill

Use this skill when starting work in a workspace to verify it is a kumiki project and set it up if needed.

Step 1: Decide if this is a kumiki project

A kumiki project is one of:

• An empty folder (or nearly empty — maybe just a .git/)
• A folder that already contains Python files with from kumiki import * or import kumiki
• A folder that already has a .kigumi/ directory or .venv/ with kumiki installed

Stop and ask the user before proceeding if the folder shows signs it belongs to something else:

• package.json or node_modules/ at the root → likely a JS/TS project
• pyproject.toml or setup.py that defines a package other than a kumiki frame script
• Imports of non-kumiki frameworks (Django, Flask, FastAPI, numpy, torch, etc.) in existing .py files
• A populated git repo with a README describing a different project
• Many pre-existing files unrelated to timber framing

When in doubt, show the user a brief summary of what you see in the folder and ask them to confirm before touching anything.

Step 2: Check if already initialized

A project is fully initialized when all of these are present:

• .kigumi/kigumi.yaml — written by Kigumi after a successful setup
• .venv/bin/python3 (macOS/Linux) or .venv\Scripts\python.exe (Windows)
• my_cute_frame.py — starter example file

If all three exist, skip to Step 4.

Step 3: Initialize via Kigumi

Run the VS Code command:

kigumi.initializeProjectInWorkspace

or if you can't, ask the user to run it from the command palette (cmd/ctrl+shift+p) by searching for "Kigumi: Initialize Project" OR through the Kigumi menu in the sidebar.

This command (title: "Kigumi: Initialize Project") handles everything:

• Creates .venv/ with Python 3.13 via uv
• Installs kumiki and its viewer dependencies
• Writes .kigumi/kigumi.yaml
• Creates my_cute_frame.py as a starter example
• Adds .gitignore entries (.venv/, kigumi_exports/, .kigumi/logs/)
• Creates agent instruction files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursorrules)

Wait for the command to complete (it shows a progress notification in VS Code). On success you will see: "Kigumi workspace initialized and Kumiki was updated to latest."

If it fails, check the Kigumi output channel for details and report the error to the user.

Step 4: Resolve the kumiki package path and read concepts

.venv/bin/python3 -c "import kumiki, pathlib; print(pathlib.Path(kumiki.__file__).resolve().parent)"

On Windows: .venv\Scripts\python.exe instead of .venv/bin/python3.

Read <that_path>/docs/concepts.md to load Kumiki core concepts and architecture before doing any design work.

What an initialized project looks like

my-project/
├── .venv/                  # Python venv with kumiki installed
├── .kigumi/
│   ├── kigumi.yaml         # Project metadata written by Kigumi on init
│   └── logs/               # Session logs (created on first run)
├── .gitignore              # Includes .venv/, kigumi_exports/, .kigumi/logs/
├── AGENTS.md               # Agent instruction pointer (created by Kigumi)
├── CLAUDE.md               # Claude instruction pointer (created by Kigumi)
├── my_cute_frame.py        # Starter example frame
└── *.py                    # Additional frame files the user creates

Key markers:

• .venv/bin/python3 exists and import kumiki succeeds
• Python files use from kumiki import * and define functions typed -> Frame
• No pyproject.toml / setup.py for a library (these are scripts, not packages)