claude

claude-config

Global Claude Code configuration — agents, skills, plugins, and project templates.

---

Overview

This repo is your personal Claude Code setup, versioned and reproducible across machines.

claude-config/
├── CLAUDE.md                  # Global coding preferences (style, rules, workflow)
├── settings.json              # Global permissions + SessionStart hook
├── install-plugins.sh         # One-shot installer: prerequisites + all plugins
├── link.sh                    # Symlinks this repo into ~/.claude/
├── .gitmodules                # Submodule declaration (GStack)
├── hooks/
│   └── session-start.sh       # Shows toggle plugin status at every session start
├── skills-external/
│   └── gstack/                # Git submodule — garrytan/gstack
│                                (symlinked → ~/.claude/skills/gstack)
├── agents/
│   ├── analyzer.md            # Factual codebase analysis (read-only)
│   ├── git-workflow.md        # Branch setup, commits, PR creation, conflict resolution
│   ├── interviewer.md         # Project questionnaire → PROJECT BRIEF
│   ├── plugin-advisor.md      # Detect plugin mismatches, recommend actions
│   ├── readme-updater.md      # CREATE / SYNC / AUDIT README (3 modes)
│   ├── refactorer.md          # Surgical refactoring with norm enforcement
│   └── scaffolder.md          # Project skeleton (CLAUDE.md, settings, structure)
├── skills/
│   ├── analyze/               # /analyze        — deep factual analysis
│   ├── git-pr/                # /git-pr          — commit, push, open draft PR/MR
│   ├── init-project/          # /init-project    — full project initialization
│   ├── plugin-check/          # /plugin-check    — check plugin config vs project needs
│   ├── readme/                # /readme          — full README audit + update
│   ├── refactor/              # /refactor        — improve code without changing behavior
│   └── ship-feature/          # /ship-feature    — ship a feature end-to-end
└── templates/
    ├── project-CLAUDE.md      # Template for per-project CLAUDE.md
    └── settings/
        ├── home-settings.json # Template for ~/.claude/settings.json
        ├── settings.json      # Template for project .claude/settings.json
        ├── settings.local.json# Template for personal .claude/settings.local.json
        ├── .claudeignore      # Template for project .claudeignore
        └── SETTINGS.md        # Full settings reference

Architecture:

• skills/ = entry points you invoke via /skill-name
• agents/ = execution units called by skills (never invoked directly)
• Custom skills use Superpowers agents for implementation phases
• Plugins (Superpowers, GStack, GSD, etc.) install separately via install-plugins.sh

---

Fresh install (new machine)

# 1. Clone with submodules (GStack is a git submodule)
git clone --recurse-submodules git@github.com:youruser/claude-config.git ~/claude-config

# 2. Symlink into ~/.claude/
cd ~/claude-config && bash link.sh

# 3. Install prerequisites + all plugins
#    Handles: git, Node.js 22, Rust/Cargo, Python 3, gh CLI, glab CLI,
#             RTK, GStack (submodule), GSD, all marketplace plugins
bash ~/claude-config/install-plugins.sh

# 4. Authenticate git provider CLIs (for /git-pr)
gh auth login        # GitHub
glab auth login      # GitLab
# Gogs/Gitea: see "Git setup" section below

# 5. Add Context7 API key (free at context7.com)
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_KEY

# 6. Restart Claude Code → /reload-plugins

All claude plugin install calls use --scope user — always installs to ~/.claude/plugins/ regardless of working directory.

---

Available slash commands

Custom skills (this repo)

Command	Description
/analyze	Deep factual analysis of code before any modification
/refactor	Improve code quality without changing behavior (strict norms)
/readme	Full README audit — diff vs codebase, mandatory stop, surgical updates
/plugin-check	Check active plugins vs project needs — recommend enable/disable
/git-pr	Commit all changes, push, open draft PR/MR (GitHub/GitLab/Gogs/Gitea)
/init-project	Initialize a complete project from scratch (full orchestrator)
/ship-feature	Ship a feature end-to-end with validation gates (full orchestrator)

