Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Empty file added .claude/agents/.gitkeep
Empty file.
56 changes: 56 additions & 0 deletions .claude/hooks/ask-outside-repo.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
#!/usr/bin/env bash
set -euo pipefail

# Symlinks and .. are resolved before comparison so that a path inside the
# repository cannot be used to reach outside it.
ask() {
local reason="$1"

jq -n --arg reason "$reason" '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "ask",
permissionDecisionReason: $reason
}
}'
exit 0
}

allow() {
exit 0
}

input="$(cat)"
file_path="$(jq -r '.tool_input.file_path // .tool_input.notebook_path // empty' <<<"$input")"

if [[ -z "$file_path" ]]; then
allow
fi

project_dir="${CLAUDE_PROJECT_DIR:-$(jq -r '.cwd // empty' <<<"$input")}"

if [[ -z "$project_dir" ]]; then
ask "Cannot determine the repository root, so this write cannot be confirmed as inside it."
fi

resolved_project="$(realpath -m -- "$project_dir")"

if [[ "$file_path" != /* ]]; then
file_path="$resolved_project/$file_path"
fi

resolved_target="$(realpath -m -- "$file_path")"

if [[ "$resolved_target" == "$resolved_project" || "$resolved_target" == "$resolved_project"/* ]]; then
allow
fi

# Background jobs get a sanctioned scratch directory outside the repository.
if [[ -n "${CLAUDE_JOB_DIR:-}" ]]; then
resolved_job_dir="$(realpath -m -- "$CLAUDE_JOB_DIR")"
if [[ "$resolved_target" == "$resolved_job_dir"/* ]]; then
allow
fi
fi

ask "$resolved_target is outside the repository at $resolved_project."
14 changes: 14 additions & 0 deletions .claude/hooks/block-config-change.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
#!/usr/bin/env bash
set -euo pipefail

# A session must not grant itself new permissions. Blocking here stops an
# edited settings or skill file from hot-reloading into the running session;
# the edit stays on disk for review and takes effect on the next session.
input="$(cat)"
source_type="$(jq -r '.source // "unknown"' <<<"$input")"
file_path="$(jq -r '.file_path // "unknown file"' <<<"$input")"

jq -n --arg reason "Blocked mid-session reload of $source_type ($file_path). The edit is still on disk: review the diff and start a new session to apply it." '{
decision: "block",
reason: $reason
}'
35 changes: 35 additions & 0 deletions .claude/hooks/session-start.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
#!/usr/bin/env bash
set -euo pipefail

# Stdout becomes session context for the agent. Runs on startup, resume,
# clear, and compact, so it must stay fast.
cd "${CLAUDE_PROJECT_DIR:-.}"

# Install the pre-commit hook once per clone so agent commits are checked.
if [[ -f .pre-commit-config.yaml && ! -f .git/hooks/pre-commit ]] \
&& command -v pre-commit >/dev/null 2>&1; then
pre-commit install >/dev/null 2>&1 || true
fi

if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
branch="$(git branch --show-current 2>/dev/null || true)"
echo "Branch: ${branch:-(detached HEAD)}"

# head closes the pipe once it has its 20 lines, so git dies of SIGPIPE on a
# large working tree and pipefail propagates 141. Without the `|| true` that
# exit status ends the hook under `set -e`, and the branch, commits, and
# documentation reminder below are all lost — on exactly the messy tree that
# needs them most.
status="$(git status --short 2>/dev/null | head -20 || true)"
if [[ -n "$status" ]]; then
echo "Uncommitted changes:"
echo "$status"
else
echo "Working tree clean."
fi

echo "Recent commits:"
git log --oneline -5 2>/dev/null || echo "(no commits yet)"
fi

echo "Read the nearest CLAUDE.md above every path you touch before editing, and update the owning docs after meaningful changes. The full documentation contract is .claude/rules/documentation.md."
Empty file added .claude/output-styles/.gitkeep
Empty file.
93 changes: 93 additions & 0 deletions .claude/rules/documentation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Documentation Framework

Rules to keep core contract

- `CLAUDE.md` files are binding work contracts for their subtrees
- `CLAUDE.md` files are aligned with repo structure, workflows, and durable conventions.
- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable `CLAUDE.md` plus every t `CLAUDE.md` above it
- Agent must follow these instructions across all edits and writes

## Read Before Editing

1. Read the root `CLAUDE.md`
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every `CLAUDE.md` found along each route
5. If a parent `CLAUDE.md` lists a child `CLAUDE.md` whose scope contains the path, read that child and continue from there
6. Use the nearest `CLAUDE.md` as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken the system

Do not rely on memory. Re-read the applicable `CLAUDE.md` chain in the current session before editing.

## Update After Editing

Every meaningful change requires a documentation pass before the task is done. A meaningful change is one that changes durable behavior, structure, workflow, ownership, commands, interfaces, or conventions.

Update the closest owning `CLAUDE.md` when a change affects:

- purpose, scope, ownership, or responsibilities
- durable structure, contracts, workflows, or operating rules
- required inputs, outputs, permissions, constraints, side effects, or artifacts
- durable user preferences that should affect future work in this repo
- `CLAUDE.md` creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the document pass still must happen.

## Hierarchy

- Root `CLAUDE.md` Answers the question, "How should an unfamiliar coding agent make a correct, minimal, verifiable change without introducing bugs? Typically carries project-wide instructions, global preferences, durable workflow rules, and the top-level Child Index
- Child `CLAUDE.md` files own domain-specific instructions and their own Child Index
- Each parent explains what its direct children cover and what stays owned by the parent
- The closer a doc is to the work, the more specific and practical it must be

## Child CLAUDE.md Shape

- Create a child `CLAUDE.md` when a folder becomes a durable boundary with its own purpose, ownership, rules, responsibilities, workflow, materials, or quality standards
- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

Default section order:

- Purpose
- Ownership
- Local Contracts
- Work Guidance
- Verification
- Child Index

**Note:** Root `CLAUDE.md` is exempt from the child document shape. It may evolve as the project-wide documentation contract changes, but it must remain concise and operational.

## Style

- Keep docs concise, current, and operational
- Document stable contracts, not diary entries
- Put broad rules in parent docs and concrete details in child docs
- Prefer direct bullets with explicit names
- Do not duplicate rules across many files unless each scope needs a local version
- Delete stale notes instead of explaining history
- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

## Delegation

- Built-in Explore and Plan subagents do not load `CLAUDE.md`. When delegating to them, restate the documentation obligations that apply to the delegated work in the prompt, or use a custom subagent, which does load `CLAUDE.md`.

## Closeout

1. Re-check changed paths against the chain of `CLAUDE.md` files
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child Index
4. Remove stale or contradictory text
5. Run existing verification when relevant
6. Report any docs intentionally left unchanged and why

## User Preferences

When the user requests a durable behavior change, record it in the relevant `CLAUDE.md`

## Continuous improvement

When you discover a recurring repo-specific mistake, stale doc, missing command, missing script, or missing convention that would help future agents, propose a minimal update to the closest `CLAUDE.md` Do not add broad rules from one-off incidents.

## Lessons Learned

For critical lessons learned regarding this repo, refer to docs/lessons.md. This file contains the "hard-won" knowledge required to avoid common repo-specific pitfalls.
108 changes: 108 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [],
"ask": [
"Bash(git push:*)",
"Bash(git reset --hard:*)",
"Bash(git clean:*)",
"Bash(git rebase:*)",
"Bash(gh pr create:*)",
"Bash(gh pr merge:*)",
"Bash(gh release:*)",
"Bash(gh repo delete:*)",
"Read(.env)",
"Read(.env.local)",
"Read(.env.*.local)",
"Read(.env.development)",
"Read(.env.staging)",
"Read(.env.production)",
"Read(.env.test)",
"Read(*.pem)",
"Read(*.key)",
"Read(id_rsa*)",
"Read(*.p12)",
"Read(*.pfx)",
"Read(credentials.json)",
"Read(service-account*.json)",
"Read(.npmrc)",
"Read(.pypirc)",
"Read(*.tfstate)",
"Read(*.tfstate.*)",
"Edit(.env)",
"Edit(.env.local)",
"Edit(.env.*.local)",
"Edit(.env.development)",
"Edit(.env.staging)",
"Edit(.env.production)",
"Edit(.env.test)",
"Edit(*.pem)",
"Edit(*.key)",
"Edit(id_rsa*)",
"Edit(*.p12)",
"Edit(*.pfx)",
"Edit(credentials.json)",
"Edit(service-account*.json)",
"Edit(.npmrc)",
"Edit(.pypirc)",
"Edit(*.tfstate)",
"Edit(*.tfstate.*)",
"Edit(.*)",
"Edit(.*/**)",
"Edit(**/.*)",
"Edit(**/.*/**)"
],
"deny": [],
"additionalDirectories": []
},
"env": {},
"plansDirectory": "./docs/plans",
"allowedHttpHookUrls": [],
"disableClaudeAiConnectors": true,
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh",
"args": []
}
]
}
],
"PreToolUse": [
{
"matcher": "Edit|Write|NotebookEdit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/ask-outside-repo.sh",
"args": []
}
]
}
],
"ConfigChange": [
{
"matcher": "project_settings|local_settings|skills",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-config-change.sh",
"args": []
}
]
}
]
},
"sandbox": {},
"attribution": {
"commit": "",
"pr": "",
"sessionUrl": false
},
"enabledPlugins": {},
"modelOverrides": {},
"skillOverrides": {}
}
Empty file added .claude/skills/.gitkeep
Empty file.
Empty file added .claude/workflows/.gitkeep
Empty file.
34 changes: 34 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# LF in the repo and in every working tree, all platforms.
* text=auto eol=lf

# Windows scripts need CRLF to execute correctly.
*.bat text eol=crlf
*.cmd text eol=crlf

# SVG is markup; keep it diffable and reviewable.
*.svg text

# Name the enclosing function or heading in diff hunk headers.
# Only Git's built-in drivers work; an unknown name is silently ignored.
*.md diff=markdown
*.py diff=python
*.go diff=golang
*.rs diff=rust
*.sh diff=bash
*.java diff=java
*.rb diff=ruby

# Lockfiles are generated, so line-wise merging can silently produce a
# dependency set no resolver ever validated. Conflict instead, then take
# one side and regenerate. linguist-generated collapses them on GitHub.
package-lock.json merge=binary linguist-generated
pnpm-lock.yaml merge=binary linguist-generated
yarn.lock merge=binary linguist-generated
Cargo.lock merge=binary linguist-generated
go.sum merge=binary linguist-generated
uv.lock merge=binary linguist-generated

# GitHub language statistics.
**/docs/** linguist-documentation
generated/** linguist-generated
vendor/** linguist-vendored
Loading
Loading