From 153bd5211c36f0ac189abfe1bbaf51a4557e4546 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 19:00:24 +0200 Subject: [PATCH 1/8] chore: sync shared ai prompts --- .agents/skills/.gitignore | 2 + .agents/skills/open-pr/SKILL.md | 120 ++++++++++++++++++ .agents/skills/plan/SKILL.md | 98 +++++++++++++++ .agents/skills/product-think/SKILL.md | 68 +++++++++++ .agents/skills/rabbit-round/SKILL.md | 76 ++++++++++++ .agents/skills/regression-hunt/SKILL.md | 76 ++++++++++++ .agents/skills/security-audit/SKILL.md | 77 ++++++++++++ .ai/local-skills/.gitkeep | 0 .ai/local/agents.md | 20 +++ .ai/manifest.json | 14 +++ .ai/shared | 1 + .claude/commands/.gitignore | 2 + .claude/commands/open-pr.md | 115 ++++++++++++++++++ .claude/commands/plan.md | 93 ++++++++++++++ .claude/commands/product-think.md | 63 ++++++++++ .claude/commands/rabbit-round.md | 71 +++++++++++ .claude/commands/regression-hunt.md | 71 +++++++++++ .claude/commands/security-audit.md | 72 +++++++++++ .github/workflows/ai-sync.yml | 21 ++++ .gitmodules | 3 + AGENTS.md | 154 ++++++++++++++++++++++++ CLAUDE.md | 6 + GEMINI.md | 5 + package.json | 6 +- scripts/link-codex-skills.sh | 10 ++ scripts/sync-ai-skills.sh | 10 ++ 26 files changed, 1252 insertions(+), 2 deletions(-) create mode 100644 .agents/skills/.gitignore create mode 100644 .agents/skills/open-pr/SKILL.md create mode 100644 .agents/skills/plan/SKILL.md create mode 100644 .agents/skills/product-think/SKILL.md create mode 100644 .agents/skills/rabbit-round/SKILL.md create mode 100644 .agents/skills/regression-hunt/SKILL.md create mode 100644 .agents/skills/security-audit/SKILL.md create mode 100644 .ai/local-skills/.gitkeep create mode 100644 .ai/local/agents.md create mode 100644 .ai/manifest.json create mode 160000 .ai/shared create mode 100644 .claude/commands/.gitignore create mode 100644 .claude/commands/open-pr.md create mode 100644 .claude/commands/plan.md create mode 100644 .claude/commands/product-think.md create mode 100644 .claude/commands/rabbit-round.md create mode 100644 .claude/commands/regression-hunt.md create mode 100644 .claude/commands/security-audit.md create mode 100644 .github/workflows/ai-sync.yml create mode 100644 .gitmodules create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md create mode 100755 scripts/link-codex-skills.sh create mode 100755 scripts/sync-ai-skills.sh diff --git a/.agents/skills/.gitignore b/.agents/skills/.gitignore new file mode 100644 index 0000000..5e4552b --- /dev/null +++ b/.agents/skills/.gitignore @@ -0,0 +1,2 @@ +# Generated by sync-ai-skills.sh. +# Keep this file so the directory exists even when no commands are synced yet. diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md new file mode 100644 index 0000000..f22e6d5 --- /dev/null +++ b/.agents/skills/open-pr/SKILL.md @@ -0,0 +1,120 @@ +--- +name: open-pr +description: "Prepare the current worktree branch for a pull request: rebase, self-review, quality checks, and open a draft PR." +--- + +# Open PR + +Prepare the current worktree branch for a pull request: rebase, +self-review, quality checks, and open a draft PR. + +## Instructions + +1. **Verify you are on an isolated feature branch**: + + ```bash + CURRENT=$(git branch --show-current) + if [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then + echo "Error: /open-pr must not run from the default branch." + exit 1 + fi + ``` + + If on main, abort and ask the user which feature branch to + use. + + Check whether the current checkout is safe to use for PR prep: + + ```bash + git status --short + ``` + + If the checkout is the user's shared root checkout, has + unrelated local changes, or the work spans multiple repos or + submodules, stop and move to clean worktree(s) before rebasing + or committing. Create the worktree from the current feature + branch and continue the rest of this skill there; do not + rewrite history in the dirty root checkout. + +2. **Bootstrap the worktree before trusting failures**: + + Before running lint, typecheck, tests, or hooks, verify that + the worktree actually has the repo toolchain available + (`bun`, workspace dependencies, `turbo`, `oxlint`, project + bins, and env links if the repo expects them). + + If the worktree is missing the toolchain, run the repo's + normal install/setup flow first, then rerun the same command. + Do not treat missing-bin or module-resolution failures as + product-code regressions. Keep setup-only churn such as + accidental lockfile changes out of the PR unless the task + explicitly requires them. + +3. **Rebase onto remote main**: + + ```bash + git fetch origin main + git rebase origin/main + ``` + + If conflicts arise, resolve them. After resolving, continue + the rebase. If a conflict is ambiguous, ask the user. + +4. **Self-review against CLAUDE.md conventions**: + + Get the full diff against main: + + ```bash + git diff origin/main --name-only + ``` + + Read every changed file in full. Review against the + conventions in CLAUDE.md (TypeScript strictness, error + handling, security, naming, i18n, patterns). Fix any + violations directly; don't just list them. Commit fixes + separately with `fix: address self-review findings`. + +5. **Run all quality checks**: + + ```bash + bun run lint \ + && bun run format \ + && bun run typecheck \ + && bun run test + ``` + + If any check fails, fix the issue and re-run. Commit fixes + with `fix: lint/format/type errors`. + +6. **Security audit**: + + Run `/security-audit`. Fix any critical or high findings + in files changed in this PR before opening it. + Commit fixes with `fix: address security audit findings`. + +7. **Open the PR as draft**: + + Push the branch and create the PR as a **draft**: + + ```bash + git push --force-with-lease -u origin HEAD + gh pr create --fill --draft + ``` + + If `--fill` produces a poor title/body, write a proper one + following Conventional Commits (`feat:`, `fix:`, etc.) with + a very concise summary. Do not add a separate test plan unless + the user explicitly asks for one. Do not mention deployment + choices or attribute the motivation for the PR to a specific + person's feedback, request, or experience. + + This repository is public. Never include marketing language, + internal business context, pricing, competitive analysis, + user identities, conversation specifics, deployment specifics, + or security architecture beyond what the diff obviously shows. + Do not add details that would help a motivated attacker exploit + the code, especially a vulnerable previous version being fixed. + Assume the PR may be read by hostile adversaries, not only + friendly collaborators. When sensitive context would improve + readability, omit it by default; ask the user only if omission + would make the PR hard to review. diff --git a/.agents/skills/plan/SKILL.md b/.agents/skills/plan/SKILL.md new file mode 100644 index 0000000..fd5b535 --- /dev/null +++ b/.agents/skills/plan/SKILL.md @@ -0,0 +1,98 @@ +--- +name: plan +description: 'Create a new implementation plan in the repo''s planning area.' +--- + +# Create Plan + +Create a new implementation plan in the repo's planning area. + +## Arguments + +$ARGUMENTS — A short slug for the plan, ideally kebab-case. If empty, +derive a reasonable slug from the task. + +## Conventions + +Prefer this shared planning layout when the repo supports it: + +```text +.agents/ARCHITECTURE.md +.agents/GOALS.md +.agents/STATUS.md +.agents/plans/ +``` + +If the repo uses a different planning area, adapt to it rather than +creating duplicate systems. + +## Instructions + +1. **Read planning context**: + - `.agents/ARCHITECTURE.md` if present + - `.agents/GOALS.md` if present + - recent related plans if present + +2. **Determine the plan location**: + - prefer `.agents/plans/` + - if that directory does not exist, create it only if the repo is + clearly adopting the shared planning convention + - otherwise ask or use the repo's existing planning area + +3. **Determine the next plan number**: + + ```bash + ls .agents/plans/ + ``` + + Use the next sequential number when numbered plans are already in use. + If the repo does not number plans, follow its established naming. + +4. **Research before writing**: + - inspect the existing code + - read the relevant modules + - understand constraints, patterns, and likely blast radius + +5. **Write the plan** with this structure: + + ```markdown + # Plan: [Feature Name] + + Date: YYYY-MM-DD + + ## Goal + + What are we building and why? + + ## Design Decisions + + - **Decision**: Why this approach over alternatives. + + ## Scope + + **In scope:** + - ... + + **Out of scope:** + - ... + + ## Implementation + + - `path/to/file` — what changes here + + ## Test Cases + + What needs to be verified. + + ## Open Questions + + Any unresolved decisions. + ``` + +6. **Plan well, do not over-specify**: + - focus on _what_ and _why_ + - avoid locking in incidental implementation details too early + - call out migrations, security implications, and rollout risk when relevant + +7. **Confirm before finalizing** if the user is still shaping the task. + If they asked you to just create the plan, go ahead and write it. diff --git a/.agents/skills/product-think/SKILL.md b/.agents/skills/product-think/SKILL.md new file mode 100644 index 0000000..db9c256 --- /dev/null +++ b/.agents/skills/product-think/SKILL.md @@ -0,0 +1,68 @@ +--- +name: product-think +description: 'Shape a feature or problem before implementation. Use this when the request is still fuzzy, when several solutions are possible, or when execution risks outrunning product clarity.' +--- + +# Product Think + +Shape a feature or problem before implementation. Use this when the +request is still fuzzy, when several solutions are possible, or when +execution risks outrunning product clarity. + +## Arguments + +$ARGUMENTS — Feature idea, problem statement, or change request. + +## Instructions + +1. **Clarify the problem first**: + - who is affected? + - what pain or friction exists today? + - why does it matter now? + +2. **Separate problem from solution**: + - write down the user need + - write down the proposed solution + - check whether the solution actually addresses the need + +3. **Define outcome, not just output**: + - what should be better if this works? + - what user or business behavior should change? + +4. **State constraints**: + - technical constraints + - organizational constraints + - compliance or trust constraints + - timeline constraints + +5. **Explore options**: + - simplest viable option + - stronger but more expensive option + - what not to build yet + +6. **Make tradeoffs explicit**: + - speed vs correctness + - breadth vs depth + - automation vs control + - flexibility vs clarity + +7. **Define scope**: + - in scope + - out of scope + - follow-up ideas that should not block the first version + +8. **Define success**: + - what would we measure? + - what would we observe qualitatively? + - what would count as failure? + +9. **Produce a short product brief** in prose or markdown, with: + - problem + - user + - goal + - options considered + - recommendation + - risks + - success signal + +10. **Only move to implementation planning after this is coherent**. diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md new file mode 100644 index 0000000..d600b27 --- /dev/null +++ b/.agents/skills/rabbit-round/SKILL.md @@ -0,0 +1,76 @@ +--- +name: rabbit-round +description: 'Process automated PR review comments systematically. Use this for CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots.' +--- + +# Rabbit Round + +Process automated PR review comments systematically. Use this for +CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. + +## Instructions + +1. **Get context**: + + ```bash + gh pr view --json number -q '.number' + gh api user --jq '.login' + git rev-parse HEAD + ``` + +2. **Fetch review comments** from the PR: + + ```bash + gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate + ``` + + Filter for known bot accounts. Do not treat human review comments as bot comments. + +3. **Triage each bot comment**: + - **Accept** if it improves correctness, safety, maintainability, or follows repo conventions. + - **Push back** if it is incorrect, overreaching, or conflicts with documented conventions. + +4. **Implement accepted suggestions**: + - make the code changes + - group related fixes logically + - run the relevant project checks + +5. **Reply inline** to each bot comment: + + ```bash + gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + -f body="[response]" + ``` + + Good response patterns: + - accepted and implemented + - agreed, implemented with a small adjustment + - already addressed in commit `{hash}` + - pushing back, with a concrete reason and source or repo convention + +6. **Never resolve human review threads**. For bot threads, resolve only after: + - the change is implemented, or + - the pushback is clearly documented + +7. **Check nit-level comments too**. Small ones still matter if they improve clarity + or remove avoidable friction. + +8. **Commit and push** if you made changes: + - use a neutral commit message such as `fix: address review comments` + - push to the active PR branch + +## Decision Guidelines + +**Accept when the suggestion:** +- fixes a bug or real edge case +- improves type safety +- adds missing tests +- aligns with existing repo patterns +- tightens security or validation appropriately + +**Push back when the suggestion:** +- assumes facts not true in this codebase +- conflicts with canonical specs or official sources +- adds complexity for little benefit +- would undo a deliberate, documented decision +- is purely stylistic and inconsistent with the repo diff --git a/.agents/skills/regression-hunt/SKILL.md b/.agents/skills/regression-hunt/SKILL.md new file mode 100644 index 0000000..6754ccc --- /dev/null +++ b/.agents/skills/regression-hunt/SKILL.md @@ -0,0 +1,76 @@ +--- +name: regression-hunt +description: 'Track down a behavior that used to work and now fails, changed, or regressed. Use this when a bug report points to a recent breakage, especially when the cause is not obvious yet.' +--- + +# Regression Hunt + +Track down a behavior that used to work and now fails, changed, or +regressed. Use this when a bug report points to a recent breakage, +especially when the cause is not obvious yet. + +## Arguments + +$ARGUMENTS — A short description of what regressed. + +Helpful extras when available: +- failing test name or file +- error message or log line +- expected behavior +- actual behavior +- suspect PR, branch, commit, or file +- reproduction command, input, route, or endpoint + +A plain-English bug report is enough to start. The rest are accelerators, +not requirements. + +## Instructions + +1. **Restate the regression clearly**: + - what used to work? + - what is broken now? + - what is expected instead? + +2. **Reproduce it first**: + - run the failing test if one exists + - otherwise use the provided command, input, endpoint, or scenario + - if no reproduction exists, build the smallest one you can + +3. **Encode the regression in a test before fixing it**: + - prefer a focused unit or integration test that fails for the current bug + - if a nearby test file already exists, add the failing case there + - if the repo has no practical automated test harness for this area, create the + smallest reproducible check you can and say why a proper regression test was not added yet + +4. **Bound the problem**: + - identify where the behavior lives + - narrow the suspect files, modules, or commits + - compare against the last known good behavior if possible + +5. **Inspect recent change history**: + - current diff + - recent commits touching the area + - suspect PRs or refactors + + Use git history when helpful, but do not stop at blame; verify the actual cause. + +6. **Find the root cause**: + - avoid fixing only the symptom + - identify the exact logic, assumption, or edge case that changed + +7. **Fix it minimally**: + - preserve intended newer behavior where possible + - do not revert unrelated improvements just to make the symptom disappear + +8. **Verify**: + - make sure the new regression test now passes + - rerun the focused regression check first + - then run the relevant wider checks for confidence + +9. **Report back with**: + - reproduction + - regression test added + - root cause + - fix + - verification + - any remaining uncertainty diff --git a/.agents/skills/security-audit/SKILL.md b/.agents/skills/security-audit/SKILL.md new file mode 100644 index 0000000..803135c --- /dev/null +++ b/.agents/skills/security-audit/SKILL.md @@ -0,0 +1,77 @@ +--- +name: security-audit +description: 'Run a security-focused code audit with a generic checklist first, then layer on repo-specific risks.' +--- + +# Security Audit + +Run a security-focused code audit with a generic checklist first, then +layer on repo-specific risks. + +## Instructions + +1. **Start with repo context**: + - what kind of system is this? + - what data does it handle? + - what are the trust boundaries? + - what would be high-impact failures here? + +2. **Check for hardcoded secrets**: + - API keys + - tokens + - passwords + - private connection strings + +3. **Review authentication and authorization**: + - are protected routes actually protected? + - are object/resource ownership checks enforced server-side? + - are role checks done at the boundary, not just in the UI? + +4. **Review input handling**: + - validation present for user-controlled inputs + - no obvious SQL injection, command injection, XSS, or path traversal + - file paths, URLs, and object keys are sanitized appropriately + +5. **Review file and storage access** when relevant: + - upload validation + - download/presign access checks + - safe retention/deletion behavior + +6. **Review network and session behavior**: + - sane session expiration and invalidation + - rate limits where brute force is plausible + - external requests have timeouts and failure handling + - CORS is not broader than necessary + +7. **Review dependency risk**: + + ```bash + # use the repo's package manager or tooling + ``` + + Also check GitHub security or Dependabot alerts when available. + +8. **Review AI-specific risks** when applicable: + - prompt injection exposure + - unsafe interpolation of user content into system instructions + - cross-tenant or cross-document leakage through retrieval/context assembly + +9. **Layer in domain-specific risks**: + - finance, healthcare, legal, infra, auth, multi-tenant SaaS, and internal tools + all have different sharp edges + - explicitly call out the domain assumptions you used + +10. **Report findings by severity**: + - Critical + - High + - Medium + - Low + + For each finding include: + - file and line + - issue + - likely impact + - recommended fix + +11. **If there are no findings**, say so explicitly and mention what was checked + plus any residual gaps in verification. diff --git a/.ai/local-skills/.gitkeep b/.ai/local-skills/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.ai/local/agents.md b/.ai/local/agents.md new file mode 100644 index 0000000..0c96325 --- /dev/null +++ b/.ai/local/agents.md @@ -0,0 +1,20 @@ +## Repository Specifics + +This repository publishes Stella shared TypeScript and oxlint configuration packages. Changes here affect many public repositories, so compatibility matters more than local convenience. + +### Commands + +- `bun install` +- `bun run lint` +- `bun run typecheck` +- `bun test` +- `bun run build` +- `bun run publint` +- `bun run pack:dry-run` + +### Working Rules + +- Keep config exports stable and documented; consumers import these packages directly. +- Do not add stricter lint rules without checking the public repos that consume them. +- Prefer typed config helpers over copied JSON fragments. +- Fixture files should prove rule behavior and make unused disables fail when a rule regresses. diff --git a/.ai/manifest.json b/.ai/manifest.json new file mode 100644 index 0000000..547ecfc --- /dev/null +++ b/.ai/manifest.json @@ -0,0 +1,14 @@ +{ + "version": 1, + "agents": { + "title": "tooling Development Guidelines", + "modules": [ + "stella-public-repo", + "engineering", + "typescript", + "testing", + "linting" + ], + "local": ".ai/local/agents.md" + } +} diff --git a/.ai/shared b/.ai/shared new file mode 160000 index 0000000..877c8db --- /dev/null +++ b/.ai/shared @@ -0,0 +1 @@ +Subproject commit 877c8db49badcf61866e739df3d07eb4b4c0a34a diff --git a/.claude/commands/.gitignore b/.claude/commands/.gitignore new file mode 100644 index 0000000..5e4552b --- /dev/null +++ b/.claude/commands/.gitignore @@ -0,0 +1,2 @@ +# Generated by sync-ai-skills.sh. +# Keep this file so the directory exists even when no commands are synced yet. diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md new file mode 100644 index 0000000..8ea5c52 --- /dev/null +++ b/.claude/commands/open-pr.md @@ -0,0 +1,115 @@ +# Open PR + +Prepare the current worktree branch for a pull request: rebase, +self-review, quality checks, and open a draft PR. + +## Instructions + +1. **Verify you are on an isolated feature branch**: + + ```bash + CURRENT=$(git branch --show-current) + if [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then + echo "Error: /open-pr must not run from the default branch." + exit 1 + fi + ``` + + If on main, abort and ask the user which feature branch to + use. + + Check whether the current checkout is safe to use for PR prep: + + ```bash + git status --short + ``` + + If the checkout is the user's shared root checkout, has + unrelated local changes, or the work spans multiple repos or + submodules, stop and move to clean worktree(s) before rebasing + or committing. Create the worktree from the current feature + branch and continue the rest of this skill there; do not + rewrite history in the dirty root checkout. + +2. **Bootstrap the worktree before trusting failures**: + + Before running lint, typecheck, tests, or hooks, verify that + the worktree actually has the repo toolchain available + (`bun`, workspace dependencies, `turbo`, `oxlint`, project + bins, and env links if the repo expects them). + + If the worktree is missing the toolchain, run the repo's + normal install/setup flow first, then rerun the same command. + Do not treat missing-bin or module-resolution failures as + product-code regressions. Keep setup-only churn such as + accidental lockfile changes out of the PR unless the task + explicitly requires them. + +3. **Rebase onto remote main**: + + ```bash + git fetch origin main + git rebase origin/main + ``` + + If conflicts arise, resolve them. After resolving, continue + the rebase. If a conflict is ambiguous, ask the user. + +4. **Self-review against CLAUDE.md conventions**: + + Get the full diff against main: + + ```bash + git diff origin/main --name-only + ``` + + Read every changed file in full. Review against the + conventions in CLAUDE.md (TypeScript strictness, error + handling, security, naming, i18n, patterns). Fix any + violations directly; don't just list them. Commit fixes + separately with `fix: address self-review findings`. + +5. **Run all quality checks**: + + ```bash + bun run lint \ + && bun run format \ + && bun run typecheck \ + && bun run test + ``` + + If any check fails, fix the issue and re-run. Commit fixes + with `fix: lint/format/type errors`. + +6. **Security audit**: + + Run `/security-audit`. Fix any critical or high findings + in files changed in this PR before opening it. + Commit fixes with `fix: address security audit findings`. + +7. **Open the PR as draft**: + + Push the branch and create the PR as a **draft**: + + ```bash + git push --force-with-lease -u origin HEAD + gh pr create --fill --draft + ``` + + If `--fill` produces a poor title/body, write a proper one + following Conventional Commits (`feat:`, `fix:`, etc.) with + a very concise summary. Do not add a separate test plan unless + the user explicitly asks for one. Do not mention deployment + choices or attribute the motivation for the PR to a specific + person's feedback, request, or experience. + + This repository is public. Never include marketing language, + internal business context, pricing, competitive analysis, + user identities, conversation specifics, deployment specifics, + or security architecture beyond what the diff obviously shows. + Do not add details that would help a motivated attacker exploit + the code, especially a vulnerable previous version being fixed. + Assume the PR may be read by hostile adversaries, not only + friendly collaborators. When sensitive context would improve + readability, omit it by default; ask the user only if omission + would make the PR hard to review. diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md new file mode 100644 index 0000000..dbdc5bf --- /dev/null +++ b/.claude/commands/plan.md @@ -0,0 +1,93 @@ +# Create Plan + +Create a new implementation plan in the repo's planning area. + +## Arguments + +$ARGUMENTS — A short slug for the plan, ideally kebab-case. If empty, +derive a reasonable slug from the task. + +## Conventions + +Prefer this shared planning layout when the repo supports it: + +```text +.agents/ARCHITECTURE.md +.agents/GOALS.md +.agents/STATUS.md +.agents/plans/ +``` + +If the repo uses a different planning area, adapt to it rather than +creating duplicate systems. + +## Instructions + +1. **Read planning context**: + - `.agents/ARCHITECTURE.md` if present + - `.agents/GOALS.md` if present + - recent related plans if present + +2. **Determine the plan location**: + - prefer `.agents/plans/` + - if that directory does not exist, create it only if the repo is + clearly adopting the shared planning convention + - otherwise ask or use the repo's existing planning area + +3. **Determine the next plan number**: + + ```bash + ls .agents/plans/ + ``` + + Use the next sequential number when numbered plans are already in use. + If the repo does not number plans, follow its established naming. + +4. **Research before writing**: + - inspect the existing code + - read the relevant modules + - understand constraints, patterns, and likely blast radius + +5. **Write the plan** with this structure: + + ```markdown + # Plan: [Feature Name] + + Date: YYYY-MM-DD + + ## Goal + + What are we building and why? + + ## Design Decisions + + - **Decision**: Why this approach over alternatives. + + ## Scope + + **In scope:** + - ... + + **Out of scope:** + - ... + + ## Implementation + + - `path/to/file` — what changes here + + ## Test Cases + + What needs to be verified. + + ## Open Questions + + Any unresolved decisions. + ``` + +6. **Plan well, do not over-specify**: + - focus on _what_ and _why_ + - avoid locking in incidental implementation details too early + - call out migrations, security implications, and rollout risk when relevant + +7. **Confirm before finalizing** if the user is still shaping the task. + If they asked you to just create the plan, go ahead and write it. diff --git a/.claude/commands/product-think.md b/.claude/commands/product-think.md new file mode 100644 index 0000000..28dab23 --- /dev/null +++ b/.claude/commands/product-think.md @@ -0,0 +1,63 @@ +# Product Think + +Shape a feature or problem before implementation. Use this when the +request is still fuzzy, when several solutions are possible, or when +execution risks outrunning product clarity. + +## Arguments + +$ARGUMENTS — Feature idea, problem statement, or change request. + +## Instructions + +1. **Clarify the problem first**: + - who is affected? + - what pain or friction exists today? + - why does it matter now? + +2. **Separate problem from solution**: + - write down the user need + - write down the proposed solution + - check whether the solution actually addresses the need + +3. **Define outcome, not just output**: + - what should be better if this works? + - what user or business behavior should change? + +4. **State constraints**: + - technical constraints + - organizational constraints + - compliance or trust constraints + - timeline constraints + +5. **Explore options**: + - simplest viable option + - stronger but more expensive option + - what not to build yet + +6. **Make tradeoffs explicit**: + - speed vs correctness + - breadth vs depth + - automation vs control + - flexibility vs clarity + +7. **Define scope**: + - in scope + - out of scope + - follow-up ideas that should not block the first version + +8. **Define success**: + - what would we measure? + - what would we observe qualitatively? + - what would count as failure? + +9. **Produce a short product brief** in prose or markdown, with: + - problem + - user + - goal + - options considered + - recommendation + - risks + - success signal + +10. **Only move to implementation planning after this is coherent**. diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md new file mode 100644 index 0000000..7f78584 --- /dev/null +++ b/.claude/commands/rabbit-round.md @@ -0,0 +1,71 @@ +# Rabbit Round + +Process automated PR review comments systematically. Use this for +CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. + +## Instructions + +1. **Get context**: + + ```bash + gh pr view --json number -q '.number' + gh api user --jq '.login' + git rev-parse HEAD + ``` + +2. **Fetch review comments** from the PR: + + ```bash + gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate + ``` + + Filter for known bot accounts. Do not treat human review comments as bot comments. + +3. **Triage each bot comment**: + - **Accept** if it improves correctness, safety, maintainability, or follows repo conventions. + - **Push back** if it is incorrect, overreaching, or conflicts with documented conventions. + +4. **Implement accepted suggestions**: + - make the code changes + - group related fixes logically + - run the relevant project checks + +5. **Reply inline** to each bot comment: + + ```bash + gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + -f body="[response]" + ``` + + Good response patterns: + - accepted and implemented + - agreed, implemented with a small adjustment + - already addressed in commit `{hash}` + - pushing back, with a concrete reason and source or repo convention + +6. **Never resolve human review threads**. For bot threads, resolve only after: + - the change is implemented, or + - the pushback is clearly documented + +7. **Check nit-level comments too**. Small ones still matter if they improve clarity + or remove avoidable friction. + +8. **Commit and push** if you made changes: + - use a neutral commit message such as `fix: address review comments` + - push to the active PR branch + +## Decision Guidelines + +**Accept when the suggestion:** +- fixes a bug or real edge case +- improves type safety +- adds missing tests +- aligns with existing repo patterns +- tightens security or validation appropriately + +**Push back when the suggestion:** +- assumes facts not true in this codebase +- conflicts with canonical specs or official sources +- adds complexity for little benefit +- would undo a deliberate, documented decision +- is purely stylistic and inconsistent with the repo diff --git a/.claude/commands/regression-hunt.md b/.claude/commands/regression-hunt.md new file mode 100644 index 0000000..a178263 --- /dev/null +++ b/.claude/commands/regression-hunt.md @@ -0,0 +1,71 @@ +# Regression Hunt + +Track down a behavior that used to work and now fails, changed, or +regressed. Use this when a bug report points to a recent breakage, +especially when the cause is not obvious yet. + +## Arguments + +$ARGUMENTS — A short description of what regressed. + +Helpful extras when available: +- failing test name or file +- error message or log line +- expected behavior +- actual behavior +- suspect PR, branch, commit, or file +- reproduction command, input, route, or endpoint + +A plain-English bug report is enough to start. The rest are accelerators, +not requirements. + +## Instructions + +1. **Restate the regression clearly**: + - what used to work? + - what is broken now? + - what is expected instead? + +2. **Reproduce it first**: + - run the failing test if one exists + - otherwise use the provided command, input, endpoint, or scenario + - if no reproduction exists, build the smallest one you can + +3. **Encode the regression in a test before fixing it**: + - prefer a focused unit or integration test that fails for the current bug + - if a nearby test file already exists, add the failing case there + - if the repo has no practical automated test harness for this area, create the + smallest reproducible check you can and say why a proper regression test was not added yet + +4. **Bound the problem**: + - identify where the behavior lives + - narrow the suspect files, modules, or commits + - compare against the last known good behavior if possible + +5. **Inspect recent change history**: + - current diff + - recent commits touching the area + - suspect PRs or refactors + + Use git history when helpful, but do not stop at blame; verify the actual cause. + +6. **Find the root cause**: + - avoid fixing only the symptom + - identify the exact logic, assumption, or edge case that changed + +7. **Fix it minimally**: + - preserve intended newer behavior where possible + - do not revert unrelated improvements just to make the symptom disappear + +8. **Verify**: + - make sure the new regression test now passes + - rerun the focused regression check first + - then run the relevant wider checks for confidence + +9. **Report back with**: + - reproduction + - regression test added + - root cause + - fix + - verification + - any remaining uncertainty diff --git a/.claude/commands/security-audit.md b/.claude/commands/security-audit.md new file mode 100644 index 0000000..6ef09ea --- /dev/null +++ b/.claude/commands/security-audit.md @@ -0,0 +1,72 @@ +# Security Audit + +Run a security-focused code audit with a generic checklist first, then +layer on repo-specific risks. + +## Instructions + +1. **Start with repo context**: + - what kind of system is this? + - what data does it handle? + - what are the trust boundaries? + - what would be high-impact failures here? + +2. **Check for hardcoded secrets**: + - API keys + - tokens + - passwords + - private connection strings + +3. **Review authentication and authorization**: + - are protected routes actually protected? + - are object/resource ownership checks enforced server-side? + - are role checks done at the boundary, not just in the UI? + +4. **Review input handling**: + - validation present for user-controlled inputs + - no obvious SQL injection, command injection, XSS, or path traversal + - file paths, URLs, and object keys are sanitized appropriately + +5. **Review file and storage access** when relevant: + - upload validation + - download/presign access checks + - safe retention/deletion behavior + +6. **Review network and session behavior**: + - sane session expiration and invalidation + - rate limits where brute force is plausible + - external requests have timeouts and failure handling + - CORS is not broader than necessary + +7. **Review dependency risk**: + + ```bash + # use the repo's package manager or tooling + ``` + + Also check GitHub security or Dependabot alerts when available. + +8. **Review AI-specific risks** when applicable: + - prompt injection exposure + - unsafe interpolation of user content into system instructions + - cross-tenant or cross-document leakage through retrieval/context assembly + +9. **Layer in domain-specific risks**: + - finance, healthcare, legal, infra, auth, multi-tenant SaaS, and internal tools + all have different sharp edges + - explicitly call out the domain assumptions you used + +10. **Report findings by severity**: + - Critical + - High + - Medium + - Low + + For each finding include: + - file and line + - issue + - likely impact + - recommended fix + +11. **If there are no findings**, say so explicitly and mention what was checked + plus any residual gaps in verification. diff --git a/.github/workflows/ai-sync.yml b/.github/workflows/ai-sync.yml new file mode 100644 index 0000000..24782aa --- /dev/null +++ b/.github/workflows/ai-sync.yml @@ -0,0 +1,21 @@ +name: AI Instructions + +on: + push: + branches: [main] + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + workflow_dispatch: + +permissions: + contents: read + +jobs: + sync-ai: + name: Check generated AI instructions + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + with: + submodules: true + - run: bash scripts/sync-ai-skills.sh --check diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..9b4ddf6 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule ".ai/shared"] + path = .ai/shared + url = https://github.com/stella/ai-shared.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f96f029 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,154 @@ +# tooling Development Guidelines + + + + +## Stella Context + +Stella is an open-source legal workspace. + +## Ideal Customer Profile (ICP) + +**Current focus: mid-size law firms, 5-50 lawyers.** +Pragmatic, cost-conscious, not overly technical. + +**Scale target: Magic Circle firms (2,000-5,000+ lawyers).** +The architecture must not block scaling to this level. See the Scalability section +below for decision guidelines. + +International audience: do not assume English language or English typography +conventions are universal. Highlight competing standards (date formats, quotation +marks, citation styles, legal terminology) when relevant. + +## Regulated Industry + +Stella handles privileged legal data. All code must meet **SOC 2 Type II** and +**ISO 27001** standards: least privilege, audit trails, encryption, workspace +isolation, ethical walls. Full checklist in `/conventions-security`. + +## GitHub Interactions + +- When commenting on GitHub (PRs, issues), include "CC on behalf of @username" where + username is the GitHub handle of the person who requested the comment. +- This repository (including PRs, commits, comments) is public. Never include + marketing language, internal business context, pricing, competitive analysis, user + identities, conversation specifics, or security architecture beyond what the diff + shows. Write for the reviewing engineer. + +## Meta Preferences + +- Never manually reformat code you did not semantically change (auto-formatter output + from `bun run format` is fine to include) +- Vary punctuation: prefer colons, semicolons, commas, and parentheses over em dashes +- Prefer explicit over implicit; when a backend endpoint accepts a discriminator + (e.g., `?type=document|file`), thread it through the full stack (URL params, + component props) instead of hardcoding a default on the frontend +- If TypeScript can make a class of bug structurally impossible (branded types, + discriminated unions, exhaustive checks), prefer that over runtime validation or + manual discipline +- Conventional Commits: `feat:`, `chore:`, `fix:`, `docs:` +- Rebase feature branches onto main (linear history) +- Fail fast: validate at boundaries, return/throw early +- Minimize brace nesting: invert conditions, early returns +- Use named constants, not string literals for domain values +- No direct `document.cookie` assignment +- Avoid spread in loop accumulators (use `.push()`) +- If you encounter a pre-existing bug or lint error while working on something else, + fix it (separate commit) + +## Design Principles + +- No hidden complexity; code is the docs. Every operation must work for humans, + scripts, and AI agents alike. +- No lock-in: standard formats, self-hosting is first-class. +- AI is a tool, not a persona. No anthropomorphizing. +- Performance is non-negotiable. Batch operations, minimize round-trips, lazy-load + aggressively. +- **Vertical slices over horizontal layers.** Features are independent end-to-end + slices (own routes, components, handlers). New capabilities land in their own slice; + existing code stays untouched. + +## Coding Conventions + +### TypeScript + +- No enums: use `as const` objects or union types +- Model mutually exclusive internal states as discriminated unions with a stable + `type`, `status`, or domain-specific discriminator. Avoid boolean flag sets plus + optional payload fields when only some combinations are valid. +- When the linter blocks an `as` cast, restructure to narrow properly (type guards, + `in` checks, records instead of arrays). If truly unavoidable, ask before adding and + include a `// SAFETY:` comment explaining why the cast is sound. +- When a type mismatch appears, trace it to the source (e.g., the handler or query + that produces the wrong type) rather than casting at the consumer. Check git to + verify you did not introduce the mismatch yourself before blaming the framework. +- Use `.at(0)` when the element may not exist (signals possible absence). Use `[0]` + only when existence is already established (length check, or a `// SAFETY:` comment). +- Prefer arrow functions over function expressions +- Destructure in the parameter when the intermediate variable is not reused + (e.g., `{ body: { file, name } }` not `body` then `const { file, name } = body`) +- Prefer discriminated union narrowing (`obj.type === "x"`) over `"key" in obj` + checks. Use `in` only when the type is not a discriminated union and there is no + discriminator to check. +- For function arguments, including helpers: use normal typed parameters for one + argument, and also for two arguments when their types are different enough to stay + readable. Use a named `SomethingOptions`, `SomethingArgs`, or `SomethingParams` + object for 3+ arguments, or when two same-type or otherwise interchangeable + positional arguments would be easy to mix up. Reserve `Props` for React component + props. +- Reuse util types from libraries instead of hand-rolling (e.g., + `React.PropsWithChildren

