Compounding Skills:setup

compounding-skills:setup — Personalized .claude/ Setup Wizard

Run this once after installing compounding-skills. It builds a tailored .claude/ library for your project — workflow skills, expert skills, and specialized agents — based on how you actually code.

> One-time skill. After setup completes, use your generated {command_prefix}:compound skill to keep skills in sync. Never run /compounding-skills:setup again on the same project. > > Prerequisite: Run /init first to generate your CLAUDE.md file. This setup wizard focuses on workflow skills and expert skills — project context belongs in CLAUDE.md.

Process knowledge: Load the skill-garden skill for generator logic, codebase analysis techniques, and all output templates.

Communication Style

Pay attention to context cues about the user's technical level. Not every user is a senior developer — some are designers, product managers, or people new to the terminal.

Signals of technical familiarity: Uses terms like "ORM", "middleware", "service objects" naturally; references specific tools by name; has opinions about architecture.

Signals of less familiarity: Asks what things mean; uses general language ("the database thing"); expresses uncertainty about terminal commands.

Adapt accordingly:

• For technical users: use precise terminology, skip explanations of basic concepts
• For less technical users: explain jargon when you first use it, use analogies, keep options simple
• When in doubt, lean toward clarity over brevity — a brief explanation costs less than confusion

Phase 0 — Context Check

Before starting the wizard, scan the current conversation history for signals that the user has already expressed preferences or described their project. Look for:

• Stack mentions ("I'm building a Rails app", "this is a Next.js project")
• Workflow preferences ("I use feature branches", "we do TDD")
• Architectural preferences ("I prefer service objects", "we use domain-driven design")
• Specific tool mentions ("we use Jest", "Sidekiq for background jobs")
• Framework details ("we use Pundit for authorization", "Prisma for the ORM")

If the conversation already contains answers to questions from Phases 1–4, pre-fill those answers and skip the corresponding questions. Present a summary of what was inferred:

"I picked up the following from our conversation:

• Stack: Rails 7.2
• Git workflow: feature branches + PRs
• Testing: RSpec, TDD approach

I'll skip those questions and ask about the rest. Sound right?"

Use AskUserQuestion with options: "Looks right — continue" / "Let me correct something"

If the conversation has no relevant context, proceed directly to Phase 1.

Phase 1 — Detect Project Type

Auto-detect whether this is a brownfield (existing code) or greenfield (new) project:

# Count commits
git log --oneline -5 2>/dev/null | wc -l

# Check for project files
ls Gemfile package.json pyproject.toml tsconfig.json go.mod 2>/dev/null

Brownfield (≥5 commits OR recognized project files exist): Proceed to Phase 2A. Greenfield (0–4 commits, no recognized project files): Proceed to Phase 2B.

Also detect the project name from the current directory:

basename $(pwd)

Then ask the user to choose their skill prefix — this becomes the namespace for all workflow skills:

question: "What would you like to prefix your workflow skills with? This becomes the namespace (e.g., workflow:plan, workflow:work, workflow:brainstorm)."
header: "Skill prefix"
options:
  - label: "workflow (Recommended)"
    description: "e.g., workflow:plan, workflow:work, workflow:brainstorm"
  - label: "{detected directory name}"
    description: "e.g., {detected_name}:plan, {detected_name}:work, {detected_name}:brainstorm"
  - label: "Short project alias"
    description: "Use an abbreviated name (you'll type it for every skill)"
  - label: "Generic (no prefix)"
    description: "Skills named simply plan, work, brainstorm — use if this is your only project"

If the user selects "Short project alias" or wants a custom name, prompt for the exact string. Record as {command_prefix}.

Announce: "Detected [brownfield/greenfield] project. Using {command_prefix} as skill prefix."

Process Flexibility

After detecting the project type and choosing a prefix, gauge the user's appetite for configuration:

Use AskUserQuestion:

question: "How much do you want to customize?"
header: "Setup depth"
options:
  - label: "Quick setup (recommended for most projects)"
    description: "I'll analyze your codebase and use smart defaults — takes about 2 minutes"
  - label: "Detailed setup"
    description: "Walk me through each configuration choice — takes about 5 minutes"
  - label: "Just generate defaults"
    description: "Use sensible defaults for my stack, I'll fine-tune later with compound"

Quick setup: Run Phase 2A (brownfield) or Phase 2B with only Q1 (greenfield). Skip Phase 2C — infer framework details from codebase analysis or stack defaults. Use smart defaults for Phases 3–4. Go straight to Phase 5.

Detailed setup: Run all phases as documented below.

Just generate defaults: Skip Phases 2–4 entirely. Detect stack from project files, use all defaults from references/greenfield.md "Greenfield Defaults by Stack" section, and generate with a note that /{command_prefix}:compound should be run to personalize.

Phase 2A — Brownfield: Codebase Analysis

Process knowledge: See references/brownfield.md for the full step-by-step analysis process.

Launch these Explore subagents in parallel to analyze the codebase:

1. Tech Stack Detector

Task Explore: Identify the tech stack and framework versions.
Look for: Gemfile, package.json, pyproject.toml, go.mod, tsconfig.json, .ruby-version, .node-version, Cargo.toml.
Return: Primary language, framework + version, key dependencies, runtime version.

2. Convention Mapper

Task Explore: Map file and directory conventions.
Look for: Where do controllers/services/components/models live?
What naming patterns exist (snake_case, camelCase, kebab-case)?
Any notable structural patterns (feature folders, domain-driven, etc.)?
Check: app/, src/, lib/, pkg/ directories.
Return: Directory structure map, naming conventions, key organizational patterns.

3. Real Pattern Extractor

Task Explore: Find 2-3 representative files that best show coding patterns.
Avoid test files and auto-generated code.
Look for: A typical service/controller, a model/schema, a utility function.
Return: File paths + full content of the 2-3 most representative files.

4. Tooling Inspector

Task Explore: Identify existing tooling setup.
Look for: Test runner (RSpec, Jest, pytest, go test), linter config (.rubocop.yml, .eslintrc, pyproject.toml [tool.ruff]), CI setup (.github/workflows/, .circleci/), formatter (prettier, black, gofmt).
Return: Test command, lint command, CI system, formatter.

5. Git Workflow Analyzer

Task Explore: Analyze git workflow patterns.
Run: git log --oneline -20 2>/dev/null
Look for: Branch naming convention (feat/, fix/, chore/ prefixes), commit message style, PR/merge frequency.
Return: Branch naming pattern, commit message format, workflow style.

Wait for all subagents to complete, then compile findings into a structured summary:

Stack:        {language} {framework} {version}
Structure:    {key directories and naming}
Test runner:  {command}
Linter:       {command}
Git workflow: {pattern}

Display this summary to the user and announce: "Found your stack. Now let's configure your workflow skills."

Phase 2B — Greenfield: Preference Interview

Process knowledge: See references/greenfield.md for the full question bank and rationale.

Use AskUserQuestion to ask these questions. Ask them one at a time.

Question 1 — Language & Framework:

question: "What's your primary language and framework?"
header: "Stack"
options:
  - label: "Ruby on Rails"
    description: "Rails — full stack web framework"
  - label: "TypeScript / Node.js"
    description: "TypeScript with Node, Next.js, or similar"
  - label: "Python"
    description: "Python with Django, FastAPI, or similar"
  - label: "Go"
    description: "Go — standard library or framework"
  - label: "PHP"
    description: "PHP with Laravel, Symfony, or similar"

Question 2 — File Structure:

question: "How do you prefer to organize files?"
header: "Structure"
options:
  - label: "By type (MVC)"
    description: "controllers/, models/, services/ — group by role"
  - label: "By feature/domain"
    description: "users/, orders/, payments/ — group by business domain"
  - label: "Flat with conventions"
    description: "Single directory with naming conventions"
  - label: "Framework default"
    description: "Whatever the framework suggests"

Question 3 — Testing:

question: "What's your testing approach?"
header: "Testing"
options:
  - label: "TDD — tests first"
    description: "Write tests before implementation"
  - label: "Tests after, high coverage"
    description: "Implement first, then write thorough tests"
  - label: "Integration tests only"
    description: "Focus on end-to-end and integration, skip unit tests"
  - label: "Minimal testing"
    description: "Test only critical paths"

Question 4 — Git Workflow:

question: "How do you work with git?"
header: "Git"
options:
  - label: "Feature branches + PRs"
    description: "Branch per feature, review via PR before merging"
  - label: "Trunk-based development"
    description: "Small commits directly to main, fast iteration"
  - label: "Gitflow"
    description: "main + develop + feature/release/hotfix branches"
  - label: "Solo / no strict workflow"
    description: "Commit when ready, no formal process"

Record answers as greenfield_prefs for use in Phase 3+.

Phase 2C — Framework Deep-Dive Interview

Ask stack-specific architecture questions to drive the content of the expert developer skill. Use AskUserQuestion for each question.

Brownfield pre-fill: Before asking, check Phase 2A findings for auto-detectable answers (e.g., pundit in Gemfile → pre-select Pundit, sidekiq → pre-select Sidekiq). Present as confirmation questions — the user confirms and catches anything not auto-detected.

Rails Projects

Question 1 — Architectural Layers:

question: "Which architectural layers does this Rails project use?"
header: "Layers"
multiSelect: true
options:
  - label: "Service objects"
    description: "Business logic in app/services/"
  - label: "Form objects"
    description: "Form validation in app/forms/"
  - label: "Presenters"
    description: "View logic in app/presenters/"
  - label: "Query objects"
    description: "Complex queries in app/queries/"
  - label: "Decorators"
    description: "Draper-style decorators in app/decorators/"
  - label: "Concerns"
    description: "Shared modules in app/models/concerns/ and app/controllers/concerns/"
  - label: "Serializers"
    description: "Response serialization in app/serializers/"
  - label: "Channels"
    description: "ActionCable channels in app/channels/"
  - label: "Mailers"
    description: "Email logic in app/mailers/"
  - label: "Background jobs"
    description: "Job classes in app/jobs/"

