feat: Comprehensive Claude Agent Enhancements

[osterman]

Summary

Comprehensive enhancements to Claude agents for the Atmos project, adding critical requirements for CLI development, code review, testing, documentation, and code organization patterns.

Key Additions:

• Zero-config philosophy and sensible defaults
• Global flags consistency (--chdir, --no-color, --identity, etc.)
• XDG Base Directory support for cache/credentials
• Cross-platform file operations (filepath functions, named constants)
• Dynamic terminal width handling
• Environment variable conventions (ATMOS_ prefix, configuration precedence)
• Code organization patterns (cmd/markdown, go:embed, error wrapping)
• GitHub CLI command reference for PR review automation
• CI workflow for agent file size limits

Agents Enhanced

cli-developer (6 commits)

• Flag design questioning and testability
• Global flags consistency patterns
• Environment variable binding with Viper
• XDG Base Directory usage
• Cross-platform file operations
• Terminal width dynamic sizing
• Code organization patterns (cmd/markdown, go:embed, error wrapping)
• Zero-config philosophy

code-reviewer (2 commits)

• Review filesystem operations for XDG usage
• Check for hardcoded path separators
• Verify magic number prevention with named constants
• Environment variable conventions (ATMOS_ prefix, viper.BindEnv)
• Cross-platform compatibility validation

documentation-writer (1 commit)

• Document environment variables for EVERY flag
• Show configuration precedence in examples

pr-review-resolver (1 commit)

• GitHub CLI commands for CodeRabbit review comments
• Rate limit handling (retry up to 1 hour)
• Efficient token usage (pagination, minimal preview)
• Reply mechanism with GraphQL API
• CI failure detection and log extraction

security-auditor (1 commit)

• Library vetting and licensing requirements
• CodeQL compliance and SBOM tracking

CI Enhancements

.github/workflows/claude.yml (1 commit)

