alexei-led-cc-thingz

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 notes and versions, runs make check for generated drift, and creates only a local annotated tag. It does not repeat the full test suite; full CI and runtime smoke tests gate publication in the release workflow. 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, hook-runner, permission-gate, and plan-mode. Use the separate pi-tasks package for task tracking. The compatibility runner has no personal defaults; configure messaging, notifications, and plan review at user scope. Portable Agent Bundler hooks must not be registered 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.

Workflow ownership

Use coding-posture for the general debug, fix, review, test-first, refactor, and optimize procedure. cc-thingz keeps defect evidence contracts, review rubrics, test-design references, and language tooling. Do not load two skills just to repeat the same checklist.

• Design exploration: brainstorming-ideas; implementation requires approval.
• Releases: releasing-code, following the project's publication workflow.
• Ordinary review: reviewing-code. Use Revmux for explicitly requested multi-agent review and Revdiff for interactive annotations when installed.
• Authoring: writing-skills; instruction scoring: reviewing-instructions; behavioral evaluation: the eval commands.
• Configuration audits: evolving-config; installation inventory: installation-doctor.

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.

Writing

The dev-flow package includes writing-style for concise commit messages, PR/MR descriptions, issues, and review comments. It keeps risks and uncertainty explicit and omits boilerplate. Drafting text does not authorize publishing it. Use documenting-code for project docs and supported, render-checked visuals, writing-skills for AI instructions, and releasing-code for release notes.

Repository AGENTS.md sets writing defaults for this checkout. Installed skills load by task. They do not impose a global style on every answer. Put universal writing preferences in your own top-level agent instructions.

Git cleanup

An explicit cleanup request lets the agent remove verified merged branches and clean worktrees, including squash merges, without a second confirmation. Risky objects stay until you approve their specific loss; the agent then runs the command itself. See cleanup policy and consent limits.

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