Claude Code Toolkit — Bonitasoft
bonitasoft-ps/ofelia-claude-code-toolkit
Metodologia de dev com IA: skills, hooks e commands para Bonitasoft
Ver no GitHubCatálogo centralizado de skills, comandos, hooks e configurações para Claude Code que padroniza o desenvolvimento de software na Bonitasoft. Inclui 55 skills especializadas, 5 agentes delegados, 18 comandos slash e 15 hooks automáticos para garantir qualidade, testing e consistência entre projetos BPM/BPA.
Instalação
npx convez-ai bonitasoft-ps/ofelia-claude-code-toolkit1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Padronizar desenvolvimento entre times Bonitasoft com automação de qualidade
- Executar análises, testes e auditorias automáticas via hooks durante coding
- Delegar tarefas especializadas (review, testes, documentação) a agentes isolados
- Reutilizar templates, configs e skills em múltiplos projetos BPM
Veredito

Toolkit maduro e bem estruturado para times Bonitasoft que automatiza fluxos de dev complexos via Claude Code. Requer setup de dependências (Git Bash, Python, Java, Maven), mas retorna consolidação metodológica e redução de erros em larga escala.
README
A tradução para o português deste README ainda está na fila.
Claude Code Toolkit — Bonitasoft Development Methodology
New to the Ofelia / Bonitasoft PS ecosystem? Start with the Ofelia PS Handbook in this repo — it maps the four repos (this one plus
ofelia-ai-agent-mcp,ofelia-document-toolkit,ps-consultant-plugin), explains how they call each other, and walks you through the onboarding checklist. Companion:DOCUMENT-TYPES-MASTER.md— index of where every PS deliverable type's apartados live.
A catalog of skills, commands, hooks, and configurations for Claude Code that defines how Bonitasoft builds software with AI.
Clone this repository. Pick what you need. Install at the right scope. Code better.
git clone https://github.com/bonitasoft-ps/ofelia-claude-code-toolkit.git
Prerequisites
- Git Bash (Windows) or bash (macOS/Linux) — required for hooks
- Python 3.x — required for analysis hooks
- Java 17+ — required for compile hooks
- Maven 3.9+ — required for build hooks
Table of Contents
- Install as a Claude Code Plugin (ofelia-claude-code-toolkit)
- Session continuity — never lose context (/save-session)
- What is this?
- The 3 Scopes + Priority System
- Resource Catalog by Scope
- Installation Guide
- What are Commands, Hooks, Skills?
- Agents (Subagents)
- MCP Skills
- Plugins
- When to Use What
- Where to Define Things
- Repository Structure
- Contributing
- Projects Using This Toolkit
What is this?
This repository is the single source of truth for Bonitasoft's AI-assisted development methodology. It contains:
| What | Purpose | How many |
|---|---|---|
| Skills | Expert knowledge with progressive disclosure (BDM, REST API, UIB, Audit, Testing...) | 55 |
| Agents | Isolated subagents for delegated tasks (code review, test generation, audit, docs) | 5 |
| Commands | Slash commands for common tasks (/run-tests, /generate-tests) | 18 |
| Hooks | Automatic checks that fire without user action (format, style, compile, git workflow) | 15 |
| Configs | Standard rule files (Checkstyle, PMD, EditorConfig) | 3 |
| Templates | Ready-to-use settings, CLAUDE.md starter, GitHub Actions | 4 |
Why this exists
Without a shared methodology, each developer writes code differently, forgets quality checks, and reinvents solutions. This toolkit:
- Homogenizes development — Everyone follows the same standards, automatically
- Prevents errors — Hooks catch issues during development, not in code review
- Ensures testing — Auto-test agents create and run tests when Claude finishes
- Avoids duplication — Commands check for existing implementations before creating new ones
- Onboards instantly — New team members get everything by cloning the project
How to use it
- Clone this repository
- Choose which resources you need (see the catalog below)
- Install at the right scope (Enterprise, Personal, or Project)
- Restart Claude Code
You can also use the automated installer:
bash install.sh
Install as a Claude Code Plugin (ofelia-claude-code-toolkit)
This repository also distributes ofelia-claude-code-toolkit, a Claude Code plugin that bundles the Bonita expert skills, agents and slash commands listed above. If you just want the AI assistance — without the methodology files, hooks templates, configs and project scaffolds — install the plugin. No clone, no scripts.
Renamed in v2.0. The plugin slug was previously
bonita-ai-agentand the marketplace wasbonitasoft-ps. Both were renamed toofelia-claude-code-toolkitto align with the Ofelia rebrand and to avoid confusion with the sibling MCP server repo (bonita-ai-agent-mcp, which is a different artifact). If your~/.claude/settings.jsonstill has the old names, replace them with the new ones below.
Where to run the commands below: inside the Claude Code prompt (the chat with Claude), not in your terminal. The
/pluginslash commands work on every Claude Code surface that runs locally:
- CLI (
claudein your terminal) — full support, all three install options work- Desktop app (Mac / Windows) — full support, but you also need to confirm the plugin from the UI after editing
settings.json(see Option A below)- IDE extensions (VS Code, JetBrains) — full support
All three share the same
~/.claude/config on your machine, so installing once makes the plugin available everywhere.What about
claude.ai(the web app)? As of 2026-05, plugin installation is blocked at the organization level for thebonitasoft.comworkspace —Customize → Connect tools you use → Pluginslists the plugins but the install button is disabled. Use the CLI, Desktop or IDE for now. If/when admins lift the restriction, the same/pluginflow described below will work inclaude.aitoo.
Three install options
Option A — Auto-install via settings.json (recommended for the team)
Add the following to ~/.claude/settings.json (Windows: %USERPROFILE%\.claude\settings.json):
{
"extraKnownMarketplaces": {
"ofelia-claude-code-toolkit": {
"source": {
"source": "git",
"url": "https://github.com/bonitasoft-ps/ofelia-claude-code-toolkit.git"
},
"autoUpdate": true
}
},
"enabledPlugins": {
"ofelia-claude-code-toolkit@ofelia-claude-code-toolkit": true
}
}
Restart Claude Code and accept the Trust marketplace prompt that appears. "autoUpdate": true keeps the plugin on the latest commit from master.
On the CLI: that's all — the plugin is installed and ready.
On the Desktop app (Mac / Windows), one extra UI step:
- Open Customize (top-right or main menu).
- Scroll to the Custom Plugins section.
- Click the
+button and add the plugin (it appears automatically because the marketplace is already registered viasettings.json).
Alternatively from the same Customize panel: Explorar → plugins → Buscar en código (search by name), open the plugin card and click Más / More → Install.
After this UI confirmation the Desktop app loads the plugin like the CLI does.
Option B — Interactive UI
In any Claude Code session, type /plugin. Tab to Marketplaces → Add new marketplace → paste https://github.com/bonitasoft-ps/ofelia-claude-code-toolkit.git → accept trust prompt. Then tab to Discover → select ofelia-claude-code-toolkit → press Enter → Install.
Option C — Slash commands (one at a time)
/plugin marketplace add https://github.com/bonitasoft-ps/ofelia-claude-code-toolkit.git
Wait for "Marketplace added", then:
/reload-plugins
Wait, then:
/plugin install ofelia-claude-code-toolkit@ofelia-claude-code-toolkit
Each line is a separate message. Pasting them all at once makes Claude Code treat the concatenation as one argument and fail.
Use the full HTTPS URL ending in
.git— the shorthandbonitasoft-ps/ofelia-claude-code-toolkitdefaults to an SSH clone (git@github.com:...) which fails on most machines because there is no SSH key configured for GitHub. HTTPS uses the credential helper set up bygh auth setup-git.
Verify the install
/plugin
Tab to Installed — ofelia-claude-code-toolkit@ofelia-claude-code-toolkit should appear with all its skills, agents and the MCP server. Tab to Errors to see any loading issue (if everything is fine, that tab is empty).
You can also confirm from the shell:
claude plugin list
This prints every installed plugin with its marketplace and version.
After install — quick start
Skills auto-invoke. Once the plugin is loaded, the 55 Bonita expert skills become available with the namespace prefix ofelia-claude-code-toolkit: (for example ofelia-claude-code-toolkit:bonita-audit-expert, ofelia-claude-code-toolkit:bonita-pdf-corporate). You don't have to call them by name — Claude picks the right one when it detects a relevant task. Just describe what you want:
"Audit this Bonita project against the PS audit rules" "Plan an upgrade from Bonita 7.5.2 to 2026.1" "Generate a connector spec for a Salesforce REST API"
To force a specific skill, prefix the slash command with the namespace:
/ofelia-claude-code-toolkit:bonita-audit-expert
Agents are also namespaced. To delegate to a sub-agent:
delegate to ofelia-claude-code-toolkit:bonita-code-reviewer: review this controller
List everything the plugin provides at any time:
/help
Skills, agents and commands from the plugin appear under the ofelia-claude-code-toolkit heading.
Update the plugin
If you used Option A with "autoUpdate": true, updates happen automatically when Claude Code starts.
Manual update on demand:
/plugin marketplace update ofelia-claude-code-toolkit
Then:
/reload-plugins
Each on its own message.
To pin to a specific branch or tag, set a ref on the marketplace source in settings.json:
"source": {
"source": "git",
"url": "https://github.com/bonitasoft-ps/ofelia-claude-code-toolkit.git",
"ref": "v1.2.0"
}
Any branch, tag or commit SHA works as ref.
Session continuity — never lose context (/save-session)
The plugin keeps a living LAST_SESSION.md in your project root: a short, AI-generated summary of the current Claude Code session so you (or the next session) can pick up exactly where you left off. No setup needed — it ships with the plugin and is active as soon as it is installed.
What it does
It writes/updates LAST_SESSION.md with a structured summary:
# Last Session Context
**Date**: 2026-06-08 17:42
**Branch**: claude/feat/my-change
**Summary**: One or two lines describing what this session was about.
## Hecho (what was done)
## Decisiones (decisions taken)
## Pendiente (next steps)
## Ficheros (files touched)
Read it at the start of your next session (open the file, or add a line to your CLAUDE.md telling Claude to read LAST_SESSION.md first) and you resume with full context.
When it runs
| Trigger | Event | Behaviour |
|---|---|---|
| Automatic, periodic | Stop (end of each turn) | Throttled to once every 30 min. Almost every turn just checks a timestamp and exits — near-zero tokens, runs in the background, never blocks or spams. |
| Automatic, on exit | SessionEnd | Forces a fresh, complete summary when you close the session. |
| Manual (like Ctrl+S) | command | /save-session — save right now. |
| Manual (short alias) | command | /save-s — identical to /save-session, just shorter to type. |
/save-session and /save-s are the same command; the alias exists only for speed. Use whichever you prefer:
/ofelia-claude-code-toolkit:save-session
/ofelia-claude-code-toolkit:save-s
Why it is cheap and quiet
- The summary is generated with Haiku (the cheapest model), and only when the 30-min throttle allows or you force it. The vast majority of stops cost 0 tokens.
- The automatic
Stophook isasync: it runs in the background, so it never blocks your turn or produces on-screen feedback. - A recursion guard (
CC_NO_SESSION_SUMMARY) stops the helper from re-triggering the hooks.
Requirements
- The
claudeCLI must be on yourPATH(it is, if you run Claude Code). - Node.js (also required by Claude Code). The whole feature is a single cross-platform Node script (
scripts/save-session.mjs), so it works the same on Windows, macOS and Linux — no PowerShell/bash variants to maintain.
Tuning / disabling
- Change the interval: edit the
Stophook command inhooks/hooks.jsonand add--throttle <minutes>(e.g.--throttle 15). - Manual-only: remove the
Stopand/orSessionEndentries fromhooks/hooks.json(or disable the plugin's hooks) and rely on/save-session. - Apply changes in an already-open session: run
/reload-plugins, or just restart Claude Code. New sessions pick it up automatically.
LAST_SESSION.mdis local context. Add it to your.gitignoreif you don't want to commit it.
The 3 Scopes + Priority System
Claude Code uses a priority system for skills, commands, hooks, and settings. When two resources share the same name, the higher-priority scope wins:
┌──────────────────────────────────────────────────────────────┐
│ │
│ PRIORITY 1 ★★★ Enterprise │
│ Organization-wide. Cannot be overridden. Maximum control. │
│ │
│ PRIORITY 2 ★★☆ Personal │
│ Your home directory. Available in ALL your projects. │
│ │
│ PRIORITY 3 ★☆☆ Project │
│ Inside the repo. Shared with team via git. │
│ │
│ PRIORITY 4 ☆☆☆ Plugin │
│ Namespaced (plugin-name:skill-name). Lowest priority. │
│ │
└──────────────────────────────────────────────────────────────┘
Example: If you have a skill called
bonita-bdm-expertat the Enterprise level AND at the Project level, the Enterprise version always wins. This lets the organization enforce standards that individuals cannot override.
★★★ Enterprise Scope — Priority 1
What: Organization-wide configuration managed by administrators. Cannot be overridden by Personal or Project settings.
Where it lives:
| OS | Path |
|---|---|
| Windows | C:\ProgramData\ClaudeCode\managed-settings.json |
| Linux/WSL | /etc/claude-code/managed-settings.json |
| macOS | /Library/Application Support/ClaudeCode/managed-settings.json |
Who manages it: System administrators / DevOps team.
Best for: Non-negotiable standards that the organization wants to enforce for everyone:
- Code formatting rules (Checkstyle, PMD)
- Style enforcement hooks
- Compilation checks before commit
- Domain expertise skills (BDM, REST API patterns)
How Enterprise resources are deployed:
- IT/DevOps creates the
managed-settings.jsonfile at the system path - Skills can be uploaded via the Claude Skills API for organization-wide availability
- Configuration cannot be modified by individual developers
★★☆ Personal Scope — Priority 2
What: Your personal commands, skills, and settings. Available in every project you open. Not shared with anyone.
Where it lives:
~/.claude/ # Windows: C:\Users\YourName\.claude\
├── CLAUDE.md # Your global instructions for Claude
├── commands/ # Your personal commands (all projects)
│ └── my-shortcut.md
├── skills/ # Your personal skills (all projects)
│ └── my-skill/
│ └── SKILL.md
└── settings.json # Your personal hooks + permissions
Who manages it: You.
Best for: Developer productivity tools and personal preferences:
- Compilation shortcuts
- Test execution commands
- Code generation helpers
- Quality inspection tools
- Personal workflow preferences
★☆☆ Project Scope — Priority 3
What: Project-specific configuration committed to git. Shared automatically with the whole team when they pull.
Where it lives:
your-project/
├── CLAUDE.md # Project instructions (shared)
├── CLAUDE.local.md # Your personal overrides (NOT committed)
└── .claude/
├── commands/ # Project commands (shared)
├── hooks/ # Project hook scripts (shared)
├── skills/ # Project skills (shared)
├── settings.json # Project hooks config (shared)
└── settings.local.json # Your personal overrides (NOT committed)
Who manages it: The team (via git).
Best for: Resources that depend on the specific project:
- Bonita-specific checks (BDM, controllers, processes)
- Project-type-specific hooks (library test pairs, BDM validation)
- Settings templates tailored to the project
☆☆☆ Plugin Scope — Priority 4
What: Skills bundled within Claude Code plugins. Use namespaced names (plugin-name:skill-name) so they never conflict with other scopes.
Best for: Third-party or optional extensions distributed as packages.
Resource Catalog by Scope
Enterprise Resources
These resources enforce organization-wide standards. We recommend deploying them at the Enterprise level so they apply to all developers on all projects, and cannot be overridden.
Enterprise Skills
| Skill | Auto-invokes when... | What it enforces |
|---|---|---|
bonita-rest-api-expert | REST API extensions, controllers | Abstract/Concrete pattern, README, DTOs, OpenAPI |
branded-documents-redirect | PDF, HTML, Word/Excel, branding | Points at the ofelia-document-toolkit plugin (canonical source for Ofelia branding) |
bonita-uib-expert | UI Builder, Appsmith pages, widgets | Naming, async/await, JS Objects, bonita-api-plugin |
bonita-coding-standards | Code quality, Java 17, clean code | SRP, method length, Javadoc, Checkstyle, PMD |
bonita-audit-expert | Code audits, quality reports | Backend + UIB audit templates, automated checks |
safe-git-workflow | Commit, push, PR, branch, git | Branch-based workflow: claude/{type}/{desc} + PR via gh |
testing-expert | Unit tests, coverage, mutation testing | JUnit 5 + Mockito + AssertJ + jqwik + PIT |
bonita-integration-testing-expert | Integration tests, controller testing, doHandle | Full lifecycle tests, HTTP status paths, Bonita mocking |
skill-creator | Creating new skills | Anthropic methodology, progressive disclosure |
jira-workflow-expert | Jira issues, sprints, transitions | Issue types, priorities, labels, workflows (MCP skill) |
confluence-docs-expert | Confluence pages, docs, specs | Page templates, structure, labels, writing style (MCP skill) |
bonita-connector-expert | Connector.java, Filter.java, Handler.java files | AbstractConnector lifecycle, actor filters, event handlers, REST API extensions |
bonita-performance-expert | "slow", "performance", "optimize", "timeout", "memory" | BDM query optimization, engine tuning, UIB performance, database tips |
bonita-debugging-expert | "error", "exception", "bug", "debug", "stuck", stack traces | 4-step debug workflow, log patterns, exception diagnosis, resolution strategies |
bonita-estimation-expert | "estimate", "how long", "effort", "budget", "proposal" | Effort tables, risk multipliers, phase breakdown, PS service templates |
prompt-quality-advisor | Prompt writing, "is this prompt good?", improve prompt, XML tags | 8-dimension scoring, XML tag patterns, few-shot, eval templates |
project-spec-generator | "generate specs", "user stories", "PRD", "architecture", project setup | PRD, architecture docs, user stories with AC, BMAD/SDD workflow |
Multi-file structure: Every skill uses progressive disclosure — SKILL.md (< 500 lines) contains core rules;
references/,scripts/, andassets/directories contain detailed docs, executable scripts, and templates that Claude loads only when needed. This replaces the oldcontext-ia/approach where ALL docs were loaded at startup.
Enterprise Hooks
| Hook | Event | What it enforces |
|---|---|---|
pre-commit-compile.sh | PreToolUse (Bash) | Blocks git commit if mvn clean compile fails |
check-code-format.sh | PostToolUse (Edit/Write) | Tabs, trailing whitespace, line length > 120, wildcard imports, blank lines |
check-code-style.sh | PostToolUse (Edit/Write) | System.out.println, empty catch, methods > 30 lines, missing @Override |
check-hardcoded-strings.sh | PostToolUse (Edit) | Magic strings in comparisons and switch cases |
check-document-pattern.sh | PostToolUse (Edit/Write) | Document generation without BrandingConfig, hardcoded colors/fonts, iText usage |
check-skill-structure.sh | PostToolUse (Write/Edit) | SKILL.md structure validation: frontmatter, naming, description, required sections |
check-openapi-annotations.sh | PostToolUse (Edit/Write) | Missing @Tag, @Operation, @ApiResponse on REST API controllers |
pre-push-validate.sh | PreToolUse (Bash) | Blocks git push if compilation fails or sensitive files staged |
safe-git-workflow.sh | PreToolUse (Bash) | Blocks git commit/git push on main/master/develop; enforces branch workflow |
Enterprise Configs
| Config | Purpose | Maven plugin |
|---|---|---|
checkstyle.xml | Code style rules (Google-based, team-adjusted) | maven-checkstyle-plugin |
pmd-ruleset.xml | Static analysis (complexity, best practices, errors) | maven-pmd-plugin |
.editorconfig | Editor formatting (indent, line endings, charset) | Native IDE support |
Personal Resources
These are developer productivity tools. Install them in ~/.claude/ so they're available in every project without cluttering project repos.
Personal Commands
| Command | Description | Usage |
|---|---|---|
/compile | Compile project with Maven | /compile or /compile extensions |
/run-tests | Run unit/integration/property tests | /run-tests, /run-tests integration, /run-tests MyClass |
/run-mutation-tests | Run PIT mutation testing | /run-mutation-tests MyModule |
/generate-tests | Generate unit + property tests for a class | /generate-tests MyController |
/check-coverage | Run JaCoCo and verify coverage thresholds | /check-coverage |
/generate-integration-tests | Generate integration tests for a controller | /generate-integration-tests MyController |
/check-test-coverage-gap | Find classes missing test pairs and coverage | /check-test-coverage-gap or /check-test-coverage-gap extensions/myModule |
/check-code-quality | Check Javadoc, method length, code smells | /check-code-quality src/main/java/ |
/audit-compliance | Full project compliance audit | /audit-compliance |
/refactor-method-signature | Refactor method + update ALL call sites | /refactor-method-signature setName add param |
/create-constants | Extract hardcoded strings to constants | /create-constants MyService.java |
Project Resources
These resources depend on the project type. Install them in .claude/ within the specific repository and commit to git.
Project Commands (Bonita BPM)
| Command | Description | Usage |
|---|---|---|
/check-bdm-queries | Search existing BDM queries before creating new ones | /check-bdm-queries PBProcess |
/validate-bdm | Full BDM compliance audit (countFor, descriptions, indexes) | /validate-bdm |
/check-existing-extensions | Search extensions for similar functionality | /check-existing-extensions cancel process |
/check-existing-processes | Search processes for similar logic | /check-existing-processes notification |
/generate-readme | Generate README.md for a REST API controller | /generate-readme CancelController |
Project Hooks
| Hook | For project type | What it does |
|---|---|---|
check-bdm-countfor.sh | Bonita BPM | Warns about missing countFor queries when editing bom.xml |
check-controller-readme.sh | Bonita BPM | Warns when creating a controller without README.md |
check-method-usages.sh | Multi-module Java | Lists files calling a method when its signature changes |
check-test-pair.sh | Java libraries | Warns if *Test.java or *PropertyTest.java is missing |
check-docs-consistency.sh | Any project | Detects drift between documented counts and actual filesystem counts |
knowledge-file-reminder.sh | Any project | Warns when knowledge/ files change and claude-project/ may need sync |
Project Templates
| Template | For project type | What it includes |
|---|---|---|
bonita-project.json | Bonita BPM | All enterprise hooks + BDM/controller hooks + auto-test agent |
java-library.json | Java libraries | Enterprise hooks + test-pair check + auto-test agent |
test-toolkit/ | Bonita Test Toolkit | Complete .claude/ dir with commands, hooks, skill, and agent for integration tests |
CLAUDE.md.template | Any project | Starter CLAUDE.md with team standards and TODO markers |
claude-pr-review.yml | Any project | GitHub Actions: compile, test, Checkstyle/PMD, coverage gate, optional Claude review |
Agent Hooks (in templates)
| Agent | Trigger | What it does |
|---|---|---|
| Auto-test agent (Bonita) | Stop (Claude finishes) | Finds modified files, creates/updates tests, runs mvn test |
| Auto-test agent (Library) | Stop (Claude finishes) | Same + ensures PropertyTest files exist for jqwik |
Installation Guide
Option 1: Automated Installer
cd /path/to/claude-code-toolkit
bash install.sh
The script will ask you:
- Which scope (Enterprise / Personal / Project)
- Which project type (Bonita BPM / Java Library / Generic)
- Where to install (path)
Option 2: Manual Installation
Install Enterprise Resources
Deploy to the system-wide managed settings path:
Skills — Upload via Claude Skills API or copy to managed enterprise directory:
# Copy skills to a shared enterprise location
sudo mkdir -p /etc/claude-code/skills
sudo cp -r skills/bonita-bdm-expert /etc/claude-code/skills/
sudo cp -r skills/bonita-rest-api-expert /etc/claude-code/skills/
Hooks + Configs — Add to managed-settings.json:
# Windows (run as Administrator):
mkdir -p "C:\ProgramData\ClaudeCode"
cp configs/checkstyle.xml "C:\ProgramData\ClaudeCode\"
cp configs/pmd-ruleset.xml "C:\ProgramData\ClaudeCode\"
# Edit C:\ProgramData\ClaudeCode\managed-settings.json to include hook definitions
# Linux:
sudo mkdir -p /etc/claude-code
sudo cp configs/* /etc/claude-code/
# Edit /etc/claude-code/managed-settings.json
Install Personal Resources
Copy commands and settings to your home directory:
# Create directories
mkdir -p ~/.claude/commands
# Copy productivity commands
cp commands/java-maven/* ~/.claude/commands/
cp commands/quality/* ~/.claude/commands/
cp commands/testing/* ~/.claude/commands/
# Optional: copy personal settings with enterprise hooks
cp templates/bonita-project.json ~/.claude/settings.json
Install Project Resources
Copy to your project's .claude/ directory and commit:
cd your-project
mkdir -p .claude/commands .claude/hooks .claude/skills
# Copy project-specific commands (Bonita example)
cp /path/to/toolkit/commands/bonita/* .claude/commands/
# Copy hook scripts
cp /path/to/toolkit/hooks/scripts/* .claude/hooks/
chmod +x .claude/hooks/*.sh
# Copy skills
cp -r /path/to/toolkit/skills/* .claude/skills/
# Copy settings template
cp /path/to/toolkit/templates/bonita-project.json .claude/settings.json
# Copy config files to project root
cp /path/to/toolkit/configs/checkstyle.xml .
cp /path/to/toolkit/configs/pmd-ruleset.xml .
cp /path/to/toolkit/configs/.editorconfig .
# Copy and customize CLAUDE.md
cp /path/to/toolkit/templates/CLAUDE.md.template CLAUDE.md
# Commit to share with team
git add .claude/ checkstyle.xml pmd-ruleset.xml .editorconfig CLAUDE.md
git commit -m "chore: adopt Claude Code toolkit methodology"
Then restart Claude Code to load the new hooks.
What are Commands, Hooks, Skills?
Commands (Slash Commands)
What: Instructions you invoke by typing /command-name in Claude Code.
How: Markdown files in .claude/commands/ or ~/.claude/commands/. Use $ARGUMENTS for parameters.
# Run Tests
## Arguments
- `$ARGUMENTS`: test type (unit, integration, property) or class name
## Instructions
1. Execute: `mvn test -f extensions/pom.xml`
2. Show summary of results
You: /run-tests → runs all tests
You: /run-tests integration → runs integration tests
You: /run-tests MyControllerTest → runs specific class
Hooks (Automatic Checks)
What: Scripts that fire automatically on events. No user action required.
How: Defined in settings.json. Scripts receive JSON on stdin, return exit codes.
| Event | When | Use |
|---|---|---|
PreToolUse | Before Claude uses a tool | Block dangerous actions |
PostToolUse | After Claude uses a tool | Lint, validate, warn |
Stop | Claude finishes responding | Auto-run tests |
| Exit code | Meaning |
|---|---|
exit 0 | Allow (warnings via stderr) |
exit 2 | Block the action (PreToolUse only) |
Types: command (shell script), prompt (AI judgment), agent (full Claude agent with tools)
Skills (Expert Assistants)
What: Advanced commands with YAML frontmatter. Claude auto-invokes them when it detects a relevant task.
How: SKILL.md files in .claude/skills/skill-name/.
---
name: bonita-bdm-expert
description: Use when the user asks about BDM queries or data model.
allowed-tools: Read, Grep, Glob
---
You are an expert in Bonita BDM design...
| Feature | Command | Skill |
|---|---|---|
| Format | .md | SKILL.md (YAML frontmatter) |
| Location | .claude/commands/ | .claude/skills/name/ |
| Tool restrictions | No | Yes (allowed-tools) |
| Auto-invocation | No (user types /) | Yes (Claude detects context) |
Configurations
What: Standard rule files for code quality tools (Checkstyle, PMD, EditorConfig).
How: Copy to project root. Reference from Maven plugins:
<!-- Checkstyle -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.3.1</version>
<configuration>
<configLocation>checkstyle.xml</configLocation>
<failsOnError>true</failsOnError>
</configuration>
</plugin>
<!-- PMD -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.21.2</version>
<configuration>
<rulesets><ruleset>pmd-ruleset.xml</ruleset></rulesets>
<failOnViolation>true</failOnViolation>
</configuration>
</plugin>
Agents (Subagents)
Agents are isolated Claude instances that receive a delegated task, work independently with their own context, and return results. Unlike skills (which inject knowledge into your conversation), agents run autonomously.
Key facts:
- Agents do NOT see your skills automatically — skills must be listed explicitly in the agent's
skills:frontmatter - Each agent gets its own context window, isolated from your main conversation
- Agents can have different
toolsandmodelthan your main session - Install in
.claude/agents/within your project (Project scope)
Available Agents
| Agent | Skills Loaded | Best For |
|---|---|---|
bonita-code-reviewer | coding-standards, rest-api-expert, testing-expert | PR reviews, module code reviews |
bonita-test-generator | testing-expert, integration-testing-expert | Batch test creation for modules |
bonita-auditor | audit-expert, coding-standards, bdm-expert, rest-api-expert, testing-expert | Full project audits with scoring |
bonita-documentation-generator | rest-api-expert, document-expert | Batch README and Javadoc generation |
bonita-ps-ecosystem-auditor | bonita-coding-standards | Cross-repo health check: counts, drift, tests, git status for all PS repos |
Usage
You: delegate to bonita-code-reviewer: review the changes in this PR
You: delegate to bonita-test-generator: create tests for the payment module
You: delegate to bonita-auditor: run a full audit of this project
You: delegate to bonita-documentation-generator: document all REST controllers
See agents/README.md for details.
MCP Skills
MCP servers provide tools (functions Claude can call). Skills teach Claude how and when to use those tools following team conventions. Together they form a powerful pattern:
MCP Server (provides tools) + Skill (teaches conventions) = Effective AI assistant
Available MCP Skills
| Skill | MCP Server | What it teaches |
|---|---|---|
jira-workflow-expert | Jira MCP | Issue types, priority rules, label conventions, workflow transitions |
confluence-docs-expert | Confluence MCP | Page templates, structure standards, label conventions, writing style |
Why MCP Skills Matter
| Without skill | With skill |
|---|---|
| Claude creates Jira issues with generic descriptions | Claude follows your issue template (Story, Bug, Task) |
| Claude assigns random priority | Claude uses your priority rules (Blocker → Same day SLA) |
| Claude doesn't add labels | Claude adds required labels per component (bdm, rest-api, process) |
| Claude creates Confluence pages with no structure | Claude applies page templates (Tech Spec, ADR, Runbook) |
MCP Skills should be deployed at Enterprise scope so all team members follow the same conventions.
Plugins
Plugins are packaged Claude Code extensions distributed through marketplaces (npm, GitHub). They use namespaced names (plugin-name:skill-name) and have Priority 4 (lowest), so they never conflict with higher scopes.
Plugin Candidates from This Toolkit
| Resource | Why Plugin? |
|---|---|
testing-expert | JUnit 5 + Mockito + AssertJ + jqwik patterns are universal |
skill-creator | Meta-skill useful for any Claude Code user |
prompt-quality-advisor | Prompt validation and improvement is universal across all LLM users |
project-spec-generator | PRD, user stories, and architecture docs are domain-agnostic |
Dual Publishing Strategy
For generic skills, we recommend keeping them in the toolkit (Enterprise, Priority 1) AND publishing as plugins (Priority 4). Since Enterprise > Plugin, there's no conflict. External teams get the community version.
See plugins/README.md for publishing instructions.
When to Use What
Not sure which resource type to use? See WHEN_TO_USE_WHAT.md for:
- Quick decision table
- Detailed comparison of all 7 resource types
- Decision flowchart
- Scope matrix (what goes where)
- Deep dives on Agents, Plugins, and MCP+Skills pattern
Where to Define Things
Context Files (CLAUDE.md)
| File | Shared? | Scope | Purpose |
|---|---|---|---|
CLAUDE.md | Yes (git) | Project | Team rules, architecture. /init to generate. |
CLAUDE.local.md | No | Project (personal) | Your tweaks. NOT committed. |
~/.claude/CLAUDE.md | No | Global (personal) | Rules for ALL your projects. |
Priority: Project CLAUDE.md > ~/.claude/CLAUDE.md. CLAUDE.local.md adds/overrides for your session.
Full Scope Matrix
| What | Enterprise | Personal | Project (shared) | Project (personal) |
|---|---|---|---|---|
| Skills | Skills API / managed | ~/.claude/skills/ | .claude/skills/ | — |
| Commands | — | ~/.claude/commands/ | .claude/commands/ | — |
| Hooks | managed-settings.json | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| Instructions | — | ~/.claude/CLAUDE.md | CLAUDE.md | CLAUDE.local.md |
| Configs | System path | — | Project root | — |
Quick Decision Guide
| You want to... | Scope | Location |
|---|---|---|
| Enforce standards for ALL developers | Enterprise | managed-settings.json |
| Have personal productivity tools | Personal | ~/.claude/commands/ |
| Share team rules for a project | Project | CLAUDE.md + .claude/ |
| Override something just for you | Project (personal) | CLAUDE.local.md / settings.local.json |
| Set personal rules for ALL projects | Personal | ~/.claude/CLAUDE.md |
Repository Structure
claude-code-toolkit/
├── agents/ # ★☆☆ Project — delegated task agents
│ ├── README.md
│ ├── code-reviewer.md # Code review with skills
│ ├── test-generator.md # Batch test creation with skills
│ ├── bonita-auditor.md # Full project audit with skills
│ ├── documentation-generator.md # Batch documentation with skills
│ └── bonita-ps-ecosystem-auditor.md # Cross-repo PS ecosystem health check
├── commands/
│ ├── java-maven/ # ★★☆ Personal — developer productivity
│ │ ├── compile.md
│ │ ├── run-tests.md
│ │ └── run-mutation-tests.md
│ ├── bonita/ # ★☆☆ Project — Bonita-specific
│ │ ├── check-bdm-queries.md
│ │ ├── validate-bdm.md
│ │ ├── check-existing-extensions.md
│ │ ├── check-existing-processes.md
│ │ └── generate-readme.md
│ ├── quality/ # ★★☆ Personal — quality tools
│ │ ├── audit-compliance.md
│ │ ├── check-code-quality.md
│ │ ├── create-constants.md
│ │ └── refactor-method-signature.md
│ └── testing/ # ★★☆ Personal — testing tools
│ ├── generate-tests.md
│ ├── generate-integration-tests.md
│ ├── check-test-coverage-gap.md
│ └── check-coverage.md
├── hooks/
│ └── scripts/
│ ├── pre-commit-compile.sh # ★★★ Enterprise — never commit broken code
│ ├── check-code-format.sh # ★★★ Enterprise — uniform formatting
│ ├── check-code-style.sh # ★★★ Enterprise — style standards
│ ├── check-hardcoded-strings.sh # ★★★ Enterprise — constants policy
│ ├── check-document-pattern.sh # ★★★ Enterprise — corporate branding in documents
│ ├── check-skill-structure.sh # ★★★ Enterprise — SKILL.md methodology validation
│ ├── check-openapi-annotations.sh # ★☆☆ Project — OpenAPI docs on controllers
│ ├── pre-push-validate.sh # ★★★ Enterprise — never push broken code
│ ├── safe-git-workflow.sh # ★★★ Enterprise — branch workflow enforcement
│ ├── check-bdm-countfor.sh # ★☆☆ Project — Bonita BDM only
│ ├── check-controller-readme.sh # ★☆☆ Project — Bonita REST API only
│ ├── check-method-usages.sh # ★☆☆ Project — multi-module only
│ └── check-test-pair.sh # ★☆☆ Project — libraries only
├── skills/
│ ├── bonita-rest-api-expert/ # ★★★ Enterprise — REST API patterns
│ │ ├── SKILL.md
│ │ ├── references/ # controller-checklist, dto-patterns, readme-template, openapi
│ │ ├── scripts/check-controller.sh
│ │ └── assets/controller-readme-template.md
│ ├── branded-documents-redirect/ # ★★★ Enterprise — redirect to ofelia-document-toolkit
│ │ └── SKILL.md
│ ├── bonita-uib-expert/ # ★★★ Enterprise — UI Builder (Appsmith)
│ │ ├── SKILL.md
│ │ ├── references/ # widgets, api-actions, js-patterns, header, charts, naming, xml, troubleshooting
│ │ └── scripts/validate-uib-naming.sh
│ ├── bonita-coding-standards/ # ★★★ Enterprise — Java 17 & clean code
│ │ ├── SKILL.md
│ │ ├── references/ # java17-patterns, delivery-checklist, connectors, deployment
│ │ └── scripts/check-code-quality.sh
│ ├── bonita-audit-expert/ # ★★★ Enterprise — code audits & reports
│ │ ├── SKILL.md
│ │ ├── references/ # backend-audit-template, uib-audit-template, audit-checklist
│ │ └── scripts/ # generate-audit-report.sh, run-audit-checks.sh
│ ├── testing-expert/ # ★★★ Enterprise — comprehensive testing
│ │ ├── SKILL.md
│ │ ├── references/ # junit5, property-testing, mutation-testing, bonita-mocking
│ │ └── scripts/ # run-tests.sh, check-coverage.sh
│ ├── bonita-integration-testing-expert/ # ★★★ Enterprise — controller integration tests
│ │ ├── SKILL.md
│ │ ├── references/ # bonita-test-harness, controller-test-patterns, dto-validation
│ │ └── assets/IntegrationTestTemplate.java
│ ├── safe-git-workflow/ # ★★★ Enterprise — branch-based git workflow
│ │ ├── SKILL.md
│ │ └── references/branch-examples.md
│ ├── skill-creator/ # ★★★ Enterprise — meta-skill for creating skills
│ │ └── SKILL.md
│ ├── jira-workflow-expert/ # ★★★ Enterprise — MCP skill for Jira conventions
│ │ ├── SKILL.md
│ │ └── references/issue-templates.md
│ └── confluence-docs-expert/ # ★★★ Enterprise — MCP skill for Confluence conventions
│ ├── SKILL.md
│ └── references/page-templates.md
│ ├── bonita-connector-expert/ # ★★★ Enterprise — connectors, filters, handlers, REST API ext.
│ │ └── SKILL.md
│ ├── bonita-performance-expert/ # ★★★ Enterprise — diagnosis, BDM/engine/UIB optimization
│ │ └── SKILL.md
│ ├── bonita-debugging-expert/ # ★★★ Enterprise — structured debug workflow, log patterns
│ │ └── SKILL.md
│ └── bonita-estimation-expert/ # ★★★ Enterprise — PS effort estimation framework
│ └── SKILL.md
│ ├── prompt-quality-advisor/ # ★★★ Enterprise — prompt validation and improvement
│ │ ├── SKILL.md
│ │ └── references/
│ │ ├── techniques.md
│ │ └── eval-templates.md
│ └── project-spec-generator/ # ★★★ Enterprise — PRD, architecture, user stories (SDD/BMAD)
│ ├── SKILL.md
│ └── references/
│ ├── templates.md
│ └── bmad-guide.md
├── configs/
│ ├── checkstyle.xml # ★★★ Enterprise — code style rules
│ ├── pmd-ruleset.xml # ★★★ Enterprise — static analysis
│ └── .editorconfig # ★★★ Enterprise — editor formatting
├── templates/
│ ├── bonita-project.json # ★☆☆ Project — Bonita settings template
│ ├── java-library.json # ★☆☆ Project — Library settings template
│ ├── CLAUDE.md.template # ★☆☆ Project — Starter instructions
│ ├── test-toolkit/ # ★☆☆ Project — Bonita Test Toolkit template
│ │ ├── README.md
│ │ └── .claude/ # Complete .claude/ dir for test projects
│ └── github-actions/
│ └── claude-pr-review.yml # ★★★ Enterprise — CI/CD quality gates + Claude review
├── plugins/
│ └── README.md # Guide for publishing toolkit skills as plugins
├── install.sh # Interactive installer (prompts for scope/type)
├── setup-dev-env.sh # Non-interactive installer (--personal, --project, --list)
├── WHEN_TO_USE_WHAT.md # Decision guide: when to use each resource type
├── README.md # This file
├── CONTRIBUTING.md # How to contribute to the toolkit
└── ADOPTION_GUIDE.md # Step-by-step adoption guide
Legend: ★★★ Enterprise | ★★☆ Personal | ★☆☆ Project
Contributing
See CONTRIBUTING.md for detailed instructions on:
- How to add new commands, hooks, skills, and configs
- How to classify resources by scope
- Naming conventions and quality checklist
- Ideas for future contributions
Quick contribution guide
- Clone this repo
- Add or improve a resource
- Classify it by scope (Enterprise / Personal / Project) in the README
- Test in a real project
- Submit a PR
Projects Using This Toolkit
PS Toolkit Repos (bonitasoft-ps)
| Repository | Skills | Hooks | Commands |
|---|---|---|---|
| bonita-upgrade-toolkit | 10 | 2 | 6 |
| bonita-audit-toolkit | 12 | 3 | 7 |
| bonita-connectors-generator-toolkit | 5 | 4 | 9 |
| bonita-ai-agent-mcp | 1 | 1 | 4 |
| template-test-toolkit | 1 | 3 | 0 |
Presales Projects (bonitasoft-presales)
Note: These repositories remain under the
bonitasoft-presalesGitHub organization, separate from the PS toolkit repos underbonitasoft-ps.
| Repository | Description |
|---|---|
| ps-process-builder | Bonita BPM Process Builder |
| process-builder-extension-library | Shared Java library |
Quick Setup
For PS team members, the fastest way to get everything configured:
# Clone bonita-ai-agent-mcp and run the all-in-one setup
git clone git@github.com:bonitasoft-ps/bonita-ai-agent-mcp.git
bash bonita-ai-agent-mcp/scripts/setup-ps-tools.sh ~/ps-tools
This clones all 6 repos, installs MCP dependencies, configures personal commands, and generates the Claude Desktop config.
Alternatively, use the non-interactive installer directly:
# Install personal commands only
bash setup-dev-env.sh --personal
# Configure a specific project
bash setup-dev-env.sh --project /path/to/project --project-type bonita
# See what's available
bash setup-dev-env.sh --list
License
Internal use — Bonitasoft Professional Services