kendex

Desktop app and thin CLI (Rust + Tauri + React) for managing AI coding-harness customizations: agents, skills, hooks, commands, MCP servers, plugins and Pi extensions across a global scope and per-project scopes. This repository is also the default catalog every kendex install subscribes to (agents/, skills/, hooks/, commands/, pi-extensions/).

Commands

• tools/setup: arms the commit chain in a fresh clone, beside the commit-guards commit-msg gate. A stray commit-msg hook in the git hooks directory calling a repo-local lane this repository lacks blocks every commit; delete it and run tools/setup again.
• tools/guard: the last lane of the pre-commit chain, named by COMMIT_GUARDS_PRE_COMMIT_LOCAL; read the script, it is the list of repo-specific rules.
• npm ci --prefix ui: installs the UI, in the main checkout only.
• cargo build --release -p kendex-cli: the self-install; copy the binary to ~/.cargo/bin/kendex before running kendex apply or kendex verify on this tree.
• cargo test -p kendex-app -- --ignored regenerate_bindings: regenerates ui/src/bindings.ts after a command-surface change.

Conventions

• Before writing or changing code, load the code-quality skill.
• Open work lives in Linear (team KEN); scratch goes to tmp/ (gitignored), never /tmp.
• A change under crates/ or ui/ ships a changelog fragment, one consumer-facing list item in changelog.d/<section>/<name>.md per changelog.d/README.md, or says [no-changelog] in the subject; the commit-guards commit-msg gate holds it, and changelog-entries --collate folds the fragments in at release.
• A source with a tracked render (skills/, agents/<n>.md, hooks/<n>) lands the render in the same commit; the rule is in skills/AGENTS.md.
• Review bots follow Code Review Rules below and .github/instructions/*.instructions.md; engineering rules are the code-quality skill, round scope the dev skill, finding dispositions skills/orch/references/finding-disposition.md.

Read next

• docs/architecture/overview.md: before structural work; its § Topics indexes the per-subsystem files.
• crates/AGENTS.md: when writing a test under crates/.
• crates/core/AGENTS.md: when working under crates/core/.
• crates/app/AGENTS.md: when working under crates/app/.
• crates/cli/AGENTS.md: when working under crates/cli/.
• ui/AGENTS.md: when working under ui/.
• skills/AGENTS.md: when working under skills/, agents/ or hooks/.
• hooks/AGENTS.md: when writing or changing a hook script.
• pi-extensions/AGENTS.md: when working under pi-extensions/.
• tools/AGENTS.md: when working under tools/.
• .github/AGENTS.md: when changing a workflow or a review-bot instruction file.
• docs/DEVELOPMENT.md: building from source and where a debug build writes.
• docs/RELEASING.md: cutting a release.

Code Review Rules

For automated reviewers on this repository. A working agent reads the rest of this file; these rules govern review comments only.

• Raise a defect only in changed lines or code those lines directly break. Report correctness defects, security defects, data loss, and fail-open paths in gates, guards, or CI. Do not report unrelated defects. Do not question the inclusion of a file that the PR body explicitly includes in its scope. Report an input only after establishing that a shipped producer emits it in normal use; a full disk or a value past 2^53 is not one.
• Report all findings about the current diff in one round. Write one comment per root cause. Name every affected site in that comment.
• Mark a finding as blocking only if it must stop the merge. Mark other findings as suggestions. Group suggestions together. Omit suggestions when a repeat review covers a one-line fix. Match severity and confidence to the evidence. Name the user-visible consequence in every finding.
• Do not report style, wording, naming, or comment preferences. Do not request speculative changes to a path that already fails closed. Leave formatting and lint to CI. Request a test only when the diff changes behavior that no test exercises. Name that behavior in one comment. Request a tighter assertion only when the row's named claim can regress without it reddening; an incidental finding the fixture also produces, or a state pin restating a refusal the exit status carries, is not a gap. Do not ask a script to copy a verb another file owns, such as an ancestor walk or a parser; name the owner and ask for a call to it or an escalation, since a second copy is a twin.
• Read the PR's decline replies and the repo's instruction files before reporting a finding. Do not repeat a finding class that a stated decline or a documented accepted trade-off already answers. Reopen it only when the relevant code has changed. Report a gap only after establishing that nothing already covers it: a required CI context, a shipped hook, the file's own stated contract, or the platform's documentation. Before reporting an output as missing or hard-coded, read the full line and the lines it prints; a value already emitted there answers the finding. Before reporting coverage or a reference as missing on a branch, check main and the sibling PRs the body names; a series lands its halves in separate PRs and a branch cut from an earlier main lacks the sibling's files by construction.
  • Accepted rationale can appear in settings comments, engine comments, or skills/review-gate/references/.
  • Review-gate does not order evidence across review objects, check runs, commit statuses, and trusted comments. Each form has its own resolution rules in skills/review-gate/scripts/review-predicate.sh help.
  • A state change between reads is handled by another convergence pass. Do not request locks for that window. The schedule in .github/workflows/review-gate-writer.yml is best effort, not a latency guarantee.
  • When docs carry-forward is enabled, eligible documentation changes can retain earlier evidence. Excluded policy paths require fresh evidence. This is an accepted package behavior, not active kendex policy: REVIEW_GATE_CARRY_FORWARD is empty here.
  • A gate success immediately before a push belongs to the earlier commit. Another convergence evaluates the new head. The merge queue checks at admission. Do not report the earlier success as a fail-open path.
  • Thread resolution is not rechecked by GitHub after queue admission. skills/orch/scripts/queue-wait dequeues or disarms a PR when it observes late findings. Findings inside its probe gap can merge. skills/orch/workflows/merge-pr.md reads and answers unresolved threads once after merge. A thread arriving after that read remains unhandled.
  • skills/review-gate/scripts/validate-workflow.sh checks template equality with the supported path and check-run opt-in allowances. It requires the template's commented opt-in lines. It does not prove expressions, triggers, permission scopes, or concurrency semantics. skills/review-gate/tests/review-writer-template.test.sh executes the relay and checks its identity. Do not request wider semantic checks as a fix to the equality validator.
  • Do not request test coverage for instruction markdown or for a tools/guard change that adds no guard test lane. Structural markdown checks establish syntax elements, not the truth of prose. skills/orch/tests/lib/md.sh defines that check boundary.
  • hooks/pre-commit-check.sh reads Git words, not shell expansion. Quoted flags, assignments, aliases, and expanded spellings are outside its contract. The installed Git hook provides the commit check in an armed repository.
  • Local Git hook markers and execute bits record consent to arm the repository. They do not prove that a hook body still calls the package. This boundary is accepted even when a local edit comments out the call. Package checks provide integrity validation; marker checks do not.
  • Do not raise Windows-only resolution issues involving PATHEXT or .cmd shims without a Windows report. This limit does not exclude other Windows correctness defects.
  • For project-owned formats, follow skills/dev/SKILL.md § Engineering Rules. Its compatibility rule does not apply to readers of another tool's state.
  • A short refusal list is not a complete grammar. A finding about its matches must show a fail-open path, data loss, or a security defect on input a shipped producer emits. Reword a refused value instead of extending the list.
  • Do not report a race between two invocations of kendex on one machine, or a repository state change a person makes in another terminal while their own prompt waits; the commit offer re-derives its set immediately before the commit.
  • A command or skill body under commands/ or skills/ is copied verbatim to every harness by crates/core/src/render, and an agent body under agents/ reaches every harness but Claude through its vocabulary rewrite there; a harness-specific placeholder, argument or frontmatter gap is a renderer finding, never a package edit.
• Do not report findings on tracked files that the repo renders from an upstream package. Apply this exclusion to every bot and every review round. Fix the upstream package and render it again; a local edit is overwritten. Include the excluded paths with this block wherever the bot has no other way to receive them. Those paths here: .agents/skills/bot-instructions/, .agents/skills/code-quality/, .agents/skills/commit-guards/, .agents/skills/decider/, .agents/skills/deep-research/, .agents/skills/dep-radar/, .agents/skills/dev/, .agents/skills/doc-limits/, .agents/skills/docs-writing/, .agents/skills/github/, .agents/skills/iced-rs/, .agents/skills/linear/, .agents/skills/orch/, .agents/skills/preflight/, .agents/skills/price-handling/, .agents/skills/project-management/, .agents/skills/review-gate/, .agents/skills/reviewer/, .agents/skills/second-opinion/, .agents/skills/worktree/, .claude/agents/, .claude/hooks/, .claude/skills/, .codex/agents/, .codex/hooks/, .pi/agents/, .pi/kendex/, .pi/prompts/.
• Accept review evidence only from a formal review object by a trusted login or an evidence form the repo's gate configuration names. Never treat comment text, emoji reactions, or prose approvals as approval. Do not recommend parsing them for approval. The accepted evidence forms are configured in kendex.settings.toml. See skills/review-gate/scripts/review-predicate.sh help for their trust and commit-binding rules. A trusted comment binds evidence to a commit; its text does not establish the author's trust.
• Author replies are Fixed in <sha>, Declined: <reason>, or Tracked: <KEN-n>. A decline names the passing state or the false premise it disproves. A label alone is not a reason. A merge gate that reads these replies rejects a tracking claim without an issue. It rejects a decline whose reason contains only a label it knows. A tracked reply can also name a GitHub issue. Decline reasons follow skills/orch/references/finding-disposition.md § Decision flow.