project-init

name	project-init
description	Use when project setup needs to be verified or completed — invoked automatically at session start (via hook) and by work-start before any branch work begins. NOT invoked directly by users.
slash-command	false

project-init

Normalised setup gateway. Both the session hook and work-start converge here — so the entry point doesn't matter, every session hits the same initialisation checks.

Fast path: if everything is already set up or previously declined, return immediately with no output.

Slow path: detect what's missing, run setup steps in order, write decline flags to CLAUDE.md when user says no so they are never asked again.

---

IntelliJ MCP routing — always apply

Before any other check: if both mcp__intellij-index__* and mcp__intellij__* tools are visible in this session, note this rule and apply it throughout the session:

• mcp__intellij-index__* — use for ALL code navigation, file search, diagnostics, and opening projects. Pass project_path to auto-open any closed project. Never ask the user to open a project manually.
• mcp__intellij__* — use only for build/run, terminal, and formatting. Cannot open projects.

This applies regardless of what work follows — spec writing, code review, implementation, or exploration. The rule is in effect for the whole session once noted here.

---

Fast-path exit

Run this first. If all conditions are met, return immediately — do nothing else.

python3 ~/.claude/skills/project-init/ctx.py

If CLAUDE_OK=yes AND WORKSPACE_OK=yes AND ISSUES_STATUS is not absent → return silently.

---

Checks (run in order when fast path does not exit)

Check 1 — CLAUDE.md with project type

Read CLAUDE_OK and PROJECT_TYPE from the ctx.py output (already run in fast-path).

Also check whether the file exists at all:

[ -f "CLAUDE.md" ] && echo "exists" || echo "missing"

State	Action
CLAUDE.md missing	Ask user for project type, create CLAUDE.md inline
CLAUDE.md exists, CLAUDE_OK=no	Ask user to choose type, insert ## Project Type section
CLAUDE_OK=yes	✅ Continue

Project type choices: skills · java · blog · custom · generic

When creating: use the minimal template — project type declaration plus build/test commands if detectable from the repo (pom.xml, package.json, pyproject.toml). Do not pad with boilerplate.

CLAUDE.md creation is required. If the user refuses, hard stop — no other check can run without a project type.

---

Check 2 — Workspace

Read WORKSPACE_OK and WORKSPACE_DECLINED from the ctx.py output (already run in fast-path).

State	Action
WORKSPACE_OK=yes (symlinks present or declined)	✅ Continue
WORKSPACE_DECLINED=yes	✅ Skip silently
WORKSPACE_OK=no and WORKSPACE_DECLINED=no	Offer (see below)

Offer:

No workspace configured for this project.

A workspace keeps methodology artifacts (plans, specs, handovers, blog entries) separate from the project repo. Set one up now? (YES / n)

• YES → invoke workspace-init. It handles git hooks, DESIGN.md stub, work tracking, and superpowers as part of its own flow. Once complete, skip Checks 3 and 4 — workspace-init already offered them.
• n → write workspace: declined to CLAUDE.md (see below), continue.

Writing the decline flag:

Add to CLAUDE.md under ## Project Type (or append if section not found):

workspace: declined

This is a single-line property, not a section header. Place it directly below the project type line:

## Project Type

type: java
workspace: declined

---

Check 3 — Work Tracking

Skip if: workspace was just set up this session (workspace-init offered it), or Issue tracking: declined is already in CLAUDE.md.

Read ISSUES_STATUS from the ctx.py output (already run in fast-path). Values: enabled | declined | absent.

State	Action
enabled	✅ Continue
declined	✅ Skip silently
absent	Offer (see below)

Offer:

No issue tracking configured.

Links every commit to a GitHub issue — enforces issue creation before coding, enables commit split detection, generates release notes. Set it up now? (YES / n)

• YES → invoke issue-workflow (Phase 0 runs automatically)
• n → write Issue tracking: declined into ## Work Tracking in CLAUDE.md:

## Work Tracking

Issue tracking: declined

---

Check 4 — Superpowers

Skip if: workspace was just set up this session (workspace-init offered it).

python3 -c 'import json,os; s=json.load(open(os.path.expanduser("~/.claude/settings.json"))); print("installed" if "superpowers@claude-plugins-official" in s.get("enabledPlugins",{}) else "missing")' 2>/dev/null || echo "missing"

State	Action
Installed	✅ Continue
Missing	Notify once, do not block

If missing:

Superpowers not installed. Install with: /plugin install superpowers

Adds structured TDD, debugging, brainstorming, and code review workflows.

Do not write a decline flag for superpowers — it is advisory only and does not affect workflow correctness. Show once per session, never block.

---

Return states

Outcome	What happens next
Fast path — all set up or declined	Return silently
Setup completed	Return silently
Workspace declined — flag written	Return, caller continues without workspace
Issue tracking declined — flag written	Return silently
CLAUDE.md creation refused	Hard stop

---

Resetting a decline

If a user changes their mind:

• Workspace: remove workspace: declined from CLAUDE.md — project-init will offer again next session, or they can say "set up workspace"
• Issue tracking: change Issue tracking: declined to Issue tracking: enabled in ## Work Tracking, or say "set up issue tracking" to invoke the skill directly

---

Integration points

Session hook (check_project_setup.sh)

Output at session start:

🔧 Invoke the project-init skill to verify this project is set up before proceeding.

work-start

Invoke project-init as Step 0 before path resolution. Only continue once project-init returns. If workspace was declined, proceed in single-repo mode.

---

Common Pitfalls

Mistake	Why It's Wrong	Fix
Skipping fast-path check	Runs prompts on every session even when set up	Always check all three conditions first
Not writing decline flag	User gets asked every session forever	Write to CLAUDE.md on every decline
Blocking on superpowers	User must manually install it	Notify only, always continue
Running Checks 3+4 after workspace-init	workspace-init already offered them	Skip if workspace-init ran this session

---

Skill Chaining

Invoked by:

• Session hook (check_project_setup.sh) — every session start
• work-start — Step 0, before path resolution

Invokes:

• workspace-init — if workspace missing and user accepts
• issue-workflow (Phase 0) — if issue tracking missing and user accepts

Does not invoke:

• Any branch or commit skill — setup only