docs: add Metaschema authoring skills and Metapath reference#576
Conversation
Adds critical instruction to check for existing worktrees before starting PRD-related work to prevent accidentally working in the wrong repository location.
📝 WalkthroughWalkthroughAdded four new Metaschema skill documents and a repo-specific metaschema-authoring rule; introduced a mandatory Test-Driven Development section and a "Resuming PRD Work (CRITICAL)" gating check; added a PRD and implementation plan for codegen quality improvements. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.claude/rules/development-workflow.md (1)
76-87: CRITICAL PRD section adds important safeguard, but could provide more actionable guidance.The "Resuming PRD Work" section correctly emphasizes the importance of using worktrees and avoiding accidental work in the main repository. The risks are clearly articulated. To make this more actionable, consider adding the specific command for switching to an existing worktree (e.g.,
git worktree listfollowed bygit worktree pruneor switching context).🔎 Proposed enhancement for worktree guidance
~**Before making ANY changes for PRD-related work:** 1. Run `git worktree list` to check for existing worktrees -2. If a worktree exists for this PRD/feature, switch to it +2. If a worktree exists for this PRD/feature, switch to it using `cd <worktree-path>` 3. **NEVER work in the main repository** if a worktree exists for the taskOr, if providing cleanup guidance:
+**If old worktrees exist:** +- Run `git worktree prune` to clean up stale entries +- If switching to an existing worktree: `cd <path-from-worktree-list>`
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
.claude/rules/development-workflow.md.claude/rules/metaschema-authoring.md.claude/skills/metapath-expressions.md.claude/skills/metaschema-constraints-authoring.md.claude/skills/metaschema-module-authoring.md
🧰 Additional context used
🧠 Learnings (15)
📚 Learning: 2025-12-24T21:21:52.756Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:52.756Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: The data type documentation in `website/content/specification/datatypes.md` must stay in sync with schema definitions in `schema/json/metaschema-datatypes.json` and `schema/xml/metaschema-datatypes.xsd`
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-24T21:21:59.692Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:21:59.692Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, update `schema/json/metaschema-datatypes.json`, `schema/xml/metaschema-datatypes.xsd`, and `website/content/specification/datatypes.md` in sync
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Keep `schema/json/`, `schema/xml/`, and `website/content/specification/datatypes.md` in sync when updating schema definitions
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examples
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Use semantic versioning. Version must be tracked in `package.json` and `schema/metaschema/metaschema-module-metaschema.xml`
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All changes require PR review with CODEOWNERS enforcement
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs must be created from a personal fork and must target the develop branch (BLOCKING - required by CONTRIBUTING.md)
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. 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 reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
.claude/skills/metapath-expressions.md.claude/rules/metaschema-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-01-07T00:50:46.218Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/type/InstanceOf.java:87-88
Timestamp: 2025-01-07T00:50:46.218Z
Learning: In the Metapath implementation, child expressions should be called using `accept()` rather than `evaluate()` to ensure proper management of the execution stack through push/pop operations. The `evaluate()` method is an internal implementation detail that performs the actual evaluation.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2025-12-24T21:21:35.530Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:35.530Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow package naming convention gov.nist.secauto.metaschema.* for all Java packages
Applied to files:
.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Deprecated features in specification documentation should show only non-deprecated values in the syntax overview (`_index.md`), but document deprecated values with clear notices in detailed documentation pages
Applied to files:
.claude/skills/metaschema-constraints-authoring.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (6)
.claude/skills/metaschema-module-authoring.md (1)
1-611: Comprehensive skill documentation with clear structure and strong examples.The module authoring skill is well-organized with parallel YAML/XML examples, thorough coverage of definition types, data types, format-specific features, and practical patterns. Documentation clearly delineates between required/optional header elements, explains scope control with detailed lookup rules, and provides real-world examples (identifier flags, location references, enumerated tokens, collections, optional fields). The cross-references to related skills and specifications are appropriate.
.claude/skills/metapath-expressions.md (1)
1-395: Excellent comprehensive reference for Metapath expressions.This skill provides authoritative documentation of the Metapath language with clear tables, syntax examples, and practical patterns. The function library is exhaustive, the error handling semantics are explained, and the common expression patterns (constraint validation, navigation) are immediately useful. Strong alignment with XPath 3.1 specification as the authoritative reference.
.claude/skills/metaschema-constraints-authoring.md (2)
553-554: Link domain consistency issue (shared with metaschema-module-authoring.md).Uses
https://pages.nist.gov/metaschema/specification/domain for Metaschema specification references. This is consistent withmetaschema-module-authoring.mdbut differs from theframework.metaschema.devdomain used elsewhere. See link verification comment in the module-authoring review.
1-556: Comprehensive constraint authoring skill with excellent examples and design patterns.The constraint authoring documentation is thorough, covering all constraint types with both YAML and XML examples, clear attribute explanations, and practical guidance. The best-practices section (inline vs external) and design patterns (hierarchical, cross-reference, conditional) are particularly valuable. The anti-patterns section helps users avoid common mistakes, and the connection to metapath-expressions skill and severity levels rounds out the guidance.
.claude/rules/development-workflow.md (1)
33-35: New project skills properly registered in development workflow.The three new Metaschema authoring skills are correctly added to the Project Skills section with appropriate descriptions that align with their respective skill file purposes. Integration is clean and follows existing formatting conventions.
.claude/rules/metaschema-authoring.md (1)
1-90: Clear repository-specific conventions establishing authoring standards.The metaschema-authoring rule effectively establishes conventions for this repository, specifying YAML as the preferred format, providing clear file locations, namespace patterns, and specific testing/code generation commands. The IDE validation guidance and bootstrap binding instructions are practical and help developers get started correctly. The skill references at the end properly connect to the detailed documentation in the new skill files.
david-waltermire
force-pushed
the
feature/metaschema-authoring-skills
branch
3 times, most recently
from
6800ac7 to
9ae66ac
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.claude/rules/development-workflow.md.claude/rules/metaschema-authoring.md.claude/skills/metapath-expressions.md.claude/skills/metaschema-constraints-authoring.md.claude/skills/metaschema-java-library.md.claude/skills/metaschema-module-authoring.md
🚧 Files skipped from review as they are similar to previous changes (2)
- .claude/skills/metaschema-constraints-authoring.md
- .claude/skills/metaschema-java-library.md
🧰 Additional context used
🧠 Learnings (17)
📓 Common learnings
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. 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 reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
.claude/skills/metapath-expressions.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examples
Applied to files:
.claude/skills/metapath-expressions.md.claude/skills/metaschema-module-authoring.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-01-07T00:50:46.218Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/type/InstanceOf.java:87-88
Timestamp: 2025-01-07T00:50:46.218Z
Learning: In the Metapath implementation, child expressions should be called using `accept()` rather than `evaluate()` to ensure proper management of the execution stack through push/pop operations. The `evaluate()` method is an internal implementation detail that performs the actual evaluation.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2025-01-07T00:51:17.257Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySequenceConstructor.java:63-63
Timestamp: 2025-01-07T00:51:17.257Z
Learning: In the Metapath implementation, expression evaluation must go through the `accept()` method rather than calling `evaluate()` directly, as `accept()` handles the push/pop operations on the execution stack which is used for debugging and error reporting.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2024-11-14T18:19:40.200Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 245
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IBooleanItem.java:86-104
Timestamp: 2024-11-14T18:19:40.200Z
Learning: In the file `core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IBooleanItem.java`, the 3-step approach in the `cast` method is consistent with the XPath 3.1 specification.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2025-12-24T21:21:52.756Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:52.756Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-24T21:21:59.692Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:21:59.692Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, update `schema/json/metaschema-datatypes.json`, `schema/xml/metaschema-datatypes.xsd`, and `website/content/specification/datatypes.md` in sync
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: The data type documentation in `website/content/specification/datatypes.md` must stay in sync with schema definitions in `schema/json/metaschema-datatypes.json` and `schema/xml/metaschema-datatypes.xsd`
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Use RFC 2119 keywords (MUST, SHOULD, MAY) consistently in uppercase in specification documentation
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Deprecated features in specification documentation should show only non-deprecated values in the syntax overview (`_index.md`), but document deprecated values with clear notices in detailed documentation pages
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-24T21:21:35.530Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:35.530Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow package naming convention gov.nist.secauto.metaschema.* for all Java packages
Applied to files:
.claude/rules/metaschema-authoring.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs must be created from a personal fork and must target the develop branch (BLOCKING - required by CONTRIBUTING.md)
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All changes require PR review with CODEOWNERS enforcement
Applied to files:
.claude/rules/development-workflow.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (12)
.claude/rules/development-workflow.md (2)
33-36: Skill listings are comprehensive and well-positioned.The new Metaschema authoring skills are correctly registered in the Project Skills section, providing clear visibility for developers working on module authoring, constraints, and Metapath expressions.
77-88: Excellent operational safeguard for PRD work.The new "Resuming PRD Work" section provides clear, actionable guidance that prevents common mistakes when working across multiple git worktrees. The placement before the approval phase ensures developers check prerequisites before committing work.
.claude/skills/metapath-expressions.md (2)
1-8: Excellent introduction and metadata.The skill is properly formatted with clear metadata and a strong opening that correctly identifies Metapath as based on XPath 3.1. The description targets the right audience (constraint/query writers).
10-113: Navigation and operator coverage is comprehensive and accurate.The path expressions, axis navigation, and operator sections correctly represent XPath 3.1 semantics, including the important distinction between general comparison (sequence-aware) and value comparison operators. Examples are practical and help readers understand when to use each construct.
.claude/skills/metaschema-module-authoring.md (5)
1-20: Clear metadata and appropriate scope delineation.The introduction properly references the repository-specific rules document, establishing a clean separation between general Metaschema authoring knowledge (in the skill) and metaschema-java conventions (in the rule). This is exactly the right structure.
22-75: Module structure guidance is clear and well-exemplified.Both YAML and XML format examples are complete and accurately represent the required header structure. The separated tables for required vs optional elements help readers quickly understand what's mandatory.
206-427: Format-specific features are thoroughly explained with practical examples.The sections on cardinality, grouping, and format-specific features cover XML, JSON, and YAML mappings with clear examples showing both definition syntax and resulting data structure. The json-key and json-value-key patterns are particularly well-explained with output examples.
429-611: Imports, scope, and patterns are comprehensively documented.The module imports section correctly explains cross-format compatibility, and the scope control section provides clear lookup and resolution rules. Best practices and common patterns sections offer practical guidance that developers will find immediately useful. All reference links consistently use
framework.metaschema.dev.
173-197: Specification domain consistency verified.All 25 specification references throughout the document consistently use
framework.metaschema.devas the canonical domain. No references topages.nist.govexist..claude/rules/metaschema-authoring.md (3)
1-68: Repository conventions are clearly defined and actionable.The rule correctly focuses on metaschema-java specifics: format preference, file locations, IDE validation, namespace patterns, and testing commands. The YAML-first approach aligns with project conventions, and the testing commands are specific and immediately usable.
84-97: Excellent documentation maintenance guidance.The "Maintaining Skill Documentation" section establishes a clear maintenance contract: specific code changes require corresponding skill updates. This ensures the new documentation stays synchronized with the implementation. The table mapping is comprehensive and the function location pointer is helpful.
99-106: Related skills are appropriately referenced.The rule concludes with a helpful reference to all related skills that support metaschema authoring.
Add comprehensive skills for Metaschema module and constraint authoring: - metaschema-module-authoring: Module structure, definitions, data types, XML/JSON-specific features, scope control, and cross-format imports - metaschema-constraints-authoring: Constraint types, inline vs external constraints, validation patterns, and best practices - metapath-expressions: Complete function reference, path syntax, operators, and common expression patterns based on XPath 3.1 - metaschema-java-library: Key interfaces, exception hierarchy, Metapath evaluation, constraint validation, and serialization APIs Add repository-specific conventions rule: - metaschema-authoring: File locations, namespace conventions, testing commands, code generation workflow, and skill maintenance requirements Closes metaschema-framework#569 Closes metaschema-framework#570
david-waltermire
force-pushed
the
feature/metaschema-authoring-skills
branch
from
9ae66ac to
106b752
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.claude/rules/development-workflow.md (1)
113-124: PRD resumption section addresses a real operational problem. Thegit worktree listcheck and guidance to avoid working in the main repository (lines 116-118) with clear rationale (lines 120-123) helps prevent common mistakes. Placement right after "PRD Directory Structure" makes it discoverable.Consider adding this section to Phase 1: PRD Development as a mandatory pre-step before creating the PRD directory, since it should be checked even earlier—ideally before starting any PRD-related work. Current placement (after Phase 1 intro) works but could be moved to the very start of Phase 1 for maximum visibility.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.claude/rules/development-workflow.md.claude/rules/metaschema-authoring.md.claude/skills/metapath-expressions.md.claude/skills/metaschema-constraints-authoring.md.claude/skills/metaschema-java-library.md.claude/skills/metaschema-module-authoring.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .claude/rules/metaschema-authoring.md
🧰 Additional context used
🧠 Learnings (23)
📓 Common learnings
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: When adding or modifying datatypes, update `schema/json/metaschema-datatypes.json`, `schema/xml/metaschema-datatypes.xsd`, and `website/content/specification/datatypes.md` in sync
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-24T21:21:59.692Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:21:59.692Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-java-library.md
📚 Learning: 2025-12-24T21:21:52.756Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:52.756Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-java-library.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: The data type documentation in `website/content/specification/datatypes.md` must stay in sync with schema definitions in `schema/json/metaschema-datatypes.json` and `schema/xml/metaschema-datatypes.xsd`
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Keep `schema/json/`, `schema/xml/`, and `website/content/specification/datatypes.md` in sync when updating schema definitions
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Use RFC 2119 keywords (MUST, SHOULD, MAY) consistently in uppercase in specification documentation
Applied to files:
.claude/skills/metaschema-module-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Applies to website/content/specification/**/*.md : Deprecated features in specification documentation should show only non-deprecated values in the syntax overview (`_index.md`), but document deprecated values with clear notices in detailed documentation pages
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: Constraints are documented in `website/content/specification/syntax/constraints.md`. When adding new constraint types, update the constraint type lists for `define-flag`, `define-field`, and `define-assembly`, and add a new section with syntax table and examples
Applied to files:
.claude/skills/metaschema-module-authoring.md.claude/skills/metaschema-constraints-authoring.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All changes require PR review with CODEOWNERS enforcement
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Code changes should use TDD principles: write tests first before implementing code, watch tests fail, write minimal code to pass tests, then refactor. For existing code without tests, add tests when modifying files to ensure behavioral equivalence.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow Test-Driven Development (TDD) principles: write tests first before implementing functionality, verify tests fail with current implementation, implement minimal code to pass tests, then refactor while keeping tests green
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs must be created from a personal fork and must target the develop branch (BLOCKING - required by CONTRIBUTING.md)
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: 100% of unit tests must pass before pushing code (BLOCKING)
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/metapath/**/*.java : Metapath is an implementation of XPath 3.1. 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 reference when implementing new functions, fixing bugs, or understanding error handling. Raise clarification before making changes if implementation differs from spec.
Applied to files:
.claude/skills/metaschema-constraints-authoring.md.claude/skills/metapath-expressions.md.claude/skills/metaschema-java-library.md
📚 Learning: 2025-01-07T00:50:46.218Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/type/InstanceOf.java:87-88
Timestamp: 2025-01-07T00:50:46.218Z
Learning: In the Metapath implementation, child expressions should be called using `accept()` rather than `evaluate()` to ensure proper management of the execution stack through push/pop operations. The `evaluate()` method is an internal implementation detail that performs the actual evaluation.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2025-01-07T00:51:17.257Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 336
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySequenceConstructor.java:63-63
Timestamp: 2025-01-07T00:51:17.257Z
Learning: In the Metapath implementation, expression evaluation must go through the `accept()` method rather than calling `evaluate()` directly, as `accept()` handles the push/pop operations on the execution stack which is used for debugging and error reporting.
Applied to files:
.claude/skills/metapath-expressions.md
📚 Learning: 2024-11-14T18:19:40.200Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 245
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IBooleanItem.java:86-104
Timestamp: 2024-11-14T18:19:40.200Z
Learning: In the file `core/src/main/java/gov/nist/secauto/metaschema/core/metapath/item/atomic/IBooleanItem.java`, the 3-step approach in the `cast` method is consistent with the XPath 3.1 specification.
Applied to files:
.claude/skills/metapath-expressions.md.claude/skills/metaschema-java-library.md
📚 Learning: 2025-12-24T21:21:35.530Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:35.530Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
.claude/skills/metaschema-java-library.md
📚 Learning: 2025-12-19T04:01:45.001Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Applied to files:
.claude/skills/metaschema-java-library.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow package naming convention gov.nist.secauto.metaschema.* for all Java packages
Applied to files:
.claude/skills/metaschema-java-library.md
📚 Learning: 2024-11-28T04:53:23.842Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 266
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/DynamicFunctionCall.java:73-77
Timestamp: 2024-11-28T04:53:23.842Z
Learning: In the `DynamicFunctionCall` class in `core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/DynamicFunctionCall.java`, it's acceptable to rely on `toAtomicItem()` to throw an exception if the specifier is not an `IAtomicItem`, rather than checking the instance type before calling `toAtomicItem()`.
Applied to files:
.claude/skills/metaschema-java-library.md
🔇 Additional comments (23)
.claude/skills/metapath-expressions.md (3)
1-10: Documentation is well-structured and comprehensive. The file correctly references XPath 3.1 as the authoritative basis for Metapath and provides clear organization from basic navigation through advanced patterns.
312-320: Metaschema-specific functions correctly documented. The function names at lines 316-319 match the implementation with proper-textsuffix and both overloads formp:recurse-depth. This addresses the previous review concern about function name accuracy.
128-133: Good reference to source code for authoritative signatures. Directing users to the library source code for complete function signatures is a pragmatic approach given XPath 3.1's function overloading complexity..claude/skills/metaschema-java-library.md (5)
1-8: Well-organized skill documentation with clear purpose. The file structure logically progresses from loading modules through serialization, constraint validation, and testing. Related skills are appropriately cross-referenced.
29-40: Key packages table is helpful. Provides a clear mapping of packages to their purposes, aiding developers in navigating the library structure.
186-260: Exception hierarchy section is comprehensive. Clear categorization with error code prefixes makes it easy for developers to understand and handle different exception types. The function-specific exceptions (lines 232-259) are particularly useful.
261-307: Function implementation example follows proper patterns. The use of builder API, property declarations, and handler registration demonstrates correct library usage. Structure mirrors XPath 3.1 function patterns appropriately.
389-426: Testing patterns demonstrate practical usage. Both isolated function testing (lines 393-406) and document-context testing (lines 411-425) provide realistic examples for developers implementing or testing Metapath functionality..claude/skills/metaschema-module-authoring.md (5)
1-20: Introduction clearly sets context and links to repository conventions. The reference to.claude/rules/metaschema-authoring.mdfor repository-specific conventions (line 10) properly delineates the scope of this skill document.
12-55: Parallel YAML/XML format guidance is exemplary. The consistent side-by-side examples throughout the document (illustrated in lines 24-55) make it easy for authors to understand format equivalence and make informed format choices.
171-205: Data types reference is comprehensive with linked documentation. Each data type includes a link to detailed specification, providing clear reference paths without duplicating specification content.
429-452: Cross-format import compatibility is clearly explained. The examples demonstrating YAML modules importing XML modules and vice versa (lines 433-451) clearly communicate an important capability that might otherwise be missed.
607-611: Specification references use consistent domain. All references useframework.metaschema.devconsistently, addressing the previous standardization concern..claude/skills/metaschema-constraints-authoring.md (6)
1-30: Clear introduction and constraint type overview. The table at lines 12-21 provides an excellent quick reference for which constraints apply to which definition types, helping authors choose the right tool for each validation need.
69-104: allowed-values constraint is well-documented with examples. Theextensibleattribute and deprecation pattern (lines 106-114) are particularly helpful for long-term constraint management.
335-345: Excellent delegation to metapath-expressions skill. Rather than duplicating Metapath documentation, this section appropriately references the dedicated skill and describes how it applies to constraints.
422-482: Best practices and anti-patterns provide practical guidance. The "When to Use Inline vs External Constraints" section (lines 424-435) and common anti-patterns (lines 476-482) help authors make sound design decisions. The design patterns section provides realistic examples.
484-492: Testing section appropriately references repository conventions. Deferring to.claude/rules/metaschema-authoring.mdfor testing commands keeps this skill focused on constraint concepts while pointing to repository-specific implementation.
550-556: References section is complete and authoritative. Includes Metaschema constraints spec, Metapath expression reference, and XPath 3.1 foundations, providing clear reference hierarchy..claude/rules/development-workflow.md (4)
28-50: Skill inventory is well-organized and current. The addition of four new Metaschema-focused skills (lines 33-36) to the Project Skills section is appropriate and clearly documented. The distinction between Project Skills and Managed Skills remains clear.
56-90: TDD section is comprehensive and enforceable. The structure—cycle (lines 60-66), red flags (lines 68-75), handling existing code (lines 77-82), and enforcement (lines 84-88)—provides clear guidance without ambiguity. The emphasis on "watch it fail" (line 88) is critical for test validity.
130-144: Development phase workflow integrates TDD naturally. The reference tosuperpowers:test-driven-development(line 133) and auto-applied testing anti-patterns skill (line 138) cleanly integrate the new TDD mandate into the existing phase structure.
209-224: Workflow summary diagram is clear. The ASCII flow from issue through PRD construction, approval, development, and PR provides a good visual reference for the full lifecycle.
…rement - Mark PR 1 as completed (PR metaschema-framework#577) - Add PR 2 for collection-class override support in binding configuration - Update issue metaschema-framework#572 with collection implementation override requirement - Renumber PRs to accommodate new work item
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.claude/rules/development-workflow.mdPRDs/20251224-codegen-quality/PRD.mdPRDs/20251224-codegen-quality/implementation-plan.md
🧰 Additional context used
🧠 Learnings (13)
📓 Common learnings
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:21:59.692Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
📚 Learning: 2025-12-24T21:21:35.530Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/csrc/ns/metaschema/test_suite/_1_0/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:35.530Z
Learning: In metaschema-framework/metaschema-java, generated binding classes in package gov.nist.csrc.ns.metaschema.test_suite._1_0 (and similar generated binding packages) are pre-generated by metaschema-maven-plugin and checked into source control. Javadoc coverage issues in these generated classes should be tracked as code generator improvements rather than file-level issues, and improvements are deferred to generator enhancements.
Applied to files:
PRDs/20251224-codegen-quality/implementation-plan.mdPRDs/20251224-codegen-quality/PRD.md
📚 Learning: 2025-12-24T21:21:59.692Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/GenerationCase.java:74-80
Timestamp: 2025-12-24T21:21:59.692Z
Learning: Files in the package gov.nist.secauto.metaschema.model.testing.testsuite in metaschema-testing are generated binding classes created from Metaschema definitions. Documentation and style improvements for these files should be made at the code generator level (metaschema-maven-plugin) rather than by manually editing the generated code.
Applied to files:
PRDs/20251224-codegen-quality/implementation-plan.mdPRDs/20251224-codegen-quality/PRD.md
📚 Learning: 2025-12-24T21:21:52.756Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 567
File: metaschema-testing/src/main/java/gov/nist/secauto/metaschema/model/testing/testsuite/Metaschema.java:41-47
Timestamp: 2025-12-24T21:21:52.756Z
Learning: In metaschema-testing, generated binding classes under gov.nist.secauto.metaschema.model.testing.testsuite are produced by metaschema-maven-plugin from YAML metaschema definitions. Javadoc issues in these generated classes should not be flagged for manual fixes; improvements are tracked and handled through code generator enhancements rather than manual edits to the generated source.
Applied to files:
PRDs/20251224-codegen-quality/implementation-plan.mdPRDs/20251224-codegen-quality/PRD.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : All code changes must follow the Javadoc style guide (docs/javadoc-style-guide.md). New code requires 100% Javadoc coverage on public/protected members. Modified code must add/update Javadoc on any members touched. All Javadoc must include param, return, throws tags in the correct order (BLOCKING)
Applied to files:
PRDs/20251224-codegen-quality/implementation-plan.md.claude/rules/development-workflow.mdPRDs/20251224-codegen-quality/PRD.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Code changes should use TDD principles: write tests first before implementing code, watch tests fail, write minimal code to pass tests, then refactor. For existing code without tests, add tests when modifying files to ensure behavioral equivalence.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: Applies to **/*.java : Follow Test-Driven Development (TDD) principles: write tests first before implementing functionality, verify tests fail with current implementation, implement minimal code to pass tests, then refactor while keeping tests green
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: For larger initiatives requiring multiple PRs, use structured PRD (Product Requirements Document) approach. PRDs stored in PRDs/<YYYYMMDD>-<name>/ with PRD.md and implementation-plan.md. Target ≤50 files per PR, maximum 100 files per PR.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs must be created from a personal fork and must target the develop branch (BLOCKING - required by CONTRIBUTING.md)
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All changes require PR review with CODEOWNERS enforcement
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-13T21:16:12.281Z
Learnt from: CR
Repo: metaschema-framework/metaschema PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T21:16:12.281Z
Learning: All PRs must target the `develop` branch, not `main`. The `main` branch receives merges only from `develop` during releases.
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-17T13:27:43.679Z
Learnt from: CR
Repo: metaschema-framework/metaschema-java PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-17T13:27:43.679Z
Learning: All PRs require passing CI checks before merge
Applied to files:
.claude/rules/development-workflow.md
📚 Learning: 2025-12-19T04:01:45.001Z
Learnt from: david-waltermire
Repo: metaschema-framework/metaschema-java PR: 550
File: core/src/main/java/gov/nist/secauto/metaschema/core/metapath/format/JsonPointerFormatter.java:56-100
Timestamp: 2025-12-19T04:01:45.001Z
Learning: In Java code for metaschema-framework/metaschema-java, override methods (annotated with Override) that implement interface methods automatically inherit Javadoc from the interface and do not require redundant documentation in the implementing class unless there is implementation-specific behavior that needs to be documented beyond what the interface specifies.
Applied to files:
PRDs/20251224-codegen-quality/PRD.md
🪛 markdownlint-cli2 (0.18.1)
PRDs/20251224-codegen-quality/implementation-plan.md
39-39: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
111-111: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
182-182: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Code
- GitHub Check: Website
🔇 Additional comments (6)
.claude/rules/development-workflow.md (3)
33-36: Verify that new skill files exist in the PR.Lines 33–36 reference four new project skills (
metaschema-module-authoring,metaschema-constraints-authoring,metapath-expressions,metaschema-java-library), but the skill files themselves are not included in the files provided for review. Ensure that the corresponding.claude/skills/*.mdfiles are added in this PR.
56-90: TDD section is well-structured and clear.The new mandatory TDD section effectively communicates the Red-Green-Refactor cycle, identifies common pitfalls, and provides practical guidance for modifying existing code. The emphasis on mandatory enforcement and the reference to the superpowers skill are appropriate. This aligns well with the learnings about TDD principles in the codebase.
98-126: Worktree check and PRD structure guidance are well-integrated.The critical worktree check (lines 101–103) with clear rationale prevents common pitfalls (wrong directory, wrong branch commits). The PRD directory structure example aligns with the documented conventions (PRDs/-/ with PRD.md and implementation-plan.md). This addition strengthens the workflow documentation.
PRDs/20251224-codegen-quality/implementation-plan.md (2)
1-37: Prerequisites and TDD requirement are clear and appropriate.The document opens with clear prerequisites and emphasizes the mandatory TDD requirement, which aligns with the development workflow. The structure sets the right expectations for contributors.
38-268: Implementation details are comprehensive and well-organized.The three PR sections provide clear implementation approaches with specific files, numbered steps, example configurations, and testable acceptance criteria. Status tracking ([x] complete, [ ] pending) and issue linkage provide good traceability. The verification commands are practical and actionable.
PRDs/20251224-codegen-quality/PRD.md (1)
1-210: PRD is comprehensive, well-structured, and properly scoped.This PRD clearly identifies the problem (extraneous quotes, missing Javadoc, missing annotations in generated code), defines specific, measurable goals, and articulates functional and non-functional requirements with examples. The success metrics table, risk assessment, and tracking of open questions demonstrate solid planning. The reference to the implementation-plan.md provides appropriate detail for execution, and cross-references to related GitHub issues establish good traceability.
aj-stein
left a comment
aj-stein
left a comment
There was a problem hiding this comment.
This is sick, can't wait to use these skills in the future!
david-waltermire
merged commit a6330f7
into
metaschema-framework:develop
2 participants
Summary
New Skills
metaschema-module-authoringmetaschema-constraints-authoringmetapath-expressionsNew Rule
metaschema-authoringDocumentation Structure
Test plan
Closes #569
Closes #570
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.