diff --git a/development/claude-plugins-marketplace.md b/development/claude-plugins-marketplace.md new file mode 100644 index 0000000..3ce0024 --- /dev/null +++ b/development/claude-plugins-marketplace.md @@ -0,0 +1,130 @@ +--- +title: "Claude Plugins Personal Marketplace" +description: "Reference for the cal/claude-plugins Gitea repo — personal Claude Code plugin marketplace with 20 plugins (10 agents, 10 skills), including installation, adding new plugins, and maintenance." +type: reference +domain: development +tags: [claude-code, plugins, gitea, marketplace] +--- + +# Claude Plugins Personal Marketplace + +**Repo:** `cal/claude-plugins` on Gitea ([https://git.manticorum.com/cal/claude-plugins](https://git.manticorum.com/cal/claude-plugins)) +**Local clone:** `/mnt/NV2/Development/claude-plugins/` +**License:** AGPL-3.0 + +## What It Is + +A self-hosted Claude Code plugin marketplace containing 20 plugins (10 agents, 10 skills) extracted from local `~/.claude/` definitions. Registered via `claude plugin marketplace add https://git.manticorum.com/cal/claude-plugins.git` (stored in `~/.claude/settings.json` under `extraKnownMarketplaces`). + +## Plugin Inventory + +### Agents (10) + +| Name | Description | +|------|-------------| +| architect | PRD creation, system design, technical specs | +| claude-researcher | Web research with multi-query decomposition | +| designer | UX/UI design review, visual design, accessibility | +| engineer | Code implementation, debugging, optimization, testing | +| issue-worker | Autonomous Gitea issue fixer — creates PRs | +| pentester | Penetration testing and vulnerability assessments | +| pr-reviewer | Automated Gitea PR reviewer | +| swarm-coder | Implementation agent for orchestrated swarms | +| swarm-reviewer | Code reviewer for orchestrated swarms | +| swarm-validator | Spec validator for orchestrated swarms | + +### Skills (10) + +| Name | Description | +|------|-------------| +| backlog | Surface next Gitea issue or TODO to work on | +| create-scheduled-task | Manage headless Claude scheduled tasks on systemd timers | +| json-pretty | JSON prettifier CLI tool | +| optimise-claude | Guide for writing effective CLAUDE.md files | +| playwright-cli | Browser automation for testing and screenshots | +| project-plan | Generate PROJECT_PLAN.json for task tracking | +| resume-tailoring | Tailored resume generation with company research | +| save-doc | Save documentation to KB with proper frontmatter | +| youtube-transcriber | Transcribe YouTube videos via OpenAI GPT-4o-transcribe | +| z-image | Local GPU image generation with Z-Image Turbo | + +## Installation + +```bash +# Marketplace is already registered. To install a plugin: +claude plugin install @cal-claude-plugins --scope user + +# Enable/disable: +claude plugin enable @cal-claude-plugins +claude plugin disable @cal-claude-plugins + +# Update marketplace cache (pulls latest from Gitea): +claude plugin marketplace update cal-claude-plugins +``` + +## Adding a New Plugin + +### Directory Structure + +Each plugin lives under `plugins//` with this layout: + +``` +plugins// + .claude-plugin/ + plugin.json # name, description, version + skills// # for skill plugins + SKILL.md # skill definition with frontmatter + agents/ # for agent plugins + .md # agent definition +``` + +### plugin.json + +```json +{ + "name": "my-plugin", + "description": "One-line description of what it does.", + "version": "1.0.0" +} +``` + +### SKILL.md Frontmatter + +```yaml +--- +allowed-tools: Read,Write,Edit,Glob,Grep,Bash +description: What this skill does +user-invocable: true +--- +``` + +### Register in marketplace.json + +Add an entry to `.claude-plugin/marketplace.json` in the `plugins` array: + +```json +{ + "name": "my-plugin", + "source": "./plugins/my-plugin", + "description": "One-line description." +} +``` + +### Commit and Push + +```bash +cd /mnt/NV2/Development/claude-plugins +git add plugins/my-plugin .claude-plugin/marketplace.json +git commit -m "feat: add my-plugin skill" +git push origin main +``` + +Then update the cache: `claude plugin marketplace update cal-claude-plugins` + +## Important Notes + +- **SKILL.md `name:` must match directory name** — a mismatch causes the skill to not load (e.g., the `optimise-claude` plugin had `name: claude-optimised` which broke it) +- **SSH remote** — uses `git@git.manticorum.com:cal/claude-plugins.git` via SSH config alias (`~/.ssh/config` maps `git.manticorum.com` → `10.10.0.225` as user `git`) +- **No secrets** — repo is public; plugins are just prompt definitions, no credentials +- **Plugins requiring MCP servers** — `backlog`, `issue-worker`, and `pr-reviewer` require `gitea-mcp`; they install fine without it but those tool calls won't execute +- **sync-kb does NOT apply here** — this is a standalone repo, not part of claude-home. Changes require manual commit/push diff --git a/development/permission-manager-classifier-development.md b/development/permission-manager-classifier-development.md new file mode 100644 index 0000000..6541658 --- /dev/null +++ b/development/permission-manager-classifier-development.md @@ -0,0 +1,138 @@ +--- +title: "Writing Classifiers for permission-manager (agent-toolkit)" +description: "Guide to adding new command classifiers to the St0nefish/agent-toolkit permission-manager plugin for Claude Code, covering project structure, conventions, testing, and PR workflow." +type: guide +domain: development +tags: [claude-code, permissions, agent-toolkit, bash, classifier] +--- + +# Writing Classifiers for permission-manager + +## Overview + +The `permission-manager@agent-toolkit` plugin (St0nefish/agent-toolkit) provides a `cmd-gate` PreToolUse hook that classifies Bash commands before execution. Classifiers are bash scripts in `plugins-claude/permission-manager/scripts/classifiers/` that decide whether commands should be auto-allowed, require user approval, or be denied. + +## Project Structure + +``` +plugins-claude/permission-manager/ + scripts/ + cmd-gate.sh # Hook entry point + lib-classify.sh # Classification framework + dispatcher + classifiers/ + cargo.sh # cargo/rust + docker.sh # docker/compose + find.sh # find (deny -delete/-exec rm) + git.sh # git (with protected branch logic) + gh.sh # GitHub CLI + gradle.sh # gradle/gradlew + jvm-tools.sh # java/mvn + npm.sh # npm/node/pnpm/yarn/npx + pip.sh # pip/python/poetry/pyenv + read-only-tools.sh # cat, ls, grep, jq, ps, etc. + tea.sh # Gitea CLI + uv.sh # uv/uvx (added 2026-03-18) +tests/permission-manager/ + test-classify.sh # Main test harness (618+ tests) +``` + +## Classification Decisions + +Three possible outcomes: +- **`allow`** — auto-approve, no prompt (read-only or safe local operations) +- **`ask`** — prompt user for approval (destructive, remote, or elevated operations) +- **`deny`** — block the command (e.g., `find -delete`) +- **passthrough** — `return 0` without calling allow/ask/deny; defers to Claude Code's built-in permission system + +## Classifier Conventions + +### File Header +```bash +# shellcheck shell=bash +# shellcheck source=../lib-classify.sh +``` + +### Function Naming +- Entry point: `check_()` (e.g., `check_uv`, `check_docker`) +- Subcommand extractor: `extract__subcommand()` (for tools with global flags) + +### Entry Guard Pattern + +Simple tools (cargo, npm, pip) use `awk` + `case`: +```bash +local first_token +first_token=$(echo "$command" | awk '{print $1}') +case "$first_token" in + uv) ;; + *) return 0 ;; +esac +``` + +Complex tools (docker, git) use `perl` guard: +```bash +echo "$command" | perl -ne '$f=1,last if /^\s*docker(\s|$)/; END{exit !$f}' || return 0 +``` + +### Reason Message Style +- Read-only: `" is read-only"` +- Local ops: `" is a local build/dev operation"` +- Ask: `" modifies "` +- Deny: `" is not allowed"` + +### Classification Philosophy (from existing classifiers) +| Category | Decision | Examples | +|----------|----------|---------| +| Read-only inspection | allow | `git status`, `docker ps`, `pip list` | +| Local build/install | allow | `npm install`, `pip install`, `cargo build` | +| Global tool install | ask | `cargo install`, `uv tool install` | +| Package uninstall | ask | `pip uninstall`, `uv pip uninstall` | +| Publish/deploy | ask | `npm publish`, `cargo publish`, `uv publish` | +| Execute arbitrary packages | passthrough | `npx`, `uvx`, `uv run --with` | +| Destructive operations | deny | `find -delete` | + +## Wiring a New Classifier + +In `lib-classify.sh`, add to `classify_single_command()`: +```bash +check_ +[[ "$CLASSIFY_MATCHED" -eq 1 ]] && return 0 +``` + +Place it logically near related classifiers (e.g., `check_uv` after `check_pip`). + +## Testing + +### Test Format +```bash +run_test_both "" ["label"] +``` +`run_test_both` runs the test in both Claude and Copilot modes. Expected values: `allow`, `ask`, `deny`, `none` (passthrough). + +### Test Section Structure +```bash +# ===== ALLOW: read-only ===== +echo "── read-only ──" +run_test_both allow "" + +# ===== ALLOW: local build/dev ===== +echo "── local build/dev ──" +... +``` + +### Running Tests +```bash +bash tests/permission-manager/test-classify.sh # Full suite +bash tests/permission-manager/test-classify.sh uv # Filter by keyword +``` + +## PR Workflow + +1. Fork `St0nefish/agent-toolkit` on GitHub +2. Branch from `master` (not `main`) +3. Add classifier, wire it, update tests +4. Run full test suite — zero regressions required +5. PR via `gh pr create --repo St0nefish/agent-toolkit --base master` + +## Reference PR + +- [PR #38: feat: add uv/uvx classifier](https://github.com/St0nefish/agent-toolkit/pull/38) — full uv/uvx classifier with 102 tests, submitted 2026-03-18