https://github.com/alexei-led/cc-thingz
Battle-tested Claude/Codex/Gemini/Pi plugin marketplace — 27 skills, 34 agents, 9 hooks for code review, Go/Python/TypeScript/Web dev, infrastructure ops, and spec-driven development
https://github.com/alexei-led/cc-thingz
ai-coding claude-code claude-code-marketplace claude-code-plugin code-review codex codex-cl codex-cli-plugin developer-tools gemini gemini-cli gemini-cli-extension golang mcp pi-agent pi-agent-extension pi-coding-agent python
Last synced: 18 days ago
JSON representation
Battle-tested Claude/Codex/Gemini/Pi plugin marketplace — 27 skills, 34 agents, 9 hooks for code review, Go/Python/TypeScript/Web dev, infrastructure ops, and spec-driven development
- Host: GitHub
- URL: https://github.com/alexei-led/cc-thingz
- Owner: alexei-led
- License: mit
- Created: 2025-07-05T18:26:35.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-06-23T11:21:20.000Z (22 days ago)
- Last Synced: 2026-06-23T13:27:09.224Z (22 days ago)
- Topics: ai-coding, claude-code, claude-code-marketplace, claude-code-plugin, code-review, codex, codex-cl, codex-cli-plugin, developer-tools, gemini, gemini-cli, gemini-cli-extension, golang, mcp, pi-agent, pi-agent-extension, pi-coding-agent, python
- Language: Python
- Homepage:
- Size: 3.74 MB
- Stars: 33
- Watchers: 0
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-claude-skills - alexei-led/cc-thingz
- awesome-claude-plugins - alexei-led/cc-thingz - plugin` | ✅ ok | | (Source Catalog)
README
# cc-thingz — Coding Companion
[](https://github.com/alexei-led/cc-thingz/actions/workflows/ci.yml)
[](https://github.com/alexei-led/cc-thingz/tags)
[](LICENSE)
[](https://docs.anthropic.com/en/docs/claude-code)
[](https://agents.md)
[](https://developers.openai.com/codex/plugins)
[](https://geminicli.com/docs/extensions)
[](src/plugins/)
[](src/plugins/)
A portable skill suite for **Pi**, **Claude Code**, **Codex CLI**, and **Gemini CLI** — 28 skills, 3 agents, and 10 hooks. One source of truth in `src/`, compiled to platform-optimized output for each tool. Supports [AGENTS.md](https://agents.md)-compatible tools too. Built over 6+ months of daily use and continuous refinement.
## Why This Exists
AI coding tools are powerful out of the box, but specialized workflows need specialized prompts. After months of iterating on skills, agents, and hooks across C# /.NET, Go, Java/Kotlin, Python, Rust, TypeScript, infrastructure, and planning workflows, these plugins encode hard-won patterns:
- **Code review** with evidence-backed severity scoring, depth modes, optional team/external review, and stable review-score rubrics
- **Smart hooks** that auto-suggest skills, lint after edits, protect secrets, and run tests
- **Spec-driven development** with a lightweight one-task-at-a-time loop, markdown task state, checkpoints, and validation
- **Infrastructure ops** with validated K8s, Terraform, and Helm deployments
- **Developer utilities** including git-flow hygiene, docs lookup, web research, and brainstorming
Every skill has been manually crafted and refined through real-world use — not generated boilerplate.
## Installation
> Each section below assumes the corresponding CLI is already installed and on
> `PATH`. If you don't have the CLI yet, install it first
> ([Claude Code](https://docs.anthropic.com/en/docs/claude-code/quickstart),
> [Codex CLI](https://github.com/openai/codex),
> [Gemini CLI](https://github.com/google-gemini/gemini-cli),
> [Pi](https://pi.dev/docs/latest/quickstart)).
> All targets consume artifacts from `dist//`, which is regenerated
> from `src/` by `make build`.
### Claude Code
```bash
/plugin marketplace add alexei-led/cc-thingz
# then install any plugin(s) you want:
/plugin install dev-flow@cc-thingz
/plugin install discovery@cc-thingz
/plugin install git-flow@cc-thingz
/plugin install programming@cc-thingz
/plugin install browser@cc-thingz
# ... repeat for infra-ops and spec-flow
```
Use `--scope project` to install into `.claude/settings.json` for team sharing.
`dev-flow` wires development hooks automatically on install. Install `git-flow` for git guardrails and worktree hooks.
| Event | Matcher | Hook | Effect |
| ------------------ | ------------- | ------------------- | ---------------------------------------- |
| `SessionStart` | — | `session-start.py` | Prints branch, last commit, project type |
| `UserPromptSubmit` | — | `skill-enforcer.sh` | Suggests relevant skills from prompt |
| `PreToolUse` | `Write\|Edit` | `file-protector.py` | Blocks writes to `.env`, keys, secrets |
| `PostToolUse` | `Write\|Edit` | `smart-lint.sh` | Runs formatter/linter on changed files |
| `Stop` | — | `test-runner.sh` | Runs focused tests for edited files |
| `Notification` | — | `notify.sh` | macOS notification (Kitty + tmux focus) |
### OpenAI Codex CLI
```bash
git clone https://github.com/alexei-led/cc-thingz.git ~/src/cc-thingz
cd ~/src/cc-thingz
make build # generates dist/codex/plugins/ from src/
codex
# inside Codex: /plugins → install plugins from this local marketplace
```
The marketplace manifest lives at `.agents/plugins/marketplace.json` and
points each plugin source at `./dist/codex/plugins//`, generated by
`make build`. To use skills without the plugin marketplace, point Codex at a
per-plugin skill directory directly:
```jsonc
// ~/.codex/config.json (excerpt)
{
"skills": ["~/src/cc-thingz/dist/codex/plugins/dev-flow/skills"],
}
```
`dev-flow` wires focused development hooks via `dist/codex/plugins/dev-flow/hooks/hooks.json`. Install `git-flow` for destructive-git guardrails.
| Event | Matcher | Hook | Effect |
| -------------- | --------------- | ------------------- | ---------------------------------------- |
| `SessionStart` | — | `session-start.py` | Prints branch, last commit, project type |
| `PreToolUse` | `^apply_patch$` | `file-protector.py` | Blocks writes to `.env`, keys, secrets |
| `PostToolUse` | `^apply_patch$` | `smart-lint.sh` | Auto-format and lint edited files |
| `Stop` | — | `test-runner.sh` | Runs focused tests for edited files |
Plugin hooks require two feature flags in `~/.codex/config.toml`:
```toml
[features]
hooks = true # enable user-defined hooks
plugin_hooks = true # enable plugin-bundled hooks (under development)
```
After enabling and restarting Codex, run `/hooks` to review and approve
the hooks before they execute. Codex fingerprints each hook command;
any change to name or command triggers a re-approval prompt.
### Google Gemini CLI
```bash
gemini extensions install https://github.com/alexei-led/cc-thingz
```
For local development, link the checkout instead of copying it:
```bash
gemini extensions link /path/to/cc-thingz
```
Gemini reads `gemini-extension.json` at the repo root, loads context from
`AGENTS.md` (auto-generated; shared with Codex and other AGENTS.md-aware
tools), and discovers skills, agents, and hooks by scanning extension-root
subdirectories by hard-coded name. Root-level `skills/`, `agents/`, and
`hooks/` symlinks point into `dist/gemini/` so Gemini finds them; the
compiler regenerates these symlinks on every `make build`.
`dist/gemini/hooks/hooks.json` registers:
| Event | Matcher | Hook | Effect |
| -------------- | --------------------- | ------------------- | ---------------------------------------- |
| `SessionStart` | — | `session-start.py` | Prints branch, last commit, project type |
| `BeforeAgent` | — | `skill-enforcer.sh` | Suggests relevant skills from prompt |
| `BeforeTool` | `write_file\|replace` | `file-protector.py` | Blocks writes to `.env`, keys, secrets |
| `BeforeTool` | `run_shell_command` | `git-guardrails.sh` | Blocks destructive git commands |
| `AfterTool` | `write_file\|replace` | `smart-lint.sh` | Auto-format and lint edited files |
| `AfterAgent` | — | `test-runner.sh` | Runs focused tests for edited files |
| `Notification` | — | `notify.sh` | macOS notification on agent completion |
All paths resolve via `${extensionPath}`, Gemini's substitution variable for
the extension root.
### Pi
Pi uses generated skills, agents, **and TypeScript extensions** that mirror
Claude-Code-native features (plan mode, todos, AskUserQuestion, subagents,
file/path protection, post-edit lint, completion notifications).
**Required prerequisite** — install a Pi subagents package (any compatible one
works; [`nicobailon/pi-subagents`](https://github.com/nicobailon/pi-subagents)
is the recommended choice):
```bash
pi install npm:pi-subagents
```
**Install extensions and skills** — one command installs skills and extensions
and clones the repo under `~/.pi/agent/git/`:
```bash
pi install git:github.com/alexei-led/cc-thingz
```
For local development (build first, then install from the checkout):
```bash
git clone https://github.com/alexei-led/cc-thingz.git ~/src/cc-thingz
cd ~/src/cc-thingz && make build
pi install "$(pwd)"
```
**Install agents** — Pi's subagent runtime loads agents from
`~/.pi/agent/agents/`. After `pi install`, the repo is already at
`~/.pi/agent/git/github.com/alexei-led/cc-thingz` — symlink the agent tree
from there:
```bash
ln -snf \
~/.pi/agent/git/github.com/alexei-led/cc-thingz/dist/pi/agents \
~/.pi/agent/agents
```
`ln -snf` replaces an existing symlink but will not overwrite a real directory
— move it aside first (`mv ~/.pi/agent/agents ~/.pi/agent/agents.bak`).
Override the agent dir with `PI_CODING_AGENT_DIR=` if you run Pi from a
non-default location. Restart Pi or run `/reload` after installing.
**Advisor subagent (`advisor`)** — follows the standard source layout used by
other Pi agents:
- `src/agents/advisor/AGENT.md`
- `src/agents/advisor/pi/frontmatter.yaml`
Compiled output is `dist/pi/agents/advisor.md`. Behavior: strategic review with
read-only code exploration (no file edits) and output sections `Verdict`,
`Top Risks`, and `Next Actions`.
Background usage (separate context + parent context inherited):
```ts
const run = Agent({
subagent_type: "advisor",
description: "Architecture risk review",
prompt: "Review my plan and propose the safest next steps.",
inherit_context: true,
run_in_background: true,
});
get_subagent_result({ agent_id: run.agent_id, wait: true });
```
Foreground usage:
```ts
Agent({
subagent_type: "advisor",
description: "Blocking strategy check",
prompt: "Challenge this implementation plan and suggest corrections.",
inherit_context: true,
run_in_background: false,
});
```
**Bundled Pi extensions** (`dist/pi/extensions/`):
| Extension | Role |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `ask-user-question.ts` | `ask_user_question` tool with structured options UI |
| `permission-gate.ts` | Confirms dangerous bash commands (rm -rf, sudo, chmod 777) |
| `protected-paths.ts` | Blocks writes to `.env`, `.git/`, `node_modules/` |
| `plan-mode/` | `/plan` toggle for read-only exploration and step tracking |
| `todo.ts` | `todo` tool + `/todos` command, branch-aware state |
| `structured-output.ts` | `structured_output` tool that terminates the agent loop |
| `notify.ts` | macOS notification via `terminal-notifier` on completion (requires Homebrew `terminal-notifier`) |
**Pi gets**: all 3 agents — `engineer`, `reviewer`, `advisor` (requires a Pi
subagents package) — all 28 skills, and 7 bundled extensions. Each
agent has a Pi-specific frontmatter overlay tuned for OpenAI Codex models
(`openai-codex/gpt-5.5`), thinking levels, tool restrictions, and turn limits.
`advisor` ships to Codex, Gemini, and Pi; Claude is excluded because it has a
built-in advisor. The old scout→planner→worker→reviewer pipeline is superseded
by the 3-role model.
### Other AGENTS.md-Compatible Tools
The `AGENTS.md` at the repo root provides a skill catalog readable by any tool supporting the [AGENTS.md standard](https://agents.md) (GitHub Copilot, Cursor, Windsurf, Devin, and others).
## Prerequisites
Repo-wide code search, AST evidence, codegraph, and GitNexus workflows are intentionally outside cc-thingz. Use a separate codebase-analysis plugin for repo-wide analysis, such as [architect](https://github.com/alexei-led/architect). cc-thingz does not ship a general repo-wide code-search skill; its review, fix, test, and refactor skills may use GitNexus, codegraph, `rg`, `fd`, LSP, or similar local tools when they are already available and help answer a focused change-safety question.
Portable docs lookup is one public `looking-up-docs` skill. It starts with the [Context7 CLI](https://github.com/upstash/context7), then falls back to official ecosystem docs/registries, Perplexity-backed source discovery, and GitHub releases/source when version-specific docs are missing.
```bash
npm install -g ctx7@latest
# or with Bun:
bun add -g ctx7@latest
# one-shot (no global install):
npx ctx7@latest library react "React hooks"
npx ctx7@latest docs /facebook/react "React hooks"
# or with Bun:
bunx ctx7@latest docs /facebook/react "React hooks"
```
Claude Code agents can also use optional MCP servers for enhanced capabilities.
These are optional — plugins degrade gracefully without them. Pi exports do not
assume MCP tools.
| MCP Server | Purpose | Used By |
| ------------------------------------------------------------ | ------------------------------------------- | ----------------------------------------------------------------------- |
| [Perplexity](https://github.com/ppl-ai/modelcontextprotocol) | Web research and technical comparisons | Claude Code dev-flow, discovery, infra-ops |
| [MorphLLM](https://github.com/morphllm/morph-claude-code) | Fast codebase search and batch file editing | Claude Code `engineer` role via dev-flow, programming, infra, spec-flow |
> Stepwise reasoning previously came from the
> [Sequential Thinking MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking).
> It now ships as the [`sequential-thinking` skill](src/skills/sequential-thinking/SKILL.md) — no MCP install required and portable across Claude Code, Codex, Gemini, and Pi.
### Claude-Mem Integration
All agents and several skills optionally integrate with [claude-mem](https://github.com/thedotmack/claude-mem) for cross-session memory and AST-based code navigation. Install with:
```bash
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem@thedotmack
```
**What this enables:**
| Capability | Tools Used | Benefit |
| ----------------------------- | ----------------------------------------------- | -------------------------------------------------- |
| AST code navigation | `smart_search`, `smart_outline`, `smart_unfold` | 10-20x fewer tokens than reading full files |
| Cross-session memory | `search`, `get_observations`, `timeline` | Find past decisions, known gotchas, recurring bugs |
| Historical context in reviews | `search` + `get_observations` | Review agents check past findings before starting |
**Graceful degradation**: All plugins work without claude-mem. When it's not installed, MCP tools are silently absent — agents fall back to local tools such as `rg`, `fd`, and platform Read/Grep/Glob where needed. No errors, no configuration needed.
**How it works**: Agent frontmatter lists claude-mem MCP tools alongside standard tools. Claude Code silently omits unavailable tools at runtime, so agents always have their core tools (Read, Grep, Glob, LSP) and gain AST/memory tools when claude-mem is present. Skill instructions use "when available" / "if claude-mem available" phrasing to guide Claude's behavior.
## Plugins
| Plugin | Skills | Agents | Description | Depends on |
| ------------------------------------------------------ | ------ | ------ | ------------------------------------------------------------------------------------------------ | ----------- |
| [**dev-flow**](src/plugins/dev-flow/plugin.yaml) | 6 | 2 | Fix, refactor, review, document, commit; `engineer` and `reviewer` roles; 6 hooks | — |
| [**spec-flow**](src/plugins/spec-flow/plugin.yaml) | 1 | 2 | Lightweight spec loop: plan one slice, execute one task, checkpoint or close | dev-flow |
| [**git-flow**](src/plugins/git-flow/plugin.yaml) | 3 | 0 | Worktrees, cleanup, hooks, Gitleaks, `.gitignore`, git config, and guardrails | — |
| [**browser**](src/plugins/browser/plugin.yaml) | 2 | 1 | Browser testing, validation, screenshots, recordings, and quick automation | programming |
| [**infra-ops**](src/plugins/infra-ops/plugin.yaml) | 2 | 1 | Kubernetes, Terraform, Helm, GitHub Actions, AWS, GCP | — |
| [**programming**](src/plugins/programming/plugin.yaml) | 8 | 1 | Idiomatic development across C# /.NET, Go, Java/Kotlin, Python, Rust, TypeScript, shell, and web | dev-flow |
| [**discovery**](src/plugins/discovery/plugin.yaml) | 6 | 1 | Research, docs lookup, instruction review, reasoning, and agent config audits | — |
**Totals**: 28 skills, 2 plugin-owned role agents (`engineer`, `reviewer`), 10 hooks
## Skills
Skills teach the AI model domain-specific knowledge and workflows. All skills are authored in cc-thingz and exported with platform-optimized instructions for Codex CLI, Gemini CLI, Pi, and [AGENTS.md](https://agents.md)-compatible tools. On Claude Code, the `skill-enforcer` hook auto-suggests relevant skills based on your prompt.
### User-Invocable
Invoke as `/skill-name` or let the skill enforcer suggest them.
| Skill | What It Does | Example Trigger |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `brainstorming-ideas` | Brainstorm ideas and stress-test draft plans or trade-offs | "brainstorm", "debate plan" |
| `cleanup-git` | Remove merged branches and stale worktrees | "cleanup branches", "tidy git" |
| `committing-code` | Smart git commits with logical grouping | "commit", "save changes" |
| `configuring-git-hygiene` | Configure git hooks, Gitleaks, `.gitignore`, git config, and guardrails | "setup pre-commit", "gitleaks" |
| `deploying-infra` | Validate infrastructure changes and, after explicit confirmation, apply Terraform, Helm, Kustomize, or Kubernetes deployments | "deploy to staging", "rollout" |
| `documenting-code` | Update docs based on recent changes | "update docs", "document" |
| `evolving-config` | Audit AI coding-agent configuration; review-only by default, explicit approval for fixes | "evolve", "audit config" |
| `fixing-code` | Reproduce, diagnose, patch, regression-test, and verify one code defect at a time | "fix errors", "make it pass" |
| `improving-tests` | Improve test design, speed, and coverage with behavior seams, fast feedback, TDD, and test refactoring | "improve tests", "slow tests" |
| `looking-up-docs` | Find current docs via Context7, official registries/docs, Perplexity/web, and GitHub fallback | "ctx7", "latest API", "look up" |
| `researching-web` | Web research via platform web tools with grounded source selection and stale-source reporting | "research", "X vs Y" |
| `reviewing-code` | Evidence-backed code review with severity/confidence rubric, quick/deep/team/external modes, and optional graph evidence | "review code", "check this" |
| `browser-automation` | Rendered UI exploration, validation, screenshots, recordings, and browser test flows | "use browser", "screenshot", "e2e" |
| `reviewing-instructions` | Review and score AI-facing instruction files with scoped lint, model resolution, scoring caps, confidence, and calibration anchors | "lint instructions", "audit prompts" |
| `sequential-thinking` | Structured stepwise reasoning with explicit revisions and branches | "think step by step", "plan this out" |
| `using-git-worktrees` | Isolated git worktrees for parallel development | "worktree", "isolate" |
### Auto-Activated
These activate silently when relevant patterns are detected — no `/skill-name` needed.
| Skill | Activates When |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `operating-infra` | IaC, Kubernetes, cloud resources, CI/CD, Linux |
| `refactoring-code` | Behavior-preserving batch refactors with mapped sites and optional graph-backed impact checks |
| `writing-csharp` | C# files, `.csproj`/`.sln`, `dotnet`, ASP.NET Core, xUnit/NUnit/MSTest |
| `writing-go` | Go files, tests, lint, Go-specific terms |
| `writing-java-kotlin` | Java/Kotlin files, Gradle/Maven, JUnit/Kotest, ktlint, detekt, JVM frameworks |
| `writing-python` | Python files, pytest, fast test feedback, pip, frameworks |
| `writing-rust` | Rust files, Cargo crates/workspaces, tests, rustfmt, Clippy |
| `writing-shell` | Shell scripts, pipelines, shell lint/test |
| `writing-typescript` | TS/TSX files, tests, lint, npm/bun, React, Node.js |
| `writing-web` | HTML/CSS/JS/HTMX templates |
### Support-Only
- `playwright-skill` — bundled Playwright runtime/reference loaded by
`browser-automation` when the Playwright fallback is needed. Not routed from
user intent directly.
## Agents
Three role agents: a capability envelope plus a reasoning stance no skill can supply. Consolidated from 39 → 3 — see `docs/agent-audit-2026-05-16.md` and the executed plan in `docs/plans/completed/`. Domain procedure and output format live in skills; language specifics live in each skill's `references/.md`. Role × skill × references compose — language is not a routing key. Envelope enforcement is per-target: Claude and Gemini grant a hard `tools:` allowlist (Gemini via its subagent frontmatter `tools:` field); Codex blocks writes via `sandbox_mode: read-only`; Pi has no tool-allowlist primitive, so the envelope there is a system-prompt directive. Gemini frontmatter has no read-only sandbox primitive, so `advisor` is granted `run_shell_command` and held read-only by its body directive, the same tradeoff as Pi.
| Role | Envelope | Stance | Claude model | Pi model |
| ---------- | -------------------------------- | ---------------------------------------------------------------- | ------------------- | ----------------------- |
| `engineer` | Read + write + execute | Sole mutator: applies changes, runs the build/test/lint gate | sonnet | gpt-5.4 thinking:high |
| `reviewer` | Read, Grep, Glob, LS — no writes | Adversarial evaluator: emits findings/proposals, applies nothing | sonnet | gpt-5.4 thinking:medium |
| `advisor` | Read + read-only Bash | Strategic escalation: verdict, ranked risks, next actions | built-in (Opus 4.7) | gpt-5.5 thinking:xhigh |
`engineer` is the fork target for `writing-{csharp,go,java-kotlin,python,rust,shell,typescript,web}` and `operating-infra`. `reviewer` absorbs the review family, code search, and planning (via `spec`). `advisor` ships to Codex, Gemini, and Pi; Claude is excluded because it has a built-in advisor. On Pi, `advisor` is invoked via transcript forwarding; on Gemini and Codex it is spawned as a normal custom subagent under its tool/sandbox envelope.
Model tiers are matched per role across vendors. `engineer`/`reviewer` use Claude `sonnet`; their Pi counterparts pin `gpt-5.4` (not `gpt-5.5`) because GPT-5.5 is a frontier tier above Sonnet 4.6 — using it for the same role would make the Pi agent materially stronger and ~2× costlier for no parity reason. `advisor` is an escalation role: Claude's built-in advisor runs Opus 4.7 (frontier), so the Pi advisor stays at `gpt-5.5 thinking:xhigh` to match that tier. On Codex, the agent inherits the model chosen at `codex` launch, so there is no model to pin without brittleness.
Pi model names use the `openai-codex/` provider prefix (e.g. `openai-codex/gpt-5.4`) to avoid ambiguous fuzzy matching when multiple providers expose the same model ID.
## Hooks
| Hook | Event | What It Does |
| -------------------- | ---------------- | ------------------------------------------- |
| `session-start.sh` | SessionStart | Shows git branch, last commit, file context |
| `skill-enforcer.sh` | UserPromptSubmit | Pattern-matches prompt and suggests skills |
| `file-protector.py` | PreToolUse | Blocks edits to settings.json, secrets |
| `git-guardrails.sh` | PreToolUse | Blocks destructive git commands |
| `smart-lint.sh` | PostToolUse | Auto-runs focused lint after file edits |
| `test-runner.sh` | Stop | Auto-runs focused tests after agent turns |
| `notify.sh` | Notification | Desktop notifications for long operations |
| `worktree-create.sh` | WorktreeCreate | Sets up isolated git worktree environment |
| `worktree-remove.sh` | WorktreeRemove | Cleans up worktree on exit |
### Hook Prerequisites
`smart-lint.sh` and `test-runner.sh` auto-detect project type and prefer focused tools. Missing optional tools warn or fall through; tool failures block.
For Java/Kotlin fast local hooks on macOS, use JDK 25 LTS plus file-scoped tools:
```bash
brew install --cask temurin@25
brew install gradle maven kotlin google-java-format ktlint detekt
```
An existing newer JDK can stay installed, but Gradle/Maven toolchains should pin the project compile/test target.
#### Focused path
`smart-lint.sh` runs after edits. It reads hook stdin first, records the edited file set, then formats and lints only matching files. If hook input lacks paths, it falls back to git diff only when the changed-file count is at or below `SMART_LINT_DIFF_FALLBACK_LIMIT` (default: 5). For C# /.NET, source edits use `dotnet format` on the nearest project or containing solution with `--include`; `.csproj`, `.sln`, `.props`, and `.targets` edits use the nearest safe project or solution target.
`test-runner.sh` runs at agent-finish time (`Stop` for Claude/Codex/Pi, `AfterAgent` for Gemini). It uses the edited-file state recorded by `smart-lint.sh`, then falls back to git diff. For C# /.NET, focused tests choose the nearest obvious test `*.csproj`, else the containing `*.sln`, else the nearest `*.csproj`. For Java/Kotlin, focused tests prefer the nearest Gradle module `test --tests ` or Maven `-Dtest= test`. Full project tests require `TEST_RUNNER_FULL=1`.
Focused checks matter. Project-wide scripts are slower, burn context, and often produce unrelated failures. Keep package and Makefile fallbacks as safety nets, not the normal path. Smart-lint tracks formatting and linting separately: a focused formatter does not suppress a project-level lint fallback.
#### Tool order
| Ecosystem | Format / lint path | Test path |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| C# /.NET | `dotnet format --include ` when possible; project/solution target for `.csproj` / `.sln` / `.props` / `.targets` | `dotnet test` on the nearest obvious test `*.csproj`, else the containing `*.sln`, else the nearest `*.csproj` |
| Java / Kotlin | `google-java-format -i`, `ktlint --format`, `detekt --input`; configured Gradle/Maven Spotless/detekt fallback | Gradle `:module:test --tests ` or Maven `-Dtest= test`; module test fallback when no matching test |
| Python | `ruff` format once, `ruff check --fix`; `black` / `flake8` fallback | matching `test_*.py` / `*_test.py` via `pytest -q --maxfail=1 --tb=short` |
| Pyright | `pyright --outputjson`; `reportMissingImports` filtered structurally | — |
| JavaScript / TS | local/global `prettier --write`, local/global `eslint --fix` | Vitest `related --run`, Jest `--findRelatedTests`, direct test files |
| Bun | package-script fallback via `bun run ` when selected by lock | `bun test <tests>` or package-script fallback |
| Go | `gofmt -w`, package-scoped `golangci-lint --fix` / `go vet` | `go test -failfast ./changed/pkg` |
| Rust | `rustfmt`, manifest-scoped `cargo clippy --fix` / `cargo check` | `cargo test --manifest-path <Cargo.toml> --all-targets` |
| Shell / Bash | `shfmt -w`, `shellcheck` | matching `.bats` files |
| Package scripts | last fallback for missing side: `fmt` / `format`, then `lint` | last fallback: `test`, `tests`, `check`, `verify` scripts |
| Makefile | last fallback for missing side: root `fmt`, then `lint` | nearest non-root `test`, `tests`, `check`, `verify` target before generic runners; root only in `TEST_RUNNER_FULL=1` |
Package-script selection: `yarn.lock` → `yarn run`, `bun.lock` / `bun.lockb` → `bun run`, otherwise `npm run --silent` when npm is available. npm and Yarn run package scripts and expose local binaries on the script PATH; Bun `run` can run package scripts and local executables.
Fallbacks fill gaps only. If focused formatting ran but no focused linter ran, smart-lint may still run project `lint`. If focused linting ran, it skips project `lint`. For tests, a nearest non-root Makefile target wins for files under that subtree; otherwise focused language runners try first, then package-script fallback. `TEST_RUNNER_FULL=1` is the explicit project-level test path: root Makefile target first, then Go/Rust/Java/Kotlin/C#/.NET/Python project runners, then package scripts by the same yarn/bun/npm selection.
#### Fallback controls
| Control | Effect |
| ---------------------------- | ---------------------------------------------------------- |
| `SKIP_LINT=1` or `.nolint` | skip smart-lint completely |
| `SKIP_TESTS=1` or `.notests` | skip test-runner completely |
| `HOOK_PROJECT_FALLBACK=0` | disable package-script and Makefile fallbacks |
| `.nohooks-project` | repo-local file form of `HOOK_PROJECT_FALLBACK=0` |
| `TEST_RUNNER_FULL=1` | run one project-level test target instead of focused tests |
#### Output and exit codes
Hooks write concise diagnostics to stderr for agent consumption.
- Exit `0`: checks passed, skipped, or no relevant focused target found.
- Exit `2`: blocking lint/test failure. Agents should fix the shown issue before retrying.
- Compact output keeps the first relevant lines and truncates long logs. This preserves context budget and makes the failing file, line, and command visible.
- Formatters run once. Post-format “check” passes are avoided in the interactive path to stop formatter/linter ping-pong.
Recommended installs for tools that don't ship with their language runtime:
```bash
# Python
brew install uv # manages interpreter + venv + lockfile
brew install ruff # linter + formatter, replaces flake8 + black
# JavaScript / TypeScript
brew install bun # runtime + test runner + package manager
# Go
go install gotest.tools/gotestsum@latest # cleaner output than go test
brew install golangci-lint
# Rust
rustup component add rustfmt clippy rust-analyzer
cargo install cargo-nextest # optional faster test runner
# Shell
brew install bats-core # Bash Automated Testing System
brew install shellcheck shfmt
# macOS notifications (used by notify.sh)
brew install terminal-notifier
```
## Skill Export Architecture
One source of truth (`src/`) compiles into per-target trees (`dist/<target>/`).
The compiler is `scripts/build/compile.py`.
| Target | Output | Notes |
| ----------- | ---------------------------------------------------- | ------------------------------------------------------ |
| Claude Code | `dist/claude/plugins/<plugin>/` | Skills + markdown agents + hooks + commands per plugin |
| Codex CLI | `dist/codex/plugins/<plugin>/`, `dist/codex/agents/` | Skills + hooks per plugin; standalone TOML agents |
| Gemini CLI | `dist/gemini/{skills,agents,hooks}/` | Flat per kind; root symlinks for extension loader |
| Pi | `dist/pi/{skills,agents,extensions}/` | Flat layout; symlinked into `~/.pi/agent/` |
### Structure
```text
src/ # ALL hand-edited
├── skills/<skill>/SKILL.md # vendor-neutral base + optional <target>/ overlay
├── agents/<agent>/AGENT.md # same pattern as skills
├── hooks/<hook>/HOOK.sh # + meta.yaml (event, timeout)
└── plugins/<plugin>/plugin.yaml # plugin composition (skills/agents/hooks lists)
dist/ # ALL generated; linguist-generated=true
├── claude/plugins/<plugin>/
├── codex/plugins/<plugin>/
├── gemini/{skills,agents,hooks}/
└── pi/{skills,agents,extensions}/
# Root-level files generated by the compiler:
.claude-plugin/marketplace.json # → ./dist/claude/plugins/*
.agents/plugins/marketplace.json # → ./dist/codex/plugins/*
gemini-extension.json # → ${extensionPath}/dist/gemini/
AGENTS.md # AGENTS.md catalog
skills -> dist/gemini/skills # symlink — Gemini scans extension root by name
agents -> dist/gemini/agents # symlink — Gemini scans extension root by name
hooks -> dist/gemini/hooks # symlink — Gemini scans extension root by name
```
Regenerate everything with:
```bash
make build
```
Validate with:
```bash
make validate # frontmatter + vendor-neutrality checks
make check # build + git diff --exit-code (drift gate)
make test # pytest
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add plugins, run validation, and submit PRs.
## License
[MIT](LICENSE)