From 25d1b3be2e9349a46a648fa55a132f5d4f35a21e Mon Sep 17 00:00:00 2001 From: Emeric Favarel <47535798+moukrea@users.noreply.github.com> Date: Tue, 24 Feb 2026 18:04:51 +0100 Subject: [PATCH] docs: restructure README with dedicated per-plugin documentation --- CONTRIBUTING.md | 5 +- README.md | 134 ++---------------------------------- plugins/craft/README.md | 29 ++++++++ plugins/git-pilot/README.md | 56 +++++++++++++++ plugins/opaq/README.md | 41 +++++++++++ 5 files changed, 136 insertions(+), 129 deletions(-) create mode 100644 plugins/craft/README.md create mode 100644 plugins/git-pilot/README.md create mode 100644 plugins/opaq/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88ce2ab..cd84f3b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,8 +24,9 @@ claude-code-plugins/ │ ├── release.yml # Auto-release on main │ └── tag-release.yml # GitHub release creation └── plugins/ - ├── opaq/ # Credential security plugin - └── craft/ # Prompt generation plugin + ├── craft/ # Prompt generation plugin + ├── git-pilot/ # Git workflow automation plugin + └── opaq/ # Credential security plugin ``` ## Adding a New Plugin diff --git a/README.md b/README.md index 85650b7..2f25bcd 100644 --- a/README.md +++ b/README.md @@ -4,81 +4,11 @@ Productivity and security plugins for [Claude Code](https://claude.ai/code). ## Plugins -### opaq — Secure Credential Access - -Gives Claude Code secure access to your credentials without ever exposing secret values in the conversation, shell history, or files. - -**What it does:** - -- Teaches Claude the `opaq search` + `opaq run` workflow via a skill file -- Blocks direct access to the encrypted store and OS keychain via hooks -- Auto-wraps commands containing `{{SECRET}}` placeholders with `opaq run --` -- Prevents Claude from writing placeholder patterns to files - -**In practice:** - -``` -You: "Deploy the app to production" - -Claude: Let me find the deployment credentials. - $ opaq search deploy - # {{DEPLOY_TOKEN}} Production deployment API token - $ opaq run -- curl -X POST -H "Authorization: Bearer {{DEPLOY_TOKEN}}" ... -``` - -The secret value is injected at runtime and scrubbed from all output. Claude never sees it. - -Requires the [opaq](https://github.com/moukrea/opaq) binary installed on your system. - -### git-pilot — Git Workflow Autopilot - -Manages the full git workflow lifecycle automatically — branch creation, commit formatting, push prompts, and merge request creation. - -**What it does:** - -- Enforces branch naming conventions and prevents direct commits to the default branch -- Validates commit messages against configurable patterns (conventional commits by default) -- Prompts to push after every commit and offers merge request creation at session end -- Provides `/branch`, `/finish`, `/summary`, and `/configure` skills - -**In practice:** - -``` -You: "Add dark mode support" - -Claude: [git-pilot] On default branch 'main'. Prompt the user to create - a branch before making changes. - → Creates feat/add-dark-mode-support - → Works, commits with validated messages - → Prompts to push after each commit - → Offers to create a PR when done -``` - -Configuration via `~/.claude/git-pilot.json` (global) or `.claude/git-pilot.json` (per-project). - -### craft — Autonomous Implementation Prompts - -Generates orchestration prompts that coordinate agent teams to implement entire projects from a technical specification. - -**What it does:** - -- Analyzes a technical spec and breaks it into self-contained module documents -- Designs a bottom-up build order and task dependency graph -- Generates a `PROMPT.md` that orchestrates multi-phase agent teams - -**Usage:** - -``` -/craft @TECHNICAL-SPEC.md -``` - -Or describe what you want to build: - -``` -/craft A CLI tool that converts markdown files to PDF with custom themes -``` - -craft will generate a spec first, then produce the orchestration prompt. +| Plugin | Description | +|--------|-------------| +| [opaq](plugins/opaq/) | Secure credential access — use secrets in commands without ever exposing them | +| [git-pilot](plugins/git-pilot/) | Automated git workflow — branch creation, commit formatting, push and MR prompts | +| [craft](plugins/craft/) | Generate multi-phase implementation prompts from technical specs | ## Installation @@ -94,8 +24,8 @@ Install plugins: ``` /plugin install opaq@moukrea-plugins -/plugin install craft@moukrea-plugins /plugin install git-pilot@moukrea-plugins +/plugin install craft@moukrea-plugins ``` ### From a local clone @@ -110,57 +40,7 @@ Add the local directory as a marketplace source: /plugin marketplace add ./claude-code-plugins ``` -Install plugins: - -``` -/plugin install opaq@moukrea-plugins -/plugin install craft@moukrea-plugins -/plugin install git-pilot@moukrea-plugins -``` - -## How Plugins Work - -### Skills - -Skills are markdown files that teach Claude when and how to use a tool. They include: - -- **Trigger conditions** — when the skill should activate (e.g., "when a task requires credentials not in the environment") -- **Workflow instructions** — step-by-step usage -- **Security rules** — constraints Claude must follow -- **Examples** — concrete command patterns - -### Hooks - -Hooks intercept Claude's tool calls before execution. Examples: - -| Plugin | Hook | Trigger | Action | -|--------|------|---------|--------| -| opaq | Bash guard | Any Bash command | Blocks store/keychain access, auto-wraps `{{SECRET}}` commands | -| opaq | File guard | Write, Edit, MultiEdit | Blocks writing `{{SECRET}}` placeholders to files | -| opaq | Session start | New session | Announces opaq availability | -| git-pilot | Session start | New session | Detects branch state, prompts for branch creation | -| git-pilot | Pre-commit | `git commit` | Validates commit message format and body policy | -| git-pilot | Post-bash | `git commit` | Prompts to push unpushed commits | -| git-pilot | Session stop | Session end | Shows work summary, offers push and MR creation | - -## Plugin Structure - -Each plugin lives in `plugins//` and contains: - -``` -plugins// -├── .claude-plugin/ -│ └── plugin.json # Plugin manifest (name, version, description) -├── skills/ -│ └── / -│ └── SKILL.md # Skill definition with YAML frontmatter -├── hooks/ -│ └── hooks.json # Hook definitions (optional) -└── scripts/ - └── *.sh # Hook implementation scripts (optional) -``` - -The root `.claude-plugin/marketplace.json` is the registry that lists all available plugins. +Then install plugins using the same commands as above. ## License diff --git a/plugins/craft/README.md b/plugins/craft/README.md new file mode 100644 index 0000000..2d02d7e --- /dev/null +++ b/plugins/craft/README.md @@ -0,0 +1,29 @@ +# craft — Autonomous Implementation Prompts + +Generates orchestration prompts that coordinate agent teams to implement entire projects from a technical specification. + +## What it does + +- Analyzes a technical spec and breaks it into self-contained module documents +- Designs a bottom-up build order and task dependency graph +- Generates a `PROMPT.md` that orchestrates multi-phase agent teams + +## Usage + +``` +/craft @TECHNICAL-SPEC.md +``` + +Or describe what you want to build: + +``` +/craft A CLI tool that converts markdown files to PDF with custom themes +``` + +craft will generate a spec first, then produce the orchestration prompt. + +## Installation + +``` +/plugin install craft@moukrea-plugins +``` diff --git a/plugins/git-pilot/README.md b/plugins/git-pilot/README.md new file mode 100644 index 0000000..29b6ca9 --- /dev/null +++ b/plugins/git-pilot/README.md @@ -0,0 +1,56 @@ +# git-pilot — Git Workflow Autopilot + +Manages the full git workflow lifecycle automatically — branch creation, commit formatting, push prompts, and merge request creation. + +## What it does + +- Enforces branch naming conventions and prevents direct commits to the default branch +- Validates commit messages against configurable patterns (conventional commits by default) +- Prompts to push after every commit and offers merge request creation at session end +- Provides `/branch`, `/finish`, `/summary`, and `/configure` skills + +## In practice + +``` +You: "Add dark mode support" + +Claude: [git-pilot] On default branch 'main'. Prompt the user to create + a branch before making changes. + -> Creates feat/add-dark-mode-support + -> Works, commits with validated messages + -> Prompts to push after each commit + -> Offers to create a PR when done +``` + +## Skills + +| Skill | Description | +|-------|-------------| +| `/branch` | Create a new branch using the configured naming pattern | +| `/finish` | Commit remaining changes, push, and optionally create a merge request | +| `/summary` | Show a summary of work done on the current branch | +| `/configure` | Change git-pilot settings using natural language | + +## Hooks + +| Hook | Trigger | Action | +|------|---------|--------| +| Session start | New session | Detects branch state, prompts for branch creation | +| Pre-commit | `git commit` | Validates commit message format and body policy | +| Post-bash | `git commit` | Prompts to push unpushed commits | +| Session stop | Session end | Shows work summary, offers push and MR creation | + +## Configuration + +Settings can be defined at two levels (local overrides global): + +- **Global**: `~/.claude/git-pilot.json` +- **Per-project**: `.claude/git-pilot.json` + +Use `/configure` to change settings interactively, or edit the JSON files directly. Configuration covers branch naming, commit format, remote behavior, merge request defaults, and more. + +## Installation + +``` +/plugin install git-pilot@moukrea-plugins +``` diff --git a/plugins/opaq/README.md b/plugins/opaq/README.md new file mode 100644 index 0000000..5fa3f64 --- /dev/null +++ b/plugins/opaq/README.md @@ -0,0 +1,41 @@ +# opaq — Secure Credential Access + +Gives Claude Code secure access to your credentials without ever exposing secret values in the conversation, shell history, or files. + +## What it does + +- Teaches Claude the `opaq search` + `opaq run` workflow via a skill file +- Blocks direct access to the encrypted store and OS keychain via hooks +- Auto-wraps commands containing `{{SECRET}}` placeholders with `opaq run --` +- Prevents Claude from writing placeholder patterns to files + +## In practice + +``` +You: "Deploy the app to production" + +Claude: Let me find the deployment credentials. + $ opaq search deploy + # {{DEPLOY_TOKEN}} Production deployment API token + $ opaq run -- curl -X POST -H "Authorization: Bearer {{DEPLOY_TOKEN}}" ... +``` + +The secret value is injected at runtime and scrubbed from all output. Claude never sees it. + +## Requirements + +The [opaq](https://github.com/moukrea/opaq) binary must be installed on your system. + +## Hooks + +| Hook | Trigger | Action | +|------|---------|--------| +| Bash guard | Any Bash command | Blocks store/keychain access, auto-wraps `{{SECRET}}` commands | +| File guard | Write, Edit, MultiEdit | Blocks writing `{{SECRET}}` placeholders to files | +| Session start | New session | Announces opaq availability | + +## Installation + +``` +/plugin install opaq@moukrea-plugins +```