diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..a3dbf40 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,129 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "defaultMode": "default", + "deny": [ + "Bash(gh pr merge*)", + "Bash(gh pr review --approve*)", + "Bash(gh pr review -a*)", + "Bash(gh pr close*)", + + "Bash(git push * main)", + "Bash(git push * main *)", + "Bash(git push * master)", + "Bash(git push * master *)", + "Bash(git push --force *)", + "Bash(git push -f *)", + "Bash(git reset --hard*)", + "Bash(git clean -f*)", + "Bash(git branch -D *)", + "Bash(git checkout -- .)", + "Bash(git restore .)", + + "Bash(rm -rf *)", + "Bash(rm -r *)", + "Bash(sudo *)", + "Bash(chmod 777 *)", + "Bash(curl * | sh*)", + "Bash(curl * | bash*)", + "Bash(wget * | sh*)", + "Bash(wget * | bash*)", + + "Edit(~/.ssh/**)", + "Edit(~/.aws/**)", + "Edit(~/.gnupg/**)", + "Edit(~/.config/gh/**)", + "Write(~/.ssh/**)", + "Write(~/.aws/**)", + "Write(~/.gnupg/**)", + "Write(~/.config/gh/**)" + ], + "allow": [ + "Read", + "Glob", + "Grep", + "WebFetch", + "WebSearch", + "Task", + + "Edit(/**)", + "Write(/**)", + + "Bash(git status*)", + "Bash(git log*)", + "Bash(git diff*)", + "Bash(git add *)", + "Bash(git commit *)", + "Bash(git checkout *)", + "Bash(git switch *)", + "Bash(git branch*)", + "Bash(git fetch*)", + "Bash(git pull*)", + "Bash(git stash*)", + "Bash(git show *)", + "Bash(git rev-parse *)", + "Bash(git remote *)", + "Bash(git merge *)", + "Bash(git rebase *)", + "Bash(git cherry-pick *)", + "Bash(git push --force-with-lease *)", + "Bash(git push *)", + + "Bash(cargo build*)", + "Bash(cargo test*)", + "Bash(cargo check*)", + "Bash(cargo clippy*)", + "Bash(cargo fmt*)", + "Bash(cargo doc*)", + "Bash(cargo run*)", + "Bash(cargo clean*)", + "Bash(cargo tree*)", + "Bash(cargo metadata*)", + "Bash(cargo bench*)", + + "Bash(make *)", + "Bash(make)", + + "Bash(gh pr view *)", + "Bash(gh pr list*)", + "Bash(gh pr diff *)", + "Bash(gh pr checks *)", + "Bash(gh pr status*)", + "Bash(gh issue view *)", + "Bash(gh issue list*)", + "Bash(gh issue create *)", + "Bash(gh api *)", + + "Bash(docker build *)", + "Bash(docker run *)", + "Bash(docker compose *)", + "Bash(docker ps*)", + "Bash(docker images*)", + "Bash(docker logs *)", + + "Bash(ls *)", + "Bash(ls)", + "Bash(pwd)", + "Bash(which *)", + "Bash(echo *)", + "Bash(wc *)", + "Bash(sort *)", + "Bash(head *)", + "Bash(tail *)", + "Bash(mkdir *)", + "Bash(cp *)", + "Bash(mv *)", + "Bash(cat *)", + "Bash(date*)", + "Bash(env)", + "Bash(printenv *)", + "Bash(basename *)", + "Bash(dirname *)", + "Bash(realpath *)", + "Bash(touch *)", + "Bash(file *)", + + "Bash(rm /tmp/*)" + ] + } +} diff --git a/.gitignore b/.gitignore index bcdbb83..b6e13a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,4 @@ .idea/ target/ bin/ -CLAUDE.md .output.txt -/.claude/settings.json diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7097588 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,118 @@ + AGENT SAFEGUARDS (non-negotiable) + +Operating principles +1) Prefer clear code over comments. + - Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express. + - Prefer descriptive names, small functions, and explicit types over commentary. + +2) Solve root cause, not band-aids. + - Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix. + - If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now. + +3) Use idioms of the language and ecosystem. + - Follow standard style guides, conventions, directory layout, and tooling. + - Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions. + +Quality gates +4) Tests must run after each modification. + - After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes. + - If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required. + - Never leave the repo in a state where tests are known failing. + +5) Documentation for all features. + - Every new feature must have usage docs + one runnable example. + - Docs must include intent, flags/config, and failure modes. + - Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets. + +6) Update CHANGELOG with all changes. + - Every user-visible change must be added to CHANGELOG.md under “Unreleased”. + - Use categories: Added / Changed / Fixed / Security / Deprecated / Removed. + - Mention migration steps if behavior changes. + +Robustness & correctness +7) Include error handling everywhere it matters. + - Never ignore errors; propagate with context. + - Wrap/annotate errors so the caller has actionable info. + - Ensure exit codes/return values are correct and consistent. + +8) Test edge cases and invariants. + - Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant. + - Include at least one test for each bug fixed to prevent regressions. + +Security & safety (important for agentic tooling) +9) No harmful actions by default. + - Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested. + - Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags. + +10) Least privilege and safe defaults. +- Minimize permissions, capabilities, scopes, and access tokens. +- For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified. + +11) No secret leakage. +- Never print tokens, passwords, or full credential material to logs. +- Redact known secret patterns; avoid echoing env vars that might contain secrets. + +12) Deterministic builds and reproducibility. +- Prefer pinned versions, lockfiles, and deterministic packaging. +- Avoid “download latest at build time” unless necessary. + +Change management rules +13) Small, reviewable diffs. +- Prefer incremental changes with clear commit boundaries. +- If a refactor is needed, do it in a separate commit/PR before feature changes. + +14) Respect existing standards and tooling. +- Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.). +- If tooling is missing, add it in a minimal conventional way. + +15) Provide a “How to verify” section in PR descriptions/output. +- Include exact commands: build, lint, unit tests, integration tests (if any). + +Agent execution constraints (for local runners / GH actions) +16) Only modify files that are in-scope for the task. +- Do not reformat unrelated files. +- Do not introduce new dependencies unless justified. + +17) When uncertain, choose the safer option and make it explicit. +- Prefer failing fast with actionable errors over silent fallback. +- If ambiguity remains, implement a guardrail and document the decision. + +18) When really uncertain, ask for help. +- Avoid making assumptions without asking for confirmation. + +19) When running locally, prefer the mcp edit tool to direct file edits. +- If issues arise where files seems unedited, alert the user before continuing + +20) Prefer bash commands/scripts to python3 when investigating + +Definition of implement issue +- Find the issue in github issues. +- If not found, inform the user. +- If found: + - Fetch the git origin + - Create a branch with the issue number in the name from origin/main. + - Implement the issue. + - Run all e2e tests. + - If during implementation, obvious errors was found in the ooriginating issue, also add a comment to the issue about the fix. + - If running from Claude Code or Claude Desktop: + - Do NOT create a PR automatically. + - Instead, present a summary of changes and let the user decide when to create the PR. + - Otherwise (e.g. GitHub Copilot, Junie, or other automated agents): + - Create a PR with the issue number in the title. + - Make sure the PR passes CI. + +Definition of done +- Code compiles without warnings. +- Code is linted. +- Code is formatted. +- Tests pass. +- Docs updated. +- CHANGELOG updated. +- Edge cases tested. +- Security posture maintained. +- Output includes a concise summary of changes + how to verify. +- For rust code: + - All unsafe code is annotated. + - Use explicit lifetimes where necessary. + - Use clippy lints. +