Skip to content

Commit 0043be1

Browse files
david-waltermiredavid-waltermire
authored
Streamline CLAUDE.md and reference dev-metaschema plugin skills (#629)
* Streamline CLAUDE.md and reference dev-metaschema plugin skills * fix: wrap bare URL in angle brackets per markdown best practices
1 parent 0ec905a commit 0043be1

File tree

4 files changed

+270
-308
lines changed

4 files changed

+270
-308
lines changed

‎.claude/CLAUDE.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
The Metaschema Java framework provides libraries for working with models defined by the Metaschema modeling language. It supports creating, modifying, parsing, and writing XML, JSON, and YAML instance data conforming to Metaschema models.
8+
9+
**Metapath** is the project's implementation of XPath 3.1. When implementing or fixing Metapath functions, use the [XPath 3.1 specification](https://www.w3.org/TR/xpath-31/) and [XPath Functions 3.1](https://www.w3.org/TR/xpath-functions-31/) as authoritative references. If behavior differs from the spec, clarify with the user before making changes.
10+
11+
## Build Commands
12+
13+
```bash
14+
# Initialize submodules (required before first build, or in new worktrees)
15+
git submodule update --init --recursive
16+
17+
# Build and install all modules
18+
mvn install
19+
20+
# CI/CD build (REQUIRED before pushing - includes all quality checks)
21+
mvn install -PCI -Prelease
22+
23+
# Run tests only
24+
mvn test
25+
26+
# Run single test class/method
27+
mvn -pl core test -Dtest=FnCountTest
28+
mvn -pl core test -Dtest=FnCountTest#testCount
29+
30+
# Build specific module (with dependencies)
31+
mvn -pl core -am install
32+
33+
# Skip tests during build
34+
mvn install -DskipTests
35+
36+
# Run the CLI locally (after building)
37+
java -jar metaschema-cli/target/metaschema-cli-*-metaschema-cli.jar --help
38+
```
39+
40+
### Code Quality Commands
41+
42+
```bash
43+
mvn license:check # Check license headers
44+
mvn license:format # Add license headers
45+
mvn formatter:validate # Check code formatting
46+
mvn formatter:format # Auto-format code
47+
mvn checkstyle:check # Check Javadoc and style
48+
mvn javadoc:javadoc # Generate Javadoc (find errors)
49+
```
50+
51+
## Static Analysis
52+
53+
Tools configured in parent POM ([oss-maven](https://github.com/metaschema-framework/oss-maven)):
54+
55+
- **Checkstyle**: Code style, Javadoc enforcement
56+
- **PMD**: Source code analysis (fails on priority 2+ violations)
57+
- **SpotBugs**: Bug pattern detection (uses `spotbugs-exclude.xml`)
58+
- **Jacoco**: Code coverage (target: 60%)
59+
60+
## Project Architecture
61+
62+
### Module Hierarchy
63+
64+
```text
65+
metaschema-framework (parent)
66+
├── core - Core API, Metapath expression language
67+
├── databind - Data binding and code generation
68+
├── schemagen - XML/JSON schema generation
69+
├── databind-modules - Metaschema binding modules
70+
├── metaschema-maven-plugin - Maven plugin for code/schema generation
71+
├── metaschema-testing - Testing utilities
72+
├── cli-processor - CLI framework
73+
└── metaschema-cli - Command-line interface
74+
```
75+
76+
### Core Module Structure (dev.metaschema.core)
77+
78+
- **model/** - Metaschema model interfaces (`IModule`, `IAssemblyDefinition`, `IFieldDefinition`, `IFlagDefinition`)
79+
- **metapath/** - Metapath query language implementation
80+
- **antlr/** - ANTLR4-generated parser (from `src/main/antlr4`)
81+
- **cst/** - Concrete syntax tree expressions
82+
- **function/** - Function library (`core/src/main/java/.../function/library/`)
83+
- **item/** - Metapath item types (node items, atomic items)
84+
- **datatype/** - Data type adapters for Metaschema types
85+
- **mdm/** - Metaschema Document Model node items
86+
87+
### Key Interfaces
88+
89+
- `IModule` - Represents a Metaschema module with definitions
90+
- `IModuleLoader` - Loads Metaschema modules from various sources
91+
- `IDataTypeAdapter` - Adapts between Java types and Metaschema data types
92+
- `StaticContext` / `DynamicContext` - Metapath evaluation contexts
93+
94+
### Generated Code
95+
96+
- **Metaschema bindings**: Generated from Metaschema modules via metaschema-maven-plugin
97+
- **ANTLR4**: Metapath parser from `core/src/main/antlr4`
98+
99+
Generated sources go to `target/generated-sources/` and are excluded from style checks.
100+
101+
### Bootstrap Binding Classes
102+
103+
Several modules contain pre-generated binding classes due to circular dependencies. **Never manually edit these** - modify the source Metaschema module instead.
104+
105+
| Module | Bootstrap POM | Source Metaschema |
106+
|--------|--------------|-------------------|
107+
| metaschema-testing | `pom-bootstrap.xml` | `unit-tests.yaml` |
108+
| databind | `pom-bootstrap-config.xml` | `metaschema-bindings.yaml` |
109+
| databind | `pom-bootstrap-model.xml` | `metaschema-module-metaschema.xml` |
110+
111+
To regenerate:
112+
113+
```bash
114+
mvn install -DskipTests
115+
mvn -f {module}/pom-bootstrap.xml process-sources
116+
```
117+
118+
### Metaschema Module Authoring
119+
120+
**YAML-first approach**: Prefer YAML format over XML for new modules.
121+
- Store in `src/main/metaschema/` with `.yaml` extension
122+
- Use JSON schema at `databind-modules/target/generated-resources/schema/json/metaschema-model_schema.json` for IDE validation
123+
124+
## Testing
125+
126+
- Tests use JUnit 5 with parallel execution enabled
127+
- Test utilities in `metaschema-testing` module
128+
- 100% of unit tests must pass before pushing (BLOCKING)
129+
130+
### Test-Driven Development (TDD)
131+
132+
All code changes must follow TDD:
133+
1. **Write tests first** - capture expected behavior
134+
2. **Watch tests fail** - verify tests are meaningful
135+
3. **Write minimal code** - make tests pass
136+
4. **Refactor** - clean up while keeping tests green
137+
138+
## Code Style
139+
140+
- Java 11 target
141+
- SpotBugs annotations (`@NonNull`, `@Nullable`) for null safety
142+
- Package structure: `dev.metaschema.*`
143+
144+
### Javadoc Requirements (BLOCKING)
145+
146+
Use `dev-metaschema:javadoc-style-guide` skill for full guide.
147+
148+
- **New code**: 100% Javadoc on `public`/`protected` members (BLOCKING)
149+
- **Modified code**: Add/update Javadoc on touched members
150+
- **Exceptions**: `@Override` methods, `@Test` methods, generated code
151+
152+
## Git Workflow
153+
154+
- Repository: <https://github.com/metaschema-framework/metaschema-java>
155+
- **All PRs MUST be created from a personal fork** (BLOCKING)
156+
- **All PRs MUST target the `develop` branch** (BLOCKING)
157+
- Clone with submodules: `git clone --recurse-submodules`
158+
- All changes require PR review (CODEOWNERS enforced)
159+
160+
## Git Worktrees (MANDATORY)
161+
162+
**All development work MUST be done in a git worktree**, not in the main checkout.
163+
164+
Worktrees are stored in `.worktrees/` (gitignored).
165+
166+
```bash
167+
# Create worktree for new feature
168+
git worktree add .worktrees/<feature-name> -b <feature-branch> origin/develop
169+
cd .worktrees/<feature-name>
170+
git submodule update --init --recursive
171+
172+
# Check existing worktrees
173+
git worktree list
174+
175+
# Remove after PR merged
176+
git worktree remove .worktrees/<feature-name>
177+
```
178+
179+
## PRD Workflow
180+
181+
For larger initiatives, use PRDs stored in `PRDs/<YYYYMMDD>-<name>/`:
182+
- `PRD.md` - Requirements document
183+
- `implementation-plan.md` - Detailed PR breakdown
184+
185+
**PR Size**: Target ≤50 files, maximum 100 files per PR.
186+
187+
**Verification**: Run `mvn clean install -PCI -Prelease` after each PR.
188+
189+
### Active PRDs
190+
191+
| PRD | Description | Status |
192+
|-----|-------------|--------|
193+
| `PRDs/20251206-build-cleanup/` | Build warnings and deprecation removal | In Progress |
194+
195+
### Completed PRDs
196+
197+
| PRD | Description | Completed |
198+
|-----|-------------|-----------|
199+
| `PRDs/20251229-javadoc-coverage/` | Complete Javadoc coverage for schemagen, databind, and maven-plugin modules | 2025-12-29 |
200+
| `PRDs/20251228-targeted-report-constraint/` | Add constraint processing support for TargetedReportConstraint (issue #592) | 2025-12-29 |
201+
| `PRDs/20251228-validation-errors/` | Validation error message improvements (#595, #596, #205) | 2025-12-28 |
202+
| `PRDs/20251224-codegen-quality/` | Code generator Javadoc and quality improvements | 2025-12-28 |
203+
| `PRDs/20251217-cli-processor-refactor/` | CLI processor refactoring (issue #252) | 2025-12-21 |
204+
| `PRDs/20251217-context-functions/` | Complete Metapath context functions (issue #162) | 2025-12-17 |
205+
| `PRDs/20251221-xmlbeans-removal/` | Replace XMLBeans with Metaschema bindings | 2025-12-24 |
206+
207+
## Available Skills
208+
209+
Use these skills via the Skill tool when working in this repository:
210+
211+
### Metaschema-Specific (dev-metaschema plugin)
212+
213+
- `dev-metaschema:development-workflow` - TDD, PRD workflow, parallel agents, debugging
214+
- `dev-metaschema:prd-construction` - Creating PRDs and implementation plans
215+
- `dev-metaschema:repo-organization` - Project structure and module relationships
216+
- `dev-metaschema:unit-test-writing` - Edge case checklist, test patterns
217+
- `dev-metaschema:javadoc-style-guide` - Javadoc requirements and patterns
218+
- `dev-metaschema:claude-md-conventions` - CLAUDE.md structure and content rules
219+
- `dev-metaschema:pr-feedback` - Addressing PR review feedback
220+
221+
### Metaschema Concepts (metaschema plugin)
222+
223+
- `metaschema:metaschema-basics` - Introduction and overview
224+
- `metaschema:metaschema-module-authoring` - Module structure, definitions
225+
- `metaschema:metaschema-constraints-authoring` - Constraint types, validation
226+
- `metaschema:metapath-expressions` - Path syntax, operators, functions
227+
228+
### Metaschema Java Library (metaschema-tools plugin)
229+
230+
- `metaschema-tools:metaschema-java-library` - Key interfaces, exceptions, Metapath evaluation
231+
- `metaschema-tools:using-metaschema-java` - CLI commands for validation, schema generation
232+
233+
### Development Workflow (superpowers plugin)
234+
235+
- `superpowers:brainstorming` - Refine ideas into designs through collaborative questioning
236+
- `superpowers:writing-plans` - Create detailed implementation plans
237+
- `superpowers:executing-plans` - Execute tasks in batches with review checkpoints
238+
- `superpowers:test-driven-development` - Write tests first, then implementation
239+
- `superpowers:systematic-debugging` - 4-phase debugging framework
240+
- `superpowers:root-cause-tracing` - Trace bugs backward to find source
241+
- `superpowers:verification-before-completion` - Confirm work is complete before claiming done
242+
- `superpowers:requesting-code-review` - Review implementation against plan
243+
- `superpowers:receiving-code-review` - Handle code review feedback properly
244+
- `superpowers:dispatching-parallel-agents` - Concurrent work on independent tasks
245+
- `superpowers:subagent-driven-development` - Quality-gated autonomous work
246+
- `superpowers:using-git-worktrees` - Isolated worktree creation and management
247+
- `superpowers:testing-anti-patterns` - Avoid common testing mistakes

‎.claude/settings.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,22 @@
11
{
2+
"extraKnownMarketplaces": {
3+
"metaschema-framework": {
4+
"source": {
5+
"source": "github",
6+
"repo": "metaschema-framework/claude-plugins"
7+
}
8+
},
9+
"superpowers-marketplace": {
10+
"source": {
11+
"source": "github",
12+
"repo": "obra/superpowers"
13+
}
14+
}
15+
},
16+
"enabledPlugins": {
17+
"metaschema@metaschema-framework": true,
18+
"metaschema-tools@metaschema-framework": true,
19+
"dev-metaschema@metaschema-framework": true,
20+
"superpowers@superpowers-marketplace": true
21+
}
222
}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@ pom.xml.versionsBackup
2424
release.properties
2525
velocity.log*
2626

27+
# Java files
28+
javac.*.args
29+
2730
# oXygen files
2831
/metaschema.xpr
2932

0 commit comments

Comments
 (0)