convez.ai
SkillProdutividadeAvançado
bonitasoft-ps

Claude Code Toolkit — Bonitasoft

bonitasoft-ps/ofelia-claude-code-toolkit

Metodologia de dev com IA: skills, hooks e commands para Bonitasoft

Ver no GitHub
InicialPluginScore · de 0 a 100

Catá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-toolkit

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 2 semanas
Versão
—
Issues abertas
1
Contribuidores
2

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


What is this?

This repository is the single source of truth for Bonitasoft's AI-assisted development methodology. It contains:

WhatPurposeHow many
SkillsExpert knowledge with progressive disclosure (BDM, REST API, UIB, Audit, Testing...)55
AgentsIsolated subagents for delegated tasks (code review, test generation, audit, docs)5
CommandsSlash commands for common tasks (/run-tests, /generate-tests)18
HooksAutomatic checks that fire without user action (format, style, compile, git workflow)15
ConfigsStandard rule files (Checkstyle, PMD, EditorConfig)3
TemplatesReady-to-use settings, CLAUDE.md starter, GitHub Actions4

Why this exists

Without a shared methodology, each developer writes code differently, forgets quality checks, and reinvents solutions. This toolkit:

  1. Homogenizes development — Everyone follows the same standards, automatically
  2. Prevents errors — Hooks catch issues during development, not in code review
  3. Ensures testing — Auto-test agents create and run tests when Claude finishes
  4. Avoids duplication — Commands check for existing implementations before creating new ones
  5. Onboards instantly — New team members get everything by cloning the project

