Setup Project

Setup Project — Repo Hygiene

Audit or initialize a project's repository structure.

Step 0 — Load Extensions

Check for optional overrides. Use Glob to verify each path exists before reading. Do NOT call Read on files that may not exist — skip missing files silently (no output).

1. Global: ~/.claude/skills/setup-project/SKILL.md + reference.md
2. Project: {project}/.claude/skills/setup-project/SKILL.md + reference.md
3. Merge: project > global > plugin defaults

Arguments

• --audit: Check existing repo and report issues (default for existing repos)
• --init: Full initialization — create missing files, set up ignores, scaffold extensions
• --fix: Auto-fix issues found during audit

No argument: detect if repo is new (no commits) → --init, otherwise → --audit.

Step 1 — Analyze the project

1. git status — is this a git repo?
2. Detect tech stack from manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, *.csproj)
3. Read existing .gitignore
4. Check LICENSE, README.md, .claude/ directory
5. Detect monorepo structure (packages/, apps/, workspaces)

Step 2 — .gitignore

2.1 — Language/Framework ignores (dynamic)

Instead of shipping static templates, fetch the appropriate rules:

1. Detect the project's language/framework from Step 1
2. Fetch from gitignore.io API: https://www.toptal.com/developers/gitignore/api/{stack}

• Example: node, python, rust, go, csharp, java

1. For IDEs, also fetch: visualstudiocode, intellij, vim, etc.
2. Merge fetched rules with the mandatory sections below

If the API is unavailable, fall back to basic rules from Claude's knowledge.

2.2 — Claude / AI tooling ignores (mandatory, always included)

See deep-knowledge/claude-directory-structure.md for the canonical .claude/ layout.

MUST be tracked (never ignore):

• CLAUDE.md, .claudeignore (root level, required by Claude Code)
• .claude/commands/, .claude/skills/, .claude/hooks/
• .claude/settings.json, .claude/agents/, .claude/agents.json, .claude/launch.json
• .claude/graphify.json — the graph opt-out/consent record. It is a deliberate

project decision, not runtime state, and ignoring it silently re-enables the graph for everyone who clones the repo.

• .claude/deep-knowledge/, .claude/project-map.md — authored content.

The line to hold: plugin configuration is tracked, plugin runtime state is ignored. Both live under .claude/, and only that distinction separates them.

MUST be ignored:

