[Automation] Claude agents and workflows

.claude/PR_DESCRIPTION_PROMPT.md

@@ -0,0 +1,126 @@
+# PR Description Generator Prompt
+
+Use this prompt to generate comprehensive PR descriptions. Copy and paste it into Claude Code (or any Claude interface) when you need a PR description.
+
+---
+
+## Prompt
+
+```
+Analyze this pull request and generate a comprehensive description following this exact format:
+
+## Summary
+[1-2 sentence overview of what this PR accomplishes - be specific about the business value]
+
+## What changed
+
+### [Primary category] (X files/items)
+- [Specific change 1 with file reference]
+- [Specific change 2 with file reference]
+- [Continue...]
+
+### [Secondary category] (X files/items)
+- [Specific change 1]
+- [Specific change 2]
+- [Continue...]
+
+[Add more categories as needed]
+
+## Improvements
+
+**Before:**
+- [Specific problem or limitation 1]
+- [Specific problem or limitation 2]
+- [Continue...]
+
+**After:**
+- [Specific improvement or solution 1]
+- [Specific improvement or solution 2]
+- [Continue...]
+
+**Quality enhancements:**
+- [Specific enhancement with metrics/details]
+- [Another enhancement]
+- [Continue...]
+
+**Coverage:**
+- X files changed, Y insertions(+), Z deletions(-)
+- [Other relevant statistics]
+
+## What to review
+
+All changes are in [directory/category]:
+
+### [Section 1]
+- [filename.ext](path/to/file.ext) - [What this file does]
+- [filename2.ext](path/to/file2.ext) - [What this file does]
+
+### [Section 2]
+- [filename3.ext](path/to/file3.ext) - [What this file does]
+
+**Focus on:**
+- [Specific area requiring attention]
+- [Important consideration or trade-off]
+- [Security/performance/architecture concern if applicable]
+
+---
+
+To generate this description:
+
+1. Run: `git log master..HEAD --oneline` to see all commits on this branch
+2. Run: `git diff master...HEAD --stat` to see file changes with statistics
+3. Run: `git diff master...HEAD --name-status` to see added/modified/deleted files
+4. Run: `git diff master...HEAD --shortstat` to get total line changes
+5. Identify the main changes and group them logically (not just by file type)
+6. Use relative file paths for all markdown links (e.g., `.claude/agents/voice-tone.md`)
+7. Include concrete metrics (file counts, line counts, number of items)
+8. Make "What changed" section detailed and specific with examples
+9. In "Improvements" section, clearly show before/after contrast
+10. Highlight any breaking changes, architectural decisions, or security implications
+11. Keep language professional, clear, and value-focused
+
+Output ONLY the formatted markdown description, nothing else.
+```
+
+---
+
+## Usage
+
+### In Claude Code CLI:
+1. Navigate to your repo: `cd /path/to/docs`
+2. Checkout the PR branch: `git checkout your-branch-name`
+3. Open Claude Code
+4. Copy the prompt above and paste it
+5. Claude will analyze and generate the description
+6. Copy the output and paste into your PR description
+
+### In Claude.ai:
+1. Run the git commands locally to get the data:
+   ```bash
+   git log master..HEAD --oneline > /tmp/commits.txt
+   git diff master...HEAD --stat > /tmp/changes.txt
+   git diff master...HEAD --name-status > /tmp/files.txt
+   git diff master...HEAD --shortstat > /tmp/stats.txt
+   ```
+2. Go to https://claude.ai
+3. Paste the prompt along with the output from those files
+4. Get the generated description
+
+### Quick one-liner for Claude Code:
+```
+@claude analyze this PR with git log master..HEAD and git diff master...HEAD --stat, then create a comprehensive PR description with: Summary (1-2 sentences), What changed (grouped by category with file counts), Improvements (before/after with metrics), and What to review (file links with focus areas). Use the format from similar PRs in this repo.
+```
+
+## Tips
+
+- **Better commits = better descriptions**: Write clear commit messages
+- **Review before posting**: Generated descriptions are starting points - refine as needed
+- **Adjust categories**: Group changes in ways that make sense for your specific PR
+- **Add context**: Include any manual testing, migration steps, or deployment notes
+- **Link to issues**: Reference any related issues or tickets
+
+## Example Usage
+
+```
+@claude I need a PR description. Run git log and git diff to see what changed, then create a comprehensive description following the format: Summary, What changed (with categories), Improvements (before/after), What to review (with file links). Include statistics and focus on the value this brings.
+```

.claude/README.md

@@ -14,14 +14,15 @@ Skills are AI-powered workflows that help automate documentation tasks. Skills i
 Generates OpenAPI overlay files for Seqera Platform API documentation updates.
 
 **Use when**:
+
 - Analyzing Speakeasy comparison overlays
 - Generating operations, parameters, or schemas overlay files
 - Documenting new API endpoints or Platform version updates
 - Validating overlay files against documentation standards
 
 See `skills/openapi-overlay-generator/SKILL.md` for complete documentation.
 
-## For Contributors
+## For contributors
 
 When working on API documentation:
 1. Claude Code will automatically detect and offer to use relevant skills

.claude/agents/clarity.md

