feat: Add CLI metadata extraction infrastructure and enrich-cli-help skill#574
Open
llewellyn-sl wants to merge 2 commits intomasterfrom
Open
feat: Add CLI metadata extraction infrastructure and enrich-cli-help skill#574llewellyn-sl wants to merge 2 commits intomasterfrom
llewellyn-sl wants to merge 2 commits intomasterfrom
Conversation
Replace brittle Python regex parsing with deterministic Java reflection using picocli's CommandSpec API. Integrate metadata updates into PR workflow via checklist. ## Added - Java metadata extractor (CliMetadataExtractor.java) - Uses picocli CommandSpec API for reflection-based extraction - Automatically resolves all @mixin annotations - Captures 1011 options deterministically - Outputs complete type information - Gradle task: extractCliMetadata - Runs the Java extractor - Outputs to docs/cli-metadata.json - PR template with metadata update checklist - Enforces running extractor before merge - Final step before merging CLI changes - GitHub Actions workflow for release automation - Triggers docs repo on release - Verifies metadata exists - Claude Code configuration and enrich-cli-help skill - Provides guidance for improving CLI help text - Documents metadata extraction workflow ## Benefits - Deterministic: Same input always produces same output - Complete: Captures all options including platform/provider mixins - Maintainable: Type-safe Java code, no regex brittleness - Integrated: Part of build system, no Python dependency - Enforced: PR template checklist ensures metadata stays current Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
llewellyn-sl
force-pushed
the
ll-cli-docs-automation-infrastructure
branch
from
73a473b to
51473a8
Compare
llewellyn-sl
changed the title
Add comprehensive guidelines for handling default values in CLI option descriptions,
based on learnings from PR 569 review feedback (2026-01-29).
Key additions:
1. Six rules for different default value scenarios:
- CLI-enforced defaults (use "Default: X")
- Platform-enforced defaults (use "If absent, Platform defaults to X")
- Boolean flags (omit default mention)
- Required fields (omit default mention)
- Using ${COMPLETION-CANDIDATES} for enums
2. Verification checklist for default value handling
3. Real-world examples in Quality Standards Reference:
- CLI-enforced: --type with defaultValue="stdout"
- Platform-enforced: --port, --boot-disk-size
- Enum with placeholder: --type with ${COMPLETION-CANDIDATES}
Prevents future confusion about "Default: X" vs "If absent, Platform defaults to X"
patterns. Ensures consistency across all future CLI help enrichment work.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace brittle Python regex parsing with deterministic Java reflection using picocli's CommandSpec API. Add Claude Code skill for improving CLI help text. Integrate metadata updates into PR workflow.
What Changed
Added
Java metadata extractor (
CliMetadataExtractor.java)@MixinannotationsGradle task:
extractCliMetadata./gradlew extractCliMetadatadocs/cli-metadata.jsonPR template with checklist
Claude Code skill:
enrich-cli-helpGitHub Actions workflow
Updated
.gitignore- Removed command-spec.json entrydocs/README.md- Documented Java reflection approach.claude/README.md- Added contributor guideRemoved
Benefits
Testing
Output:
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com