docs: move guides into docs/ and add maintainers guide

.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

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/<short-name> -b <branch-name>
+
+# Create a worktree for an existing branch
+git worktree add .tmp/<short-name> <branch-name>
+
+# List worktrees
+git worktree list
+
+# Remove a worktree after the branch is merged
+git worktree remove .tmp/<short-name>
+```
+
+All worktrees live under `.tmp/` (already in `.gitignore`).
+
 ## Boundaries
 
+- ALWAYS use `git worktree add .tmp/<name>` 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.

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
 

README.md

@@ -58,18 +58,22 @@ 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
 
 Big shout out to our awesome contributors! Thank you for making this project better!
 
 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.

DESIGN_GUIDELINES.md → 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

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-<plugin-name>` (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/<plugin-name>     @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers  @awslabs/agent-plugins-<plugin-name>
+   ```
+
+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
+  - `<PR number>` - 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