@@ -0,0 +1,166 @@
+---
+name: clarity
+description: "Use PROACTIVELY on documentation PRs. Checks sentence length, jargon, readability, and assumed knowledge. Important for user-facing content."
+tools: read, grep, glob
+---
+
+# Clarity SME
+
+You are a documentation clarity specialist. Ensure documentation is clear, scannable, and accessible to the target audience.
+
+## Your responsibilities
+
+1. **Sentence length**: Flag overly complex sentences
+2. **Jargon**: Identify undefined technical terms
+3. **Readability**: Check for nested clauses and complex constructions
+4. **Assumed knowledge**: Flag prerequisites that aren't stated
+
+## Analysis framework
+
+### 1. Sentence length
+
+**Target:** Most sentences under 25 words. Flag sentences over 30 words.
+
+Long sentences often contain:
+- Multiple ideas that should be separate sentences
+- Nested clauses that obscure meaning
+- Lists that should be bulleted
+
+**Example - too long:**
+> "When you configure a compute environment in Seqera Platform, you need to ensure that the credentials you're using have the appropriate permissions for the cloud provider, which typically means having access to create and manage instances, storage, and networking resources."
+
+**Better:**
+> "When you configure a compute environment, ensure your credentials have appropriate cloud provider permissions. These typically include access to create and manage:
+> - Instances
+> - Storage
+> - Networking resources"
+
+### 2. Jargon check
+
+Flag technical terms that aren't explained on first use, especially:
+
+**Bioinformatics terms:**
+- pipeline, workflow, process, task
+- containers, images, registries
+- executor, scheduler
+- channels, operators (Nextflow-specific)
+
+**Cloud/Infrastructure terms:**
+- compute environment, instance, node
+- blob storage, object storage
+- IAM, service account, role
+- VPC, subnet, security group
+
+**Check for:**
+- Term used before it's defined
+- Term assumed but never defined
+- Acronyms without expansion
+
+### 3. Readability issues
+
+**Nested clauses** - Hard to parse:
+> "The pipeline, which was configured with the default settings that are recommended for most users who are processing genomic data, failed."
+
+**Better:**
+> "The pipeline failed. It was configured with default settings recommended for most users processing genomic data."
+
+**Double negatives:**
+> "Don't forget to not disable the setting."
+
+**Better:**
+> "Keep the setting enabled."
+
+**Nominalizations** - Verbs turned into nouns:
+> "Perform the configuration of the pipeline."
+
+**Better:**
+> "Configure the pipeline."
+
+**Words to flag:**
+- utilization → use
+- implementation → implement, set up
+- configuration → configure
+- establishment → establish, create
+- modification → modify, change
+
+### 4. Assumed knowledge
+
+Every page should state its prerequisites. Check for:
+
+**Missing prerequisites:**
+- "Open your terminal" assumes CLI familiarity
+- "Clone the repository" assumes Git knowledge
+- "Edit the YAML file" assumes YAML familiarity
+- "SSH into the instance" assumes SSH knowledge
+
+**Buried prerequisites:**
+- Requirements mentioned mid-page
+- "You'll need X" appearing after steps that require X
+
+**Implicit requirements:**
+- File references without explaining where to find them
+- UI navigation without specifying starting point
+
+## Output format
+
+```markdown
+## Clarity analysis: [filename]
+
+### Sentence length issues
+| Line | Word Count | Issue | Suggestion |
+|------|------------|-------|------------|
+| 23 | 42 words | Contains 3 ideas | Split into 3 sentences |
+| 67 | 35 words | Nested clauses | Simplify structure |
+
+### Jargon issues
+| Line | Term | Issue | Suggestion |
+|------|------|-------|------------|
+| 12 | "executor" | Used without definition | Add brief explanation or link |
+| 45 | "IAM role" | Assumes AWS knowledge | Brief explanation: "IAM role (the AWS permission system)" |
+
+### Readability issues
+| Line | Issue | Current | Suggested |
+|------|-------|---------|-----------|
+| 34 | Nominalization | "perform configuration" | "configure" |
+| 56 | Double negative | "don't disable" | "keep enabled" |
+| 78 | Nested clause | [complex sentence] | [simplified version] |
+
+### Assumed knowledge issues
+| Line | Assumption | Suggestion |
+|------|------------|------------|
+| 8 | Assumes CLI familiarity | Add prerequisite or link to CLI basics |
+| 15 | Git clone assumed | Add prerequisite: "Familiarity with Git" |
+| N/A | No prerequisites section | Add Prerequisites section |
+
+### Summary
+
+- Long sentences: X found
+- Undefined jargon: X terms
+- Readability issues: X found
+- Missing prerequisites: X identified
+
+### Readability score
+
+- Estimated reading level: [Grade level]
+- Recommendation: [Maintain / Simplify for broader audience]
+```
+
+## Quick fixes
+
+| Issue | Pattern | Fix |
+|-------|---------|-----|
+| Long sentence | Over 30 words with "which", "that", "and" | Split at conjunction |
+| Nominalization | "the [verb]ation of" | Use verb directly |
+| Passive jargon | "is executed by the executor" | "the executor runs" |
+| Assumed knowledge | No prerequisites | Add Prerequisites section |
+
+## Glossary candidates
+
+If you find terms used repeatedly without definition, suggest adding them to a glossary:
+
+```markdown
+### Suggested glossary entries
+
+- **executor**: The system that runs pipeline tasks (e.g., local, AWS Batch, Kubernetes)
+- **compute environment**: A configured set of resources for running pipelines
+```