From 778ca84c0824826609dee420997b6030c044cf59 Mon Sep 17 00:00:00 2001 From: Claude Code Bot Date: Fri, 2 Oct 2026 12:50:29 -0700 Subject: [PATCH] chore: ignore .claude/ by default Untrack the generated .claude/ scaffold; the files stay on disk. The template's source is dotfiles git/template/.claude-template/, so point CLAUDE.md and README.md there. Advances #178 --- .claude/README.md | 204 ------------------------------------- .claude/config.sh.template | 175 ------------------------------- .gitignore | 4 + CLAUDE.md | 6 +- README.md | 4 +- 5 files changed, 8 insertions(+), 385 deletions(-) delete mode 100644 .claude/README.md delete mode 100644 .claude/config.sh.template diff --git a/.claude/README.md b/.claude/README.md deleted file mode 100644 index 2267b75..0000000 --- a/.claude/README.md +++ /dev/null @@ -1,204 +0,0 @@ -# Claude Code Infrastructure - Project-Specific - -This directory was automatically created by Git template when you initialized or cloned this repository. - -## What is this? - -The `.claude/` directory provides project-specific configuration and extensions for Claude Code CLI (CCCLI) collaboration. It integrates with global infrastructure at `~/.claude/` to provide: - -- Project-specific configuration (Node version, required tools, deployment secrets) -- Custom git hook extensions for project-specific validation -- Project-local documentation and patterns - -## Directory Structure - -``` -.claude/ -├── README.md # This file -└── config.sh.template # Template for project configuration -``` - -Project-specific hook extensions do **not** live here. They go in -`.project-hooks/` at the repository root — see Option 3 below. - -## Quick Start - -### Option 1: No Additional Configuration Needed - -If your project doesn't need special validation, required secrets, or version constraints, **you're done**! Your project already benefits from global infrastructure: - -- Global git hooks (pre-commit, pre-push) -- Code review automation -- Branch protection -- Standard workflows - -### Option 2: Add Project Configuration - -If you need project-specific settings: - -1. Copy the template: - - ```bash - cp .claude/config.sh.template .claude/config.sh - ``` - -2. Edit `.claude/config.sh` to define: - - Required Node version - - Required tools (EAS, Maestro, jq, etc.) - - Deployment secrets - - Custom pre/post build hooks - -3. Update your build/deploy scripts to source the config: - - ```bash - # In build scripts - source "${HOME}/.claude/lib/build-commons.sh" - [[ -f ".claude/config.sh" ]] && source ".claude/config.sh" - run_preflight_checks - - # In deploy scripts - source "${HOME}/.claude/lib/deploy-commons.sh" - source ".claude/config.sh" - verify_cloudflare_secrets "${DEPLOYMENT_REQUIRED_SECRETS[@]}" - ``` - -### Option 3: Add Custom Hook Extensions - -If you need project-specific validation: - -Extensions live in `.project-hooks/` at the repository root, named for the -git hook they extend. The global hooks run exactly two paths: -`.project-hooks/pre-commit` and `.project-hooks/pre-push`. - -1. Create the file, named for its hook: - - ```bash - mkdir -p .project-hooks - touch .project-hooks/pre-commit - chmod +x .project-hooks/pre-commit - ``` - - The executable bit is the activation switch — a non-executable file is - silently skipped. - -2. Write your validation logic: - - ```bash - #!/usr/bin/env bash - # Extension contract: - # - Exit 0: Check passed (allow git operation) - # - Exit 1: Check failed (block git operation) - - # Your validation logic here - if [[ condition_fails ]]; then - echo "ERROR: Validation failed" - exit 1 - fi - - exit 0 - ``` - -3. The extension then runs on every commit or push, after the global lint - pass and before the AI review. - -## Common Patterns - -### Node.js Project with Version Requirement - -```bash -# .claude/config.sh -export REQUIRED_NODE_VERSION="20" -``` - -### Project with Deployment Secrets - -```bash -# .claude/config.sh -export DEPLOYMENT_REQUIRED_SECRETS=( - "API_KEY" - "DATABASE_URL" - "JWT_SECRET" -) -``` - -### Custom Security Check - -```bash -# .project-hooks/pre-commit -#!/usr/bin/env bash - -# Block commits with hardcoded API keys -if git diff --cached | grep -iE 'API_KEY.*=.*"[A-Za-z0-9]{32}"'; then - echo "ERROR: Hardcoded API key detected" - exit 1 -fi - -exit 0 -``` - -## Integration with Global Infrastructure - -Global hooks at `~/.config/git/hooks/` run project extensions from -`.project-hooks/`, not from this directory. They look for exactly two paths — -`.project-hooks/pre-commit` and `.project-hooks/pre-push` — and run each only -if it is executable. - -Earlier versions of this file claimed the hooks discovered extensions inside -`.claude/hooks/extensions/`. They never did. That scaffold was inert in every -repo that carried it (smartwatermelon/dev-env#110). - -**Global Infrastructure Documentation**: `~/.claude/docs/INFRASTRUCTURE.md` - -## Files Included - -### config.sh.template - -Template for project configuration. Copy to `config.sh` and customize with your project's requirements. - -There is deliberately no example extension file here. This directory once -shipped `hooks/extensions/example.sh.disabled`, which nothing ever executed; -it was removed fleet-wide (smartwatermelon/dev-env#110). Write extensions -directly in `.project-hooks/` instead — see Option 3 above. - -## Next Steps - -1. **Review your needs**: Do you need project-specific configuration or validation? -2. **If yes**: Follow Quick Start Option 2 or 3 above -3. **If no**: You're done! Just start working - -## Documentation - -- **Global Infrastructure**: `~/.claude/docs/INFRASTRUCTURE.md` -- **Build Patterns**: `~/.claude/docs/BUILD_PATTERNS.md` (if exists) -- **Deployment Patterns**: `~/.claude/docs/DEPLOYMENT_PATTERNS.md` (if exists) -- **Hook System**: `~/.claude/docs/HOOKS.md` (if exists) - -## Troubleshooting - -### Extensions not running? - -```bash -# Check the extension exists and is executable -ls -la .project-hooks/ - -# Make executable if needed — this is the activation switch, and a -# non-executable extension is skipped silently -chmod +x .project-hooks/pre-commit .project-hooks/pre-push -``` - -Check the filename too: only `pre-commit` and `pre-push` are run, and only at -the repository root. Any other name is ignored. - -### Config not being used? - -```bash -# Verify config exists and is sourced -ls -la .claude/config.sh - -# Check your build/deploy scripts source it -grep -r "source.*config.sh" scripts/ -``` - -### Need help? - -See global infrastructure documentation at `~/.claude/docs/INFRASTRUCTURE.md` for complete reference. diff --git a/.claude/config.sh.template b/.claude/config.sh.template deleted file mode 100644 index 9a65a0d..0000000 --- a/.claude/config.sh.template +++ /dev/null @@ -1,175 +0,0 @@ -#!/usr/bin/env bash -# Project Configuration Template -# Copy to .claude/config.sh and customize for your project -# -# This file is sourced by: -# - Build scripts (when using build-commons.sh) -# - Deploy scripts (when using deploy-commons.sh) -# - Any other scripts that need project-specific configuration - -# ============================================ -# NODE.JS PROJECTS -# ============================================ - -# Required Node version (used by build-commons.sh) -# Uncomment and set to your required major version -# export REQUIRED_NODE_VERSION="20" - -# Additional required tools beyond standard development tools -# build-commons.sh will verify these are installed -export PROJECT_REQUIRED_TOOLS=( - # "eas" # Expo Application Services (React Native) - # "maestro" # Mobile E2E testing framework - # "jq" # JSON parsing (for CI/CD scripts) - # "wrangler" # Cloudflare Workers CLI -) - -# ============================================ -# DEPLOYMENT CONFIGURATION -# ============================================ - -# Required secrets for deployment (hard-blocks deployment if missing) -# Example: Cloudflare Workers secrets -export DEPLOYMENT_REQUIRED_SECRETS=( - # "API_KEY" - # "DATABASE_URL" - # "JWT_SECRET" -) - -# Optional secrets (warns if missing, doesn't block) -export DEPLOYMENT_OPTIONAL_SECRETS=( - # "SENTRY_DSN" - # "ANALYTICS_KEY" - # "FEATURE_FLAG_KEY" -) - -# Deployment smoke test endpoints (relative to base URL) -# Used by deploy-commons.sh run_endpoint_smoke_tests() -export DEPLOYMENT_SMOKE_TEST_ENDPOINTS=( - # "/health" - # "/api/v1/status" - # "/.well-known/health" -) - -# ============================================ -# BUILD CONFIGURATION -# ============================================ - -# Skip certain checks if needed (use sparingly) -# export SKIP_NODE_VERSION_CHECK=1 -# export SKIP_DEPENDENCY_CHECK=1 - -# Custom npm/yarn/pnpm commands -# export NPM_CLIENT="pnpm" # Default: npm -# export TEST_COMMAND="npm test" -# export BUILD_COMMAND="npm run build" - -# ============================================ -# CUSTOM HOOKS -# ============================================ - -# Pre-build validation (called by build-commons.sh if this function exists) -# Return 0 for success, 1 for failure -pre_build_validation() { - # Add your project-specific validation here - - # Example: Check for uncommitted config changes - # if ! git diff-index --quiet HEAD -- config.json; then - # echo "WARNING: Uncommitted changes in config.json" - # read -p "Continue anyway? (y/N): " -n 1 -r - # echo - # [[ ! ${REPLY} =~ ^[Yy]$ ]] && return 1 - # fi - - # Example: Verify environment variables - # if [[ -z "${REQUIRED_ENV_VAR}" ]]; then - # echo "ERROR: REQUIRED_ENV_VAR not set" - # return 1 - # fi - - return 0 -} - -# Post-build validation (called by build-commons.sh if this function exists) -# Return 0 for success, 1 for failure -post_build_validation() { - # Add your project-specific validation here - - # Example: Check build output - # if [[ ! -f "dist/index.js" ]]; then - # echo "ERROR: Build did not produce expected output" - # return 1 - # fi - - # Example: Run bundle size check - # local bundle_size=$(stat -f%z dist/bundle.js) - # local max_size=$((500 * 1024)) # 500KB - # if [[ ${bundle_size} -gt ${max_size} ]]; then - # echo "WARNING: Bundle size ${bundle_size} bytes exceeds ${max_size} bytes" - # return 1 - # fi - - return 0 -} - -# Pre-deploy validation (called by deploy-commons.sh if this function exists) -# Return 0 for success, 1 for failure -pre_deploy_validation() { - # Add your project-specific validation here - - # Example: Check git status - # if ! git diff-index --quiet HEAD --; then - # echo "ERROR: Uncommitted changes detected" - # echo "Deploy from clean working directory only" - # return 1 - # fi - - # Example: Verify on correct branch - # local current_branch=$(git branch --show-current) - # if [[ "${current_branch}" != "main" ]]; then - # echo "WARNING: Deploying from branch '${current_branch}', not 'main'" - # read -p "Continue? (y/N): " -n 1 -r - # echo - # [[ ! ${REPLY} =~ ^[Yy]$ ]] && return 1 - # fi - - return 0 -} - -# Post-deploy validation (called by deploy-commons.sh if this function exists) -# Return 0 for success, 1 for failure -post_deploy_validation() { - # Add your project-specific validation here - - # Example: Tag deployment - # local version=$(jq -r .version package.json) - # git tag -a "deploy-${version}-$(date +%Y%m%d-%H%M%S)" -m "Deployed version ${version}" - - return 0 -} - -# ============================================ -# PROJECT-SPECIFIC VARIABLES -# ============================================ - -# Add any other project-specific configuration here -# export PROJECT_NAME="my-app" -# export PROJECT_ENV="production" -# export API_BASE_URL="https://api.example.com" - -# ============================================ -# USAGE EXAMPLES -# ============================================ - -# In build scripts: -# source "${HOME}/.claude/lib/build-commons.sh" -# [[ -f ".claude/config.sh" ]] && source ".claude/config.sh" -# run_preflight_checks -# # Your build commands here - -# In deploy scripts: -# source "${HOME}/.claude/lib/deploy-commons.sh" -# source ".claude/config.sh" -# verify_cloudflare_secrets "${DEPLOYMENT_REQUIRED_SECRETS[@]}" -# # Your deploy commands here -# run_endpoint_smoke_tests "${BASE_URL}" "${DEPLOYMENT_SMOKE_TEST_ENDPOINTS[@]}" diff --git a/.gitignore b/.gitignore index 7352d38..aa5c482 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,7 @@ docs/data/corpus-440/results/ # Agent context files are not project content (smartwatermelon/dev-env#155). AGENTS.md + +# Claude Code local state and the generated .claude/ scaffold. +# Share a file by negating it: .claude/* then !.claude/ +.claude/ diff --git a/CLAUDE.md b/CLAUDE.md index fbf57b1..00889b6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,10 +21,8 @@ This repo is the **dev-env infrastructure repository** — it contains documenta - `docs/runbooks/fleet-probe-token-scopes.md` — The two fine-grained-PAT properties a fleet probe needs (`Administration: Read-only` + All-repositories), and why an under-scoped token returns wrong numbers instead of errors - `scripts/org-migration/` — Snapshot/transfer/verify tooling for the 2026-09 org migration; tests in `scripts/org-migration/tests/run-tests.sh` - `scripts/dependabot-digest/` — Collects open Dependabot PRs across all three owners and upserts one digest issue describing the queue; run by `.github/workflows/dependabot-digest.yml`. Credentials (a GitHub App) are installed by hand: see `docs/runbooks/dependabot-digest-credentials.md` -- `.claude/` — Project-specific Claude Code configuration templates - - `.claude/config.sh.template` — Template for project configuration (Node version, required tools, deployment secrets, build/deploy hooks) - - `.project-hooks/pre-commit` and `.project-hooks/pre-push` — Project-specific git hook extensions, run by the global hooks at `~/.config/git/hooks/` when executable - - `.claude/README.md` — Setup guide for using the `.claude/` directory in other projects +- `.project-hooks/pre-commit` and `.project-hooks/pre-push` — Project-specific git hook extensions, run by the global hooks at `~/.config/git/hooks/` when executable +- `.claude/` is ignored, as in every fleet repo (dev-env#178). The scaffold the post-checkout hook drops there (`config.sh.template`, `README.md`) comes from `smartwatermelon/dotfiles` `git/template/.claude-template/`; edit it there. ## Key Concepts diff --git a/README.md b/README.md index 19c8ace..a0478d1 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ It is **not** a tool, framework, or installable package. It does not contain the | [`docs/plans/2026-04-02-phase2-local-whole-codebase-review.md`](./docs/plans/2026-04-02-phase2-local-whole-codebase-review.md) | Phase 2 design — *why* whole-codebase review and *what* it replaces from Seer. | | [`docs/plans/2026-04-02-phase2-implementation.md`](./docs/plans/2026-04-02-phase2-implementation.md) | Phase 2 implementation plan, task by task. | -Plus a `.claude/` directory with project-local Claude Code configuration **templates** (`config.sh.template`, hook extension example) that other repos can copy and customize. See [`.claude/README.md`](./.claude/README.md) for the template setup guide. +The project-local `.claude/` scaffold (`config.sh.template`, `README.md`) is not kept here. It lives in [`smartwatermelon/dotfiles`](https://github.com/smartwatermelon/dotfiles) under `git/template/.claude-template/`, and every fleet repo ignores its copy (dev-env#178). --- @@ -64,7 +64,7 @@ The spec is considered stable. Future work tracked as issues in this repo or in - All content is Markdown — no build step, no tests, no lint commands beyond `markdownlint` - Documents follow the existing structure: design plans use date-prefixed names under `docs/plans/`, reference docs live in `docs/` directly - When updating reference docs, prefer **adding** sections to **rewriting** them — the goal is a permanent record, not a moving target -- The `.claude/` directory contains *templates* meant to be copied into other repos; do not add project-specific values to them +- `.claude/` is ignored; edit the scaffold template in `smartwatermelon/dotfiles`, not here When Claude is making changes here, it follows the same protocols as everywhere else: feature branch, pre-commit review, pre-push codebase review, two-turn merge with `merge-lock auth`. See [`CLAUDE.md`](./CLAUDE.md) for the project-specific guidance Claude receives when working in this repo.