Skip to content

Commit 51473a8

Browse files
llewellyn-slclaude
llewellyn-sl
and
claude
committed
feat: Add CLI metadata extraction infrastructure
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>
1 parent c3359a4 commit 51473a8

File tree

13 files changed

+43468
-1
lines changed

13 files changed

+43468
-1
lines changed

‎.claude/README.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Claude Code Configuration for Seqera Platform CLI
2+
3+
This directory contains Claude Code configuration and skills for contributors working on the Seqera Platform CLI codebase.
4+
5+
## Skills Available
6+
7+
### enrich-cli-help
8+
9+
Systematic workflow for enriching CLI command option descriptions with OpenAPI-quality standards.
10+
11+
**Use this skill when:**
12+
- Improving help text for CLI command families
13+
- Adding technical context and practical guidance to options
14+
- Preparing CLI documentation updates for releases
15+
- Following up on metadata extraction to enhance descriptions
16+
17+
**Quick start:**
18+
```
19+
/enrich-cli-help [command-family-name]
20+
```
21+
22+
Or simply mention: "Let's enrich the [family] command options"
23+
24+
**Documentation:**
25+
- `skills/enrich-cli-help/SKILL.md` - Complete workflow guide
26+
- `skills/enrich-cli-help/README.md` - Quick reference
27+
- `skills/enrich-cli-help/references/` - Quality standards and architecture patterns
28+
29+
**Proven track record:**
30+
- Phase 3g: Compute-envs (13 platforms, 500+ options)
31+
- Phase 3h: Credentials (12 providers, 29 options)
32+
- Phase 3i: Runs (12 commands, 38 options)
33+
- Phase 3j: Organizations/Teams/Members (15 commands, 26 options)
34+
35+
**Total:** 593+ option descriptions enriched across 52 files
36+
37+
## Project Context
38+
39+
### Repository Structure
40+
```
41+
tower-cli/
42+
├── src/main/java/io/seqera/tower/cli/
43+
│ ├── commands/ # CLI command implementations
44+
│ └── utils/metadata/
45+
│ └── CliMetadataExtractor.java # Java reflection-based metadata extractor
46+
├── docs/
47+
│ ├── cli-metadata.json # Extracted CLI metadata (966+ options)
48+
│ ├── seqera-api-latest-decorated.yaml # OpenAPI spec with overlays
49+
│ └── README.md # Documentation automation process
50+
├── .claude/ # Claude Code configuration (this folder)
51+
└── build.gradle # Gradle task: extractCliMetadata
52+
```
53+
54+
### Key Files
55+
56+
**Metadata Extraction:**
57+
- `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java` - Java reflection-based extractor using picocli CommandSpec API
58+
- `build.gradle` - Contains `extractCliMetadata` Gradle task
59+
- `docs/cli-metadata.json` - Generated metadata for 162 commands, 966+ options
60+
61+
**Documentation:**
62+
- `docs/README.md` - Complete automation process, workflow, and quality standards
63+
- `.github/pull_request_template.md` - PR checklist ensures metadata stays current
64+
65+
**OpenAPI Integration:**
66+
- `docs/seqera-api-latest-decorated.yaml` - Decorated OpenAPI spec (API descriptions inform CLI help text quality)
67+
68+
## Workflow Overview
69+
70+
### CLI Documentation Automation Pipeline
71+
72+
```
73+
1. Enrich Descriptions
74+
└─> Use /enrich-cli-help skill for command families
75+
└─> Manual editing of @CommandLine.Option descriptions in Java files
76+
└─> OpenAPI schemas provide quality baseline
77+
78+
2. Extract Metadata (Java Reflection)
79+
└─> ./gradlew extractCliMetadata
80+
└─> Deterministically captures all 966+ options including resolved mixins
81+
└─> Outputs to docs/cli-metadata.json
82+
83+
3. Verify & Commit
84+
└─> git diff to review changes
85+
└─> Comprehensive commit message with statistics
86+
└─> PR template checklist ensures metadata is updated
87+
└─> Push to feature branch
88+
89+
4. On Release
90+
└─> GitHub Actions workflow notifies docs repository
91+
└─> Docs repo fetches cli-metadata.json from release
92+
└─> Automated PR updates CLI reference documentation
93+
```
94+
95+
### Branch Strategy
96+
97+
All CLI enrichment work should be done on a dedicated feature branch (e.g., `feature/enrich-[command-family]`).
98+
99+
## Getting Started
100+
101+
### For New Contributors
102+
103+
1. **Read the documentation:**
104+
```bash
105+
cat docs/README.md
106+
```
107+
108+
2. **Check enrichment status:**
109+
- Completed: compute-envs, credentials, runs, orgs/teams/members (624+ options)
110+
- Remaining: Additional command families available for enrichment
111+
112+
3. **Choose a command family to enrich:**
113+
- Pipelines, workspaces, actions, datasets, secrets, labels, participants, etc.
114+
- Use `/enrich-cli-help [family-name]` to start
115+
116+
4. **Follow the proven workflow:**
117+
- Phase 1: Parallel agent research (4 agents)
118+
- Phase 2: Synthesis & planning
119+
- Phase 3: Manual enrichment with quality standards
120+
- Phase 4: Verification & commit
121+
122+
5. **Update metadata before merging:**
123+
```bash
124+
./gradlew extractCliMetadata
125+
git add docs/cli-metadata.json
126+
git commit -m "Update CLI metadata"
127+
```
128+
129+
### Quality Standards
130+
131+
All enriched descriptions must meet these criteria:
132+
- **Technical precision**: Specify data types, formats, units
133+
- **Practical guidance**: Include examples, prerequisites, command references
134+
- **Security context**: Warn about sensitive fields, data loss
135+
- **Operational clarity**: Explain scope, defaults, constraints
136+
- **Pattern consistency**: Use standard descriptions for common options
137+
138+
See `skills/enrich-cli-help/references/quality-standards.md` for detailed examples.
139+
140+
## Architecture Patterns
141+
142+
The tower-cli codebase uses several option definition patterns:
143+
144+
### Pattern 1: Platform/Provider Mixin
145+
- **Examples**: compute-envs, credentials
146+
- **Characteristics**: Options in separate Platform/Provider classes
147+
- **Metadata extraction**: Automatically captured via Java reflection (resolves @Mixin annotations)
148+
- **Enrichment**: Manual editing of Platform/Provider Java files
149+
150+
### Pattern 2: Direct Options
151+
- **Examples**: runs, organizations, teams, members
152+
- **Characteristics**: Options defined directly in command classes
153+
- **Metadata extraction**: Automatically captured via Java reflection
154+
- **Enrichment**: Manual editing for quality enhancement
155+
156+
See `skills/enrich-cli-help/references/architecture-patterns.md` for complete pattern documentation.
157+
158+
## Contributing
159+
160+
### Adding New Skills
161+
162+
To add a new skill to this repository:
163+
164+
1. Create skill directory:
165+
```bash
166+
mkdir -p .claude/skills/[skill-name]
167+
```
168+
169+
2. Add required files:
170+
- `SKILL.md` - Main skill documentation with workflow
171+
- `README.md` - Quick reference guide
172+
- `references/` - Supporting documentation
173+
- `scripts/` - Automation scripts (optional)
174+
175+
3. Update this README with skill description
176+
177+
4. Commit to repository:
178+
```bash
179+
git add .claude/
180+
git commit -m "Add [skill-name] skill for contributors"
181+
```
182+
183+
### Settings
184+
185+
Local Claude Code settings can be configured in `.claude/settings.local.json`.
186+
187+
Current settings preserve conversation history for context continuity.
188+
189+
## Resources
190+
191+
### Documentation
192+
- **Automation process**: `docs/README.md`
193+
- **Metadata extractor**: `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java`
194+
- **Quality standards**: `skills/enrich-cli-help/references/quality-standards.md`
195+
- **Architecture patterns**: `skills/enrich-cli-help/references/architecture-patterns.md`
196+
197+
### External Links
198+
- **CLI documentation**: https://docs.seqera.io/platform/latest/cli/overview
199+
- **Seqera Platform API**: https://docs.seqera.io/platform/latest/api/overview
200+
- **Claude Code docs**: https://claude.com/claude-code
201+
202+
---
203+
204+
**Questions or issues?** Open an issue in the tower-cli repository or ask in #team-documentation Slack channel.

