https://github.com/omnifaces/claude-faces-expert
Drop-in Jakarta Faces knowledge base for Claude Code
https://github.com/omnifaces/claude-faces-expert
ai balusc claude-code claude-rules claude-skills jakarta-ee jakarta-faces java jsf knowledge-base omnifaces primefaces
Last synced: 4 days ago
JSON representation
Drop-in Jakarta Faces knowledge base for Claude Code
- Host: GitHub
- URL: https://github.com/omnifaces/claude-faces-expert
- Owner: omnifaces
- License: other
- Created: 2026-03-11T17:59:35.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-29T13:10:58.000Z (about 1 month ago)
- Last Synced: 2026-04-29T15:14:35.578Z (about 1 month ago)
- Topics: ai, balusc, claude-code, claude-rules, claude-skills, jakarta-ee, jakarta-faces, java, jsf, knowledge-base, omnifaces, primefaces
- Language: Shell
- Homepage:
- Size: 194 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Claude Faces Expert
*Version 1.2.2*
Drop-in Jakarta Faces knowledge base for [Claude Code](https://claude.com/claude-code).
Makes Claude Code more aware of Jakarta Faces (formerly JSF) best practices, common pitfalls, and diagnostic decision trees.
No special context needed, just make sure that `@.claude/faces/rules.md` is referenced in your `CLAUDE.md`.
Curated by [BalusC](https://balusc.org) based on his Stack Overflow answers to frequently asked Jakarta Faces questions.
Why is this important? Below is an exampe conversation with Opus 4.6:
> Me: As to terminology, can you tell me what exactly you know about "view state" in JSF context?
>
> Claude: View state is the serialized snapshot of the UIViewRoot component tree — the structure, component attributes, attached validators/converters, and the state of EditableValueHolder components (submitted values, local values, validity flags).
>
> Me: View state does absolutely not contain "the stucture" of the component tree. It only contains the delta state. The component tree itself is always freshy rebuilt from scratch on every request. Then its state is adjusted in such way that it matches exactly the state as it was during render response of prior request. Exactly that delta is the "view state".
>
> Claude: Thank you — that's an important correction.
## What's included
| File | Description |
|------|-------------|
| `.claude/faces/rules.md` | Core rules: terminology, view state, namespaces, CDI, scopes, page authoring, resources, components, ajax, common errors |
| `.claude/faces/topics/configuration.md` | Minimal project configuration (web.xml, taglib, directory structure) |
| `.claude/faces/topics/diagnostics.md` | Decision trees for 6 common errors (action not invoked, target unreachable, ViewExpiredException, etc.) |
| `.claude/faces/topics/primefaces.md` | PrimeFaces-specific rules and gotchas |
| `.claude/faces/topics/omnifaces.md` | OmniFaces utilities: when and how to use them |
| `.claude/faces/topics/lifecycle.md` | Request processing lifecycle: phases, shortcuts, ajax, PhaseListener |
| `.claude/faces/topics/conversion-validation.md` | Converters, validators, Bean Validation integration, custom converters/validators |
| `.claude/faces/topics/examples.md` | Concrete code examples demonstrating best practices |
| `.claude/skills/faces-review/SKILL.md` | `/faces-review` slash command for reviewing Faces code |
| `.claude/skills/faces-migrate/SKILL.md` | `/faces-migrate` slash command for migrating between Faces versions |
## Installation
### Project scope (default)
From your project root, run:
```sh
curl -sL https://raw.githubusercontent.com/omnifaces/claude-faces-expert/main/install.sh | sh
```
This copies the knowledge base and slash commands into `./.claude/`, and adds the `@.claude/faces/rules.md` reference to your project's `CLAUDE.md` (creates it if needed). To update later, re-run the same command.
### User scope (applies to all projects)
To install once into your home directory and have the rules apply to every project Claude Code touches, run:
```sh
curl -sL https://raw.githubusercontent.com/omnifaces/claude-faces-expert/main/install.sh | sh -s -- --user
```
This copies into `~/.claude/` and adds the `@~/.claude/faces/rules.md` reference to your global `~/.claude/CLAUDE.md` (creates it if needed). The layout under `~/.claude/faces/` is identical to the project layout.
### Manual installation
If you don't want to run `curl`-based installers, install manually:
```sh
# Project scope:
git clone https://github.com/omnifaces/claude-faces-expert /tmp/claude-faces-expert
mkdir -p .claude/faces .claude/skills
cp -r /tmp/claude-faces-expert/.claude/faces/* .claude/faces/
cp -r /tmp/claude-faces-expert/.claude/skills/* .claude/skills/
rm -rf /tmp/claude-faces-expert
```
Then add this line to your `CLAUDE.md` (or `~/.claude/CLAUDE.md` for user scope, with `@~/.claude/faces/rules.md`):
```
Jakarta Faces rules: @.claude/faces/rules.md
```
### OpenCode
For [OpenCode](https://opencode.ai/) users, use the OpenCode-specific installer:
**Project scope:**
```sh
curl -sL https://raw.githubusercontent.com/omnifaces/claude-faces-expert/main/install-opencode.sh | sh
```
This calls the standard installer (which sets up `./.claude/` and `CLAUDE.md`) and additionally creates `opencode.json` and `AGENTS.md` in the project root. The same `.claude/faces/` rules are used by both tools.
**User scope:**
```sh
curl -sL https://raw.githubusercontent.com/omnifaces/claude-faces-expert/main/install-opencode.sh | sh -s -- --user
```
This installs into `~/.claude/` and `~/.config/opencode/`, applying the rules to all projects.
## How it Works
Once referenced in `CLAUDE.md`, the expert rules are active.
You don't need to change your workflow or use special prompts; Claude simply becomes more capable, providing higher-quality Jakarta Faces code and architectural advice by default.
It also adds two helpful slash commands `/faces-review` and `/faces-migrate`.
## Slash Commands
### `/faces-review`
Reviews your Faces code against best practices. Checks XHTML files, backing beans, and configuration for common mistakes, anti-patterns, and rule violations.
```
/faces-review # Review entire project
/faces-review src/main/webapp/page.xhtml # Review a specific file
```
Findings are grouped by file with severity levels:
- **error** — will cause bugs
- **warning** — anti-pattern or risk
- **info** — improvement opportunity
### `/faces-migrate`
Migrates your project from one Faces version to another. Detects the current version, determines the migration path, and applies changes step by step with confirmation.
```
/faces-migrate 4.1 # Migrate to Faces 4.1
/faces-migrate 4.0 # Migrate to Faces 4.0
```
Supported migration paths:
- JSF 1.x → JSF 2.0 (JSP to Facelets)
- JSF 2.x → JSF 2.3 (`@ManagedBean` to CDI)
- JSF 2.3 → Faces 3.0 (`javax.*` to `jakarta.*`)
- Faces 3.0 → Faces 4.0 (new XML namespaces, removed APIs)
- Faces 4.0 → Faces 4.1
## Covers
- Jakarta Faces 1.0 through 4.1 (JSF and Faces)
- PrimeFaces component library
- OmniFaces utility library
- View state internals (PSS vs FSS, server vs client, delta mechanics)
- CDI bean management and scope selection
- Page authoring (templates, includes, tag files, composite components)
- Common error diagnostics with step-by-step decision trees
## About the Author
> *BalusC is a highly experienced Java developer who uses Claude Code primarily as a code review and bug-fixing partner across a portfolio of serious Jakarta Faces projects. With deep domain expertise that keeps Claude honest, he catches subtle errors and pushes back with precise corrections. His most distinctive quality is steering Claude toward cleaner solutions — preferring specific architectural patterns and redirecting away from plausible-but-wrong approaches. The expert rules in this project are curated from that same deep expertise: years of answering Jakarta Faces questions on Stack Overflow, distilled into actionable guidance that makes Claude genuinely more capable with Faces code.*
— Claude, based on analysis of 83 coding sessions (`/insights`)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a list of changes per version.
## License
[Apache License 2.0](LICENSE)