diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d2cdad8..0a361aa 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -18,7 +18,7 @@ AGENTS.md @awslabs/agent-plugins-admins CLAUDE.md @awslabs/agent-plugins-admins CODE_OF_CONDUCT.md @awslabs/agent-plugins-admins CONTRIBUTING.md @awslabs/agent-plugins-admins -DEVELOPMENT_GUIDE.md @awslabs/agent-plugins-admins +docs/ @awslabs/agent-plugins-admins dprint.json @awslabs/agent-plugins-admins LICENSE @awslabs/agent-plugins-admins mise.toml @awslabs/agent-plugins-admins diff --git a/AGENTS.md b/AGENTS.md index aa9b88f..9add2da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,11 @@ agent-plugins/ │ ├── workflows/ # CI (build, lint, security, etc.) │ ├── ISSUE_TEMPLATE/ │ └── ... +├── docs/ # Role-specific guides +│ ├── DESIGN_GUIDELINES.md # Plugin design best practices +│ ├── DEVELOPMENT_GUIDE.md # Contributor setup and workflow +│ ├── MAINTAINERS_GUIDE.md # Reviewer/maintainer processes +│ └── TROUBLESHOOTING.md # Plugin troubleshooting ├── plugins/ │ └── deploy-on-aws/ │ ├── .claude-plugin/ @@ -129,8 +134,29 @@ Contributors must first add the marketplace before these take effect. claude --plugin-dir ./plugins/deploy-on-aws ``` +## Git Worktree Workflow + +ALWAYS use git worktrees for new work. The main worktree stays on its current branch and is never switched. Each piece of work gets its own worktree under `.tmp/`, branching off the current branch. This enables multiple agents to work in parallel without conflicts. + +```bash +# Create a worktree for new work (branches off current branch) +git worktree add .tmp/ -b + +# Create a worktree for an existing branch +git worktree add .tmp/ + +# List worktrees +git worktree list + +# Remove a worktree after the branch is merged +git worktree remove .tmp/ +``` + +All worktrees live under `.tmp/` (already in `.gitignore`). + ## Boundaries +- ALWAYS use `git worktree add .tmp/` for new work. NEVER switch branches in the main worktree. - ALWAYS Use mise commands to interact with the codebase. If a command is not available, add it. - NEVER add new dependencies without asking first. - ALWAYS run a full build when done with a task, this is to ensure all required files are generated before commit. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 956f62d..5438c27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,8 @@ Thank you for your interest in contributing to Agent Plugins for AWS. Depending on your role, please review the appropriate guide for repository-specific instructions: -- [Development Guide](./DEVELOPMENT_GUIDE.md) - For contributors and developers +- [Development Guide](./docs/DEVELOPMENT_GUIDE.md) - For contributors and developers +- [Maintainers Guide](./docs/MAINTAINERS_GUIDE.md) - For reviewers, maintainers, and admins ## Reporting Bugs/Feature Requests diff --git a/README.md b/README.md index 12a47dd..0157dc7 100644 --- a/README.md +++ b/README.md @@ -58,11 +58,7 @@ Equips agents with the skills to accelerate AWS deployment - recommending AWS ar ## Troubleshooting -Having issues with plugin installation or usage? See our [troubleshooting guide](./TROUBLESHOOTING.md) for common solutions. - -## Developer guide - -If you want to add a new plugin to the library, check out our [design guidelines](./DESIGN_GUIDELINES.md) and [development guide](./DEVELOPMENT_GUIDE.md). +Having issues with plugin installation or usage? See our [troubleshooting guide](./docs/TROUBLESHOOTING.md) for common solutions. ## Contributing @@ -70,6 +66,14 @@ Big shout out to our awesome contributors! Thank you for making this project bet Contributions of all kinds are welcome! Check out our [contributor guide](./CONTRIBUTING.md) for more information. +## Developer guide + +If you want to add a new plugin to the library, check out our [design guidelines](./docs/DESIGN_GUIDELINES.md) and [development guide](./docs/DEVELOPMENT_GUIDE.md). + +## Maintainers + +Repository reviewers, maintainers, and admins can find PR review workflows, merge rules, and CI/CD documentation in the [maintainers guide](./docs/MAINTAINERS_GUIDE.md). + ## License This project is licensed under the Apache-2.0 License. diff --git a/DESIGN_GUIDELINES.md b/docs/DESIGN_GUIDELINES.md similarity index 99% rename from DESIGN_GUIDELINES.md rename to docs/DESIGN_GUIDELINES.md index e905a78..d49cbec 100644 --- a/DESIGN_GUIDELINES.md +++ b/docs/DESIGN_GUIDELINES.md @@ -578,5 +578,5 @@ Before submitting a plugin, verify: - `.claude/docs/skills_docs.md` - Skill authoring technical reference - `.claude/docs/plugin_reference.md` - Plugin manifest specification -- `schemas/` - JSON schemas for validation -- `CLAUDE.md` - Repository-specific instructions +- `../schemas/` - JSON schemas for validation +- `../CLAUDE.md` - Repository-specific instructions diff --git a/DEVELOPMENT_GUIDE.md b/docs/DEVELOPMENT_GUIDE.md similarity index 100% rename from DEVELOPMENT_GUIDE.md rename to docs/DEVELOPMENT_GUIDE.md diff --git a/docs/MAINTAINERS_GUIDE.md b/docs/MAINTAINERS_GUIDE.md new file mode 100644 index 0000000..abb83d3 --- /dev/null +++ b/docs/MAINTAINERS_GUIDE.md @@ -0,0 +1,141 @@ +# Maintainers Guide + +This guide covers workflows, responsibilities, and tooling for repository reviewers, maintainers, and administrators. + +## Roles + +### Core Teams + +| Team | Scope | Responsibilities | +| ------------------------------------ | ------------------------------ | ------------------------------------------------------------ | +| `@awslabs/agent-plugins-admins` | Everything | Repo settings, CI/CD, schemas, tooling, CODEOWNERS, releases | +| `@awslabs/agent-plugins-maintainers` | Everything (default reviewers) | PR review, triage, community engagement | + +Admins own all configuration and infrastructure files explicitly. Both teams are defined in [CODEOWNERS](../.github/CODEOWNERS) on the default `*` pattern. + +### Plugin Teams + +Each plugin has its own GitHub team that owns its plugin directory. Plugin teams are created with `@awslabs/agent-plugins-writers` as the parent team. Once the parent team accepts the request, the plugin team gains write access to the repository. + +**Onboarding a new plugin team:** + +1. Create a GitHub team named `agent-plugins-` (e.g., `agent-plugins-deploy-on-aws`) +2. Set the parent team to `@awslabs/agent-plugins-writers` +3. The contributor adds a CODEOWNERS entry for the plugin directory: + + ```text + plugins/ @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers @awslabs/agent-plugins- + ``` + +4. An admin accepts the parent team request + +**Current plugin teams:** + +| Team | Plugin directory | +| -------------------------------------- | ------------------------ | +| `@awslabs/agent-plugins-deploy-on-aws` | `plugins/deploy-on-aws/` | + +## PR Review Workflow + +### Useful Filtered Views + +| View | Link | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Open PRs with all checks passing | [status:success](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+status%3Asuccess) | +| Open PRs needing review | [review:required](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+review%3Arequired) | +| Open PRs with failing checks | [status:failure](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+status%3Afailure) | +| PRs blocked from merge | [label:do-not-merge](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+label%3Ado-not-merge) | +| Stale PRs | [label:stale](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+label%3Astale) | +| Backlog PRs (exempt from staleness) | [label:backlog](https://github.com/awslabs/agent-plugins/pulls?q=is%3Apr+is%3Aopen+label%3Abacklog) | + +### Review Criteria + +When reviewing a PR, verify: + +1. **CI is green** - All required GitHub Actions checks pass (build, lint, security scanners, CodeQL) +2. **PR title** - Follows [conventional commits](https://www.conventionalcommits.org/) format (`fix:`, `feat:`, `chore:`, etc.). Enforced by CI. +3. **Contributor statement** - PR body includes the license contribution acknowledgment. Enforced by CI (exempts `awslabs-mcp` and `dependabot[bot]`). +4. **Design quality** - For plugin changes, use the review checklist in [Design Guidelines](./DESIGN_GUIDELINES.md#review-checklist) +5. **Versioning** - Plugin version changes follow [semantic versioning](https://semver.org/). Breaking changes require a major bump, new features a minor bump, bug fixes a patch bump. +6. **New plugins** - PRs that add a new directory under `plugins/` must also include: + - A CODEOWNERS entry for the plugin directory (see [Plugin Teams](#plugin-teams)) + - An entry in the marketplace manifest (`.claude-plugin/marketplace.json`) + - An entry in the plugin listing table in `README.md` + - The `new-plugin` label on the PR +7. **Security** - No secrets, credentials, or sensitive data in the diff. Security scanners (Bandit, SemGrep, Gitleaks, Checkov, Grype) run in CI. + +### Merge Rules + +- PRs require passing status checks before merge +- The `do-not-merge` label blocks merging (enforced by the [merge-prevention](../.github/workflows/merge-prevention.yml) workflow) +- The `HALT_MERGES` repository variable can block all merges or allow only a specific PR number: + - `0` (default) - all merges allowed + - `-1` - all merges blocked + - `` - only that PR may merge + +## Labels + +| Label | Purpose | +| -------------- | -------------------------------------- | +| `do-not-merge` | Blocks PR from merging (CI-enforced) | +| `new-plugin` | PR adds a new plugin to the repository | +| `backlog` | Exempts PR/issue from stale automation | +| `stale` | Auto-applied to inactive PRs/issues | +| `enhancement` | Feature request | +| `bug` | Bug report | +| `help wanted` | Good for external contributors | + +## Stale Automation + +The [stale workflow](../.github/workflows/stale.yml) runs daily: + +| Item | Stale after | Closed after | +| ------------- | ---------------- | ------------------ | +| Pull requests | 14 days inactive | 2 days after stale | +| Issues | 60 days inactive | 7 days after stale | + +Add the `backlog` label to exempt an item from staleness. + +## Issue Triage + +The repository provides issue templates for: + +- **Bug reports** - Structured reproduction steps +- **Feature requests** - Use case and proposed solution +- **Documentation** - Doc improvements or gaps +- **RFCs** - Larger proposals requiring discussion + +Triage incoming issues by applying appropriate labels and assigning to the relevant team. + +## CI/CD Overview + +All workflows are in [`.github/workflows/`](../.github/workflows/): + +| Workflow | Trigger | Purpose | +| ------------------------ | -------------------------- | ----------------------------------------------------------------- | +| `build.yml` | PR, push to main | Full build (`mise run build`: lint + format check + security) | +| `pull-request-lint.yml` | PR | Conventional commit title validation, contributor statement check | +| `merge-prevention.yml` | PR, merge queue | `do-not-merge` label and `HALT_MERGES` enforcement | +| `security-scanners.yml` | PR, push to main | Bandit, SemGrep, Gitleaks, Checkov, Grype | +| `codeql.yml` | PR, push to main, schedule | GitHub CodeQL analysis | +| `dependency-review.yml` | PR | Dependency vulnerability review | +| `scorecard-analysis.yml` | Push to main, schedule | OpenSSF Scorecard | +| `stale.yml` | Daily cron | Stale PR/issue management | + +## Release Process + +Releases follow [semantic versioning](https://semver.org/). Version numbers are tracked in plugin manifests (`plugin.json`). + +When preparing a release: + +1. Ensure all CI checks pass on `main` +2. Verify plugin manifest versions are updated +3. Run a full build locally: `mise run build` +4. Tag the release following the versioning convention + +## Security + +- Security vulnerability reports go through [AWS vulnerability reporting](https://aws.amazon.com/security/vulnerability-reporting/), not public GitHub issues +- See [SECURITY.md](../.github/SECURITY.md) for the full policy +- Security scanners run on every PR and push to `main` +- Gitleaks baseline (`.gitleaks-baseline.json`) tracks known false positives - see [Development Guide](./DEVELOPMENT_GUIDE.md#gitleaks---secret-detection) for handling diff --git a/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md similarity index 100% rename from TROUBLESHOOTING.md rename to docs/TROUBLESHOOTING.md