Question 2 — Authorization:

question: "Which authorization library does this project use?"
header: "Authorization"
options:
  - label: "Pundit"
    description: "Policy objects in app/policies/"
  - label: "CanCanCan"
    description: "Ability-based access control"
  - label: "Custom"
    description: "Project-specific authorization logic"
  - label: "None"
    description: "No authorization framework"

Question 3 — Serialization:

question: "How does this project serialize API responses?"
header: "Serialization"
options:
  - label: "Jbuilder"
    description: "JSON views in app/views/ (.json.jbuilder)"
  - label: "ActiveModel::Serializers"
    description: "Serializer classes"
  - label: "Blueprinter"
    description: "Blueprint classes"
  - label: "fast_jsonapi / jsonapi-serializer"
    description: "JSONAPI-compliant serializers"
  - label: "Plain Ruby"
    description: "Custom to_json or hash methods"

Question 4 — Background Jobs:

question: "Which background job system does this project use?"
header: "Background jobs"
options:
  - label: "Sidekiq"
    description: "Redis-backed background processing"
  - label: "Resque"
    description: "Redis-backed Resque jobs"
  - label: "Solid Queue"
    description: "DB-backed job queue (Rails 8+)"
  - label: "None"
    description: "No background job system"

Question 5 — API Style:

question: "What API style does this project use?"
header: "API style"
options:
  - label: "REST only"
    description: "Standard RESTful JSON API"
  - label: "GraphQL"
    description: "GraphQL API (graphql-ruby)"
  - label: "Mixed (REST + GraphQL)"
    description: "Both REST and GraphQL endpoints"
  - label: "Full-stack (HTML views)"
    description: "Server-rendered HTML with Hotwire/Turbo"

TypeScript/Node Projects

Question 1 — Framework Variant:

question: "Which Node.js framework are you using?"
header: "Framework"
options:
  - label: "Express"
    description: "Classic Express.js"
  - label: "Fastify"
    description: "High-performance Fastify"
  - label: "NestJS"
    description: "Angular-inspired NestJS"
  - label: "Next.js (API routes)"
    description: "Next.js with API route handlers"

Question 2 — ORM / DB:

question: "Which ORM or database layer does this project use?"
header: "ORM/DB"
options:
  - label: "Prisma"
    description: "Type-safe ORM with schema-first approach"
  - label: "TypeORM"
    description: "Decorator-based ORM"
  - label: "Drizzle"
    description: "Lightweight TypeScript ORM"
  - label: "Sequelize"
    description: "Promise-based ORM"
  - label: "Raw SQL"
    description: "Direct SQL queries (pg, mysql2, etc.)"

Question 3 — Validation:

question: "Which validation library does this project use?"
header: "Validation"
options:
  - label: "Zod"
    description: "Schema-first TypeScript validation"
  - label: "Yup"
    description: "Schema builder for object validation"
  - label: "class-validator"
    description: "Decorator-based validation (common with NestJS)"
  - label: "None"
    description: "Custom or no validation library"

Question 4 — Testing:

question: "Which test framework does this project use?"
header: "Testing"
options:
  - label: "Jest"
    description: "Standard Jest testing"
  - label: "Vitest"
    description: "Vite-native testing framework"
  - label: "Other"
    description: "Custom or other test framework"

Python Projects

Question 1 — Framework:

question: "Which Python web framework does this project use?"
header: "Framework"
options:
  - label: "Django"
    description: "Full-stack Django framework"
  - label: "FastAPI"
    description: "Modern async FastAPI"
  - label: "Flask"
    description: "Lightweight Flask"

Question 2 — ORM:

question: "Which ORM or database layer does this project use?"
header: "ORM"
options:
  - label: "Django ORM"
    description: "Built-in Django database layer"
  - label: "SQLAlchemy"
    description: "Python SQL toolkit and ORM"
  - label: "Tortoise ORM"
    description: "Async ORM inspired by Django ORM"
  - label: "None / Raw SQL"
    description: "Direct SQL or no ORM"

Question 3 — Testing:

question: "Which test framework does this project use?"
header: "Testing"
options:
  - label: "pytest"
    description: "Standard pytest"
  - label: "unittest"
    description: "Python built-in unittest"

Go Projects

Question 1 — Router:

question: "Which HTTP router does this project use?"
header: "Router"
options:
  - label: "chi"
    description: "Lightweight, idiomatic chi ro

…

## Source & license

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

- **Author:** [profburial](https://github.com/profburial)
- **Source:** [profburial/compounding-skills](https://github.com/profburial/compounding-skills)
- **License:** MIT

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