Superpowers skills (auto-invoked or explicit)

Command	When it auto-activates
/superpowers:brainstorm	When you describe something to build
/superpowers:write-plan	After design is approved
/superpowers:execute-plan	With an approved plan
systematic-debugging	Auto — when debugging
test-driven-development	Auto — when implementing
requesting-code-review	Auto — after a feature step

GStack skills (full-product projects only)

Submodule at skills-external/gstack/, symlinked to ~/.claude/skills/gstack/. Use when: project has UI + design + deploy + browser QA. Skip for backend-only, libs, CLI, scripts.

Command	Description
/office-hours	Discovery consultant — scope and challenge before code
/plan-ceo-review	CEO challenges product scope and feature value
/plan-eng-review	Staff engineer locks architecture decisions
/design-consultation	Build a design system from scratch
/design-shotgun	Generate multiple visual variants for comparison
/design-html	Turn approved mockup into production HTML
/review	Code review (GStack version)
/ship	One-command: test → build → deploy
/qa	QA with real Chrome browser automation
/browse	Headless Chrome web navigation
/careful	Activate safety guardrails
/freeze	Lock edits to current directory
/retro	Engineering retrospective
/gstack-upgrade	Self-update GStack to latest

GSD skills (multi-session large features)

Installed globally via npx get-shit-done-cc --claude --global (done by install-plugins.sh). Use when: feature spans multiple days/sessions.

Command	Description
/gsd:discuss-phase	Refine spec for a phase through conversation
/gsd:plan-phase	Generate hierarchical phase plan
/gsd:execute-phase	Execute phase in an isolated context window
/gsd:ship	Create PR from verified work
/gsd:next	Auto-advance to the next phase

Other plugin commands

Command	Plugin	Description
/pr-review-toolkit:review-pr	pr-review-toolkit	Multi-agent PR review (6 specialized agents)
/context7:docs <lib>	context7	Manual doc lookup for a specific library

---

Orchestrators in detail

/init-project

Same rigor as /ship-feature. Two validation gates. Full TDD subagent pipeline for v1 features. Scaffolder creates only the skeleton. readme-updater handles README in two passes (CREATE + SYNC). Always works on a feature branch — never on main/master.

/init-project <project idea>
    │
    ├── STEP 0a: BRANCH SETUP (git-workflow)          ← create feature branch from main
    │                                                    or sync existing branch
    ├── STEP 0b: PLUGIN CHECK (plugin-advisor)        ← blocks if wrong plugins
    ├── STEP 1:  INTERVIEWER (custom)                 → PROJECT BRIEF
    ├── STEP 2:  ANALYZER (custom)                    → ANALYSIS REPORT
    ├── STEP 3:  superpowers:brainstorming             → VALIDATED DESIGN
    ├── STEP 4:  VALIDATION GATE #1                   → approve architecture
    ├── STEP 5:  SCAFFOLDER (custom)                  → skeleton (CLAUDE.md + settings +
    │                                                    structure + empty entry points,
    │                                                    NO features, NO README)
    ├── STEP 5b: README-UPDATER create mode           → CREATE README from CLAUDE.md
    ├── STEP 6:  superpowers:writing-plans             → decompose v1 features into tasks
    ├── STEP 7:  VALIDATION GATE #2                   → approve task plan
    ├── STEP 8:  superpowers:subagent-driven (TDD)    → implement each feature
    ├── STEP 9:  ANALYZER (custom)                    → regression + deviation check
    ├── STEP 10: superpowers:requesting-review         → full code review
    ├── STEP 11: superpowers:finishing-branch          → cleanup + build + tests
    └── STEP 12: README-UPDATER sync mode             → sync README with implementation

/ship-feature

