cc-thingz — Coding Companion

Portable skills, agents, hooks, and Pi-native extensions for Claude Code, Codex CLI, GitHub Copilot, Cursor, Grok, and Pi. Gemini is retired.

Build

Requires Agent Bundler with build, check, and package, plus support for per-agent sidecars, declared hook environments, Pi-native assets, and Codex project-agent profiles. Verify packaging support:

agbun package --help

Build and check the complete generated tree:

make build
make check

make build is a direct agbun build --root . invocation. make check runs the non-mutating agbun check --root . drift gate. Agent Bundler replaces the configured dist/ output tree during builds, so do not edit generated files.

Source layout

agentbundle.json                    # Agent Bundler manifest
src/
├── skills/<name>/SKILL.md          # canonical YAML-frontmatter skills
│   └── .agentbundler/targets/*.json # optional target overlays
├── agents/<name>.md                # canonical agent assets
├── .agentbundler/packages/*.json   # package membership and metadata
├── hooks/<name>/                   # typed Agent Bundler hooks
└── plugins/pi/<asset>/             # declarative Pi-native extension tree
    └── extensions/                 # Pi-native tools and compatibility runner

dist/<target>/<package>/             # generated Agent Bundler package roots
.claude-plugin/marketplace.json      # repository-root compatibility wrapper
.agents/plugins/marketplace.json     # repository-root compatibility wrapper
.codex/agents/*.toml                 # fixed-path Codex project-agent profiles
.github/plugin/marketplace.json      # repository-root compatibility wrapper
.cursor-plugin/marketplace.json      # repository-root compatibility wrapper
package.json#pi                      # merged Pi root compatibility manifest

Skills use Agent Bundler overlays for target-specific frontmatter, body, and support-file changes. Target-wide preambles are composition entries in agentbundle.json. Canonical source remains readable Markdown with YAML frontmatter; Agent Bundler emits normalized JSON frontmatter.

Package membership is defined by src/.agentbundler/packages/*.json. Each package lists exact skill and agent asset paths. Root marketplace files are routing wrappers only: their entries point into dist/<target> and contain no independent package trees. Do not edit dist/ or give the wrappers independent metadata.

Targets and output

Release packages

agbun package --root . --out DIR creates deterministic, target-native release archives:

• alexei-led-cc-thingz-claude.tar.gz
• alexei-led-cc-thingz-codex.tar.gz
• alexei-led-cc-thingz-pi.tgz
• alexei-led-cc-thingz-copilot.tar.gz
• alexei-led-cc-thingz-cursor.tar.gz
• alexei-led-cc-thingz-grok.tar.gz

The release workflow attaches all six files. Each archive expands directly to the native package or marketplace root shown above. The Codex archive also includes separate .codex/agents/*.toml profiles; they are not plugin contents. Installation and marketplace registration use the target vendor's CLI; Agent Bundler does not mutate user configuration or publish to a vendor registry.

Release flow

The committed version section in CHANGELOG.md is the single authored notes source. Validate it before the release commit:

python3 src/skills/releasing-code/scripts/release_notes.py check-release \
  --root . --tag v6.13.0 --changelog CHANGELOG.md --budget minor

The renderer adds package and distribution metadata separately; its word budget is advisory and does not truncate migration or known-issue details.

Prepare and review a release without committing or tagging:

make release V=6.13.0
# Edit and review CHANGELOG.md and generated output, then commit the release changes.
make release-finalize V=6.13.0

release-finalize requires a clean release commit, validates its notes, runs make ci, and creates only a local annotated tag. It does not push. External publication requires explicit authorization. The tag-triggered .github/workflows/release.yml is the only GitHub release publisher for cc-thingz. Its workflow_dispatch repair requires the existing tag and a full notes_source_sha commit. The trusted default-branch workflow reads only CHANGELOG.md from that commit and uses package metadata from the tagged release. It requires an already-published non-draft, non-prerelease release, verifies tag/version and six attached artifacts, and preserves the prior title/body in a linked 90-day workflow artifact. It allows title correction, then verifies the exact tag title and corrected notes without uploading packages. An optional direct-command guard can be enabled with HOOK_RELEASE_GUARD=1; it checks a narrow set of gh release commands and is not publication authorization.

Repository-root installation

Compatibility manifests at the repository root preserve Git and local-path installation while keeping dist/<target> canonical:

claude plugin marketplace add alexei-led/cc-thingz
codex plugin marketplace add alexei-led/cc-thingz
copilot plugin marketplace add alexei-led/cc-thingz
grok plugin marketplace add alexei-led/cc-thingz
pi install git:github.com/alexei-led/cc-thingz

Marketplace registration exposes the seven cc-thingz packages; install the required package IDs separately. Pi loads the aggregate package. Cursor uses the root .cursor-plugin/marketplace.json through Cursor Marketplace rather than a plugin-management CLI.

Grok reads the Claude root marketplace for compatibility. Use dist/grok for Grok-specific overlays because Claude and Grok share the same root marker and cannot both select different target paths from one manifest. Root .codex/agents mirrors the generated project-agent profiles for checkout use; marketplace plugin installation does not install those fixed-path profiles into an unrelated Codex project.

See Repository-root compatibility for local paths, verification, limitations, and migration details. Install npm:pi-subagents separately when using the packaged cc-thingz.* agents in Pi.

The Pi archive is directly installable. Install pi-subagents separately only when using the packaged cc-thingz.* agents:

pi install npm:pi-subagents -l
pi install ./alexei-led-cc-thingz-pi.tgz -l

For a local release rehearsal:

agbun build --root .
agbun check --root .
agbun package --root . --out /tmp/cc-thingz-release

The generated Pi package includes its typed hook adapter, native ask_user_question and todo tools, plus hook-runner, permission-gate, and plan-mode. Its compatibility config contains only Pi-specific revdiff plan review and notifications, so portable Agent Bundler hooks do not run twice.

The package command, flat per-agent sidecars, safe Pi hook environments, native extension assets, and Codex project-agent profiles require a compatible installed Agent Bundler pinned in .agentbundler-version.

Installation diagnostics

Use the installation-doctor skill from the installed discovery plugin to inspect cached plugins without changing configuration or cloning this repository. The checkout also retains make doctor. See doctor usage and migration and runtime defaults before upgrading older installations.

Target differences and gaps

See Agent Bundler port status for target-specific behavior, runtime validation, and upstream/vendor boundaries. Do not recreate a custom compiler or post-process dist/.

Development checks

make lint
make validate
make build
make check
make test
make test-ts
make ci
agbun package --root . --out /tmp/cc-thingz-release

make validate checks Agent Bundler availability, source genericity, executable source scripts, and that every generated hook config uses known events and references files that exist in its plugin. make test also runs each generated hook command from its plugin root and verifies source/release helpers, hook manifests, target inventories, agent envelopes, version consistency, archives, and Pi decision-hook protocol output.

JS/TS hooks select project-declared tooling first. Without a project choice, they use available Oxfmt, Biome, and Oxlint before falling back to Prettier and ESLint. The formatter and linter are selected independently, so overlapping lint passes are not run. The resolver discovers top-level JS/TS roots such as src/, test/, and tests/, and skips projects without JS/TS files. make fmt and make lint use the same selection policy. make test-ts covers Pi-native extension and compatibility-runner behavior.

Contributing

Read CONTRIBUTING.md. Keep canonical content under src/, package configuration in agentbundle.json and src/.agentbundler/packages/, and generated output under dist/.

License

MIT