Project Init

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mdproctor
• Source: mdproctor/cc-praxis
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.