# Project Init

> One-time project bootstrap workflow for new repos. Use whenever the user says "initialize project," "set up this repo for Cursor and Claude," "new Cursor project," "set up Cursor," "bootstrap docs/context," or "new project setup." Prefer this before first handoff in a repo. Do NOT use for end-of-session updates in active projects; use handoff for that.

- Skill: `ngreenwall/project-init` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add ngreenwall/project-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ngreenwall/project-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ngreenwall (https://skillmd.com/u/ngreenwall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ngreenwall/project-init

---

# SKILL: Project Init

Initialize a project so future sessions and handoffs work consistently in both Cursor and Claude Code. Default to the minimum: three docs plus git. A project earns more files by outgrowing these, not on day 0.

## MISSION
Create the minimum durable scaffolding a project needs on day 0:
- Git repo initialized with a `.gitignore`, and an MIT `LICENSE` whenever the project uses git
- `CLAUDE.md` for project-facing AI guidance, including a short "What this is" and "Key decisions" section
- `docs/WORKLOG.md` with the task checklist (Now / Next) up top and rolling session notes below
- `README.md` baseline sections so agents and humans can pick up the repo quickly
- `.cursor/rules/context-router.md` for Cursor startup routing

Do NOT create SPEC.md, DECISIONS.md, ROADMAP.md, or PROJECT.md. Spec and decision content starts as sections inside CLAUDE.md; the escalation path (below) covers projects that outgrow that.

## PROTOCOL (run in this exact order)

Invoking this skill is the user's confirmation for its standard outputs: create the files for the chosen scope without per-file approval. Only two questions need answers at either scope: the scope question and the git question. This overrides any general "state proposed changes and wait for confirmation" habit for files this skill is defined to create.

### Step 1: Determine project scope
Ask the user:

> "Is this a simple, smaller project (a script, a one-off page, a config, a quick artifact), or an in-depth build (an app or tool you'll develop over time)?"

Do not infer the answer from file types or folder contents, only the user knows how deep this project goes. Exception: if the user already described the project's depth earlier in the conversation, state the scope you inferred and ask them to confirm instead of asking from scratch.

**Simple project:**
1. Ask one setup question: "Will this live on git?"
   - **Yes:** run `git init` if not already a repo, create a minimal `.gitignore` (`.DS_Store`, `.env`, `CLAUDE.local.md`, plus stack-specific entries if detected), and create an MIT `LICENSE`, all automatically, no further questions. Use a different license only if the user names one. Do NOT ask where it will be pushed or create a remote; the completion report covers connecting to GitHub later. After all files are created, make an initial commit (`Initial scaffold`) so the folder is push-ready.
   - **No:** skip git, `.gitignore`, and `LICENSE` entirely.
2. Create or patch `README.md` with just: What this is, How to install/use it, and any key configuration. Skip "How to run it" / "How to test or preview" if they don't apply.
3. Create a minimal `CLAUDE.md` so return sessions start oriented (it's the file AI tools auto-load), using the template in `assets/claude-md-simple.md`.

4. Create `.cursor/rules/context-router.md` so Cursor loads CLAUDE.md too, using the template in `assets/context-router-simple.md`.

5. Do not create WORKLOG.md or a `docs/` folder, a simple project doesn't need session scaffolding. If it grows into a real build later, rerun `project-init` and answer "in-depth"; it patches in the missing files.
6. Report completion using the "Simple project" checklist in Step 7 and stop.

**In-depth build:** continue to Step 2.

### Step 2: Verify workspace and detect current state
Confirm you are in the project root and inventory whether these files already exist:
- `CLAUDE.md`
- `docs/WORKLOG.md`
- `README.md`
- `.cursor/rules/context-router.md`

Prefer patching existing files over replacing them.

### Step 3: Ask the git question
Ask: "Will this live on git?" (Skip the question if the project root is already a git repo, treat that as a yes.)

- **Yes:** run `git init` if not already a repo. If `.gitignore` does not exist, create one with sensible defaults for the detected stack (check for `package.json`, `requirements.txt`, `Gemfile`, etc.), at minimum `.DS_Store`, `.env`, `CLAUDE.local.md`, `node_modules/` (if JS/TS), and editor/IDE cruft. Create an MIT `LICENSE` automatically (use a different license only if the user names one). No further git questions. Do not ask where the repo will be pushed or create a remote; after all scaffolding steps finish, make an initial commit (`Initial scaffold`) so the folder is push-ready, and the completion report's follow-up block covers connecting to GitHub later.
- **No:** skip git, `.gitignore`, and `LICENSE`. Note in the report that `handoff`'s commit step won't apply until git is initialized.

If `.gitignore` or `LICENSE` already exist, leave them untouched.

### Step 4: Create CLAUDE.md and docs/WORKLOG.md
Ensure the `docs/` folder exists.

If `CLAUDE.md` is missing, create it using the template in `assets/claude-md-indepth.md` (fill in what you know from the conversation; leave honest placeholders otherwise). If `CLAUDE.md` exists, patch in the worklog check line and any missing section headers, don't rewrite existing content.

Note: Claude Code also loads a gitignored `CLAUDE.local.md` for personal-only prefs; this skill doesn't create one automatically.

If `docs/WORKLOG.md` is missing, create it using the template in `assets/worklog-template.md`.

### Step 5: Create or patch README baseline
Ensure `README.md` includes these minimum sections, adapting or omitting any that don't apply:
- What this is
- How to run it
- How to test or preview
- Key configuration
- Project structure (lightweight, top-level paths)

If `README.md` already exists, preserve project-specific details and only add missing sections.

### Step 6: Create/repair Cursor context router
Ensure `.cursor/rules/context-router.md` exists, using the template in `assets/context-router-indepth.md`.

### Step 7: Report completion checklist (required)

For the **simple** branch, return:

```markdown
Project init checklist (simple project):
- [x] Git repo + `.gitignore` + MIT `LICENSE` (created|skipped-no-git|already good)
- [x] `README.md` (created|updated|already good)
- [x] Minimal `CLAUDE.md` (created|updated|already good)
- [x] `.cursor/rules/context-router.md` (created|already good)
- [x] WORKLOG.md, docs/: not applicable at this scope

Manual follow-up:
- <only include items that still need user action>
```

If git was initialized (either scope) and no remote exists, always append this to Manual follow-up. Substitute the real values before printing (folder name from the project root, username via `gh api user -q .login`), the command must be copy-pasteable exactly as shown, no `<placeholders>`. If `gh` isn't installed or isn't authenticated, that lookup fails, in that case print the block with `ACTUAL-USERNAME` left as a literal placeholder and add a one-line note that the user needs to fill in their own GitHub username:

```markdown
- This folder is committed and ready to push whenever you want it on GitHub:
  - Fastest (creates the repo and pushes in one step, paste as-is): `gh repo create ACTUAL-FOLDER-NAME --private --source=. --push` (use `--public` to share it)
  - Or create the repo on github.com first, then connect it:
    ```bash
    git remote add origin git@github.com:ACTUAL-USERNAME/ACTUAL-FOLDER-NAME.git
    git branch -M main
    git push -u origin main
    ```
```

For the **in-depth** branch, return:

```markdown
Project init checklist:
- [x] Git repo + `.gitignore` + MIT `LICENSE` (created|skipped-no-git|already good)
- [x] `CLAUDE.md` (created|updated|already good)
- [x] `docs/WORKLOG.md` (created|updated|already good)
- [x] `README.md` baseline sections (created|updated|already good)
- [x] `.cursor/rules/context-router.md` (created|updated|already good)

Manual follow-up:
- <only include items that still need user action>
```

## DEFAULTS AND GUARDRAILS
- Never guess scope, always ask (Step 1). Folder contents are not a reliable signal for how deep a project will go.
- Both scopes ask the git question once; a yes covers `.gitignore` and MIT `LICENSE` automatically, a no skips all three. Never create a remote at scaffold time.
- Never delete existing project content to satisfy this skill; patch minimally.
- Never rewrite a full `README.md` if only sections are missing.
- Keep file paths in output explicit and copy-pasteable.
- This skill only creates `CLAUDE.md`, not `AGENTS.md`. If you already use `AGENTS.md` from another tool, `handoff` will still recognize and update it, project-init just doesn't create one itself.

## Tool-specific notes

**Cursor:** `context-router.md` points Cursor at `CLAUDE.md` and `docs/WORKLOG.md`. If you maintain a separate global-context file shared across projects, link or reference it from your own Cursor setup; that's outside this skill's scope.

**Claude Code:** if you keep global instructions in `~/.claude/CLAUDE.md`, that's a one-time, machine-level setup, not per-project. This skill does not configure it.

## BOUNDARY
- `project-init` is for one-time bootstrap or repairing missing scaffolding.
- `handoff` is for recurring session updates (session notes, Now/Next checklist, README health check, durable doc deltas) and owns the escalation when CLAUDE.md's "What this is"/"Key decisions" sections outgrow a screen of content and move to `docs/PROJECT.md` (the last tier, never split further; the task checklist always stays in `docs/WORKLOG.md`, never a separate ROADMAP.md). Not part of day-0 init.
- Do not move recurring handoff logging into `project-init`.