• Extended to check ALL .claude/agents/*.md files
• Same 40k character limit for agents as CLAUDE.md
• Clear size reporting (chars and percentage)

Technical Details

Key Conventions

• ATMOS_ prefix: Mandatory for all environment variables
• Configuration precedence: CLI flags → ENV vars → Config files → Defaults
• XDG for cache: ~/.cache/atmos/, ~/.local/share/atmos/, ~/.config/atmos/
• File operations: Use filepath.Join (never hardcoded "/" separators)
• Terminal width: templates.GetTerminalWidth() for dynamic sizing
• Error wrapping: Always provide context with fmt.Errorf("%w: ...", err)
• Code organization: cmd/markdown/*.md for examples, go:embed for text blocks

File Size Management

All agents pass 40k character limit:

• cli-developer: 39,992 chars (99.9% - at limit)
• security-auditor: 35,665 chars (89%)
• code-reviewer: 26,516 chars (66%)
• All others well under limit

Test Plan

• ✅ All agent files under 40k character limit
• ✅ CI workflow validates agent sizes
• ✅ No .scratch files staged for commit
• ✅ Pre-commit hooks pass (trim whitespace, yaml validation)
• ✅ Comprehensive documentation of all requirements

References

• XDG Base Directory Spec
• Cobra Framework
• Viper Configuration
• Charm Bracelet Libraries
• Go standard library: filepath, go:embed, context

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Added comprehensive internal AI agent specifications and development guidelines to support project infrastructure.
  • Enhanced CI/CD workflow validation for agent documentation files.
  • Updated project configuration for code ownership and exclusions.

---

Note: This release contains infrastructure and internal documentation updates only. No user-facing features or changes are included.

[github-actions[bot]]

[!WARNING] This PR is blocked from merging because a required semver label is missing.

major, minor, patch, no-release

You'll need to add one before this PR can be merged.

[mergify[bot]]

[!WARNING]

This PR exceeds the recommended limit of 1,000 lines.

Large PRs are difficult to review and may be rejected due to their size.

Please verify that this PR does not address multiple issues. Consider refactoring it into smaller, more focused PRs to facilitate a smoother review process.

[mergify[bot]]

[!IMPORTANT]

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

[github-actions[bot]]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

This PR introduces a comprehensive agent specification framework by adding 16 new Claude agent definition documents to .claude/agents/, expanding CLAUDE.md with scratch folder conventions and additional mandatory guidelines, updating the CI workflow to discover and validate agent file sizes, and adding planning/context documents in .scratch/ for future refinement.

Changes

Cohort / File(s)	Summary
Agent Specifications .claude/agents/bug-investigator.md, .claude/agents/changelog-writer.md, .claude/agents/ci-failure-resolver.md, .claude/agents/cli-developer.md, .claude/agents/code-reviewer.md, .claude/agents/documentation-writer.md, .claude/agents/example-builder.md, .claude/agents/feature-development-orchestrator.md, .claude/agents/frontend-developer.md, .claude/agents/lint-resolver.md, .claude/agents/pr-manager.md, .claude/agents/pr-review-resolver.md, .claude/agents/prd-writer.md, .claude/agents/refactoring-architect.md, .claude/agents/security-auditor.md, .claude/agents/test-automation-expert.md	New agent role specifications defining responsibilities, workflows, quality standards, collaboration patterns, and operational guidelines for specialized development tasks (e.g., bug investigation, CI failure resolution, code review, documentation, security audits).
CI Workflow & Governance .github/workflows/claude.yml, .github/CODEOWNERS	Extended CI workflow to discover and validate agent Markdown files under 40,000 characters; added .claude/ and CLAUDE.md to CODEOWNERS under admin group.
Core Documentation CLAUDE.md	Added Scratch Folder Convention section and expanded mandatory guidelines covering environment variables, logging patterns, schemas, theming, code reuse, cross-platform considerations, and telemetry.
Metadata & Ignore .gitignore	Added .scratch/* with exception for .scratch/README.md to ignore scratch directory contents while preserving README.
Planning & Context .scratch/README.md, .scratch/ADDITIONAL_CONTEXT.md, .scratch/AGENT_ANALYSIS.md, .scratch/FINAL_UPDATES_SUMMARY.md	New working documents detailing test strategy updates (TestKit, Sandbox patterns), agent role analysis and gaps, implementation roadmap, and migration conventions for scratch-to-production content.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Areas requiring attention:
  • Agent role boundaries and potential overlaps (e.g., PR Manager vs. PR Review Resolver; Code Reviewer vs. CI Failure Resolver)
  • CI workflow file discovery logic and size-check thresholds (40,000 character limit rationale)
  • Consistency of mandatory patterns (Registry, Interface-Driven Design, testing expectations) across all agent definitions
  • Alignment between agent specifications, CLAUDE.md expansions, and existing project patterns
  • Scratch directory content scope and migration pathway clarity

Possibly related PRs

• cloudposse/atmos#1419 — Both PRs modify CLAUDE.md development guidelines with overlapping mandatory sections and standards.
• cloudposse/atmos#1693 — Both PRs extend CI workflows with size enforcement for CLAUDE-related documentation artifacts.
• cloudposse/atmos#1463 — Both PRs reorganize agent guidance, replacing centralized AGENTS.md with distributed .claude/agents/* specifications.

Suggested labels

no-release

Suggested reviewers

• aknysh

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "feat: Comprehensive Claude Agent Enhancements" directly relates to the changeset's primary objective: introducing a comprehensive suite of Claude agent specifications and supporting infrastructure. The PR adds 15+ new agent markdown files (.claude/agents/*.md) covering CLI development, code review, testing, documentation, security, and related roles, along with workflow updates (.github/workflows/claude.yml), codeowner configuration, and expanded guidance in CLAUDE.md. The term "Comprehensive" accurately captures the scope and scale of additions. The title is specific enough for a teammate scanning PR history to understand the main change without confusion.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch claude-agents

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 68.93%. Comparing base (f12f63d) to head (401a7eb). :warning: Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1733      +/-   ##
==========================================
+ Coverage   68.70%   68.93%   +0.22%     
==========================================
  Files         381      381              
  Lines       34822    34930     +108     
==========================================
+ Hits        23925    24079     +154     
+ Misses       8656     8588      -68     
- Partials     2241     2263      +22     

Flag	Coverage Δ
unittests	68.93% <ø> (+0.22%)	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more. see 9 files with indirect coverage changes

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mergify[bot]]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