feat: Add CLI metadata extraction infrastructure and enrich-cli-help skill

.claude/README.md

@@ -0,0 +1,204 @@
+# Claude Code Configuration for Seqera Platform CLI
+
+This directory contains Claude Code configuration and skills for contributors working on the Seqera Platform CLI codebase.
+
+## Skills Available
+
+### enrich-cli-help
+
+Systematic workflow for enriching CLI command option descriptions with OpenAPI-quality standards.
+
+**Use this skill when:**
+- Improving help text for CLI command families
+- Adding technical context and practical guidance to options
+- Preparing CLI documentation updates for releases
+- Following up on metadata extraction to enhance descriptions
+
+**Quick start:**
+```
+/enrich-cli-help [command-family-name]
+```
+
+Or simply mention: "Let's enrich the [family] command options"
+
+**Documentation:**
+- `skills/enrich-cli-help/SKILL.md` - Complete workflow guide
+- `skills/enrich-cli-help/README.md` - Quick reference
+- `skills/enrich-cli-help/references/` - Quality standards and architecture patterns
+
+**Proven track record:**
+- Phase 3g: Compute-envs (13 platforms, 500+ options)
+- Phase 3h: Credentials (12 providers, 29 options)
+- Phase 3i: Runs (12 commands, 38 options)
+- Phase 3j: Organizations/Teams/Members (15 commands, 26 options)
+
+**Total:** 593+ option descriptions enriched across 52 files
+
+## Project Context
+
+### Repository Structure
+```
+tower-cli/
+├── src/main/java/io/seqera/tower/cli/
+│   ├── commands/                           # CLI command implementations
+│   └── utils/metadata/
+│       └── CliMetadataExtractor.java       # Java reflection-based metadata extractor
+├── docs/
+│   ├── cli-metadata.json                   # Extracted CLI metadata (966+ options)
+│   ├── seqera-api-latest-decorated.yaml    # OpenAPI spec with overlays
+│   └── README.md                           # Documentation automation process
+├── .claude/                                # Claude Code configuration (this folder)
+└── build.gradle                            # Gradle task: extractCliMetadata
+```
+
+### Key Files
+
+**Metadata Extraction:**
+- `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java` - Java reflection-based extractor using picocli CommandSpec API
+- `build.gradle` - Contains `extractCliMetadata` Gradle task
+- `docs/cli-metadata.json` - Generated metadata for 162 commands, 966+ options
+
+**Documentation:**
+- `docs/README.md` - Complete automation process, workflow, and quality standards
+- `.github/pull_request_template.md` - PR checklist ensures metadata stays current
+
+**OpenAPI Integration:**
+- `docs/seqera-api-latest-decorated.yaml` - Decorated OpenAPI spec (API descriptions inform CLI help text quality)
+
+## Workflow Overview
+
+### CLI Documentation Automation Pipeline
+
+```
+1. Enrich Descriptions
+   └─> Use /enrich-cli-help skill for command families
+   └─> Manual editing of @CommandLine.Option descriptions in Java files
+   └─> OpenAPI schemas provide quality baseline
+
+2. Extract Metadata (Java Reflection)
+   └─> ./gradlew extractCliMetadata
+   └─> Deterministically captures all 966+ options including resolved mixins
+   └─> Outputs to docs/cli-metadata.json
+
+3. Verify & Commit
+   └─> git diff to review changes
+   └─> Comprehensive commit message with statistics
+   └─> PR template checklist ensures metadata is updated
+   └─> Push to feature branch
+
+4. On Release
+   └─> GitHub Actions workflow notifies docs repository
+   └─> Docs repo fetches cli-metadata.json from release
+   └─> Automated PR updates CLI reference documentation
+```
+
+### Branch Strategy
+
+All CLI enrichment work should be done on a dedicated feature branch (e.g., `feature/enrich-[command-family]`).
+
+## Getting Started
+
+### For New Contributors
+
+1. **Read the documentation:**
+   ```bash
+   cat docs/README.md
+   ```
+
+2. **Check enrichment status:**
+   - Completed: compute-envs, credentials, runs, orgs/teams/members (624+ options)
+   - Remaining: Additional command families available for enrichment
+
+3. **Choose a command family to enrich:**
+   - Pipelines, workspaces, actions, datasets, secrets, labels, participants, etc.
+   - Use `/enrich-cli-help [family-name]` to start
+
+4. **Follow the proven workflow:**
+   - Phase 1: Parallel agent research (4 agents)
+   - Phase 2: Synthesis & planning
+   - Phase 3: Manual enrichment with quality standards
+   - Phase 4: Verification & commit
+
+5. **Update metadata before merging:**
+   ```bash
+   ./gradlew extractCliMetadata
+   git add docs/cli-metadata.json
+   git commit -m "Update CLI metadata"
+   ```
+
+### Quality Standards
+
+All enriched descriptions must meet these criteria:
+- **Technical precision**: Specify data types, formats, units
+- **Practical guidance**: Include examples, prerequisites, command references
+- **Security context**: Warn about sensitive fields, data loss
+- **Operational clarity**: Explain scope, defaults, constraints
+- **Pattern consistency**: Use standard descriptions for common options
+
+See `skills/enrich-cli-help/references/quality-standards.md` for detailed examples.
+
+## Architecture Patterns
+
+The tower-cli codebase uses several option definition patterns:
+
+### Pattern 1: Platform/Provider Mixin
+- **Examples**: compute-envs, credentials
+- **Characteristics**: Options in separate Platform/Provider classes
+- **Metadata extraction**: Automatically captured via Java reflection (resolves @Mixin annotations)
+- **Enrichment**: Manual editing of Platform/Provider Java files
+
+### Pattern 2: Direct Options
+- **Examples**: runs, organizations, teams, members
+- **Characteristics**: Options defined directly in command classes
+- **Metadata extraction**: Automatically captured via Java reflection
+- **Enrichment**: Manual editing for quality enhancement
+
+See `skills/enrich-cli-help/references/architecture-patterns.md` for complete pattern documentation.
+
+## Contributing
+
+### Adding New Skills
+
+To add a new skill to this repository:
+
+1. Create skill directory:
+   ```bash
+   mkdir -p .claude/skills/[skill-name]
+   ```
+
+2. Add required files:
+   - `SKILL.md` - Main skill documentation with workflow
+   - `README.md` - Quick reference guide
+   - `references/` - Supporting documentation
+   - `scripts/` - Automation scripts (optional)
+
+3. Update this README with skill description
+
+4. Commit to repository:
+   ```bash
+   git add .claude/
+   git commit -m "Add [skill-name] skill for contributors"
+   ```
+
+### Settings
+
+Local Claude Code settings can be configured in `.claude/settings.local.json`.
+
+Current settings preserve conversation history for context continuity.
+
+## Resources
+
+### Documentation
+- **Automation process**: `docs/README.md`
+- **Metadata extractor**: `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java`
+- **Quality standards**: `skills/enrich-cli-help/references/quality-standards.md`
+- **Architecture patterns**: `skills/enrich-cli-help/references/architecture-patterns.md`
+
+### External Links
+- **CLI documentation**: https://docs.seqera.io/platform/latest/cli/overview
+- **Seqera Platform API**: https://docs.seqera.io/platform/latest/api/overview
+- **Claude Code docs**: https://claude.com/claude-code
+
+---
+
+**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

@@ -0,0 +1,51 @@
+# CLI Help Text Enrichment Skill
+
+This skill encapsulates the proven workflow for enriching Seqera Platform CLI command option descriptions with OpenAPI-quality standards.
+
+## Quick Start
+
+To use this skill:
+
+```
+/enrich-cli-help [command-family-name]
+```
+
+Or simply mention the family you want to enrich and I'll use this skill automatically.
+
+## What This Skill Does
+
+1. **Research Phase**: Launches 4 parallel agents to analyze command family architecture
+2. **Planning Phase**: Synthesizes findings and creates enrichment plan
+3. **Enrichment Phase**: Guides systematic manual enrichment with quality standards
+4. **Verification Phase**: Reviews changes and creates comprehensive commit
+
+## Proven Track Record
+
+Successfully used to enrich:
+- **Phase 3g**: Compute-envs (13 platforms, 500+ options)
+- **Phase 3h**: Credentials (12 providers, 29 options)
+- **Phase 3i**: Runs (12 commands, 38 options)
+- **Phase 3j**: Organizations/Teams/Members (15 commands, 26 options)
+
+**Total**: 593+ option descriptions across 52 files in 5 command families
+
+## Key Features
+
+- Parallel agent research for efficient intelligence gathering
+- Architecture pattern recognition (Platform/Provider vs Direct Options)
+- OpenAPI schema integration for quality baseline
+- Consistent pattern application across options
+- Security and safety warning guidance
+- Atomic commits with comprehensive documentation
+
+## Files
+
+- `SKILL.md` - Complete skill documentation
+- `references/quality-standards.md` - Description quality standards and examples
+- `references/architecture-patterns.md` - CLI architecture patterns reference
+
+## Requirements
+
+- Repository: `/Users/llewelyn-van-der-berg/Documents/GitHub/tower-cli`
+- Branch: `ll-metadata-extractor-and-docs-automation`
+- OpenAPI spec: `docs/seqera-api-latest-decorated.yaml`