‎.claude/skills/enrich-cli-help/README.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# CLI Help Text Enrichment Skill
2+
3+
This skill encapsulates the proven workflow for enriching Seqera Platform CLI command option descriptions with OpenAPI-quality standards.
4+
5+
## Quick Start
6+
7+
To use this skill:
8+
9+
```
10+
/enrich-cli-help [command-family-name]
11+
```
12+
13+
Or simply mention the family you want to enrich and I'll use this skill automatically.
14+
15+
## What This Skill Does
16+
17+
1. **Research Phase**: Launches 4 parallel agents to analyze command family architecture
18+
2. **Planning Phase**: Synthesizes findings and creates enrichment plan
19+
3. **Enrichment Phase**: Guides systematic manual enrichment with quality standards
20+
4. **Verification Phase**: Reviews changes and creates comprehensive commit
21+
22+
## Proven Track Record
23+
24+
Successfully used to enrich:
25+
- **Phase 3g**: Compute-envs (13 platforms, 500+ options)
26+
- **Phase 3h**: Credentials (12 providers, 29 options)
27+
- **Phase 3i**: Runs (12 commands, 38 options)
28+
- **Phase 3j**: Organizations/Teams/Members (15 commands, 26 options)
29+
30+
**Total**: 593+ option descriptions across 52 files in 5 command families
31+
32+
## Key Features
33+
34+
- Parallel agent research for efficient intelligence gathering
35+
- Architecture pattern recognition (Platform/Provider vs Direct Options)
36+
- OpenAPI schema integration for quality baseline
37+
- Consistent pattern application across options
38+
- Security and safety warning guidance
39+
- Atomic commits with comprehensive documentation
40+
41+
## Files
42+
43+
- `SKILL.md` - Complete skill documentation
44+
- `references/quality-standards.md` - Description quality standards and examples
45+
- `references/architecture-patterns.md` - CLI architecture patterns reference
46+
47+
## Requirements
48+
49+
- Repository: `/Users/llewelyn-van-der-berg/Documents/GitHub/tower-cli`
50+
- Branch: `ll-metadata-extractor-and-docs-automation`
51+
- OpenAPI spec: `docs/seqera-api-latest-decorated.yaml`

0 commit comments

Comments
 (0)