| created | 2025-12-20 |
|---|---|
| modified | 2026-04-21 |
| reviewed | 2026-04-21 |
Claude Code plugin collection providing skills and agents for development workflows.
<plugin-name>/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (see .claude/rules/plugin-structure.md)
├── README.md # Plugin documentation
├── CHANGELOG.md # Auto-generated by release-please
├── skills/
│ └── <skill-name>/
│ ├── SKILL.md # Skill definition (user-invocable and auto-discovered)
│ └── workflows/ # Bundled *.workflow.js templates (optional)
└── agents/ # Agent definitions (optional)
| Rule | Purpose |
|---|---|
.claude/rules/conventional-commits.md |
Commit and PR title format standards - drives release-please automation |
.claude/rules/plugin-structure.md |
plugin.json schema and directory layout |
.claude/rules/release-please.md |
Version management and changelog automation |
.claude/rules/skill-development.md |
Skill creation patterns |
.claude/rules/skill-consolidation.md |
Merging/deleting skills: verify the premise first, cross-plugin = name-reference (not shared REFERENCE.md), and the merge/delete checklist |
.claude/rules/agentic-optimization.md |
CLI output optimization for AI |
.claude/rules/skill-naming.md |
Skill namespace conventions |
.claude/rules/shell-scripting.md |
Safe shell patterns and frontmatter extraction |
.claude/rules/agentic-permissions.md |
Granular tool permissions for skills |
.claude/rules/auto-mode.md |
Auto mode availability, classifier rules, allow-rule fate, and authoring guidance |
.claude/rules/skill-quality.md |
Skill size limits, required sections, and quality checklist |
.claude/rules/skill-argument-handling.md |
9-axis rubric for args/argument-hint/parsing-vs-intent fit; the haiku+opus cold-read sweep that finds mismatches and the model delta that calibrates it |
.claude/rules/skill-execution-structure.md |
Imperative execution patterns for user-invocable skills |
.claude/rules/handling-blocked-hooks.md |
How to respond when hooks block commands |
.claude/rules/hook-block-vs-nudge.md |
Block (exit 2) only for safety; nudge for style — why a hard block on a tool-substitution dead-ends subagents lacking the tool, and the "what does it exempt?" litigation test |
.claude/rules/hooks-reference.md |
Complete hook event reference (2.1.50+): all events, schemas, timeouts, PermissionRequest |
.claude/rules/prompt-agent-hooks.md |
When to use prompt/agent hooks — decision tree, config schema, prompts guide |
.claude/rules/agent-development.md |
Agent configuration, isolation, background execution, memory, and teams |
.claude/rules/skill-fork-context.md |
When to set context: fork and agent: on skills |
.claude/rules/workflow-vs-skill.md |
When a bundled workflow .js earns its agents — enumerable N, real barrier, script-decidable bound; the workflows/ layout |
.claude/rules/regression-testing.md |
Required: add a script check for every skill bug fixed |
.claude/rules/skill-evaluation.md |
How we measure skill effectiveness: tiered cost, deterministic-vs-judge grading, cross-model delta signal |
.claude/rules/context-engineering.md |
Claude 5 context-engineering position — rank cuts by always-loaded cost, scope new rules with paths:, split large skills across many files; demotes three skill-quality.md mandates |
.claude/rules/sandbox-guidance.md |
Sandbox constraints, CLAUDE_CODE_REMOTE detection, and remote/local skill patterns |
.claude/rules/plugin-flow-diagrams.md |
When and how to add Mermaid flow diagrams |
.claude/rules/agent-coworker-detection.md |
Detect other agents working in the same repo clone before destructive git ops |
.claude/rules/pr-branch-sync.md |
Before building further on a PR branch, confirm it's live and in sync (remote sibling of coworker-detection) — the /git:pr-sync-check skill + check-branch-sync-on-push.sh hook + git-drift-probe.sh trio |
.claude/rules/workflow-naming.md |
<Domain>: <Action> naming for .github/workflows/*.yml and skill-generated workflow examples |
.claude/rules/github-actions-security.md |
GitHub Actions secure-use baseline — least-privilege GITHUB_TOKEN, script-injection env-var indirection, pull_request_target hazards, CODEOWNERS on workflows; the checklist every workflow-scaffolding skill follows |
.claude/rules/workflow-model-effort.md |
Workflow Claude model/effort standard — every .github/workflows invocation pins --model opus + explicit --effort (cost-economics, not the subagent-contamination argument); enforced by check-workflow-model.sh |
.claude/rules/bash-tool-replacements.md |
find/grep/rg/cat/head/tail → dedicated tools; when the Bash form is genuinely fine |
.claude/rules/gh-json-fields.md |
Correct gh --json field names (PR state/mergedAt, not merged); --limit and head: truncation traps |
.claude/rules/structured-script-output.md |
=== HEADER === / KEY=VALUE / STATUS= convention for diagnostic shell scripts |
.claude/rules/terminology.md |
Glossary of development terms with strong intent (scoping, review, parallelism, work state, code ops, requirements) — positive definitions with Use when disambiguation |
.claude/rules/parallel-safe-queries.md |
Query commands that exit non-zero on empty results silently cancel sibling parallel tool calls — use the machine-readable variant (--json/export + jq) |
.claude/rules/docs-currency.md |
Code and the docs describing it land in the same commit (stub → blueprint:blueprint-docs-currency) |
.claude/rules/version-pinning.md |
Version pins in skill examples (uses:/FROM/image:/rev:) are a Renovate-managed surface — SHA+comment convention, the coverage guard, and what's illustrative vs. managed |
.claude/rules/loop-integrity.md |
Long-running/self-continuing loops need an independent stop condition (a fresh verifier judges "done", not the worker) and a compact state packet each iteration (objective/ref/files/verifier-result/changed-since/exit-condition) — else they optimize for completion over correctness or automate context drift |
.claude/rules/gitattributes.md |
.gitattributes conventions — merge=union only for one-line-per-entry append-only files, linguist-generated for build output (always safe), LF normalization; the configure-gitattributes skill + resolve-additive-conflicts.py pre-pass |
.claude/rules/task-id-stability.md |
Taskwarrior numeric IDs renumber after every close — resolve the immutable UUID once and mutate by UUID, including within a single skill's own multi-step lifecycle, not just across bulk loops |
.claude/rules/generated-fleet-drift.md |
Auditing a generated fleet — divergence is not automatically drift: it is bidirectional (never auto-apply template → instance), an identically-diverging cohort signals intent, and undeclared intent is unauditable |
.claude/rules/plugin-usage-telemetry.md |
~/.claude.json's pluginUsage.usageCount counts hook fires, so it ranks trigger cadence rather than plugin value — nothing in this repo reads it (incl. health-check --scope=usage, which mines transcripts); the delivery signal is the lowercase-first attributionPlugin/attributionSkill/attributionAgent |
Auditing these docs: docs/audits/README.md records the Layer 1 (automated, monthly) / Layer 2 (quarterly + milestone-triggered) cadence and holds past findings artifacts.
Invoke /plugin-authoring — it carries the create-a-skill and create-a-user-invocable-skill frontmatter shapes, the seven metadata files a plugin add/delete must touch, and the development workflow. All four are procedures with a clear trigger, so they live in a skill rather than here (#2140).
See .claude/rules/agentic-optimization.md for detailed patterns.
Key principles:
- Compact output:
--dots,--reporter=github,-c - Fail fast:
--bail=1,-x - CI modes:
--reporter=junit,--frozen-lockfile - Machine-readable: JSON output when available
| Plugin Type | Example | Contains |
|---|---|---|
| Tool-focused | tools-plugin |
CLI tool skills (fd, rg, jq) |
| Language-focused | typescript-plugin |
Language ecosystem skills |
| Workflow-focused | git-plugin |
Git/GitHub operations |
| Infrastructure | configure-plugin |
Configuration automation |
CRITICAL: Commits and PR titles MUST follow conventional commit format.
All commits and PR titles must follow the pattern:
<type>(<scope>): <subject>
Why: This drives release-please version automation and maintains clean git history.
- Commits: Use
git commit -m "feat(plugin): description"with issue references - PR titles: MUST match conventional format - used as commit message on squash-merge
- Scope: Plugin or feature name (e.g.,
feat(git-plugin),fix(skill-development)) - Types:
feat,fix,perf,refactor,docs,test,ci,build,chore
See .claude/rules/conventional-commits.md for complete guide and examples.
# Write and test code
git add src/feature.ts tests/feature.test.ts
# Commit with conventional format + issue reference
git commit -m "feat(git-plugin): add new workflow
Closes #42
Refs #99"
# PR title must also be conventional
gh pr create --title "feat(git-plugin): add new workflow"Run this marketplace's skills inside local-model coding agents. Two targets, one mechanism (the adapter):
| Target | Source of truth | Doc | Recipes |
|---|---|---|---|
| pi (pi.dev) — adapter (ADR-0022) | adapters/pi/ binding |
adapters/README.md § pi, docs/pi-export.md |
just pi-adapter-check, pi-adapter, pi-adapter-register, pi-adapter-unregister (group adapters); serve-pi-model, setup-pi (group pi) |
| OpenCode — adapter (ADR-0022) | adapters/opencode/ binding |
adapters/README.md, docs/opencode-export.md |
just oc-adapter-check, oc-adapter-register, oc-adapter-unregister (group adapters); export-opencode, install-opencode, setup-opencode (group opencode) |
Both harnesses load Claude Code SKILL.md unmodified but neither budgets the skill listing: pi costs ~111 tok/skill and OpenCode ~88 (measured 2026-08-24 — ~34,000 standing tokens for 382 skills), both uncapped. The adapter (ADR-0022) closes that gap for each: a search_skills pull tool + per-turn ranked top-k push injection reaching all ~400 skills at ~600 standing tokens — see adapters/README.md.
Both cutovers are done. pi's curated tier installer (pi/tiers.yaml + scripts/install-pi.sh, ~9,900 standing tokens over ~95 skills) was removed in #2093; OpenCode's rulesync export was retired in #2094, once its own token calibration landed beside the retrieval gate frozen at main_hit_at_k_min = 0.57 on 2026-07-22 (adapters/CUTOVER.md §1 and §8). just export-opencode survives for the two surfaces the adapter does not cover — subagents (OpenCode does not auto-load ~/.claude/agents/) and hooks (OpenCode has no hook surface at all).
This repo runs blueprint-plugin against itself in a deliberately constrained mode. State lives in docs/blueprint/; see docs/blueprint/README.md for the full rationale.
| Task | Status | Why |
|---|---|---|
adr-validate, sync-ids, feature-tracker-sync |
enabled | Read-leaning workflows that genuinely add value across 16 ADRs / 2 PRDs / 5 PRPs |
story-audit, story-reconcile |
enabled | story-audit is read-only and writes only its own dated artifact under docs/blueprint/audits/. story-reconcile mutates PRDs only and confirms each edit interactively. |
derive-plans (subsumes former derive-prd/derive-adr), derive-rules, generate-rules, claude-md, curate-docs |
disabled | Would treat plugin source as project requirements or could overwrite the 18 hand-written rules / hand-curated CLAUDE.md |
Always run /blueprint:sync-ids with --dry-run first. Each disabled task carries a context.disabled_reason in the manifest — read it before flipping any flag back on.
Autonomy level 3 is consumer-only (ADR-0020, #2005). This repo stays at automation.autonomy_level: 1 and never runs the level-3 out-of-band pipeline. /blueprint:autonomy-level3 scaffolds that pipeline (the blueprint-autorun + blueprint-wo-execute workflow templates + gate/parser scripts) into a downstream consumer repo that opts in; it is authored and tested here but not exercised here.
| Scope | Effect | Use for |
|---|---|---|
chore(blueprint): … |
No version bump | Manifest bookkeeping, sync runs, ID assignments inside docs/blueprint/ |
feat(blueprint-plugin): … |
Minor version bump on the published plugin | Skill changes inside blueprint-plugin/ |
fix(blueprint-plugin): … |
Patch version bump | Bug fixes inside blueprint-plugin/ |
What keeps dogfooding from publishing the plugin is the chore type (no bump) plus keeping edits under docs/blueprint/ — not the blueprint scope. release-please routes by files touched, not by scope (.claude/rules/conventional-commits.md), so fix(blueprint): … on a file inside blueprint-plugin/ would publish.
- Skill names: lowercase-hyphenated (
bun-development) - Skill invocation: lowercase with colons for nesting (
/bun:install) - Plugin names: suffix with
-plugin(typescript-plugin) - Use tables for quick reference (flags, options)
- Include both short and long flag forms where applicable
|
.claude/rules/drift-detection-triggering.md| drift detection triggering | |.claude/rules/offload-to-deterministic-substrate.md| offload to deterministic substrate |