cc-thingz — Coding Companion

A portable skill suite for Pi, Claude Code, Codex CLI, and Gemini CLI — 25 skills, 3 agents, and 10 hooks. One source of truth in src/, compiled to platform-optimized output for each tool. Supports 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 Go, Python, 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, Codex CLI, Gemini CLI, Pi). All targets consume artifacts from dist/<target>/, which is regenerated from src/ by make build.

Claude Code

/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.

OpenAI Codex CLI

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/<plugin>/, generated by make build. To use skills without the plugin marketplace, point Codex at a per-plugin skill directory directly:

// ~/.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.

Plugin hooks require two feature flags in ~/.codex/config.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

gemini extensions install https://github.com/alexei-led/cc-thingz

For local development, link the checkout instead of copying it:

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:

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 the subagent runtime once:

pi install npm:@tintinweb/pi-subagents

Install extensions and skills — one command installs skills and extensions and clones the repo under ~/.pi/agent/git/:

pi install git:github.com/alexei-led/cc-thingz

For local development (build first, then install from the checkout):

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 (@tintinweb/pi-subagents) 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:

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=<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):

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:

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/):

Pi gets: all 3 agents — engineer, reviewer, advisor (requires @tintinweb/pi-subagents) — all 25 skills, and 8 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 (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. 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, then falls back to official ecosystem docs/registries, Perplexity-backed source discovery, and GitHub releases/source when version-specific docs are missing.

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.

Stepwise reasoning previously came from the Sequential Thinking MCP. It now ships as the sequential-thinking skill — 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 for cross-session memory and AST-based code navigation. Install with:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem@thedotmack

What this enables:

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

Totals: 25 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-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.

Auto-Activated

These activate silently when relevant patterns are detected — no /skill-name needed.

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/<lang>.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.

engineer is the fork target for writing-{go,python,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 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.

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).

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. 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

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. TEST_RUNNER_FULL=1 is the explicit project-level test path: root Makefile target first, then Go/Python project runners, then package scripts by the same yarn/bun/npm selection.

Fallback controls

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:

# 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

# 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.

Structure

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:

make build

Validate with:

make validate    # frontmatter + vendor-neutrality checks
make check       # build + git diff --exit-code (drift gate)
make test        # pytest

Contributing

See CONTRIBUTING.md for how to add plugins, run validation, and submit PRs.

License

MIT