Skip to content

Commit 3c3404e

Browse files
david-waltermiredavid-waltermire
authored
Add Claude Code configuration (#224)
* Add Claude Code configuration Add CLAUDE.md with project guidance for Claude Code including: - Build commands and Maven profiles documentation - Architecture overview with correct package structure - Command pattern inheritance hierarchy - Git workflow and worktree requirements - Testing and dependency information Also adds Claude settings.json for plugin configuration and updates .gitignore for Claude local files. * Add Available Skills section to CLAUDE.md * fix: address PR review feedback - Wrap bare URL in angle brackets for proper markdown formatting - Fix TESTING.md link path to use relative parent directory
1 parent 3b8e78a commit 3c3404e

File tree

3 files changed

+212
-0
lines changed

3 files changed

+212
-0
lines changed

‎.claude/CLAUDE.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build Commands
6+
7+
```bash
8+
# Build and install locally
9+
mvn install
10+
11+
# Replicate CI/CD build (recommended before pushing)
12+
mvn install -PCI -Prelease
13+
14+
# Run tests only
15+
mvn test
16+
17+
# Run a single test class
18+
mvn test -Dtest=CLITest
19+
20+
# Run a single test method
21+
mvn test -Dtest=CLITest#testHelp
22+
23+
# Skip tests during build
24+
mvn install -DskipTests
25+
26+
# Check license headers
27+
mvn license:check
28+
29+
# Auto-format source code
30+
mvn formatter:format
31+
32+
# Check for Checkstyle issues
33+
mvn checkstyle:check
34+
```
35+
36+
### Maven Profiles
37+
38+
- `-Prelease`: Enables release configuration (GPG signing, source/javadoc jars)
39+
- `-PCI`: Enables CI-specific configuration
40+
- `-Psnapshots`: Enables snapshot deployment to the snapshot repository
41+
42+
## Project Overview
43+
44+
oscal-cli is a command-line tool for working with [OSCAL](https://pages.nist.gov/OSCAL/) and [Metaschema](https://github.com/metaschema-framework/metaschema) content. It provides:
45+
46+
- Converting OSCAL content between XML, JSON, and YAML formats
47+
- Validating OSCAL resources for well-formedness and validity
48+
- Resolving OSCAL Profiles
49+
- Validating Metaschema model definitions
50+
- Generating XML and JSON Schemas from Metaschema models
51+
52+
This tool is built on [Metaschema Java Tools](https://github.com/metaschema-framework/metaschema-java) and [liboscal-java](https://github.com/metaschema-framework/liboscal-java/).
53+
54+
## Architecture
55+
56+
This is a single-module Maven project producing the `oscal-cli-enhanced` artifact.
57+
58+
### Package Structure
59+
60+
- `dev.metaschema.oscal.tools.cli.core` - CLI entry point (`CLI.java` main class)
61+
- `dev.metaschema.oscal.tools.cli.core.commands` - Top-level commands (validate, convert, resolve-profile)
62+
- `dev.metaschema.oscal.tools.cli.core.commands.<model>` - Model-specific subcommands (catalog, profile, ssp, etc.)
63+
- `dev.metaschema.oscal.tools.cli.core.utils` - Utility classes
64+
65+
### CLI Framework
66+
67+
The CLI uses the `cli-processor` module from metaschema-java for command parsing and execution.
68+
69+
### Command Pattern
70+
71+
Commands follow an inheritance hierarchy:
72+
- **Parent commands** (e.g., `CatalogCommand`) extend `AbstractParentCommand` and register subcommands
73+
- **Validation commands** extend `AbstractOscalValidationCommand` → `AbstractValidateContentCommand`
74+
- **Convert commands** extend `AbstractOscalConvertCommand`
75+
- **Resolve commands** extend `AbstractResolveCommand`
76+
77+
Each OSCAL model type (catalog, profile, ssp, component-definition, assessment-plan, assessment-results, poam) has its own package with validate and convert subcommands.
78+
79+
## Code Style
80+
81+
- Java 11 target
82+
- Uses SpotBugs annotations (`@NonNull`, `@Nullable`) for null safety
83+
84+
## Git Workflow
85+
86+
- Repository: <https://github.com/metaschema-framework/oscal-cli>
87+
- **All PRs MUST be created from a personal fork** (required by CONTRIBUTING.md)
88+
- **All PRs MUST target the `develop` branch**
89+
- All changes require PR review
90+
91+
## Git Worktrees (MANDATORY)
92+
93+
**All development work MUST be done in a git worktree, not in the main repository checkout.**
94+
95+
### Why Worktrees Are Required
96+
97+
- Isolates feature work from the main checkout
98+
- Prevents accidental commits to the wrong branch
99+
- Allows parallel work on multiple features
100+
- Keeps the main checkout clean for reference and review
101+
102+
### Worktree Location
103+
104+
Worktrees are stored in `.worktrees/` directory (gitignored) relative to the repository root.
105+
106+
### Workflow
107+
108+
1. **Before starting any feature work**, create a worktree:
109+
110+
```bash
111+
# Create worktree for a new feature branch
112+
git worktree add .worktrees/<feature-name> -b <feature-branch> origin/develop
113+
```
114+
115+
2. **Check for existing worktrees** before making changes:
116+
117+
```bash
118+
git worktree list
119+
```
120+
121+
3. **Switch to the appropriate worktree** if one already exists for your task
122+
123+
4. **Remove worktrees** after PRs are merged:
124+
125+
```bash
126+
git worktree remove .worktrees/<feature-name>
127+
```
128+
129+
### Red Flags (You're Working in the Wrong Directory)
130+
131+
- Making changes without first checking `git worktree list`
132+
- Working in the main repository when a worktree exists for the feature
133+
- Creating files or commits in the main checkout for feature work
134+
135+
Use the `superpowers:using-git-worktrees` skill for guided worktree creation and management.
136+
137+
## Testing
138+
139+
- Tests use JUnit 5
140+
- All PRs require passing CI checks before merge
141+
- 100% of unit tests must pass before pushing code
142+
- See [TESTING.md](../TESTING.md) for detailed testing documentation
143+
144+
## Dependencies
145+
146+
This tool depends on:
147+
- `metaschema-java` (core Metaschema framework, including cli-processor)
148+
- `liboscal-java` (OSCAL Java library)
149+
150+
## Running the CLI
151+
152+
After building, run the CLI:
153+
154+
```bash
155+
# From the build output
156+
target/oscal-cli/bin/oscal-cli --help
157+
158+
# Disable colored output for legacy terminals
159+
oscal-cli --no-color <command>
160+
```
161+
162+
## Available Skills
163+
164+
### Metaschema (metaschema plugin)
165+
- `metaschema:metaschema-basics` - Introduction to Metaschema concepts
166+
- `metaschema:metaschema-module-authoring` - Creating/modifying Metaschema modules
167+
- `metaschema:metaschema-constraints-authoring` - Writing Metaschema constraints
168+
- `metaschema:metapath-expressions` - Metapath query syntax and functions
169+
170+
### OSCAL (oscal plugin)
171+
- `oscal:oscal-basics` - Working with OSCAL documents
172+
- `oscal:oscal-catalog` - OSCAL catalog documents
173+
- `oscal:oscal-profile` - OSCAL profiles and baselines
174+
- `oscal:oscal-ssp` - System Security Plans
175+
- `oscal:oscal-component-definition` - Component definitions
176+
177+
### Development (dev-metaschema plugin)
178+
- `dev-metaschema:development-workflow` - TDD, debugging, PRD workflow
179+
- `dev-metaschema:javadoc-style-guide` - Javadoc requirements and patterns
180+
- `dev-metaschema:unit-test-writing` - Test patterns and edge cases
181+
182+
### Tools
183+
- `metaschema-tools:using-metaschema-java` - metaschema-java CLI commands
184+
- `oscal-tools:using-oscal-cli` - oscal-cli commands and usage

‎.claude/settings.json‎

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

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,9 @@ pom.xml.versionsBackup
1919
release.properties
2020
velocity.log*
2121

22+
# Claude
23+
CLAUDE.local.md
24+
/.claude/settings.local.json
25+
2226
# Worktrees
2327
.worktrees/

0 commit comments

Comments
 (0)