/ship-feature <feature description>
    │
    ├── STEP 0a: BRANCH SETUP (git-workflow)          ← create/sync feature branch
    ├── STEP 0b: PLUGIN CHECK (plugin-advisor)        ← blocks if wrong plugins
    ├── STEP 1:  superpowers:brainstorming             → VALIDATED DESIGN
    ├── STEP 2:  superpowers:writing-plans             → task plan
    ├── STEP 3:  VALIDATION GATE                      → user approval required
    ├── STEP 4:  superpowers:subagent-driven (TDD)    → implementation
    ├── STEP 5:  ANALYZER (custom)                    → regression / deviation check
    ├── STEP 6:  superpowers:requesting-review         → code review
    ├── STEP 7:  superpowers:finishing-branch          → cleanup
    ├── STEP 8:  README-UPDATER sync mode             → update README
    └── STEP 9:  CREATE PR (optional gate)            → /git-pr if user approves

/git-pr

Works on any provider. Retroactive — git diff <base>...HEAD sees ALL changes since branch creation, regardless of session count. Creates a draft PR — you control the merge.

/git-pr [optional title]
    │
    ├── PHASE 0: Detect provider (GitHub/GitLab/Gogs/Gitea)
    │           Check CLI: gh / glab / API fallback
    ├── PHASE 1: Analyze branch (retroactive)
    │           git diff <base>...HEAD — ALL changes since branch start
    │           Categorize: config / model / core / api / ui / test / docs / infra
    ├── PHASE 2: Propose commit plan (conventional commits)
    │           [VALIDATION GATE] — user approves before any commit
    ├── PHASE 3: Execute commits (staged per logical group)
    ├── PHASE 4: Push (with conflict-safe rebase if rejected)
    └── PHASE 5: Create draft PR/MR
                GitHub → gh pr create --draft  (or API)
                GitLab → glab mr create --draft (or API)
                Gogs   → POST /api/v1/repos/{owner}/{repo}/pulls
                Gitea  → same API format as Gogs

