Required Project Tooling
The 10-layer stack every project Kevin works on must have installed and configured. Agents should verify these when entering a new project for the first time. The stack mirrors the enforcement hierarchy in
wiki/concepts/lint-enforced-agent-guardrails.md. Moved out ofAGENTS.md(always-on) so it loads on demand — read it when setting up or auditing a project.
This page is the on-demand expansion of the root agent contract. Keep AGENTS.md thin and put project setup detail here. Source: AGENTS.md; Lint-Enforced Agent Guardrails
How agents should use this page
Read this when entering, setting up, or auditing a Kevin project. Do not blindly install every layer during unrelated work. First inspect what exists, then fill gaps that block the task or violate the project baseline.
Audit procedure:
- Read root
AGENTS.mdand nearestSKILL.md. - Check
package.json, lockfiles, CI, lint/type/test scripts, and.github/workflows. - Check agent docs enrollment with the
agent-docsskill. - Identify missing layers by impact.
- Install or propose only the layers relevant to the current task unless Kevin asked for a full setup pass.
- Run the repo's fastest doctor/lint/test after changes.
- If project setup changes agent docs, packs, config, skills, or routing surfaces, close with Generated Surface Contract.
The goal is a usable safety stack, not tool collecting.
Layer 0: Open Source Hygiene
| Item | Install / command | Purpose |
|---|---|---|
| MIT LICENSE | Root LICENSE on every public Kevin-Liu-01 repo |
Default OSS license; GitHub SPDX detection |
| License audit CLI | npx tsx scripts/ensure-mit-license.ts audit --owner Kevin-Liu-01 |
Find gaps across all public repos |
| Weekly automation | oss-license-audit |
Cron applies MIT to any new public repo that slipped through |
| Agent skill | skills/engineering/ensure-repo-license/SKILL.md |
Procedure for new repos + one-off fixes |
| Doctor check | agent-docs doctor → license warn |
Catches missing LICENSE on enrolled repos at session end |
Add LICENSE in the first commit before marking a repo public. For npm packages, also set "license": "MIT" in package.json.
Layer 1: Supply Chain Security
| Tool | Install | Purpose |
|---|---|---|
| Brin | Global Cursor hook at ~/.cursor/hooks/brin-check.sh |
Pre-scans every npm/pip/cargo install for malware, prompt injection, typosquatting. Blocks suspicious/dangerous verdicts. |
Brin intercepts package installs before they execute. For Claude Code repos, add the PreToolUse hook to .claude/settings.json. See wiki/tools/brin-agent-security.md.
Layer 2: Linting & Formatting
| Tool | Install | Purpose |
|---|---|---|
| Ultracite | bun x ultracite@latest init --linter oxlint --agents universal claude --hooks cursor claude |
Zero-config oxlint + oxfmt. Framework presets, agent rules, agentic hooks. |
| Custom ESLint rules | Per-repo eslint.config.ts |
Architecture-policy rules on top of Ultracite (no-mock-echo, query-key-deps, etc.) |
Ultracite is the baseline for all JS/TS projects. Custom ESLint rules layer on top for repo-specific policy only. See wiki/tools/ultracite-fast-validation.md and wiki/concepts/lint-enforced-agent-guardrails.md.
Layer 3: Type Checking
| Tool | Install | Purpose |
|---|---|---|
| tsgo (TS 7) | Bundled with TypeScript 7+ | ~10x faster type checking. Do not use tsc. |
Layer 4: Agent Rules & Hooks
| Tool | Install | Purpose |
|---|---|---|
| Path-scoped rules | .claude/rules/ or .cursor/rules/ |
Language-specific style guides that auto-load by file type |
| Agent hooks | .claude/settings.json or .cursor/hooks.json |
Pre/PostToolUse hooks: format on edit, style check, Brin on install |
| Ethos rule | .claude/rules/ethos.md |
Always-loaded: surgeon mindset, hard limits, minimal intervention |
See wiki/tools/claude-code-rules.md and wiki/architecture/claude-code-harness.md.
Layer 5: Code Review & Static Analysis
| Tool | Install | Purpose |
|---|---|---|
| code-review-graph | pip install code-review-graph && code-review-graph install && code-review-graph build |
Tree-sitter AST knowledge graph. 22 MCP tools for blast-radius, review context, semantic search. 8.2x token reduction. |
| Graphite | GitHub App + CLI | AI code review, stacked PRs, merge queue |
code-review-graph auto-updates on every file edit and git commit. Run code-review-graph status to verify health. See wiki/tools/code-review-graph.md.
Layer 6: Git Workflow
| Convention | Enforced via | Details |
|---|---|---|
| 200 LOC PR limit | Review policy | Larger changes use stacked diffs |
| Conventional commits | type(scope): description |
No "and" — if you need "and", it's two commits |
No git checkout / git restore |
Rules files + git guard | These commands discard or hide work too easily in shared agent sessions |
| Worktree-first | Rules files | Writes on another branch and parallel work use worktrees, not shared-checkout branch switches |
See wiki/concepts/git-workflow.md.
Layer 7: Testing & Browser Automation
| Tool | Install | Purpose |
|---|---|---|
| agent-browser + Lightpanda | npm i -g agent-browser + Lightpanda binary |
Token-efficient CDP automation (snapshots, React, Web Vitals). Registry ranks browser-harness first for ad-hoc/visual. 10x faster, 10x less memory than Chrome. Falls back to Chrome for auth-heavy flows (--engine chrome). |
| Playwright | pnpm exec playwright install |
Five-tier E2E test suites (smoke, functional, a11y, visual, performance). Use for structured test harnesses, not ad-hoc browsing. |
| Vitest / Bun test | Bundled | Unit + integration tests, run on every change |
Browser automation decision: Route by test type — canonical ranking in wiki/meta/capability-routing-map.md and wiki/concepts/complementary-browser-testing.md; config/cursor/rules/tool-hierarchy.mdc is the Cursor projection. Ad-hoc browsing / scraping / visual regression → browser-harness (real Chrome, self-healing) first, then agent-browser (token-efficient snapshots, React introspection, Web Vitals; Lightpanda engine by default — pass --engine chrome for --extension/--profile/--state/--allow-file-access), then Chrome DevTools MCP. Use Playwright only for structured E2E suites in CI.
Tests are non-negotiable. Too many tests is better than too few. See wiki/architecture/development-setup.md, skills/engineering/tests/SKILL.md, and Agent Engineering Skills.
Layer 8: CI/CD
| Tool | Install | Purpose |
|---|---|---|
| GitHub Actions | .github/workflows/ |
PR CI builds with push: false, CD publishes after merge |
| Blacksmith runners | blacksmith-4vcpu-ubuntu-2404 |
Compute-bound jobs (Docker, Rust, Go, TS builds) |
See GitHub Ecosystem, Agent Engineering Skills, and repo-local GitHub Actions docs.
Layer 9: Frontend/CSS & agent ergonomics
| Concern | Canonical wiki |
|---|---|
Tailwind + cn() first; globals.css only for CSS Tailwind cannot own; no co-located CSS for normal UI; scrollbars/hit-area per css-ui-enforcement; lean-ctx bootstrap |
wiki/style/css-ui-enforcement.md + config/cursor/rules/css-ui-enforcement.mdc |
Tool routing (Floci, Autobrowse, react-doctor, Cursor /orchestrate, zero-native, designtools.fyi, shadcn registries) |
wiki/meta/capability-routing-map.md, wiki/SKILL-RESOLVER.md, harness projection if needed |
Layer 10: Agent-Docs Mesh (every Kevin project)
| Tool | Install | Purpose |
|---|---|---|
| agent-docs skill | skills/productivity/agent-docs/SKILL.md (via npm run bootstrap) |
Enroll repos: AGENTS.md + per-dir SKILL.md, session protocol, rollout order |
| docs-doctor CLI | scripts/agent-docs/ in kevin-wiki (or scripts/run-agent-docs.ts shim in enrolled repos) |
init / scaffold / doctor — structure, safety, links; auto-blocks never clobber prose |
| Enrollment registry | config/agent-docs/registry.json |
Tracks which repos are on the mesh |
| Graphify sidecar awareness | Generated repo-graph auto-block in project AGENTS.md |
Agents use Graphify for repo topology, path/explain/affected, onboarding, and PR risk without installing Graphify hooks into the project |
On first entry to any Kevin repo: check enrollment (.agent-docs/ + agent-docs:auto markers). If missing, load agent-docs skill and init before bulk work. For structural repo questions, use the generated repo-graph block to build/query Graphify from ~/Documents/GitHub/kevin-wiki with --run outputs/graphify/<repo>. See wiki/concepts/agent-docs-mesh.md and Graphify Sidecar Workflow.
Timeline
- 2026-07-03 | Added Graphify sidecar awareness to the project tooling baseline through the Agent-Docs Mesh: projects expose safe graph commands, but Graphify remains a generated sidecar instead of a project-local hook install. Source: User request, 2026-07-03
- 2026-07-01 | Added generated-surface closeout to project tooling audits when setup changes agent docs, packs, config, skills, or routing projections. Source: User request, 2026-07-01
- 2026-06-18 | Added agent audit procedure and clarified that the 10-layer stack should be applied with task-aware judgment, not blind installation during unrelated work. Source: User request, 2026-06-18