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: ```bash 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: ```bash 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`:** ```markdown # 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`:** ```markdown # 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`:** ```markdown # 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). ```markdown # {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