` for props with children, + `React.ComponentProps<"button">` for HTML element props). Check React, TanStack, and + other deps before defining custom equivalents. +- Keep helper-local types close to the helper they describe: put `SomethingOptions`, + `SomethingResult`, and similar aliases immediately above the function, not in a + file-level type dump far away from the implementation. +- If a return type is noisy enough to hurt readability, hoist it into a nearby alias + such as `SomethingResult` and use it in the signature (e.g., `SomethingResult` or + `Promise`). If the return type is simple, keep it inline. + +### Module Side Effects + +- **No module-level side effects in shared modules.** If a module exports both a + side-effecting singleton (DB connection, auth client, pool) and reusable utilities, + split them: put utilities in a separate file so consumers can import them without + triggering initialization. The side-effecting module re-exports for convenience. +- **Never import test-only types in prod code.** If a prod generic needs to accept + both prod and test instances, use a structural constraint (`{ transaction: ... }`) + instead of importing a type from a test file. +- **Defer eager initialization with lazy singletons.** When a module-level call + (`betterAuth()`, `drizzle()`) depends on another module's export, wrap it in a + `getX()` getter so it runs at first use, not at import time. This prevents TDZ + errors from non-deterministic module evaluation order. + +## Testing + +Only test what can actually go wrong: bugs the type system, framework, or linter would +miss. Prefer invariants over examples when the input space is large. Full conventions +in `/conventions-testing`. + +## Linting + +oxlint (ultracite preset) + oxfmt. To suppress a rule: +`// eslint-disable-next-line rule-name` + +## Repository Specifics + +This repository publishes Stella shared TypeScript and oxlint configuration packages. Changes here affect many public repositories, so compatibility matters more than local convenience. + +### Commands + +- `bun install` +- `bun run lint` +- `bun run typecheck` +- `bun test` +- `bun run build` +- `bun run publint` +- `bun run pack:dry-run` + +### Working Rules + +- Keep config exports stable and documented; consumers import these packages directly. +- Do not add stricter lint rules without checking the public repos that consume them. +- Prefer typed config helpers over copied JSON fragments. +- Fixture files should prove rule behavior and make unused disables fail when a rule regresses. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2c7d760 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,6 @@ +@AGENTS.md + +## Claude Code + +Use the project skills in `.agents/skills/` or `.claude/commands/` when a task +matches one of those workflows. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..ab82e44 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,5 @@ +@AGENTS.md + +## Gemini CLI + +Use `AGENTS.md` as the project context. diff --git a/package.json b/package.json index bab0a8d..0da9462 100644 --- a/package.json +++ b/package.json @@ -12,10 +12,12 @@ "test": "bun test", "lint": "bun run build && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware .", "lint:fix": "bun --bun oxlint -c oxlint.config.ts --type-aware --fix .", - "format": "oxfmt .", + "format": "oxfmt . '!.ai/**' '!.agents/**' '!.claude/**' '!AGENTS.md' '!CLAUDE.md' '!GEMINI.md'", "publint": "publint --pack npm packages/typescript-config && publint --pack npm packages/oxlint-config", "pack:dry-run": "bun run build && (cd packages/typescript-config && npm pack --dry-run) && (cd packages/oxlint-config && npm pack --dry-run)", - "prepack": "bun run build && bun run typecheck" + "prepack": "bun run build && bun run typecheck", + "sync-ai": "bash scripts/sync-ai-skills.sh", + "sync-ai:check": "bash scripts/sync-ai-skills.sh --check" }, "devDependencies": { "@stll/oxlint-config": "workspace:*", diff --git a/scripts/link-codex-skills.sh b/scripts/link-codex-skills.sh new file mode 100755 index 0000000..b1a7a9e --- /dev/null +++ b/scripts/link-codex-skills.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [[ ! -f ".ai/shared/scripts/link-codex-skills.sh" ]]; then + echo "error: .ai/shared submodule is not initialized." >&2 + echo "Run: git submodule update --init" >&2 + exit 1 +fi + +bash .ai/shared/scripts/link-codex-skills.sh "$@" . diff --git a/scripts/sync-ai-skills.sh b/scripts/sync-ai-skills.sh new file mode 100755 index 0000000..fbfe911 --- /dev/null +++ b/scripts/sync-ai-skills.sh @@ -0,0 +1,10 @@ +#!/usr/bin/env bash +set -euo pipefail + +if [[ ! -f ".ai/shared/scripts/sync-ai-skills.sh" ]]; then + echo "error: .ai/shared submodule is not initialized." >&2 + echo "Run: git submodule update --init" >&2 + exit 1 +fi + +bash .ai/shared/scripts/sync-ai-skills.sh "$@" . From af709aeb6005ea4fa0e0da59d0cf3cd355b0d139 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 19:22:52 +0200 Subject: [PATCH 2/8] fix: address review comments --- .agents/skills/open-pr/SKILL.md | 28 +++++++++++++++++--------- .agents/skills/rabbit-round/SKILL.md | 6 +++--- .agents/skills/security-audit/SKILL.md | 5 +++-- .ai/shared | 2 +- .claude/commands/open-pr.md | 28 +++++++++++++++++--------- .claude/commands/rabbit-round.md | 6 +++--- .claude/commands/security-audit.md | 5 +++-- package.json | 2 +- scripts/link-codex-skills.sh | 7 +++++-- scripts/sync-ai-skills.sh | 7 +++++-- 10 files changed, 60 insertions(+), 36 deletions(-) diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md index f22e6d5..d662038 100644 --- a/.agents/skills/open-pr/SKILL.md +++ b/.agents/skills/open-pr/SKILL.md @@ -14,14 +14,14 @@ self-review, quality checks, and open a draft PR. ```bash CURRENT=$(git branch --show-current) - if [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then - echo "Error: /open-pr must not run from the default branch." + if [ -z "$CURRENT" ] || [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then + echo "Error: /open-pr must run from an active feature branch." exit 1 fi ``` - If on main, abort and ask the user which feature branch to - use. + If on a default branch or detached HEAD, abort and ask the + user which feature branch to use. Check whether the current checkout is safe to use for PR prep: @@ -50,11 +50,19 @@ self-review, quality checks, and open a draft PR. accidental lockfile changes out of the PR unless the task explicitly requires them. -3. **Rebase onto remote main**: +3. **Rebase onto the remote default branch**: ```bash - git fetch origin main - git rebase origin/main + DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')" + if [ -z "$DEFAULT_BRANCH" ]; then + DEFAULT_BRANCH="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)" + fi + if [ -z "$DEFAULT_BRANCH" ]; then + DEFAULT_BRANCH="main" + fi + + git fetch origin "$DEFAULT_BRANCH" + git rebase "origin/$DEFAULT_BRANCH" ``` If conflicts arise, resolve them. After resolving, continue @@ -62,10 +70,10 @@ self-review, quality checks, and open a draft PR. 4. **Self-review against CLAUDE.md conventions**: - Get the full diff against main: + Get the full diff against the default branch: ```bash - git diff origin/main --name-only + git diff "origin/$DEFAULT_BRANCH" --name-only ``` Read every changed file in full. Review against the @@ -78,7 +86,7 @@ self-review, quality checks, and open a draft PR. ```bash bun run lint \ - && bun run format \ + && bun run format:check \ && bun run typecheck \ && bun run test ``` diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md index d600b27..dcdf003 100644 --- a/.agents/skills/rabbit-round/SKILL.md +++ b/.agents/skills/rabbit-round/SKILL.md @@ -13,7 +13,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 1. **Get context**: ```bash - gh pr view --json number -q '.number' + PR_NUMBER=$(gh pr view --json number -q '.number') gh api user --jq '.login' git rev-parse HEAD ``` @@ -21,7 +21,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate + gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -38,7 +38,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/.agents/skills/security-audit/SKILL.md b/.agents/skills/security-audit/SKILL.md index 803135c..63ba90e 100644 --- a/.agents/skills/security-audit/SKILL.md +++ b/.agents/skills/security-audit/SKILL.md @@ -46,10 +46,11 @@ layer on repo-specific risks. 7. **Review dependency risk**: ```bash - # use the repo's package manager or tooling + bun pm audit ``` - Also check GitHub security or Dependabot alerts when available. + Use the repo's equivalent audit command if it does not use Bun. Also check + GitHub security or Dependabot alerts when available. 8. **Review AI-specific risks** when applicable: - prompt injection exposure diff --git a/.ai/shared b/.ai/shared index 877c8db..8070524 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 877c8db49badcf61866e739df3d07eb4b4c0a34a +Subproject commit 8070524814119e498fa315c299a15d4ab8738ace diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md index 8ea5c52..499f29a 100644 --- a/.claude/commands/open-pr.md +++ b/.claude/commands/open-pr.md @@ -9,14 +9,14 @@ self-review, quality checks, and open a draft PR. ```bash CURRENT=$(git branch --show-current) - if [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then - echo "Error: /open-pr must not run from the default branch." + if [ -z "$CURRENT" ] || [ "$CURRENT" = "main" ] || [ "$CURRENT" = "master" ]; then + echo "Error: /open-pr must run from an active feature branch." exit 1 fi ``` - If on main, abort and ask the user which feature branch to - use. + If on a default branch or detached HEAD, abort and ask the + user which feature branch to use. Check whether the current checkout is safe to use for PR prep: @@ -45,11 +45,19 @@ self-review, quality checks, and open a draft PR. accidental lockfile changes out of the PR unless the task explicitly requires them. -3. **Rebase onto remote main**: +3. **Rebase onto the remote default branch**: ```bash - git fetch origin main - git rebase origin/main + DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')" + if [ -z "$DEFAULT_BRANCH" ]; then + DEFAULT_BRANCH="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)" + fi + if [ -z "$DEFAULT_BRANCH" ]; then + DEFAULT_BRANCH="main" + fi + + git fetch origin "$DEFAULT_BRANCH" + git rebase "origin/$DEFAULT_BRANCH" ``` If conflicts arise, resolve them. After resolving, continue @@ -57,10 +65,10 @@ self-review, quality checks, and open a draft PR. 4. **Self-review against CLAUDE.md conventions**: - Get the full diff against main: + Get the full diff against the default branch: ```bash - git diff origin/main --name-only + git diff "origin/$DEFAULT_BRANCH" --name-only ``` Read every changed file in full. Review against the @@ -73,7 +81,7 @@ self-review, quality checks, and open a draft PR. ```bash bun run lint \ - && bun run format \ + && bun run format:check \ && bun run typecheck \ && bun run test ``` diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md index 7f78584..2253cb5 100644 --- a/.claude/commands/rabbit-round.md +++ b/.claude/commands/rabbit-round.md @@ -8,7 +8,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 1. **Get context**: ```bash - gh pr view --json number -q '.number' + PR_NUMBER=$(gh pr view --json number -q '.number') gh api user --jq '.login' git rev-parse HEAD ``` @@ -16,7 +16,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate + gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -33,7 +33,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies \ + gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/.claude/commands/security-audit.md b/.claude/commands/security-audit.md index 6ef09ea..fd99617 100644 --- a/.claude/commands/security-audit.md +++ b/.claude/commands/security-audit.md @@ -41,10 +41,11 @@ layer on repo-specific risks. 7. **Review dependency risk**: ```bash - # use the repo's package manager or tooling + bun pm audit ``` - Also check GitHub security or Dependabot alerts when available. + Use the repo's equivalent audit command if it does not use Bun. Also check + GitHub security or Dependabot alerts when available. 8. **Review AI-specific risks** when applicable: - prompt injection exposure diff --git a/package.json b/package.json index 0da9462..da7bfcf 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "test": "bun test", "lint": "bun run build && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware .", "lint:fix": "bun --bun oxlint -c oxlint.config.ts --type-aware --fix .", - "format": "oxfmt . '!.ai/**' '!.agents/**' '!.claude/**' '!AGENTS.md' '!CLAUDE.md' '!GEMINI.md'", + "format": "oxfmt . \"!.ai/**\" \"!.agents/**\" \"!.claude/**\" \"!AGENTS.md\" \"!CLAUDE.md\" \"!GEMINI.md\"", "publint": "publint --pack npm packages/typescript-config && publint --pack npm packages/oxlint-config", "pack:dry-run": "bun run build && (cd packages/typescript-config && npm pack --dry-run) && (cd packages/oxlint-config && npm pack --dry-run)", "prepack": "bun run build && bun run typecheck", diff --git a/scripts/link-codex-skills.sh b/scripts/link-codex-skills.sh index b1a7a9e..64f9730 100755 --- a/scripts/link-codex-skills.sh +++ b/scripts/link-codex-skills.sh @@ -1,10 +1,13 @@ #!/usr/bin/env bash set -euo pipefail -if [[ ! -f ".ai/shared/scripts/link-codex-skills.sh" ]]; then +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +if [[ ! -f "$REPO_ROOT/.ai/shared/scripts/link-codex-skills.sh" ]]; then echo "error: .ai/shared submodule is not initialized." >&2 echo "Run: git submodule update --init" >&2 exit 1 fi -bash .ai/shared/scripts/link-codex-skills.sh "$@" . +bash "$REPO_ROOT/.ai/shared/scripts/link-codex-skills.sh" "$REPO_ROOT" diff --git a/scripts/sync-ai-skills.sh b/scripts/sync-ai-skills.sh index fbfe911..b0af652 100755 --- a/scripts/sync-ai-skills.sh +++ b/scripts/sync-ai-skills.sh @@ -1,10 +1,13 @@ #!/usr/bin/env bash set -euo pipefail -if [[ ! -f ".ai/shared/scripts/sync-ai-skills.sh" ]]; then +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" + +if [[ ! -f "$REPO_ROOT/.ai/shared/scripts/sync-ai-skills.sh" ]]; then echo "error: .ai/shared submodule is not initialized." >&2 echo "Run: git submodule update --init" >&2 exit 1 fi -bash .ai/shared/scripts/sync-ai-skills.sh "$@" . +bash "$REPO_ROOT/.ai/shared/scripts/sync-ai-skills.sh" "$@" "$REPO_ROOT" From a9cccfd4cb3636abede48c4fe7af55c049576f43 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 19:42:02 +0200 Subject: [PATCH 3/8] fix: address bot review feedback --- .agents/skills/open-pr/SKILL.md | 17 +++++++++-------- .agents/skills/rabbit-round/SKILL.md | 4 ++-- .ai/shared | 2 +- .claude/commands/open-pr.md | 17 +++++++++-------- .claude/commands/rabbit-round.md | 4 ++-- AGENTS.md | 21 +++++++-------------- 6 files changed, 30 insertions(+), 35 deletions(-) diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md index d662038..62b4355 100644 --- a/.agents/skills/open-pr/SKILL.md +++ b/.agents/skills/open-pr/SKILL.md @@ -82,14 +82,15 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run all quality checks**: - - ```bash - bun run lint \ - && bun run format:check \ - && bun run typecheck \ - && bun run test - ``` +5. **Run quality checks using the repo's actual commands**: + + Run the checks the repository already defines for linting, + typechecking, tests, and non-mutating format verification. + If the repo defines `format:check`, use it. If it only + defines a mutating `format` script, do not run it as + verification unless you also commit the formatter output. + Prefer documenting a missing format check in the PR body over + inventing a one-off command that is inconsistent with the repo. If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md index dcdf003..b252662 100644 --- a/.agents/skills/rabbit-round/SKILL.md +++ b/.agents/skills/rabbit-round/SKILL.md @@ -21,7 +21,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -38,7 +38,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/.ai/shared b/.ai/shared index 8070524..a6704d6 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 8070524814119e498fa315c299a15d4ab8738ace +Subproject commit a6704d636df17dcd2a399315452cff570a47d3d8 diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md index 499f29a..4a037ec 100644 --- a/.claude/commands/open-pr.md +++ b/.claude/commands/open-pr.md @@ -77,14 +77,15 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run all quality checks**: - - ```bash - bun run lint \ - && bun run format:check \ - && bun run typecheck \ - && bun run test - ``` +5. **Run quality checks using the repo's actual commands**: + + Run the checks the repository already defines for linting, + typechecking, tests, and non-mutating format verification. + If the repo defines `format:check`, use it. If it only + defines a mutating `format` script, do not run it as + verification unless you also commit the formatter output. + Prefer documenting a missing format check in the PR body over + inventing a one-off command that is inconsistent with the repo. If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md index 2253cb5..39f6fad 100644 --- a/.claude/commands/rabbit-round.md +++ b/.claude/commands/rabbit-round.md @@ -16,7 +16,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -33,7 +33,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/AGENTS.md b/AGENTS.md index f96f029..2f321d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,26 +5,19 @@ ## Stella Context -Stella is an open-source legal workspace. - -## Ideal Customer Profile (ICP) - -**Current focus: mid-size law firms, 5-50 lawyers.** -Pragmatic, cost-conscious, not overly technical. - -**Scale target: Magic Circle firms (2,000-5,000+ lawyers).** -The architecture must not block scaling to this level. See the Scalability section -below for decision guidelines. +Stella is an open-source legal workspace and set of legal-data tooling. International audience: do not assume English language or English typography conventions are universal. Highlight competing standards (date formats, quotation marks, citation styles, legal terminology) when relevant. -## Regulated Industry +## Public Repository Context -Stella handles privileged legal data. All code must meet **SOC 2 Type II** and -**ISO 27001** standards: least privilege, audit trails, encryption, workspace -isolation, ethical walls. Full checklist in `/conventions-security`. +- Treat legal data, personal data, and repository secrets as sensitive. +- Keep project instructions, PRs, commits, and comments limited to public engineering + context visible from the repository and diff. +- Do not publish private user, customer, infrastructure, incident, pricing, roadmap, + or competitive context in generated instructions or GitHub artifacts. ## GitHub Interactions From 47e3e72a93ab617efb6501c378cc1f6af2f92bd6 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 19:50:46 +0200 Subject: [PATCH 4/8] fix: sync ai-shared guidance --- .agents/skills/rabbit-round/SKILL.md | 3 ++- .ai/shared | 2 +- .claude/commands/rabbit-round.md | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md index b252662..94965a8 100644 --- a/.agents/skills/rabbit-round/SKILL.md +++ b/.agents/skills/rabbit-round/SKILL.md @@ -38,7 +38,8 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + COMMENT_ID="123456789" + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ -f body="[response]" ``` diff --git a/.ai/shared b/.ai/shared index a6704d6..23775b3 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit a6704d636df17dcd2a399315452cff570a47d3d8 +Subproject commit 23775b3cbf6c082de7240add74c5b811820b5383 diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md index 39f6fad..961a4df 100644 --- a/.claude/commands/rabbit-round.md +++ b/.claude/commands/rabbit-round.md @@ -33,7 +33,8 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + COMMENT_ID="123456789" + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ -f body="[response]" ``` From 5a553ceebc61f9dc4fcd0aeca1b8b5f09ee0577d Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 20:17:27 +0200 Subject: [PATCH 5/8] fix: restore compliance guidance --- .agents/skills/open-pr/SKILL.md | 17 ++++++++--------- .agents/skills/rabbit-round/SKILL.md | 5 ++--- .ai/shared | 2 +- .claude/commands/open-pr.md | 17 ++++++++--------- .claude/commands/rabbit-round.md | 5 ++--- AGENTS.md | 21 ++++++++++++++------- 6 files changed, 35 insertions(+), 32 deletions(-) diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md index 62b4355..d662038 100644 --- a/.agents/skills/open-pr/SKILL.md +++ b/.agents/skills/open-pr/SKILL.md @@ -82,15 +82,14 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run quality checks using the repo's actual commands**: - - Run the checks the repository already defines for linting, - typechecking, tests, and non-mutating format verification. - If the repo defines `format:check`, use it. If it only - defines a mutating `format` script, do not run it as - verification unless you also commit the formatter output. - Prefer documenting a missing format check in the PR body over - inventing a one-off command that is inconsistent with the repo. +5. **Run all quality checks**: + + ```bash + bun run lint \ + && bun run format:check \ + && bun run typecheck \ + && bun run test + ``` If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md index 94965a8..dcdf003 100644 --- a/.agents/skills/rabbit-round/SKILL.md +++ b/.agents/skills/rabbit-round/SKILL.md @@ -21,7 +21,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -38,8 +38,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - COMMENT_ID="123456789" - gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ + gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/.ai/shared b/.ai/shared index 23775b3..8070524 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 23775b3cbf6c082de7240add74c5b811820b5383 +Subproject commit 8070524814119e498fa315c299a15d4ab8738ace diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md index 4a037ec..499f29a 100644 --- a/.claude/commands/open-pr.md +++ b/.claude/commands/open-pr.md @@ -77,15 +77,14 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run quality checks using the repo's actual commands**: - - Run the checks the repository already defines for linting, - typechecking, tests, and non-mutating format verification. - If the repo defines `format:check`, use it. If it only - defines a mutating `format` script, do not run it as - verification unless you also commit the formatter output. - Prefer documenting a missing format check in the PR body over - inventing a one-off command that is inconsistent with the repo. +5. **Run all quality checks**: + + ```bash + bun run lint \ + && bun run format:check \ + && bun run typecheck \ + && bun run test + ``` If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md index 961a4df..2253cb5 100644 --- a/.claude/commands/rabbit-round.md +++ b/.claude/commands/rabbit-round.md @@ -16,7 +16,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -33,8 +33,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - COMMENT_ID="123456789" - gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ + gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ -f body="[response]" ``` diff --git a/AGENTS.md b/AGENTS.md index 2f321d3..f96f029 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,19 +5,26 @@ ## Stella Context -Stella is an open-source legal workspace and set of legal-data tooling. +Stella is an open-source legal workspace. + +## Ideal Customer Profile (ICP) + +**Current focus: mid-size law firms, 5-50 lawyers.** +Pragmatic, cost-conscious, not overly technical. + +**Scale target: Magic Circle firms (2,000-5,000+ lawyers).** +The architecture must not block scaling to this level. See the Scalability section +below for decision guidelines. International audience: do not assume English language or English typography conventions are universal. Highlight competing standards (date formats, quotation marks, citation styles, legal terminology) when relevant. -## Public Repository Context +## Regulated Industry -- Treat legal data, personal data, and repository secrets as sensitive. -- Keep project instructions, PRs, commits, and comments limited to public engineering - context visible from the repository and diff. -- Do not publish private user, customer, infrastructure, incident, pricing, roadmap, - or competitive context in generated instructions or GitHub artifacts. +Stella handles privileged legal data. All code must meet **SOC 2 Type II** and +**ISO 27001** standards: least privilege, audit trails, encryption, workspace +isolation, ethical walls. Full checklist in `/conventions-security`. ## GitHub Interactions From 083022d102de91420bba3d7dc91b64e738713e61 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 20:21:49 +0200 Subject: [PATCH 6/8] fix: sync compliance-aware guidance --- .agents/skills/open-pr/SKILL.md | 17 +++++++------- .agents/skills/rabbit-round/SKILL.md | 5 +++-- .ai/shared | 2 +- .claude/commands/open-pr.md | 17 +++++++------- .claude/commands/rabbit-round.md | 5 +++-- AGENTS.md | 33 ++++++++++++++++------------ 6 files changed, 44 insertions(+), 35 deletions(-) diff --git a/.agents/skills/open-pr/SKILL.md b/.agents/skills/open-pr/SKILL.md index d662038..62b4355 100644 --- a/.agents/skills/open-pr/SKILL.md +++ b/.agents/skills/open-pr/SKILL.md @@ -82,14 +82,15 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run all quality checks**: - - ```bash - bun run lint \ - && bun run format:check \ - && bun run typecheck \ - && bun run test - ``` +5. **Run quality checks using the repo's actual commands**: + + Run the checks the repository already defines for linting, + typechecking, tests, and non-mutating format verification. + If the repo defines `format:check`, use it. If it only + defines a mutating `format` script, do not run it as + verification unless you also commit the formatter output. + Prefer documenting a missing format check in the PR body over + inventing a one-off command that is inconsistent with the repo. If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.agents/skills/rabbit-round/SKILL.md b/.agents/skills/rabbit-round/SKILL.md index dcdf003..94965a8 100644 --- a/.agents/skills/rabbit-round/SKILL.md +++ b/.agents/skills/rabbit-round/SKILL.md @@ -21,7 +21,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -38,7 +38,8 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + COMMENT_ID="123456789" + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ -f body="[response]" ``` diff --git a/.ai/shared b/.ai/shared index 8070524..102dd83 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 8070524814119e498fa315c299a15d4ab8738ace +Subproject commit 102dd834edbc4f2799d0dbb37061224602a529fd diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md index 499f29a..4a037ec 100644 --- a/.claude/commands/open-pr.md +++ b/.claude/commands/open-pr.md @@ -77,14 +77,15 @@ self-review, quality checks, and open a draft PR. violations directly; don't just list them. Commit fixes separately with `fix: address self-review findings`. -5. **Run all quality checks**: - - ```bash - bun run lint \ - && bun run format:check \ - && bun run typecheck \ - && bun run test - ``` +5. **Run quality checks using the repo's actual commands**: + + Run the checks the repository already defines for linting, + typechecking, tests, and non-mutating format verification. + If the repo defines `format:check`, use it. If it only + defines a mutating `format` script, do not run it as + verification unless you also commit the formatter output. + Prefer documenting a missing format check in the PR body over + inventing a one-off command that is inconsistent with the repo. If any check fails, fix the issue and re-run. Commit fixes with `fix: lint/format/type errors`. diff --git a/.claude/commands/rabbit-round.md b/.claude/commands/rabbit-round.md index 2253cb5..961a4df 100644 --- a/.claude/commands/rabbit-round.md +++ b/.claude/commands/rabbit-round.md @@ -16,7 +16,7 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 2. **Fetch review comments** from the PR: ```bash - gh api repos/:owner/:repo/pulls/"$PR_NUMBER"/comments --paginate + gh api repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments --paginate ``` Filter for known bot accounts. Do not treat human review comments as bot comments. @@ -33,7 +33,8 @@ CodeRabbit, Gemini, GitHub Copilot, Devin, Greptile, and similar bots. 5. **Reply inline** to each bot comment: ```bash - gh api -X POST repos/:owner/:repo/pulls/"$PR_NUMBER"/comments/{comment_id}/replies \ + COMMENT_ID="123456789" + gh api -X POST repos/{owner}/{repo}/pulls/"$PR_NUMBER"/comments/"$COMMENT_ID"/replies \ -f body="[response]" ``` diff --git a/AGENTS.md b/AGENTS.md index f96f029..9bf6d22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,26 +5,31 @@ ## Stella Context -Stella is an open-source legal workspace. - -## Ideal Customer Profile (ICP) - -**Current focus: mid-size law firms, 5-50 lawyers.** -Pragmatic, cost-conscious, not overly technical. - -**Scale target: Magic Circle firms (2,000-5,000+ lawyers).** -The architecture must not block scaling to this level. See the Scalability section -below for decision guidelines. +Stella is an open-source legal workspace and set of legal-data tooling. International audience: do not assume English language or English typography conventions are universal. Highlight competing standards (date formats, quotation marks, citation styles, legal terminology) when relevant. -## Regulated Industry +## Public Repository Context + +- Treat legal data, personal data, and repository secrets as sensitive. +- Keep project instructions, PRs, commits, and comments limited to public engineering + context visible from the repository and diff. +- Do not publish private user, customer, infrastructure, incident, pricing, roadmap, + or competitive context in generated instructions or GitHub artifacts. + +## Compliance-Aware Engineering + +Stella code is intended for use in environments with SOC 2 and ISO 27001 style +controls. Treat security, auditability, least privilege, data minimization, and +workspace isolation as baseline engineering requirements. -Stella handles privileged legal data. All code must meet **SOC 2 Type II** and -**ISO 27001** standards: least privilege, audit trails, encryption, workspace -isolation, ethical walls. Full checklist in `/conventions-security`. +When making changes, prefer designs that preserve clear ownership boundaries, +structured audit trails, encryption-aware data handling, and explicit access checks. +Keep public PRs and comments focused on the implementation visible in the diff; do +not describe private controls, internal security architecture, or certification +details unless they are already public in the repository. ## GitHub Interactions From 0b66705f1c85c1a8c1dba085095ae0cca9905886 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 20:25:50 +0200 Subject: [PATCH 7/8] fix: sync security audit guidance --- .agents/skills/security-audit/SKILL.md | 2 +- .ai/shared | 2 +- .claude/commands/security-audit.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/security-audit/SKILL.md b/.agents/skills/security-audit/SKILL.md index 63ba90e..6642fec 100644 --- a/.agents/skills/security-audit/SKILL.md +++ b/.agents/skills/security-audit/SKILL.md @@ -46,7 +46,7 @@ layer on repo-specific risks. 7. **Review dependency risk**: ```bash - bun pm audit + bun audit ``` Use the repo's equivalent audit command if it does not use Bun. Also check diff --git a/.ai/shared b/.ai/shared index 102dd83..94673ac 160000 --- a/.ai/shared +++ b/.ai/shared @@ -1 +1 @@ -Subproject commit 102dd834edbc4f2799d0dbb37061224602a529fd +Subproject commit 94673ac9ac7b54c55b2f0b0f759de9b62f5f3097 diff --git a/.claude/commands/security-audit.md b/.claude/commands/security-audit.md index fd99617..67d8376 100644 --- a/.claude/commands/security-audit.md +++ b/.claude/commands/security-audit.md @@ -41,7 +41,7 @@ layer on repo-specific risks. 7. **Review dependency risk**: ```bash - bun pm audit + bun audit ``` Use the repo's equivalent audit command if it does not use Bun. Also check From ba76aa78f4935ddede55507699a17823e3ee21f9 Mon Sep 17 00:00:00 2001 From: jan-kubica Date: Tue, 2 Jun 2026 21:07:25 +0200 Subject: [PATCH 8/8] chore: point ai-shared at main --- .agents/skills/regression-hunt/SKILL.md | 234 ++++++++++++++++++------ .ai/shared | 2 +- .claude/commands/regression-hunt.md | 234 ++++++++++++++++++------ 3 files changed, 365 insertions(+), 105 deletions(-) diff --git a/.agents/skills/regression-hunt/SKILL.md b/.agents/skills/regression-hunt/SKILL.md index 6754ccc..e64d9a8 100644 --- a/.agents/skills/regression-hunt/SKILL.md +++ b/.agents/skills/regression-hunt/SKILL.md @@ -16,61 +16,191 @@ $ARGUMENTS — A short description of what regressed. Helpful extras when available: - failing test name or file - error message or log line -- expected behavior -- actual behavior +- expected vs actual behavior - suspect PR, branch, commit, or file - reproduction command, input, route, or endpoint -A plain-English bug report is enough to start. The rest are accelerators, -not requirements. +A plain-English bug report is enough to start. ## Instructions -1. **Restate the regression clearly**: - - what used to work? - - what is broken now? - - what is expected instead? - -2. **Reproduce it first**: - - run the failing test if one exists - - otherwise use the provided command, input, endpoint, or scenario - - if no reproduction exists, build the smallest one you can - -3. **Encode the regression in a test before fixing it**: - - prefer a focused unit or integration test that fails for the current bug - - if a nearby test file already exists, add the failing case there - - if the repo has no practical automated test harness for this area, create the - smallest reproducible check you can and say why a proper regression test was not added yet - -4. **Bound the problem**: - - identify where the behavior lives - - narrow the suspect files, modules, or commits - - compare against the last known good behavior if possible - -5. **Inspect recent change history**: - - current diff - - recent commits touching the area - - suspect PRs or refactors - - Use git history when helpful, but do not stop at blame; verify the actual cause. - -6. **Find the root cause**: - - avoid fixing only the symptom - - identify the exact logic, assumption, or edge case that changed - -7. **Fix it minimally**: - - preserve intended newer behavior where possible - - do not revert unrelated improvements just to make the symptom disappear - -8. **Verify**: - - make sure the new regression test now passes - - rerun the focused regression check first - - then run the relevant wider checks for confidence - -9. **Report back with**: - - reproduction - - regression test added - - root cause - - fix - - verification - - any remaining uncertainty +### 1. Restate the regression clearly + +- what used to work? +- what is broken now? +- what is expected instead? + +### 2. Build a feedback loop (this is the skill) + +Everything else is mechanical. With a fast, deterministic, agent-runnable +pass/fail signal, bisection and hypothesis testing all just consume it. +Without one, no amount of staring at code will save you. Spend +disproportionate effort here. Be aggressive. Be creative. Refuse to give up. + +Try these in roughly this order: + +1. Run the failing test via the package's test script — e.g. + `bun run test -- --bail -t ""` — so flags wired into the + script (`--preload`, custom setup) are preserved; calling `bun test` + directly bypasses them. Avoid `bun --bun test` from a worktree root. + Note that `bun test` positional arguments are **file path patterns**, + not test names; use `-t ""` to filter by test name and + `--bail` to fast-fail. +2. Curl / HTTP script against the backend dev server. Wrap fetches in + `AbortSignal.timeout(10_000)` so a hung request does not rot the loop. +3. CLI invocation diffing stdout against a known-good snapshot. +4. Headless browser (Chrome DevTools MCP, Playwright, or similar) against + the frontend dev server. +5. Replay a captured trace (saved payload, event log) through the code path + in isolation. +6. Throwaway harness exercising just the bug code path with a single + function call. For DB-touching code, a fresh test database per loop is + usually faster and more honest than mocking. +7. Differential loop: same input through old-commit vs new-commit, diff + outputs. +8. Bisection harness against the loop above. Drive it through the + package script so wired flags survive, e.g.: + `git bisect run bun run test -- --bail -t ""`. + Verify the harness actually fails on a known-bad commit before + starting — `bun test` exits 0 when no test names match, which would + silently mark every commit as good and produce the wrong culprit. +9. Property / fuzz loop if the bug is "sometimes wrong output". + +Then treat the loop as a product. Iterate on it: + +- **Faster?** Cache setup, skip unrelated init, narrow scope. +- **Sharper signal?** Assert on the specific symptom, not "didn't crash". +- **More deterministic?** Pin time, seed RNG, isolate filesystem, freeze + network. + +A 30-second flaky loop is barely better than no loop. A 2-second +deterministic loop is a debugging superpower. + +For non-deterministic bugs the goal is a **higher reproduction rate**, not a +clean repro. Loop the trigger 100×, parallelise, narrow timing windows, +inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the +rate until it is. + +If you genuinely cannot build a loop, stop and say so explicitly. List what +you tried. Ask the user for: environment access, a captured artifact (HAR, +log dump, screen recording with timestamps), or permission to add temporary +instrumentation. Do **not** proceed to hypothesise without a loop. + +### 3. Encode the regression in a test before fixing it + +Only if a **correct seam** exists — one where the test exercises the real +bug pattern as it occurs at the call site. A test at the wrong seam (too +shallow, single-caller test when the bug needs multiple callers, unit test +that cannot replicate the trigger chain) gives false confidence. + +If no correct seam exists, that itself is the finding. Note it and flag the +architectural gap for step 10. The codebase is preventing the bug from +being locked down. + +Prefer focused integration tests over deep unit tests when the regression +crosses layers. If the area has no automated harness, build the smallest +reproducible check and say why a proper regression test was not added yet. + +### 4. Generate 3–5 ranked hypotheses before instrumenting + +Single-hypothesis generation anchors on the first plausible idea. Each +hypothesis must be **falsifiable** — state its prediction: + +> If is the cause, then will make it disappear / +> will make it worse. + +If you cannot state a prediction, the hypothesis is a vibe — sharpen or +discard. Show the ranked list to the user before testing; domain knowledge +often re-ranks instantly ("we just deployed a change to #3"). Don't block +on it if the user is AFK; proceed with your own ranking. + +### 5. Inspect recent change history + +- current diff +- recent commits touching the area +- suspect PRs or refactors +- **React Compiler:** if the regression is a re-render / stale-closure / + perf shift in the frontend, check whether the compiler's output for the + affected component changed. A lot of "this used to memoize and now it + doesn't" bugs live here, not in your hand-written code. + +Use git history when helpful, but do not stop at blame; verify the actual +cause. For regressions specifically, `git bisect run` against your step 2 +loop is often the fastest path to the offending commit. + +### 6. Instrument + +Each probe must map to a specific prediction from step 4. Change one +variable at a time. + +Preference: + +1. **Bun inspector.** `bun --inspect-brk` is a runtime flag that must + attach to the process actually running the code, which means wrapping + it in `bun run