|
| 1 | +--- |
| 2 | +name: amplify-workflow |
| 3 | +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. |
| 4 | +--- |
| 5 | + |
| 6 | +# Amplify Workflow |
| 7 | + |
| 8 | +Orchestrated workflow for AWS Amplify Gen 2 development. |
| 9 | + |
| 10 | +## Available references |
| 11 | + |
| 12 | +- **`references/backend.md`** -- Backend phase: SOP retrieval, constraints, error handling |
| 13 | +- **`references/frontend.md`** -- Frontend & testing phase: SOP retrieval, local testing |
| 14 | +- **`references/deploy.md`** -- Deploy phase: SOP retrieval, deployment type mapping |
| 15 | + |
| 16 | +## Available scripts |
| 17 | + |
| 18 | +- **`scripts/prereq-check.sh`** -- Validates Node.js, npm, AWS CLI, and AWS credentials |
| 19 | + |
| 20 | +## Defaults |
| 21 | + |
| 22 | +- **Phase ordering**: Backend → Sandbox → Frontend → Production (only applicable phases are included) |
| 23 | +- **Deployment target**: `sandbox` for development/testing, `cicd` for production |
| 24 | + |
| 25 | +--- |
| 26 | + |
| 27 | +## Step 1: Validate Prerequisites |
| 28 | + |
| 29 | +Run the prerequisite check script: |
| 30 | + |
| 31 | +```bash |
| 32 | +bash scripts/prereq-check.sh |
| 33 | +``` |
| 34 | + |
| 35 | +The script checks Node.js >= 18, npm, and AWS credentials in one pass and reports a clear PASS/FAIL summary. |
| 36 | + |
| 37 | +If the AWS credentials check fails, **STOP** and present this message to the user: |
| 38 | + |
| 39 | +``` |
| 40 | +## AWS Credentials Required |
| 41 | +
|
| 42 | +I can't proceed without AWS credentials configured. Please set up your credentials first: |
| 43 | +
|
| 44 | +**Setup Guide:** https://docs.amplify.aws/react/start/account-setup/ |
| 45 | +
|
| 46 | +**Quick options:** |
| 47 | +- Run `aws configure` to set up access keys |
| 48 | +- Run `aws sso login` if using AWS IAM Identity Center |
| 49 | +
|
| 50 | +Once your credentials are configured, let me know and I'll re-run the prerequisite check to verify. |
| 51 | +``` |
| 52 | + |
| 53 | +**Do NOT proceed with Amplify work until credentials are configured.** After the user confirms credentials are set up, re-run `scripts/prereq-check.sh` to verify before continuing. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Step 2: Understand the Project |
| 58 | + |
| 59 | +Once all prerequisites pass: |
| 60 | + |
| 61 | +1. Read all necessary project files (e.g., `amplify/`, `package.json`, existing code) to understand the current state |
| 62 | +2. If unsure about Amplify capabilities or best practices, use documentation tools to search and read AWS Amplify docs |
| 63 | + |
| 64 | +Do this BEFORE proposing a plan. |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Step 3: Determine Applicable Phases |
| 69 | + |
| 70 | +Based on the user's request and project state, determine which phases apply: |
| 71 | + |
| 72 | +| Phase | Applies when | Reference | |
| 73 | +| ------------------ | -------------------------------------------------------- | ------------------------ | |
| 74 | +| 1: Backend | User needs to create or modify Amplify backend resources | `references/backend.md` | |
| 75 | +| 2: Sandbox | Deploy to sandbox for testing | `references/deploy.md` | |
| 76 | +| 3: Frontend & Test | Frontend needs to connect to Amplify backend | `references/frontend.md` | |
| 77 | +| 4: Production | Deploy to production | `references/deploy.md` | |
| 78 | + |
| 79 | +Common patterns: |
| 80 | + |
| 81 | +- **New full-stack app:** 1 -> 2 -> 3 -> 4 |
| 82 | +- **Backend only (no frontend):** 1 -> 2 |
| 83 | +- **Add feature to existing backend:** 1 -> 2 |
| 84 | +- **Redeploy after changes:** 2 only |
| 85 | +- **Connect existing frontend:** 3 only |
| 86 | +- **Deploy to production:** 4 only |
| 87 | + |
| 88 | +**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. |
| 89 | + |
| 90 | +--- |
| 91 | + |
| 92 | +## Step 4: Present Plan and Confirm |
| 93 | + |
| 94 | +Present to the user: |
| 95 | + |
| 96 | +``` |
| 97 | +## Plan |
| 98 | +
|
| 99 | +### What I understood |
| 100 | +- [Brief summary of what the user wants] |
| 101 | +
|
| 102 | +### Features |
| 103 | +[list features if applicable] |
| 104 | +
|
| 105 | +### Framework |
| 106 | +[framework if known] |
| 107 | +
|
| 108 | +### Phases I'll execute |
| 109 | +1. [Phase name] - [one-line description] -> SOP: [sop-name] |
| 110 | +2. [Phase name] - [one-line description] -> SOP: [sop-name] |
| 111 | +... |
| 112 | +(Include SOP name for phases 1 and 3. Phases 2 and 4 use the amplify-deployment-guide SOP.) |
| 113 | +
|
| 114 | +Ready to get started? |
| 115 | +``` |
| 116 | + |
| 117 | +**WAIT for user confirmation before proceeding.** |
| 118 | + |
| 119 | +**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.** |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## Step 5: Execute Phases |
| 124 | + |
| 125 | +After the user confirms the plan, read **ONLY the first phase's reference file** (from the table in Step 3). |
| 126 | + |
| 127 | +**Do NOT read any other phase reference files yet.** |
| 128 | + |
| 129 | +### Phase Execution |
| 130 | + |
| 131 | +When starting a phase, announce it as a header: |
| 132 | + |
| 133 | +``` |
| 134 | +## Phase 1: Backend |
| 135 | +[Next: Phase 2: Sandbox Deployment] |
| 136 | +``` |
| 137 | + |
| 138 | +Omit "[Next: ...]" if it's the last phase in your plan. |
| 139 | + |
| 140 | +### Resuming After a Phase Completes |
| 141 | + |
| 142 | +When a phase completes (the reference file will indicate the phase is done), the orchestrator takes over: |
| 143 | + |
| 144 | +1. Summarize what the phase accomplished |
| 145 | +2. If there are more phases in the plan, ask: "Phase [N] complete. Ready to proceed to Phase [N+1]: [next phase name]?" |
| 146 | +3. **WAIT for the user to confirm before proceeding.** |
| 147 | +4. After the user confirms, read the next phase's reference file. |
| 148 | + |
| 149 | +Do NOT re-run prerequisites or re-present the plan. Simply execute the next phase. |
| 150 | + |
| 151 | +--- |
| 152 | + |
| 153 | +### Phase 1: Backend |
| 154 | + |
| 155 | +Read [references/backend.md](references/backend.md) and follow its instructions completely. |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +### Phase 2: Sandbox Deployment |
| 160 | + |
| 161 | +Read [references/deploy.md](references/deploy.md) and follow its instructions. The deployment type is **sandbox** (deployment_type: `sandbox`). |
| 162 | + |
| 163 | +--- |
| 164 | + |
| 165 | +### Phase 3: Frontend & Test |
| 166 | + |
| 167 | +**Prerequisite:** `amplify_outputs.json` must exist. If not, run Phase 2 first. |
| 168 | + |
| 169 | +Read [references/frontend.md](references/frontend.md) and follow its instructions completely. |
| 170 | + |
| 171 | +--- |
| 172 | + |
| 173 | +### Phase 4: Production Deployment |
| 174 | + |
| 175 | +Read [references/deploy.md](references/deploy.md) and follow its instructions. The deployment type is **production** (deployment_type: `cicd`). |
| 176 | + |
| 177 | +**After completion:** |
| 178 | + |
| 179 | +``` |
| 180 | +## You're live! |
| 181 | +
|
| 182 | +### Production URL |
| 183 | +[url from deployment output] |
| 184 | +
|
| 185 | +### Amplify Console |
| 186 | +https://console.aws.amazon.com/amplify/home |
| 187 | +
|
| 188 | +Your app is now deployed! Future updates: just push to your repo and it auto-deploys. |
| 189 | +``` |
| 190 | + |
| 191 | +This is the final phase. The workflow is complete. |
| 192 | + |
| 193 | +--- |
| 194 | + |
| 195 | +## Critical Rules |
| 196 | + |
| 197 | +1. **Always follow SOPs completely** -- Do not improvise or skip steps |
| 198 | +2. **Never use Gen 1 patterns** -- This is for Amplify Gen 2 only (TypeScript code-first, `defineAuth`/`defineData`/`defineStorage`/`defineFunction`) |
| 199 | +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. |
| 200 | +4. **If you encounter an error or get sidetracked:** |
| 201 | + - Fix the immediate issue |
| 202 | + - Return to the SOP and continue from where you left off |
| 203 | + - Do NOT abandon the SOP or start improvising |
| 204 | +5. **If you lose track of where you were in the SOP:** |
| 205 | + - Use the SOP retrieval tool to get the SOP again |
| 206 | + - Identify which step you completed last |
| 207 | + - Continue from the next step |
| 208 | + |
| 209 | +--- |
| 210 | + |
| 211 | +## Troubleshooting |
| 212 | + |
| 213 | +If issues occur during any phase: |
| 214 | + |
| 215 | +1. Check the SOP's troubleshooting section first |
| 216 | +2. Use documentation tools to search AWS Amplify docs for the error message |
| 217 | +3. Read the relevant documentation page |
| 218 | + |
| 219 | +**After resolving the issue, immediately return to the SOP and continue from where you left off. Do not abandon the workflow.** |
0 commit comments