How to use it

  1. Clone this repository
  2. Choose which resources you need (see the catalog below)
  3. Install at the right scope (Enterprise, Personal, or Project)
  4. 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-agent and the marketplace was bonitasoft-ps. Both were renamed to ofelia-claude-code-toolkit to 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.json still 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 /plugin slash commands work on every Claude Code surface that runs locally:

  • CLI (claude in 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 the bonitasoft.com workspace — Customize → Connect tools you use → Plugins lists the plugins but the install button is disabled. Use the CLI, Desktop or IDE for now. If/when admins lift the restriction, the same /plugin flow described below will work in claude.ai too.

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:

  1. Open Customize (top-right or main menu).
  2. Scroll to the Custom Plugins section.
  3. Click the + button and add the plugin (it appears automatically because the marketplace is already registered via settings.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 shorthand bonitasoft-ps/ofelia-claude-code-toolkit defaults 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 by gh 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

TriggerEventBehaviour
Automatic, periodicStop (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 exitSessionEndForces 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 Stop hook is async: 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 claude CLI must be on your PATH (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 Stop hook command in hooks/hooks.json and add --throttle <minutes> (e.g. --throttle 15).
  • Manual-only: remove the Stop and/or SessionEnd entries from hooks/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.md is local context. Add it to your .gitignore if 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-expert at 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:

OSPath
WindowsC:\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:

  1. IT/DevOps creates the managed-settings.json file at the system path
  2. Skills can be uploaded via the Claude Skills API for organization-wide availability
  3. 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

SkillAuto-invokes when...What it enforces
bonita-rest-api-expertREST API extensions, controllersAbstract/Concrete pattern, README, DTOs, OpenAPI
branded-documents-redirectPDF, HTML, Word/Excel, brandingPoints at the ofelia-document-toolkit plugin (canonical source for Ofelia branding)
bonita-uib-expertUI Builder, Appsmith pages, widgetsNaming, async/await, JS Objects, bonita-api-plugin
bonita-coding-standardsCode quality, Java 17, clean codeSRP, method length, Javadoc, Checkstyle, PMD
bonita-audit-expertCode audits, quality reportsBackend + UIB audit templates, automated checks
safe-git-workflowCommit, push, PR, branch, gitBranch-based workflow: claude/{type}/{desc} + PR via gh
testing-expertUnit tests, coverage, mutation testingJUnit 5 + Mockito + AssertJ + jqwik + PIT
bonita-integration-testing-expertIntegration tests, controller testing, doHandleFull lifecycle tests, HTTP status paths, Bonita mocking
skill-creatorCreating new skillsAnthropic methodology, progressive disclosure
jira-workflow-expertJira issues, sprints, transitionsIssue types, priorities, labels, workflows (MCP skill)
confluence-docs-expertConfluence pages, docs, specsPage templates, structure, labels, writing style (MCP skill)
bonita-connector-expertConnector.java, Filter.java, Handler.java filesAbstractConnector 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 traces4-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-advisorPrompt writing, "is this prompt good?", improve prompt, XML tags8-dimension scoring, XML tag patterns, few-shot, eval templates
project-spec-generator"generate specs", "user stories", "PRD", "architecture", project setupPRD, 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/, and assets/ directories contain detailed docs, executable scripts, and templates that Claude loads only when needed. This replaces the old context-ia/ approach where ALL docs were loaded at startup.

Enterprise Hooks

HookEventWhat it enforces
pre-commit-compile.shPreToolUse (Bash)Blocks git commit if mvn clean compile fails
check-code-format.shPostToolUse (Edit/Write)Tabs, trailing whitespace, line length > 120, wildcard imports, blank lines
check-code-style.shPostToolUse (Edit/Write)System.out.println, empty catch, methods > 30 lines, missing @Override
check-hardcoded-strings.shPostToolUse (Edit)Magic strings in comparisons and switch cases
check-document-pattern.shPostToolUse (Edit/Write)Document generation without BrandingConfig, hardcoded colors/fonts, iText usage
check-skill-structure.shPostToolUse (Write/Edit)SKILL.md structure validation: frontmatter, naming, description, required sections
check-openapi-annotations.shPostToolUse (Edit/Write)Missing @Tag, @Operation, @ApiResponse on REST API controllers
pre-push-validate.shPreToolUse (Bash)Blocks git push if compilation fails or sensitive files staged
safe-git-workflow.shPreToolUse (Bash)Blocks git commit/git push on main/master/develop; enforces branch workflow

Enterprise Configs

ConfigPurposeMaven plugin
checkstyle.xmlCode style rules (Google-based, team-adjusted)maven-checkstyle-plugin
pmd-ruleset.xmlStatic analysis (complexity, best practices, errors)maven-pmd-plugin
.editorconfigEditor 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

CommandDescriptionUsage
/compileCompile project with Maven/compile or /compile extensions
/run-testsRun unit/integration/property tests/run-tests, /run-tests integration, /run-tests MyClass
/run-mutation-testsRun PIT mutation testing/run-mutation-tests MyModule
/generate-testsGenerate unit + property tests for a class/generate-tests MyController
/check-coverageRun JaCoCo and verify coverage thresholds/check-coverage
/generate-integration-testsGenerate integration tests for a controller/generate-integration-tests MyController
/check-test-coverage-gapFind classes missing test pairs and coverage/check-test-coverage-gap or /check-test-coverage-gap extensions/myModule
/check-code-qualityCheck Javadoc, method length, code smells/check-code-quality src/main/java/
/audit-complianceFull project compliance audit/audit-compliance
/refactor-method-signatureRefactor method + update ALL call sites/refactor-method-signature setName add param
/create-constantsExtract 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)

CommandDescriptionUsage
/check-bdm-queriesSearch existing BDM queries before creating new ones/check-bdm-queries PBProcess
/validate-bdmFull BDM compliance audit (countFor, descriptions, indexes)/validate-bdm
/check-existing-extensionsSearch extensions for similar functionality/check-existing-extensions cancel process
/check-existing-processesSearch processes for similar logic/check-existing-processes notification
/generate-readmeGenerate README.md for a REST API controller/generate-readme CancelController

Project Hooks

HookFor project typeWhat it does
check-bdm-countfor.shBonita BPMWarns about missing countFor queries when editing bom.xml
check-controller-readme.shBonita BPMWarns when creating a controller without README.md
check-method-usages.shMulti-module JavaLists files calling a method when its signature changes
check-test-pair.shJava librariesWarns if *Test.java or *PropertyTest.java is missing
check-docs-consistency.shAny projectDetects drift between documented counts and actual filesystem counts
knowledge-file-reminder.shAny projectWarns when knowledge/ files change and claude-project/ may need sync

Project Templates

TemplateFor project typeWhat it includes
bonita-project.jsonBonita BPMAll enterprise hooks + BDM/controller hooks + auto-test agent
java-library.jsonJava librariesEnterprise hooks + test-pair check + auto-test agent
test-toolkit/Bonita Test ToolkitComplete .claude/ dir with commands, hooks, skill, and agent for integration tests
CLAUDE.md.templateAny projectStarter CLAUDE.md with team standards and TODO markers
claude-pr-review.ymlAny projectGitHub Actions: compile, test, Checkstyle/PMD, coverage gate, optional Claude review

Agent Hooks (in templates)

AgentTriggerWhat 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:

  1. Which scope (Enterprise / Personal / Project)
  2. Which project type (Bonita BPM / Java Library / Generic)
  3. 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.

EventWhenUse
PreToolUseBefore Claude uses a toolBlock dangerous actions
PostToolUseAfter Claude uses a toolLint, validate, warn
StopClaude finishes respondingAuto-run tests
Exit codeMeaning
exit 0Allow (warnings via stderr)
exit 2Block 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...
FeatureCommandSkill
Format.mdSKILL.md (YAML frontmatter)
Location.claude/commands/.claude/skills/name/
Tool restrictionsNoYes (allowed-tools)
Auto-invocationNo (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 tools and model than your main session
  • Install in .claude/agents/ within your project (Project scope)

Available Agents

AgentSkills LoadedBest For
bonita-code-reviewercoding-standards, rest-api-expert, testing-expertPR reviews, module code reviews
bonita-test-generatortesting-expert, integration-testing-expertBatch test creation for modules
bonita-auditoraudit-expert, coding-standards, bdm-expert, rest-api-expert, testing-expertFull project audits with scoring
bonita-documentation-generatorrest-api-expert, document-expertBatch README and Javadoc generation
bonita-ps-ecosystem-auditorbonita-coding-standardsCross-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

SkillMCP ServerWhat it teaches
jira-workflow-expertJira MCPIssue types, priority rules, label conventions, workflow transitions
confluence-docs-expertConfluence MCPPage templates, structure standards, label conventions, writing style

Why MCP Skills Matter

Without skillWith skill
Claude creates Jira issues with generic descriptionsClaude follows your issue template (Story, Bug, Task)
Claude assigns random priorityClaude uses your priority rules (Blocker → Same day SLA)
Claude doesn't add labelsClaude adds required labels per component (bdm, rest-api, process)
Claude creates Confluence pages with no structureClaude 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

ResourceWhy Plugin?
testing-expertJUnit 5 + Mockito + AssertJ + jqwik patterns are universal
skill-creatorMeta-skill useful for any Claude Code user
prompt-quality-advisorPrompt validation and improvement is universal across all LLM users
project-spec-generatorPRD, 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)

FileShared?ScopePurpose
CLAUDE.mdYes (git)ProjectTeam rules, architecture. /init to generate.
CLAUDE.local.mdNoProject (personal)Your tweaks. NOT committed.
~/.claude/CLAUDE.mdNoGlobal (personal)Rules for ALL your projects.

Priority: Project CLAUDE.md > ~/.claude/CLAUDE.md. CLAUDE.local.md adds/overrides for your session.

Full Scope Matrix

WhatEnterprisePersonalProject (shared)Project (personal)
SkillsSkills API / managed~/.claude/skills/.claude/skills/—
Commands—~/.claude/commands/.claude/commands/—
Hooksmanaged-settings.json~/.claude/settings.json.claude/settings.json.claude/settings.local.json
Instructions—~/.claude/CLAUDE.mdCLAUDE.mdCLAUDE.local.md
ConfigsSystem path—Project root—

Quick Decision Guide

You want to...ScopeLocation
Enforce standards for ALL developersEnterprisemanaged-settings.json
Have personal productivity toolsPersonal~/.claude/commands/
Share team rules for a projectProjectCLAUDE.md + .claude/
Override something just for youProject (personal)CLAUDE.local.md / settings.local.json
Set personal rules for ALL projectsPersonal~/.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

  1. Clone this repo
  2. Add or improve a resource
  3. Classify it by scope (Enterprise / Personal / Project) in the README
  4. Test in a real project
  5. Submit a PR

Projects Using This Toolkit

PS Toolkit Repos (bonitasoft-ps)

RepositorySkillsHooksCommands
bonita-upgrade-toolkit1026
bonita-audit-toolkit1237
bonita-connectors-generator-toolkit549
bonita-ai-agent-mcp114
template-test-toolkit130

Presales Projects (bonitasoft-presales)

Note: These repositories remain under the bonitasoft-presales GitHub organization, separate from the PS toolkit repos under bonitasoft-ps.

RepositoryDescription
ps-process-builderBonita BPM Process Builder
process-builder-extension-libraryShared 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

Ver o original no GitHub

Bom para

Relacionados