Skip to content

Latest commit

 

History

History
113 lines (89 loc) · 6.44 KB

Configuration.md

File metadata and controls

113 lines (89 loc) · 6.44 KB

🔧 Configuration

Almost everything claude-kit installs is plain, editable config in your repo. Tune it directly.

Environment toggles

Variable Default Effect
CLAUDE_KIT_MIN_COVERAGE 80 Fallback Pest coverage percentage, used only for a project installed before the manifest existed. A current install records its own tests.coverage_min (null = do not enforce).
CLAUDE_KIT_FEATURE_DOCS 1 Set to 0 to disable the "watched code needs a feature doc" Stop-hook gate.
CLAUDE_KIT_CHECKS (unset) Comma-separated subset of pint,phpstan,tests to run only those PHP checks. The Stop hook sets it from the manifest; unset means run everything configured.

Set these in your shell, CI environment, or a hook wrapper.

The .claude/claude-kit.json manifest

The installer records your choices and the hash of every file it published. The runtime gate reads it to know what to run, and claude-kit:update reads it to know what to re-publish and what you have edited since.

{
    "project_name": "Acme",
    "stack": "livewire",
    "pint": true,
    "phpstan": { "enabled": true, "level": 7, "strict": true, "larastan": true, "hook": "block" },
    "tests": { "enabled": true, "tool": "pest", "coverage_min": null, "arch": true },
    "architecture": ["services", "data-objects", "actions", "contracts"],
    "rules": { "clean_code": "balanced", "behavioral": ["anti-overengineering", "anti-assumption"], "worktrees": true },
    "hooks": { "enabled": ["stop", "pre-commit", "feature-docs"], "checks": ["pint", "phpstan", "tests"], "min_passes": 2, "feature_docs": true },
    "agents": ["design-reviewer", "docs-reviewer"],
    "skills": {
        "bundled": ["laravel-best-practices", "pest-testing"],
        "workflow": ["commit", "deploy", "dead-code", "codemap"],
        "deploy_command": "",
        "commit_convention": null
    },
    "output_style": true,
    "scaffolding": ["rules", "docs", "editorconfig", "mcp", "ci"],
    "files": { "CLAUDE.md": "9f2c…", ".claude/rules/clean-code.md": "4ab1…" }
}
Key Meaning
tests.enabled / tests.tool / tests.coverage_min Whether the gate runs tests, with which runner, and the coverage threshold (null = don't enforce).
phpstan.hook block, warn, or off — what the edit-time PHPStan hook does on failure.
hooks.checks Which checks the Stop hook runs (the pre-commit hook and CI always run everything configured).
hooks.min_passes Consecutive clean runs required before a turn may finish (1–5).
hooks.feature_docs Whether the Stop hook requires a feature doc for watched code (the env var overrides it).
commit_convention null = Conventional Commits; a string is your own convention, embedded verbatim.
files sha256 per published file. claude-kit:update compares against it to tell an untouched file from one you edited.

Note

Pint and PHPStan run whenever pint.json / phpstan.neon exist — removing one of those files disables that check. Edit the manifest to change test or hook behaviour without re-running the installer.

Tip

Installed before the manifest moved? The runtime scripts still read a legacy .claude-kit.json at the project root. Run php artisan claude-kit:install once to move it.

What lands in .claude/

.claude/
├── settings.json          hooks + permission allowlist + outputStyle (deep-merged)
├── claude-kit.json        the manifest above
├── rules/                 conventions — loaded automatically
│   ├── architecture-*.md    one per selected layer (path-scoped to app/)
│   ├── clean-code.md        your chosen preset (path-scoped to **/*.php)
│   ├── frontend.md          your stack's rule (path-scoped to its files)
│   ├── anti-*.md            always loaded, no paths
│   └── worktrees.md         always loaded, no paths
├── agents/                design-reviewer · docs-reviewer (read-only)
├── skills/                bundled skills + /commit /deploy /dead-code /codemap
├── output-styles/         concise.md
└── hooks/                 phpstan-check.sh (PostToolUse)

Rules with a paths: glob only enter context when Claude works with matching files; rules without one load every session.

Customising the output

What each file is and how to change it
  • CLAUDE.md — project identity, the gate, and an index of the rules. Content between <!-- claude-kit:begin --> and <!-- claude-kit:end --> is regenerated by claude-kit:update; put your own additions outside the markers.
  • Rules — every file under .claude/rules/ is yours. They ship as claude-kit's opinionated defaults: review them, adapt them to match your codebase, and delete what you do not want.
  • PHPStan — phpstan.neon is generated with the level, Larastan, and strict toggle you chose, analysing app/, database/, and routes/. config/ and bootstrap/app.php are deliberately left out, because Laravel's own shipped config files fail level 7 with strict-rules — widen paths by hand once your config is clean. The edit-time hook reads the same file, so it follows.
  • Pint — pint.json uses the Laravel preset plus a few strict rules.
  • Architecture tests — tests/Arch/ArchTest.php is generated from your layer choices. Add and remove arch() blocks as the app changes.
  • ESLint / Prettier / TypeScript — the stack config files are yours to edit.
  • Skills and agents — everything under .claude/skills/ and .claude/agents/ is editable; add your own alongside them.
  • Permissions & hooks — .claude/settings.json holds the hook wiring and a permission allowlist. Extend it for your project's commands; claude-kit will never remove what you add.

The pre-commit hook

claude-kit sets git config core.hooksPath .githooks during install (composer's post-autoload-dump re-runs it).

git config --unset core.hooksPath   # disable locally
git commit --no-verify              # bypass a single commit

Keeping machinery current

quality-checks.sh and the Stop hook live under vendor/…/runtime/ and update with:

composer update mohamed-ashraf-elsaed/claude-kit

To refresh the copied content (rules, skills, templates), run php artisan claude-kit:update. See Upgrading.


← Usage · 🏠 Home · Frontend stacks →