From 415d76824699b4c574028a1396d9b23196e62962 Mon Sep 17 00:00:00 2001 From: "H. Furkan Bozkurt" Date: Tue, 3 Mar 2026 10:32:40 +0000 Subject: [PATCH] feat(aws-amplify): add AWS Amplify Gen 2 plugin --- .claude-plugin/marketplace.json | 18 ++ .github/CODEOWNERS | 3 +- README.md | 30 +++ .../aws-amplify/.claude-plugin/plugin.json | 21 ++ plugins/aws-amplify/.mcp.json | 15 ++ .../skills/amplify-workflow/SKILL.md | 214 ++++++++++++++++++ .../amplify-workflow/references/backend.md | 41 ++++ .../amplify-workflow/references/deploy.md | 49 ++++ .../amplify-workflow/references/frontend.md | 57 +++++ .../amplify-workflow/scripts/prereq-check.sh | 47 ++++ 10 files changed, 494 insertions(+), 1 deletion(-) create mode 100644 plugins/aws-amplify/.claude-plugin/plugin.json create mode 100644 plugins/aws-amplify/.mcp.json create mode 100644 plugins/aws-amplify/skills/amplify-workflow/SKILL.md create mode 100644 plugins/aws-amplify/skills/amplify-workflow/references/backend.md create mode 100644 plugins/aws-amplify/skills/amplify-workflow/references/deploy.md create mode 100644 plugins/aws-amplify/skills/amplify-workflow/references/frontend.md create mode 100755 plugins/aws-amplify/skills/amplify-workflow/scripts/prereq-check.sh diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 82cd106..4ff6448 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -47,6 +47,24 @@ "source": "./plugins/amazon-location-service", "tags": ["aws", "location", "maps", "geospatial"], "version": "1.0.0" + }, + { + "category": "fullstack", + "description": "Build full-stack apps with AWS Amplify Gen 2 using guided workflows for authentication, data models, storage, GraphQL APIs, and Lambda functions.", + "keywords": [ + "aws", + "amplify", + "fullstack", + "authentication", + "data", + "storage", + "graphql", + "functions" + ], + "name": "aws-amplify", + "source": "./plugins/aws-amplify", + "tags": ["aws", "amplify", "fullstack"], + "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 3b50220..681f5fe 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ To maximize the benefits of plugin-assisted development while maintaining securi | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- | | **deploy-on-aws** | Deploy applications to AWS with architecture recommendations, cost estimates, and IaC deployment | Available | | **amazon-location-service** | Add maps, geocoding, routing, places search, and geospatial features to applications with Amazon Location Service | Available | +| **aws-amplify** | Build full-stack apps with AWS Amplify Gen 2 using guided workflows for auth, data, storage, and functions | Available | ## Installation @@ -53,6 +54,12 @@ or /plugin install amazon-location-service@agent-plugins-for-aws ``` +or + +```bash +/plugin install aws-amplify@agent-plugins-for-aws +``` + ### Cursor You can install the **deploy-on-aws** plugin from the [Cursor Marketplace](https://cursor.com/marketplace/aws). For additional information, please refer to the [Cursor plugin documentation](https://cursor.com/docs/plugins). You can also install within the Cursor application: @@ -106,6 +113,29 @@ Guides developers through adding maps, places search, geocoding, routing, and ot | ----------- | -------------------------------------- | | **aws-mcp** | AWS documentation and service guidance | +## aws-amplify + +Build full-stack apps with AWS Amplify Gen 2 using TypeScript code-first development, guided by official AWS Standard Operating Procedures. + +### Workflow + +1. **Backend** - Create Amplify Gen 2 resources (auth, data, storage, functions) +2. **Sandbox** - Deploy to sandbox for testing +3. **Frontend & Test** - Connect frontend to backend, verify locally +4. **Production** - Deploy to production + +### Agent Skill Triggers + +| Agent Skill | Triggers | +| -------------------- | ------------------------------------------------------------------------------------------------------------ | +| **amplify-workflow** | "build Amplify app", "create Amplify project", "add auth to Amplify", "deploy Amplify", "full-stack Amplify" | + +### MCP Servers + +| Server | Purpose | +| ----------- | -------------------------------------- | +| **aws-mcp** | AWS documentation and service guidance | + ## Requirements - Claude Code >=2.1.29 or [Cursor >= 2.5](https://cursor.com/changelog/2-5) diff --git a/plugins/aws-amplify/.claude-plugin/plugin.json b/plugins/aws-amplify/.claude-plugin/plugin.json new file mode 100644 index 0000000..1a7d641 --- /dev/null +++ b/plugins/aws-amplify/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "author": { + "name": "Amazon Web Services" + }, + "description": "Build full-stack apps with AWS Amplify Gen 2 using guided workflows for authentication, data models, storage, GraphQL APIs, and Lambda functions.", + "homepage": "https://github.com/awslabs/agent-plugins", + "keywords": [ + "aws", + "amplify", + "fullstack", + "authentication", + "data", + "storage", + "graphql", + "functions" + ], + "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/skills/amplify-workflow/SKILL.md b/plugins/aws-amplify/skills/amplify-workflow/SKILL.md new file mode 100644 index 0000000..c68d361 --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/SKILL.md @@ -0,0 +1,214 @@ +--- +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, CREATE, or DEPLOY Amplify projects, add authentication, data models, storage, GraphQL APIs, Lambda functions, or deploy to sandbox/production. Do NOT invoke for conceptual questions, comparisons, or troubleshooting unrelated to active development. +--- + +# Amplify Workflow + +Orchestrated workflow for AWS Amplify Gen 2 development. + +## Available references + +- **`references/backend.md`** -- Backend phase: SOP retrieval, constraints, error handling +- **`references/frontend.md`** -- Frontend & testing phase: SOP retrieval, local testing +- **`references/deploy.md`** -- Deploy phase: SOP retrieval, deployment type mapping + +## Available scripts + +- **`scripts/prereq-check.sh`** -- Validates Node.js, npm, and AWS credentials + +--- + +## Step 1: Validate Prerequisites + +Run the prerequisite check script: + +```bash +bash scripts/prereq-check.sh +``` + +The script checks Node.js >= 18, npm, and AWS credentials in one pass and reports a clear PASS/FAIL summary. + +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 2: Understand the Project + +Once all prerequisites pass: + +1. Read all necessary project files (e.g., `amplify/`, `package.json`, existing code) to understand the current state +2. If unsure about Amplify capabilities or best practices, use documentation tools to search and read AWS Amplify docs + +Do this BEFORE proposing a plan. + +--- + +## Step 3: Determine Applicable Phases + +Based on the user's request and project state, determine which phases apply: + +| Phase | Applies when | Reference | +| ------------------ | -------------------------------------------------------- | ------------------------ | +| 1: Backend | User needs to create or modify Amplify backend resources | `references/backend.md` | +| 2: Sandbox | Deploy to sandbox for testing | `references/deploy.md` | +| 3: Frontend & Test | Frontend needs to connect to Amplify backend | `references/frontend.md` | +| 4: Production | Deploy to production | `references/deploy.md` | + +Common patterns: + +- **New full-stack app:** 1 -> 2 -> 3 -> 4 +- **Backend only (no frontend):** 1 -> 2 +- **Add feature to existing backend:** 1 -> 2 +- **Redeploy after changes:** 2 only +- **Connect existing frontend:** 3 only +- **Deploy to production:** 4 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 & Test). 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. + +--- + +## Step 4: 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 4 use the amplify-deployment-guide 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.** + +--- + +## Step 5: Execute Phases + +After the user confirms the plan, read **ONLY the first phase's reference file** (from the table in Step 3). + +**Do NOT read any other phase reference files yet.** + +### Phase Execution + +When starting a phase, announce it as a header: + +``` +## Phase 1: Backend +[Next: Phase 2: Sandbox Deployment] +``` + +Omit "[Next: ...]" if it's the last phase in your plan. + +### Resuming After a Phase Completes + +When a phase completes (the reference file will indicate the phase is done), the orchestrator takes over: + +1. Summarize what the phase accomplished +2. If there are more phases in the plan, ask: "Phase [N] complete. Ready to proceed to Phase [N+1]: [next phase name]?" +3. **WAIT for the user to confirm before proceeding.** +4. After the user confirms, read the next phase's reference file. + +Do NOT re-run prerequisites or re-present the plan. Simply execute the next phase. + +--- + +### Phase 1: Backend + +Read [references/backend.md](references/backend.md) and follow its instructions completely. + +--- + +### Phase 2: Sandbox Deployment + +Read [references/deploy.md](references/deploy.md) and follow its instructions. The deployment type is **sandbox** (deployment_type: `sandbox`). + +--- + +### Phase 3: Frontend & Test + +**Prerequisite:** `amplify_outputs.json` must exist. If not, run Phase 2 first. + +Read [references/frontend.md](references/frontend.md) and follow its instructions completely. + +--- + +### Phase 4: Production Deployment + +Read [references/deploy.md](references/deploy.md) and follow its instructions. The deployment type is **production** (deployment_type: `cicd`). + +**After completion:** + +``` +## You're live! + +### Production URL +[url from deployment output] + +### Amplify Console +https://console.aws.amazon.com/amplify/home + +Your app is now deployed! Future updates: just push to your repo and it auto-deploys. +``` + +This is the final phase. The workflow is complete. + +--- + +## 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. **Wait for confirmation between phases** -- After each phase completes, ask the user to confirm before executing the next phase. Do not proceed until the user confirms. +4. **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 +5. **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 + +--- + +## 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.** diff --git a/plugins/aws-amplify/skills/amplify-workflow/references/backend.md b/plugins/aws-amplify/skills/amplify-workflow/references/backend.md new file mode 100644 index 0000000..5f073ea --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/references/backend.md @@ -0,0 +1,41 @@ +# Backend Phase Instructions + +Create or modify Amplify Gen 2 backend resources. + +## Prerequisites Confirmed + +Prerequisites (Node.js, npm, AWS credentials) were already validated by the orchestrator workflow. Do not re-validate. + +## Critical Constraints + +- **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. This phase 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. + +## Retrieve and Follow the SOP + +**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. + +**If SOP retrieval fails** (empty result, error, or timeout), STOP and inform the user: "I couldn't retrieve the backend implementation guide. Please verify that the aws-mcp server is active and try again." Do NOT attempt to write backend code from general knowledge. + +### SOP Overrides + +- **Skip the SOP's Step 1** ("Verify Dependencies") -- prerequisites were already validated by the orchestrator. +- **Skip the SOP's Step 12** ("Determine Next SOP Requirements") -- phase sequencing is controlled by the orchestrator workflow, not the SOP. + +Follow all other SOP steps (2 through 11) completely. Do not improvise or skip them. + +### Error Handling + +1. If you encounter an error, fix the immediate issue +2. Return to the SOP and continue from where you left off +3. Do NOT abandon the SOP or start improvising +4. If you lose track, retrieve the SOP again, identify your last completed step, and continue + +## Phase Complete + +After the SOP is fully executed, summarize what was created (which resources, files, configurations). + +This phase is now complete. Do not read other reference files or proceed to the next phase — return control to the orchestrator workflow (SKILL.md). diff --git a/plugins/aws-amplify/skills/amplify-workflow/references/deploy.md b/plugins/aws-amplify/skills/amplify-workflow/references/deploy.md new file mode 100644 index 0000000..74bf2c8 --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/references/deploy.md @@ -0,0 +1,49 @@ +# Deploy Phase Instructions + +Deploy an AWS Amplify Gen 2 application to sandbox or production. + +## Prerequisites Confirmed + +Prerequisites (Node.js, npm, AWS credentials) were already validated by the orchestrator workflow. Do not re-validate. + +## SOP Parameter Mapping + +The SOP uses `deployment_type` with values `sandbox` or `cicd`. Map based on the deployment target specified by the orchestrator: + +- "sandbox", "development", "testing" -> deployment_type: **sandbox** +- "production", "prod", "live", "release", "cicd" -> deployment_type: **cicd** + +**app_name**: Infer from the project's `package.json` `name` field or existing Amplify configuration. Only ask the user if it cannot be determined. + +Do not ask the user for the deployment type -- the orchestrator specifies it. + +## Retrieve and Follow the SOP + +Use the SOP retrieval tool to get **"amplify-deployment-guide"** and follow it completely. + +**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. + +**If SOP retrieval fails** (empty result, error, or timeout), STOP and inform the user: "I couldn't retrieve the deployment guide. Please verify that the aws-mcp server is active and try again." Do NOT attempt to deploy from general knowledge. + +### SOP Overrides + +- **Skip the SOP's Step 1** ("Verify Dependencies") -- prerequisites were already validated by the orchestrator. + +Follow all applicable SOP steps for the deployment type. Do not improvise or skip them. + +### Error Handling + +1. If you encounter an error, fix the immediate issue +2. Return to the SOP and continue from where you left off +3. Do NOT abandon the SOP or start improvising +4. If you lose track, retrieve the SOP again, identify your last completed step, and continue + +## Phase Complete + +After the SOP is fully executed: + +1. Confirm deployment succeeded +2. Verify `amplify_outputs.json` exists in the project root +3. Summarize the deployment results + +This phase is now complete. Do not read other reference files or proceed to the next phase — return control to the orchestrator workflow (SKILL.md). diff --git a/plugins/aws-amplify/skills/amplify-workflow/references/frontend.md b/plugins/aws-amplify/skills/amplify-workflow/references/frontend.md new file mode 100644 index 0000000..fe95c7b --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/references/frontend.md @@ -0,0 +1,57 @@ +# Frontend & Testing Phase Instructions + +Connect the frontend application to the Amplify Gen 2 backend and verify everything works. + +## Prerequisites Confirmed + +Prerequisites (Node.js, npm, AWS credentials) were already validated by the orchestrator workflow. Do not re-validate. + +**Required:** `amplify_outputs.json` must exist in the project root. If it does not exist, inform the user that sandbox deployment (Phase 2) must be completed first. Do NOT proceed without it. + +## Retrieve and Follow the SOP + +**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. + +**If SOP retrieval fails** (empty result, error, or timeout), STOP and inform the user: "I couldn't retrieve the frontend integration guide. Please verify that the aws-mcp server is active and try again." Do NOT attempt to write integration code from general knowledge. + +### SOP Overrides + +- **Skip the SOP's Step 12** ("Determine Next SOP Requirements") -- phase sequencing is controlled by the orchestrator workflow, not the SOP. + +Follow all other SOP steps completely. Do not improvise or skip them. + +### Error Handling + +1. If you encounter an error, fix the immediate issue +2. Return to the SOP and continue from where you left off +3. Do NOT abandon the SOP or start improvising +4. If you lose track, retrieve the SOP again, identify your last completed step, and continue + +## Local Testing + +After the SOP is fully executed, present the testing instructions to the user: + +``` +## Time to test! + +### Start your dev server +[framework-specific command, e.g., npm run dev, npx next dev, etc.] + +### Try these features +[list all features that were implemented in this session] + +Let me know how it goes -- or if anything needs changes! +``` + +**Wait for the user to test and respond.** + +- If the user reports issues, fix them within this phase. Use the SOP's troubleshooting section and documentation tools as needed. After fixing, ask the user to test again. +- If the user confirms everything works (or has no further changes), proceed to phase completion below. + +## Phase Complete + +Once the user confirms testing is successful (or has no changes needed), summarize the frontend integration and testing results. + +This phase is now complete. Do not read other reference files or proceed to the next phase — return control to the orchestrator workflow (SKILL.md). diff --git a/plugins/aws-amplify/skills/amplify-workflow/scripts/prereq-check.sh b/plugins/aws-amplify/skills/amplify-workflow/scripts/prereq-check.sh new file mode 100755 index 0000000..ec280fc --- /dev/null +++ b/plugins/aws-amplify/skills/amplify-workflow/scripts/prereq-check.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# Amplify prerequisite check script +# Runs deterministic checks so the agent doesn't need to execute them ad-hoc. +# Exit code 0 = all checks passed; non-zero = at least one failed. + +set -euo pipefail + +PASS=0 +FAIL=0 +RESULTS="" + +check() { + local label="$1" + shift + if output=$("$@" 2>&1); then + RESULTS="${RESULTS}\n PASS: ${label} (${output})" + PASS=$((PASS + 1)) + else + RESULTS="${RESULTS}\n FAIL: ${label}" + FAIL=$((FAIL + 1)) + fi +} + +# Node.js >= 18 +check "Node.js >= 18" node -e " + const v = parseInt(process.versions.node.split('.')[0], 10); + if (v < 18) { process.exit(1); } + process.stdout.write('v' + process.versions.node); +" + +# npm available +check "npm available" npm --version + +# AWS credentials configured +check "AWS credentials" bash -c 'AWS_PAGER="" aws sts get-caller-identity --query Account --output text' + +echo "" +echo "Amplify prerequisite check results:" +echo -e "$RESULTS" +echo "" +echo "Passed: ${PASS} Failed: ${FAIL}" + +if [ "$FAIL" -gt 0 ]; then + echo "" + echo "Some prerequisites are missing. Please fix the failures above before proceeding." + exit 1 +fi