# AI tooling — session state (never track)
.claude/worktrees/
.claude/todos/
.claude/plans/
.claude/projects/
.claude/session-env/
.claude/shell-snapshots/
.claude/backups/
.claude/telemetry/
.claude/token-cache/
.claude/.cache/
.claude/*.log
.claude/token-config.json
.claude/concept-active.json
.claude/concepts/
.claude/session-opened-files.json

Plus the devops plugin's own runtime artifacts. Everything above is generic Claude Code state; the plugin writes its own files into .claude/ too, and until they are listed here every consumer project rediscovers each one the hard way — as untracked dirt in the middle of unrelated work, added to a hand-grown ignore list one dirty worktree at a time. Emit this as a marked block so a later /setup-project run can replace it in place instead of appending a second copy (match the two marker lines; if both are present, replace everything between them, otherwise append the whole block):

# >>> devops-plugin runtime state — generated by /setup-project, do not edit >>>
# Written into the PROJECT's .claude/ by the plugin itself.
.claude/batch-activity
.claude/batch-mode.json
.claude/batch-watchdog.lock
.claude/batch.md
.claude/.ship-in-progress
.claude/.ship-lockout
.claude/.ship-watcher/
# Written by Claude Code / adjacent MCP servers, observed dirtying real repos.
.claude/handoffs/
.claude/devops-livebrief/
.claude/scheduled_tasks.lock
# `), flag as **WARNING** and recommend
splitting the volatile value into a separate gitignored file.

## Step 2b — CLAUDE.md audit

Check the project `CLAUDE.md` and the global `~/.claude/CLAUDE.md`: whether each
exists, and its line count. Budgets, what to extract and where, the extraction
procedure, and the scaffold for a missing file all live in
`{PLUGIN_ROOT}/deep-knowledge/content-conventions.md` — read it rather than
re-deriving the numbers.

Report in the final output under a `### CLAUDE.md` section, per file:
`[OK|WARNING|CRITICAL|MISSING]`, the line count against its budget, and whether
it reads as an index or as documentation. With `--fix`, run the extraction
procedure; without it, report only.

This is the one-time sweep at setup. Ongoing enforcement is the
`post.claude.budget` hook, which measures every Claude context file at write
time — do not duplicate it into a recurring check here.

## Step 2c — Platform-specific permissions audit (Windows only)

Skip entirely on non-Windows (`process.platform !== 'win32'`; or check `$env:OS` in PowerShell).

1. **Detect Desktop App launcher**: probe `%APPDATA%\Claude\claude_desktop_config.json` existence.
   - Not found → report `[INFO] Desktop App not detected — skip.` and continue to Step 3.
2. **Grep for downgrade evidence** (last 200 lines of `%APPDATA%\Claude\logs\main.log`):
   ```powershell
   Get-Content "$env:APPDATA\Claude\logs\main.log" -Tail 200 |
     Select-String "bypassPermissionsModeEnabled pref is off"
   ```
3. **Report**:
   - Match found → `[WARNING] Desktop App master switch off — every session runs as acceptEdits.`
   - No match → `[OK] No recent permission downgrade detected.`
4. **`--fix` action**: print instructions to enable **Settings → Bypass permissions mode** in the
   Desktop App UI. Do NOT auto-patch the JSON. Reference:
   `deep-knowledge/claude-desktop-app-setup.md`

Add the result to the Step 8 report under `### Platform Audit`.

## Step 3 — LICENSE

If missing: ask user via AskUserQuestion (MIT, Apache 2.0, GPL 3.0, ISC, Proprietary).
Generate with current year and user name from git config.

## Step 4 — README check

Do NOT generate — inform user to run `/setup-readme` if missing.

## Step 5 — Project Map

Generate `.claude/project-map.md` — a compact index of the project's file structure.
Run the plugin's generator script:

```bash
node {PLUGIN_ROOT}/scripts/gen-project-map.js {project-root}

This creates a tree overview with directory descriptions and key file highlights. The map is auto-regenerated by ship_build on every ship. Report the result (file count, dir count) in the final output.

Step 6 — Additional files

Check and report on: .editorconfig, .gitattributes, CHANGELOG.md. Do NOT auto-create — only report status and recommend.

Step 7 — Inform about skill extensions

Check if .claude/skills/ exists in the project. If any extensions are already present, list them in the report.

Point the user to /claude-extend-skill for interactively scaffolding or adapting extensions for any plugin skill:

> "Du kannst jedes Plugin-Skill für dieses Projekt anpassen. > Nutze /claude-extend-skill, um interaktiv eine Extension anzulegen oder > eine bestehende zu bearbeiten. Mehr dazu: siehe Plugin README."

Step 8 — Output report

## Repo Hygiene Report

### .gitignore
- [CRITICAL/WARNING/OK/INFO] ...

### LICENSE
- [OK/WARNING] ...

### README
- [OK/WARNING] ...

### Additional files
- [INFO] ...

### Platform Audit
- [WARNING/OK/INFO] ...

### Plugin Extensions
- [INFO] Run /claude-extend-skill to scaffold extensions for plugin skills

Step 9 — Completion Card

Call mcp__plugin_devops_dotclaude-completion__render_completion_card:

| Situation | Variant | |-----------|---------| | Files created/modified (.gitignore, LICENSE, project-map.md, …) | ready | | Audit only, nothing written | analysis |

Pass: variant, summary, lang, session_id, changes (per-file summary), and state when files were written. Output the markdown VERBATIM as the LAST thing in the response.

Source & license

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

• Author: Jerry0022
• Source: Jerry0022/dotclaude
• License: MIT

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