Branch → base mapping: | Branch prefix | Default base | Commit type | |---|---|---| | feature/*, feat/* | develop or main | feat: | | bugfix/*, fix/* | develop | fix: | | hotfix/* | main | fix: | | release/* | main | chore(release): |

/plugin-check

Standalone — run before any significant work. Also auto-runs as STEP 0b in /init-project and /ship-feature.

/plugin-check "React + FastAPI SaaS with auth"
→ Detects active plugins
→ Analyzes signals: frontend? design? QA? multi-session? fast-evolving libs?
→ Produces recommendation table
→ Blocks if critical plugins missing, or confirms "proceed"

---

Git setup for /git-pr

/git-pr auto-detects your provider from the remote URL and uses the best available authentication method. Here is how to set up each provider.

---

GitHub

Option A — gh CLI (recommended)

# Install (done by install-plugins.sh)
brew install gh          # macOS
sudo apt install gh      # Linux

# Authenticate (interactive — opens browser)
gh auth login
# Choose: GitHub.com → HTTPS → authenticate with browser

# Verify
gh auth status

Option B — Personal Access Token (for CI or headless)

1. Go to github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token
3. Required scopes: repo (full), read:org (if org repo)

4. Copy the token

   # Set in environment
   export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
   echo 'export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"' >> ~/.zshrc  # persist
   
   # Claude Code reads GITHUB_TOKEN automatically for gh CLI fallback
   

---

GitLab

Option A — glab CLI (recommended)

# Install (done by install-plugins.sh)
brew install glab        # macOS

# Authenticate
glab auth login
# Choose: gitlab.com → Token or browser

# For self-hosted GitLab
glab auth login --hostname gitlab.yourcompany.com

# Verify
glab auth status

Option B — Personal Access Token

1. Go to gitlab.com → User Settings → Access Tokens (or your instance)
2. Click Add new token
3. Required scopes: api, read_repository, write_repository

4. Copy the token

   export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
   echo 'export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"' >> ~/.zshrc
   
   # For self-hosted
   export GITLAB_HOST="https://gitlab.yourcompany.com"
   

---

Gogs

Gogs has no official CLI. /git-pr uses the REST API directly.

Create an API token:

1. Log in to your Gogs instance
2. Go to User Settings (top-right avatar) → Applications
3. Under Token Name, enter claude-code
4. Click Generate Token

5. Copy the token (shown only once)

   # Set in environment
   export GOGS_TOKEN="your-token-here"
   echo 'export GOGS_TOKEN="your-token-here"' >> ~/.zshrc
   
   # Verify the API works
   curl -H "Authorization: token $GOGS_TOKEN" \
   https://your-gogs-server/api/v1/user
   # Should return your user JSON
   

Required API permissions: read/write on repos (tokens in Gogs have full API access by default).

---

Gitea

Same API format as Gogs. Gitea is a Gogs fork.

Create an API token:

1. Log in to your Gitea instance
2. Go to User Settings → Applications → Manage Access Tokens
3. Enter token name claude-code
4. Select permissions: Issues: Read/Write, Repository: Read/Write

5. Click Generate Token and copy it

   export GITEA_TOKEN="your-token-here"
   echo 'export GITEA_TOKEN="your-token-here"' >> ~/.zshrc
   
   # Verify
   curl -H "Authorization: token $GITEA_TOKEN" \
   https://your-gitea-server/api/v1/user
   

---

Self-hosted GitHub Enterprise

# Configure gh for your instance
gh config set -h github.yourcompany.com git_protocol https
gh auth login --hostname github.yourcompany.com

# Verify
gh auth status --hostname github.yourcompany.com

---

Self-hosted GitLab

glab auth login --hostname gitlab.yourcompany.com --token glpat-xxxx

---

Token security

• Never commit tokens to git — they go in ~/.zshrc, ~/.bashrc, or a secrets manager
• Rotate tokens when they expire or are compromised
• Minimum scopes — only grant what /git-pr needs (repo read/write)
• Claude Code reads env vars securely — tokens are never written to disk by Claude

---

Verify your setup

# Run inside Claude Code to verify everything
/git-pr check-auth
# → Detects provider from current repo remote
# → Tests authentication
# → Reports status per provider

Or manually:

git remote get-url origin   # see which provider
gh auth status              # GitHub CLI status
glab auth status            # GitLab CLI status
curl -s -H "Authorization: token $GOGS_TOKEN" \
  <your-gogs-url>/api/v1/user | jq .login  # Gogs/Gitea

---

Plugins reference

All plugins installed by install-plugins.sh.

At-a-glance: always on vs toggle

The mechanism: Claude Code loads every active skill's description at session start into a shared budget (8000 chars). Even if never invoked, the description costs tokens. Disabling a plugin → descriptions never load.

A hooks/session-start.sh hook shows toggle status at every session start. Run /plugin-check for a full recommendation for the current project type.

Plugin	Status	Cost/session	When to enable	Installed by
security-guidance	✅ ALWAYS ON	0 (hook only)	—	marketplace
RTK	✅ ALWAYS ON	0 (hook only)	—	cargo + rtk init
Superpowers	✅ ALWAYS ON	~600–1000	— auto-activates	marketplace
skill-creator	✅ ALWAYS ON	~100	—	marketplace
pr-review-toolkit	✅ ALWAYS ON	~300	— /pr-review-toolkit:review-pr	marketplace
GStack	🔄 TOGGLE	~2500–3000	Full-product: UI + design + deploy + QA browser	submodule
GSD	🔄 TOGGLE	~500–800	Feature spanning multiple days/sessions	npx
frontend-design	🔄 TOGGLE	~200	Any project with a UI	marketplace
ui-ux-pro-max	🔄 TOGGLE	~400	Design system, color/typography	marketplace
Context7 MCP	🔄 TOGGLE	~200	Fast-evolving libs (Next.js, React, Prisma…)	MCP manual

Toggle plugins start OFF. /plugin-check signals when to enable them. /init-project and /ship-feature run plugin-check automatically as STEP 0b.

Disable a plugin for a specific project

/plugin    # inside Claude Code → toggle off

Or in .claude/settings.json:

{
  "enabledPlugins": {
    "gstack@gstack": false
  }
}

Enable a plugin for a project (share with teammates)

{
  "enabledPlugins": {
    "ui-ux-pro-max@ui-ux-pro-max-skill": true
  },
  "extraKnownMarketplaces": {
    "ui-ux-pro-max-skill": {
      "source": { "source": "github", "repo": "nextlevelbuilder/ui-ux-pro-max-skill" }
    }
  }
}

---

Settings and permissions

File hierarchy

Highest
  managed-settings.json        — enterprise, cannot be overridden
  CLI flags                    — --allowedTools / --disallowedTools (session only)
  .claude/settings.local.json  — personal machine overrides (gitignored)
  .claude/settings.json        — project rules (committed to project repo)
  ~/.claude/settings.json      — global user rules (this repo's settings.json)
Lowest

DENY always wins over ALLOW at any level.
.claudeignore applies independently of all permission rules.

Global settings.json (this repo)

Contains global deny/ask/allow rules AND a SessionStart hook:

"hooks": {
  "SessionStart": [
    { "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/session-start.sh" }] }
  ]
}

The hook prints toggle plugin status at every session start — zero API calls, filesystem only.

Section	Purpose
deny — secrets	Blocks .env, .pem, .key, SSH keys, cloud credentials
deny — destructive	Blocks rm -rf, git push --force, chmod 777
deny — system	Blocks sudo, ssh, scp, crontab, systemctl
deny — injection	Blocks curl \| bash, wget \| sh
ask — risky	Prompts before git push, docker run, package managers
allow — safe reads	Auto-approves git read-only, ls, cat, grep, find
disableBypassPermissionsMode	Prevents YOLO mode globally

Per-project setup

cd your-project && mkdir -p .claude

# Project settings (commit)
cp ~/claude-config/templates/settings/settings.json .claude/settings.json

# Personal overrides (never commit)
cp ~/claude-config/templates/settings/settings.local.json .claude/settings.local.json
echo ".claude/settings.local.json" >> .gitignore

# Hard file exclusions (commit)
cp ~/claude-config/templates/settings/.claudeignore .claudeignore

# Project CLAUDE.md (commit)
cp ~/claude-config/templates/project-CLAUDE.md .claude/CLAUDE.md

---

Updating

This repo

cd ~/claude-config && git pull
# Symlinks → changes active immediately, no restart needed

GStack (submodule)

# Option A — from Claude Code
/gstack-upgrade

# Option B — via submodule (pins version in your repo)
cd ~/claude-config
git submodule update --remote skills-external/gstack
cd skills-external/gstack && ./setup
git add skills-external/gstack
git commit -m "chore: update gstack"

Marketplace plugins

/plugin marketplace update

RTK

cargo install --git https://github.com/rtk-ai/rtk --force
rtk init -g --auto-patch   # re-apply hook if needed

---

Adding a new custom skill

1. Create agents/myagent.md — role, tasks, rules, output format

2. Create skills/myskill/SKILL.md:

   ---
   name: myskill
   description: What this skill does — front-load the key use case (max 250 chars)
   argument-hint: <what to pass>
   disable-model-invocation: true
   ---
   
   Load and follow strictly:
   - .claude/agents/myagent.md
   
   Execute MYAGENT on:
   
   $ARGUMENTS
   

3. Or use /skill-creator to generate a skill from conversation.

---

Per-project agent overrides

# Override an agent for a specific project
cp ~/claude-config/agents/refactorer.md .claude/agents/refactorer.md
# Edit — the local version takes precedence over global