project-setup

One-time interactive setup to configure a project for autonomous development.

Purpose

Create CLAUDE.md and all project configuration files in .claude/ through an interactive process with auto-detection.

Execution Steps

Step 1: Check for Existing Configuration

First, check if configuration already exists:

ls CLAUDE.md .claude/testing.md .claude/code-standards.md .claude/architecture.md 2>/dev/null

If CLAUDE.md and all 3 config files (testing.md, code-standards.md, architecture.md) exist, inform the user:

Project already configured. CLAUDE.md and config files exist in .claude/. To reconfigure, delete CLAUDE.md and .claude/ then run /project-setup again.

Otherwise, continue with setup.

Step 2: Auto-Detect Project Type

Scan the project root for configuration files to detect the tech stack:

Check for these files (in parallel):

• composer.json → PHP/Laravel/Symfony
• package.json → Node.js/React/Vue/Next.js
• Cargo.toml → Rust
• go.mod → Go
• pyproject.toml or requirements.txt → Python
• Gemfile → Ruby/Rails
• pom.xml or build.gradle → Java
• *.csproj or *.sln → .NET

For each detected file, extract:

• Framework and version
• Testing framework (from devDependencies or test config)
• Linting/formatting tools

Example auto-detection output:

Detected project configuration:
- Framework: Laravel 11 (from composer.json)
- PHP Version: 8.3
- Testing: Pest PHP (from composer.json require-dev)
- Linting: Laravel Pint (from composer.json require-dev)

Step 3: Confirm Detection

Ask user to confirm detected configuration:

I detected the following. Is this correct? (y/n) [Show detected config]

If incorrect, ask clarifying questions about each incorrect item.

Step 4: Gather Additional Information

Ask these questions (skip if already detected):

Q1: Test Command

What command runs your tests? Detected: ./vendor/bin/pest [Enter to confirm or type custom]

Q1b: Parallel Test Command

Does your test runner support parallel execution? If so, what's the command? (e.g., ./vendor/bin/pest --parallel, npm test -- --parallel, pytest -n auto, go test ./... -parallel 4) [Enter detected parallel command, type custom, or 'none' if not supported]

Auto-detect hints:

• composer.json has brianium/paratest or pestphp/pest → suggest {test command} --parallel
• package.json has jest → suggest {test command} --runInBand is serial, default is already parallel
• package.json has vitest → already parallel by default
• pytest with pytest-xdist → suggest pytest -n auto
• go test → suggest go test ./... -parallel {num}
• cargo test → already parallel by default

Q2: Lint Command

What command runs your linter? Detected: ./vendor/bin/pint [Enter to confirm or type custom]

Q3: Architectural Patterns

Which patterns does this project use? (select all that apply)

• Repository pattern
• Service classes
• Form requests / DTOs
• Event sourcing
• CQRS
• Other (specify)

Q4: Code Standards

Any specific coding standards or style guides? Detected: PSR-12 [Enter to confirm or specify]

Q5: Coverage Requirements

Minimum test coverage percentage? (e.g., 80) Default: 80

Step 5: Open-Ended Project Dump

Offer the user a chance to provide additional context:

Tell me anything else about your project I should know.

You can paste:

• README content
• Architecture decisions
• Naming conventions
• Special requirements
• Team preferences

(Paste below, then type 'done' on a new line when finished, or 'skip' to skip)

Parse the dump for:

• Directory structure descriptions
• Naming conventions
• Special patterns or rules
• Integration details

Step 6: Create Configuration Files

Create the .claude/ directory and all config files:

mkdir -p .claude

Note: The templates below show the minimum required sections. Expand each file with additional relevant details based on project complexity. For example, a framework project might include extensive architecture docs, while a simple app might stick closer to the minimum.

Create .claude/testing.md:

# Testing Configuration

## Test Framework
{detected framework}

## TDD Methodology

Each task follows strict Red → Green → Refactor:

1. Write failing test for one requirement
2. Write minimum code to pass
3. Refactor while tests stay green
4. Repeat for next requirement
5. Commit when task complete

