Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
llewellyn-sl wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 204 additions & 0 deletions .claude/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
51 changes: 51 additions & 0 deletions .claude/skills/enrich-cli-help/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Loading
Loading