diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b2e9775..c5ff177 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -31,6 +31,28 @@ "cdk" ], "version": "1.0.0" + }, + { + "category": "fullstack", + "description": "Build full-stack apps with AWS Amplify Gen 2 using guided workflows and SOPs", + "keywords": [ + "aws", + "aws agent skills", + "amazon", + "amplify", + "fullstack", + "gen2", + "workflows" + ], + "name": "aws-amplify", + "source": "./plugins/aws-amplify", + "tags": [ + "aws", + "amplify", + "fullstack", + "workflows" + ], + "version": "1.0.0" } ] } diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0a361aa..36b0e49 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -30,8 +30,9 @@ tools/ @awslabs/agent-plugins-admins ## Plugins (alphabetically listed) +plugins/aws-amplify @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers @awslabs/agent-plugins-amplify plugins/deploy-on-aws @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers @awslabs/agent-plugins-deploy-on-aws ## File must end with CODEOWNERS file -.github/CODEOWNERS @awslabs/agent-plugins-admins +.github/CODEOWNERS @awslabs/agent-plugins-admins diff --git a/README.md b/README.md index 0523024..db0b4d4 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,10 @@ To maximize the benefits of plugin-assisted development while maintaining securi ## Plugins -| Plugin | Description | Status | -| ----------------- | ------------------------------------------------------------------------------------------------ | --------- | -| **deploy-on-aws** | Deploy applications to AWS with architecture recommendations, cost estimates, and IaC deployment | Available | +| Plugin | Description | Status | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------ | --------- | +| [**aws-amplify**](plugins/aws-amplify) | Build full-stack apps with AWS Amplify Gen 2 using guided workflows and SOPs | Available | +| [**deploy-on-aws**](plugins/deploy-on-aws) | Deploy applications to AWS with architecture recommendations, cost estimates, and IaC deployment | Available | ## Installation diff --git a/plugins/aws-amplify/.claude-plugin/plugin.json b/plugins/aws-amplify/.claude-plugin/plugin.json new file mode 100644 index 0000000..a576738 --- /dev/null +++ b/plugins/aws-amplify/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "author": { + "name": "Amazon Web Services" + }, + "description": "Build full-stack apps with AWS Amplify Gen 2 using guided workflows and SOPs", + "homepage": "https://github.com/awslabs/agent-plugins", + "keywords": [ + "aws", + "amplify", + "fullstack", + "gen2", + "workflows" + ], + "license": "Apache-2.0", + "name": "aws-amplify", + "repository": "https://github.com/awslabs/agent-plugins", + "version": "1.0.0" +} diff --git a/plugins/aws-amplify/.mcp.json b/plugins/aws-amplify/.mcp.json new file mode 100644 index 0000000..b0d658b --- /dev/null +++ b/plugins/aws-amplify/.mcp.json @@ -0,0 +1,15 @@ +{ + "mcpServers": { + "aws-mcp": { + "command": "uvx", + "timeout": 100000, + "type": "stdio", + "args": [ + "mcp-proxy-for-aws@latest", + "--log-level", + "ERROR", + "https://aws-mcp.us-east-1.api.aws/mcp" + ] + } + } +} diff --git a/plugins/aws-amplify/README.md b/plugins/aws-amplify/README.md new file mode 100644 index 0000000..c020e56 --- /dev/null +++ b/plugins/aws-amplify/README.md @@ -0,0 +1,140 @@ +# AWS Amplify Claude Plugin + +Build full-stack applications with AWS Amplify Gen 2 using TypeScript code-first development. + +## Overview + +This plugin provides a workflow orchestrator for AWS Amplify Gen 2 development. It validates prerequisites, analyzes project state, retrieves official AWS SOPs via MCP, and guides you through backend creation, deployment, and frontend integration. + +## Features + +- **SOP-Driven**: Uses official AWS Amplify Standard Operating Procedures via MCP +- **Phased Workflow**: Backend → Sandbox → Frontend → Testing → Production +- **Framework Support**: React, Next.js, Vue, Angular, React Native, Flutter, Swift, Android +- **Gen 2 Only**: TypeScript code-first (`defineAuth`, `defineData`, `defineStorage`, `defineFunction`) + +## Prerequisites + +- Node.js 18.x or later +- AWS credentials configured (`aws configure` or `aws sso login`) +- `uv` package manager for MCP server: https://docs.astral.sh/uv/getting-started/installation/ + +## Installation + +### Option 1: Marketplace (recommended) + +```bash +/plugin marketplace add awslabs/agent-plugins +/plugin install aws-amplify@awslabs-agent-plugins +``` + +### Option 2: Load locally (for testing) + +```bash +git clone https://github.com/awslabs/agent-plugins +claude --plugin-dir ./agent-plugins/plugins/aws-amplify +``` + +## Usage + +### Slash Command + +``` +/aws-amplify:build I want to create a todo app with authentication +``` + +### Auto-Invoked Skill + +The `amplify-workflow` skill is automatically invoked when you ask Claude to build, modify, or deploy an Amplify Gen 2 backend or full-stack app, for example: + +- "Create a new Amplify backend with auth and a todo data model" +- "Add S3 storage and a Lambda function to my existing Amplify project" + +The `amplify-deploy` skill is the mandatory entry point for all Amplify deployments (sandbox and production). It is automatically invoked for deployment requests, for example: + +- "Deploy my Amplify sandbox environment" +- "Promote my sandbox to production" +- "Release my Amplify app" + +When `amplify-workflow` reaches its deployment phases (Phase 2: Sandbox, Phase 5: Production), it delegates to `amplify-deploy` automatically. + +These skills are **not** used for conceptual questions about Amplify, comparisons with other frameworks, or troubleshooting existing projects—ask those as normal questions without expecting the workflow to start. For build/create/deploy tasks, just describe what you want in natural language. + +## Workflow Phases + +| Phase | Description | Handled By | +| ---------- | ------------------------------- | ------------------------------------- | +| Backend | Create/modify Amplify resources | SOP: `amplify-backend-implementation` | +| Sandbox | Deploy to sandbox for testing | `amplify-deploy` skill | +| Frontend | Connect frontend to backend | SOP: `amplify-frontend-integration` | +| Testing | Local verification | Manual | +| Production | Deploy to production | `amplify-deploy` skill | + +**Common Patterns:** + +- New app: Backend → Sandbox → Frontend → Testing → Production +- Add feature: Backend → Sandbox +- Redeploy: Sandbox only +- Connect UI: Frontend → Testing +- Go live: Production only + +## Plugin Structure + +``` +aws-amplify/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +├── commands/ +│ └── build.md # /aws-amplify:build command +├── skills/ +│ ├── amplify-deploy/ +│ │ └── SKILL.md # Deployment skill (sandbox & production) +│ └── amplify-workflow/ +│ └── SKILL.md # Auto-invoked orchestrator +├── .mcp.json # AWS MCP server config +└── README.md +``` + +## AWS Credentials + +Must be configured before use: + +```bash +# Option 1: Access keys +aws configure + +# Option 2: SSO +aws sso login + +# Verify +aws sts get-caller-identity +``` + +## MCP Server + +This plugin requires the AWS MCP server for SOP retrieval. It's automatically configured via `.mcp.json`. + +Verify it's working: + +``` +/mcp +``` + +Should show `aws-mcp` as active. + +**If MCP is unavailable**, the plugin will STOP and ask you to configure it. It will not proceed without MCP. + +**Note:** The MCP endpoint (`us-east-1.api.aws`) is the API location for SOP +retrieval only. It does not affect which region your Amplify resources deploy +to — deployment region is controlled by your AWS credentials and CLI configuration. + +## License + +Apache-2.0 + +## Resources + +- [AWS Amplify Docs](https://docs.amplify.aws/) +- [Amplify Gen 2 Guide](https://docs.amplify.aws/react/start/) +- [Claude Code Plugins](https://code.claude.com/docs/en/plugins) +- [Model Context Protocol](https://modelcontextprotocol.io/) diff --git a/plugins/aws-amplify/commands/build.md b/plugins/aws-amplify/commands/build.md new file mode 100644 index 0000000..fe50494 --- /dev/null +++ b/plugins/aws-amplify/commands/build.md @@ -0,0 +1,27 @@ +--- +description: Build full-stack apps with AWS Amplify Gen 2 - describe what you want to build +argument-hint: "[description of what to build]" +--- + +# Build with AWS Amplify Gen 2 + +**Request:** $ARGUMENTS + +## Input Validation + +If `$ARGUMENTS` is empty or unclear, ask: + +``` +What would you like to build? For example: +- "A todo app with user authentication" +- "Add a GraphQL API to my existing Next.js app" +- "Deploy my app to production" +``` + +## Execution + +Delegate to the `amplify-workflow` skill and follow its complete workflow. +The skill handles prerequisite validation, phase planning, SOP retrieval, +and user confirmation gates. + +Gen 2 ONLY — no Gen 1 patterns (`amplify init`, `amplify push`). diff --git a/plugins/aws-amplify/skills/amplify-deploy/SKILL.md b/plugins/aws-amplify/skills/amplify-deploy/SKILL.md new file mode 100644 index 0000000..1247fa3 --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-deploy/SKILL.md @@ -0,0 +1,60 @@ +--- +name: amplify-deploy +description: Deploy AWS Amplify Gen 2 applications to sandbox (development) or production environments. MUST be used when user wants to DEPLOY, RELEASE, PROMOTE, or PUBLISH an Amplify app. Handles both sandbox deployment for testing and production deployment for going live. This is the mandatory entry point for all Amplify deployment operations. +--- + +# Amplify Deploy + +Deploy an AWS Amplify Gen 2 application to sandbox or production. + +## When to Use This Skill + +Use for any Amplify deployment: + +- Deploy to sandbox for development/testing +- Deploy/promote to production +- Redeploy after code changes +- Any request involving "deploy my Amplify app" + +--- + +## Invocation Context + +This skill may be invoked standalone or from the `amplify-workflow` orchestrator. + +- **From orchestrator:** The deployment type (sandbox or production) is specified + by the caller. Do not re-ask the user. Prerequisites (Node.js, npm, AWS + credentials) were already validated — skip the SOP's dependency verification step. +- **Standalone:** Determine deployment type from the user's request. Validate + prerequisites per the SOP. + +## Mapping Deployment Targets to SOP Parameters + +The SOP uses the parameter name `deployment_type` with values `sandbox` or `cicd`. +Map user/caller intent as follows: + +- "sandbox", "development", "testing" → SOP deployment_type: **sandbox** +- "production", "prod", "live", "release", "cicd" → SOP deployment_type: **cicd** + +--- + +## Retrieve and Follow the SOP + +The **"amplify-deployment-guide"** SOP must be retrieved **at least once** +during the conversation using the SOP retrieval tool from `aws-mcp`. + +**All steps in the SOP must be followed** for any type of deployment +(sandbox or production). The SOP contains the latest and most accurate +deployment procedures. Do not improvise or skip steps. + +### Critical Rules + +1. **Follow the SOP completely** - Do not improvise or skip steps +2. **If you encounter an error:** + - Fix the immediate issue + - Return to the SOP and continue from where you left off + - Do NOT abandon the SOP +3. **If you lose track of where you were:** + - Retrieve the SOP again + - Identify which step you completed last + - Continue from the next step diff --git a/plugins/aws-amplify/skills/amplify-workflow/SKILL.md b/plugins/aws-amplify/skills/amplify-workflow/SKILL.md new file mode 100644 index 0000000..dd34b24 --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/SKILL.md @@ -0,0 +1,282 @@ +--- +name: amplify-workflow +description: Orchestrates AWS Amplify Gen 2 workflows for building full-stack apps with React, Next.js, Vue, Angular, React Native, Flutter, Swift, or Android. Use when user wants to BUILD or CREATE Amplify projects, add authentication, data models, storage, GraphQL APIs, or Lambda functions. Not for conceptual questions, comparisons, or troubleshooting unrelated to active development. +--- + +# Amplify Workflow + +Orchestrated workflow for AWS Amplify Gen 2 development. + +## Scope + +This workflow covers building and creating Amplify Gen 2 projects through a phased +approach. Deployment phases delegate to the `amplify-deploy` skill automatically. + +--- + +## Step 1: Validate Prerequisites + +Run these checks before proceeding: + +1. **Node.js 18.x or later** + + ```bash + node --version + ``` + +2. **npm available** + + ```bash + npm --version + ``` + +3. **AWS credentials configured** (CRITICAL) + + ```bash + AWS_PAGER="" aws sts get-caller-identity + ``` + +## Step 2: Handle Missing AWS Credentials + +If the AWS credentials check fails, **STOP** and present this message to the user: + +``` +## AWS Credentials Required + +I can't proceed without AWS credentials configured. Please set up your credentials first: + +**Setup Guide:** https://docs.amplify.aws/react/start/account-setup/ + +**Quick options:** +- Run `aws configure` to set up access keys +- Run `aws sso login` if using AWS IAM Identity Center + +Once your credentials are configured, **come back and start a new conversation** to continue building with Amplify. +``` + +**Do NOT proceed with Amplify work until credentials are configured.** The user must restart the conversation after setting up credentials. + +## Step 3: Execute Workflow + +Once all prerequisites pass, follow the workflow below. + +--- + +## Critical Rules + +1. **Always follow SOPs completely** - Do not improvise or skip steps +2. **Never use Gen 1 patterns** - This is for Amplify Gen 2 only (TypeScript code-first, `defineAuth`/`defineData`/`defineStorage`/`defineFunction`) +3. **Understand before planning** - Read all necessary project files (e.g., `amplify/`, `package.json`, existing code) to understand the current state BEFORE proposing a plan +4. **Research before planning** - If unsure about Amplify capabilities or best practices, use documentation tools to search and read AWS Amplify docs BEFORE presenting the plan +5. **Wait for confirmation after each phase** - After completing each phase, STOP and ask the user to confirm before proceeding to the next phase +6. **If you encounter an error or get sidetracked:** + - Fix the immediate issue + - Return to the SOP and continue from where you left off + - Do NOT abandon the SOP or start improvising +7. **If you lose track of where you were in the SOP:** + - Use the SOP retrieval tool to get the SOP again + - Identify which step you completed last + - Continue from the next step + +--- + +## Determine Applicable Phases + +Based on the user's request and project state, determine which phases apply: + +| Phase | Applies when | +| ------------- | ---------------------------------------------------------- | +| 1: Backend | User needs to create or modify Amplify backend resources | +| 2: Sandbox | Deploy to sandbox for testing (via `amplify-deploy` skill) | +| 3: Frontend | Frontend needs to connect to Amplify backend | +| 4: Testing | App ready for local verification | +| 5: Production | Deploy to production (via `amplify-deploy` skill) | + +Common patterns: + +- **New full-stack app:** 1 → 2 → 3 → 4 → 5 +- **Backend only (no frontend):** 1 → 2 +- **Add feature to existing backend:** 1 → 2 +- **Redeploy after changes:** 2 only +- **Connect existing frontend:** 3 → 4 +- **Deploy to production:** 5 only + +**IMPORTANT: Only include phases that the user actually needs.** If the user asks for backend work only (e.g., "add auth", "create a data model", "add storage"), do NOT include Phase 3 (Frontend Integration) or Phase 4 (Local Testing). Frontend phases should only be included when the user explicitly asks for frontend work, a full-stack app, or to connect a frontend to Amplify. + +--- + +## Present Plan and Confirm + +Present to the user: + +``` +## Plan + +### What I understood +- [Brief summary of what the user wants] + +### Features +[list features if applicable] + +### Framework +[framework if known] + +### Phases I'll execute +1. [Phase name] - [one-line description] → SOP: [sop-name] +2. [Phase name] - [one-line description] → SOP: [sop-name] +... +(Include SOP name for phases 1 and 3. Phases 2 and 5 use the `amplify-deploy` skill. Phase 4 has no SOP.) + +Ready to get started? +``` + +**WAIT for user confirmation before proceeding.** + +**Once the user approves the plan, you MUST stick to it. Do not deviate from the planned phases or SOPs unless the user explicitly asks for changes.** + +--- + +## Execute Phases + +Execute each applicable phase IN SEQUENCE. + +**When starting a phase, announce it as a header:** + +``` +## Phase 1: Backend (SOP: amplify-backend-implementation) +[Next: Phase 2: Sandbox Deployment] + +## Phase 2: Sandbox Deployment (via amplify-deploy skill) +[Next: Phase 3: Frontend Integration] + +## Phase 3: Frontend Integration (SOP: amplify-frontend-integration) +[Next: Phase 4: Local Testing] + +## Phase 4: Local Testing +[Next: Phase 5: Production Deployment] + +## Phase 5: Production Deployment (via amplify-deploy skill) +``` + +Omit "[Next: ...]" if it's the last phase in your plan. + +--- + +### Phase 1: Backend + +**CRITICAL: Do NOT create frontend scaffolding or templates during this phase.** Do not run `create-next-app`, `create-react-app`, `create-vite`, `npm create`, or any frontend project generators. Phase 1 is strictly for Amplify backend resources (the `amplify/` directory). If a frontend project already exists, leave it untouched. If no frontend project exists and the user only asked for backend work, do NOT create one. + +Before creating any files, ensure `.gitignore` exists in the project root and includes: +`node_modules/`, `.env*`, `amplify_outputs.json`, `.amplify/`, `dist/`, `build/`. +Create or update it if these entries are missing. + +**Do NOT write any code until you have retrieved and read the SOP.** + +Use the SOP retrieval tool to get **"amplify-backend-implementation"** and follow it completely. + +**SOP overrides for orchestrator context:** + +- **Skip the SOP's Step 12** ("Determine Next SOP Requirements") — phase sequencing is controlled by this workflow, not the SOP. +- **Prerequisites were already validated** in Step 1 of this workflow. The SOP's dependency verification (Step 1) can be skipped. + +**After completion:** + +- Summarize what was created +- **STOP and ask:** "Phase 1 complete. Ready to proceed to Phase 2: Sandbox Deployment?" +- **WAIT for user confirmation before proceeding.** + +--- + +### Phase 2: Sandbox Deployment + +**Delegate to the `amplify-deploy` skill** for sandbox deployment. + +When invoking, indicate that the deployment target is **sandbox (development)**. +Also indicate that prerequisites (Node.js, npm, AWS credentials) were already +validated in Step 1 of this workflow so the deploy skill can skip re-verification. + +**After completion:** + +- Confirm deployment succeeded and `amplify_outputs.json` exists +- **STOP and ask:** "Phase 2 complete. Ready to proceed to Phase 3: Frontend Integration?" +- **WAIT for user confirmation before proceeding.** + +--- + +### Phase 3: Frontend Integration + +**Prerequisite:** `amplify_outputs.json` must exist. If not, run Phase 2 first. + +**Do NOT write any code until you have retrieved and read the SOP.** + +Use the SOP retrieval tool to get **"amplify-frontend-integration"** and follow it completely. + +**SOP overrides for orchestrator context:** + +- **Skip the SOP's Step 12** ("Determine Next SOP Requirements") — phase sequencing is controlled by this workflow, not the SOP. +- **Prerequisites were already validated** in Step 1 of this workflow. + +**After completion:** + +- Summarize integration work +- **STOP and ask:** "Phase 3 complete. Ready to proceed to Phase 4: Local Testing?" +- **WAIT for user confirmation before proceeding.** + +--- + +### Phase 4: Local Testing + +Present to the user: + +``` +## Time to test + +### Start your dev server +[framework-specific command] + +### Try out these features +[list features implemented] + +Let me know how it goes! +``` + +**After user confirms testing is successful:** + +- **STOP and ask:** "Phase 4 complete. Ready to proceed to Phase 5: Production Deployment?" +- **WAIT for user confirmation before proceeding.** + +--- + +### Phase 5: Production Deployment + +**Delegate to the `amplify-deploy` skill** for production deployment. + +When invoking, indicate that the deployment target is **production** (maps to +`cicd` deployment type in the SOP). Also indicate that prerequisites were +already validated in Step 1 of this workflow. + +**After completion:** + +``` +## You're live! + +### Production URL +[url] + +### Amplify Console +https://console.aws.amazon.com/amplify/home + +Your app is now deployed! Future updates: just push to your repo for auto-deploys. +``` + +--- + +## Troubleshooting + +If issues occur during any phase: + +1. Check the SOP's troubleshooting section first +2. Use documentation tools to search AWS Amplify docs for the error message +3. Read the relevant documentation page + +**After resolving the issue, immediately return to the SOP and continue from where you left off. Do not abandon the workflow.**