## Commands
\`\`\`bash
# Run all tests (parallel)
{parallel test command, or test command if parallelism not supported}

# Run all tests (sequential, for debugging failures)
{test command}

# Run specific test file
{test command} {path placeholder}

# Run with coverage
{test command with coverage flag}
\`\`\`

## Parallel Execution
- **Default**: Always run tests in parallel unless debugging a specific failure
- Parallel command: `{parallel test command}`
- Sequential fallback: `{test command}` (use only when parallel causes flaky failures)

## Test File Locations
- Unit tests: `{detected or standard path}`
- Feature/Integration tests: `{detected or standard path}`

## Coverage Requirements
- Minimum: {specified}%
- New code must have tests

## Test Naming Convention
- Test files: `{Convention}Test.php` or `{convention}.test.ts`
- Test methods: `it {does something}` or `test {something}`

Optional expansions: Testing principles, framework-specific features, common test patterns, mocking strategies, CI configuration.

Create .claude/code-standards.md:

# Code Standards

## Style Guide
{detected or specified - e.g., PSR-12, Airbnb, StandardJS}

## Linting
\`\`\`bash
# Check for issues
{lint check command}

# Auto-fix issues
{lint fix command}
\`\`\`

## Formatting
\`\`\`bash
{format command if different from lint}
\`\`\`

## Pre-commit Checks
- Run linter before commits
- All tests must pass
- {any additional checks}

## Naming Conventions
- Classes: {PascalCase}
- Methods: {camelCase}
- Variables: {camelCase}
- Constants: {SCREAMING_SNAKE_CASE}
- Files: {convention}

Optional expansions: Code structure rules, attribute/decorator standards, documentation standards, pre-commit hooks, code review checklist.

Create .claude/architecture.md:

# Architecture

## Directory Structure
{Map out the key directories and their purposes}

Example:
- `app/Models/` - Eloquent models
- `app/Services/` - Business logic services
- `app/Http/Controllers/` - HTTP request handlers
- `app/Http/Requests/` - Form request validation
- `tests/Unit/` - Unit tests (mirror app/ structure)
- `tests/Feature/` - Integration/feature tests

## Patterns Used
{List from user selection}
- Repository pattern: {yes/no + brief description}
- Service classes: {yes/no + brief description}
- etc.

## Conventions
{From user dump or defaults}
- One class per file
- Tests mirror source structure
- {any other conventions}

## Key Integrations
{If mentioned in dump}

Optional expansions: DI/IoC details, plugin/extension system, event system, routing, configuration, bootstrap process, error handling, versioning strategy.

Pipeline enrollment (nothing to scaffold):

Pipeline agents enroll via their own frontmatter (phase:), so a fresh setup already has a working pipeline from the plugin's bundled agents — nothing to scaffold here. devils-advocate runs at post-plan; standards-enforcer ships dormant (uncomment its phase to enable). See HOOKS.md. Running hooks/discover-hooks.sh prints exactly what is enrolled at each hook.

Tell the user:

Pipeline ready. devils-advocate is enrolled at the post-plan hook via its own agent frontmatter, so it runs automatically when you create a plan. standards-enforcer ships with HCF but is dormant — uncomment its phase key in the agent's frontmatter to enable code-standards enforcement on changed files. To add your own gate, drop an agent file in .claude/agents/ and give it a phase (one of the 8 hook points). A local agent with the same name overrides the plugin's. See HOOKS.md for the full hook list and frontmatter schema. To see what is currently enrolled at each hook, run $(claude plugin path hcf)/hooks/discover-hooks.sh — that is the fastest answer whenever an agent doesn't fire.

Advanced configuration note: .claude/hcf.json is an optional, user-owned file (its only key today is plansDir). Setup never creates it, never modifies it, and never asks about it. If one already exists, leave it exactly as it is. Its absence is the normal case — do not mention it to the user during setup.

Create CLAUDE.md in project root:

This file provides always-on context for every Claude session. Keep it concise (~30-50 lines).

# {Project Name}

{Brief 1-2 sentence description of the project.}

## Feature Development

For any feature or change beyond a simple fix, use the `hcf:plan-create` skill to trigger the autonomous development workflow. Never use Claude Code's built-in plan mode. After writing a plan, ask the user if they want to execute it, and provide the command to run it later with the `hcf:plan-orchestrate` skill.

Use this workflow for: new features, multi-file changes, anything requiring multiple steps or tests.

Skip for: quick bug fixes, single-line changes, questions, documentation. When skipped, still ensure appropriate tests exist for any added functionality.

## Tech Stack

- **Language**: {language} {version}
- **Framework**: {framework if applicable}
- **Testing**: {test framework}
- **Linting**: {linter/formatter}

## Core Principles

{Extract 3-5 key principles from user input or your judgment. These should be always-true rules that affect how code is written.}

## Project Structure

{Brief 3-5 line summary of directory structure from architecture.md}

## Commands

\`\`\`bash
# Run tests
{test command}

# Lint/format
{lint command}

# Start dev server (if applicable)
{start command or remove this line}
\`\`\`

## Key Rules

{5-10 bullet points of critical coding rules extracted from code-standards.md and user input}

## Detailed Configuration

Project configuration files are in `.claude/`:
- `architecture.md` - Technical patterns and structure
- `testing.md` - Test configuration and commands
- `code-standards.md` - Coding conventions

Step 7: Confirm Completion

After creating all files, output:

✓ Created CLAUDE.md
✓ Created .claude/testing.md
✓ Created .claude/code-standards.md
✓ Created .claude/architecture.md

Project configured for autonomous development!

Next steps:
1. Review CLAUDE.md and the generated files in .claude/
2. Customize the pipeline by enrolling agents via frontmatter — set a `phase` on an agent in .claude/agents/ to add a gate, or remove a `phase` to drop one (see HOOKS.md)
3. Describe a feature to start planning: "Help me implement..."
4. The plan-create skill will auto-trigger to help you plan

Error Handling

• If unable to detect project type: Ask user to specify manually
• If file creation fails: Report error and suggest checking permissions
• If user provides conflicting information: Ask for clarification

Idempotency

• Check for existing CLAUDE.md and .claude/ config before running
• Never overwrite existing files without explicit confirmation
• Offer to update individual files if some exist