Skip to content

Update README to reflect broader scope#2

Merged
terraboops merged 4 commits intomainfrom
terra/update-readme-scope
Feb 2, 2026
Merged

Update README to reflect broader scope#2
terraboops merged 4 commits intomainfrom
terra/update-readme-scope

Conversation

@terraboops
Copy link
Collaborator

@terraboops terraboops commented Feb 2, 2026

Summary

Comprehensive README restructure to improve clarity, remove dead links, and provide detailed action documentation.

Changes

Main README

  • Updated intro to "Reusable GitHub Actions workflows for Claude Code development and Platform Engineering"
  • Removed non-existent docs/ folder references
  • Restructured with "Actions" section listing marketplace automation first
  • Moved and expanded "Already Using" section to "Basic Marketplace Publish Workflow"
  • Added mermaid diagram showing workflow steps (Discover → Validate → Generate → PR → Auto-merge)
  • Added detailed explanation of how the workflow operates
  • Updated Quick Start with complete workflow example
  • Removed speculative "Coming Soon" section

Marketplace Action README (new)

Created comprehensive documentation at marketplace/README.md:

  • Overview of the three composable actions
  • Quick start guides (reusable workflow + individual actions)
  • Detailed reference for discover, validate, and generate actions
  • Configuration documentation with example TOML
  • Expected repository structure
  • Workflow details for each phase
  • Troubleshooting section
  • Advanced usage examples (dry-run, manual merge, custom validation)

Why

  • The previous README referenced non-existent documentation files
  • Lacked clear explanation of how the workflow actually works
  • No documentation for the individual actions
  • Structure implied this was only for marketplace automation
  • "Coming Soon" section was speculative and could become stale

Impact

  • No breaking changes - all existing workflows continue to work
  • Better documentation for users
  • Clearer positioning of repository scope
  • Self-contained action documentation

- Clarify that this repo contains reusable workflows for Claude Code development
- Position marketplace automation as one category of workflows
- Add 'More Coming Soon' section for future workflows
- Update Quick Start section header to be more specific
- Update intro to mention both Claude Code development and Platform Engineering
- Add Platform Engineering workflows to 'More Coming Soon' section
- Reflects repository's broader purpose beyond just Claude Code tooling
- Show only what's available now, not future plans
- Cleaner README focused on current functionality
- New sections can be added as workflows are released
- Remove non-existent docs/ references
- Restructure as 'Actions' list with marketplace first
- Move and expand 'Already Using' section to 'Basic Marketplace Publish Workflow'
- Add mermaid diagram showing workflow steps and data flow
- Create comprehensive marketplace action README with:
  - Individual action reference (discover, validate, generate)
  - Configuration documentation
  - Repository structure guide
  - Troubleshooting section
  - Advanced usage examples
@terraboops terraboops merged commit f377f1e into main Feb 2, 2026
4 checks passed
@terraboops terraboops deleted the terra/update-readme-scope branch February 2, 2026 07:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant